Sonicwall MCP Server

🚀 SonicWall MCP Server

A production-ready MCP server that offers intelligent analysis of SonicWall firewall logs through natural language queries, fully compliant with the MCP 2025-06-18 specification.

🚀 Quick Start

Prerequisites

• A SonicWall Device running SonicOS 7.x or 8.x.
• API Access enabled on your SonicWall (MANAGE > System Setup > Appliance > SonicOS API).
• Docker & Docker Compose (recommended) or Node.js 20+.

1. Get the Server

git clone https://github.com/gensecaihq/sonicwall-mcp-server.git
cd sonicwall-mcp-server

2. Configure Environment

# Copy example configuration
cp .env.example .env

# Edit with your SonicWall details
nano .env

Required configuration:

SONICWALL_HOST=192.168.1.1
SONICWALL_USERNAME=admin
SONICWALL_PASSWORD=your_password
SONICWALL_VERSION=7  # or 8 for SonicOS 8.x

3. Start the Server

Using Docker (Recommended):

docker compose up -d
# or using npm script
npm run docker:up

Using Node.js:

npm install
npm run build
npm start

4. Verify Installation

# Check server health
curl http://localhost:3000/health

# Expected response:
# {"status":"healthy","protocol":"MCP/2025-06-18","version":"1.0.0"}

✨ Features

• 🔍 Natural Language Log Analysis - Query firewall logs using conversational AI.
• 🛡️ Real-time Threat Detection - Advanced threat correlation and behavioral analysis.
• 🌐 Complete SonicOS Support - Accurate API endpoints for both 7.x and 8.x versions.
• 🎯 Version-Aware Integration - Automatic endpoint resolution and feature detection.
• 🚀 Enterprise Ready - Production deployment with comprehensive security.
• 📊 Advanced Analytics - Network intelligence and security metrics.
• 🔒 MCP 2025-06-18 Compliant - Latest protocol compliance with enhanced JSON-RPC 2.0.
• ⚡ High Performance - In-memory caching with intelligent TTL management.
• 🔐 Security First - Authentication, authorization, and comprehensive audit logging.

💻 Usage Examples

Basic Usage

// Example usage in Claude
"Show me suspicious network activity from external IPs in the last 2 hours"
"Find brute force attacks on SSH and RDP ports"
"Analyze malware detections and their source locations"

Advanced Usage

// Get critical threats
{
  "severity": "critical",
  "limit": 20
}

📚 Documentation

• Complete Usage Guide - Detailed examples and use cases.
• Configuration Reference - All settings explained.
• API Documentation - Complete tool specifications.
• Troubleshooting Guide - Common issues and solutions.
• Security Guide - Security best practices.
• MCP Compliance - Protocol compliance details.

🔧 Technical Details

Architecture

┌─────────────┐    ┌─────────────────┐    ┌─────────────┐
│ Claude Code │◄──►│ MCP Server      │◄──►│ SonicWall   │
│             │SSE │ (Port 3000)     │API │ Device      │
└─────────────┘    └─────────────────┘    └─────────────┘
                          │
                          ▼
                   ┌─────────────────┐
                   │ Log Analysis    │
                   │ & Intelligence  │
                   └─────────────────┘

Key Components:

• MCP Protocol Layer: Full MCP 2024-11-05 compliance with SSE transport.
• Enhanced API Client: Accurate SonicOS 7.x/8.x endpoints with session management.
• Intelligent Log Parser: Multi-format parsing with version-specific optimizations.
• Analysis Engine: AI-powered natural language processing and threat correlation.
• Performance Cache: High-performance in-memory caching with TTL management.
• Security Framework: Comprehensive authentication and input validation.

Configuration

Basic Configuration

# SonicWall Connection
SONICWALL_HOST=your.firewall.ip
SONICWALL_USERNAME=admin
SONICWALL_PASSWORD=secure_password
SONICWALL_VERSION=7

# Server Settings  
PORT=3000
LOG_LEVEL=info
CACHE_TTL_SECONDS=300

Advanced Configuration

# Authentication (Optional)
MCP_BEARER_TOKEN=your_secret_token

# Performance Tuning
CACHE_MAX_SIZE=1000
API_TIMEOUT=30000
MAX_RETRIES=3

# Security
CORS_ORIGINS=https://claude.ai,https://localhost:3000
RATE_LIMIT_MAX=100

🐳 Docker Deployment

Prerequisites

• Docker Engine 24.0+ (latest stable).
• Docker Compose V2 (integrated plugin, comes with Docker Desktop).
• Note: Legacy docker-compose command is deprecated, use docker compose.

Quick Start Commands

# Production deployment (detached mode)
docker compose up -d

# Development mode (with hot reload)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# View logs
docker compose logs -f sonicwall-mcp

# Stop all services
docker compose down

# Rebuild and restart
docker compose up --build -d

NPM Script Shortcuts

# Production deployment
npm run docker:up

# Development with hot reload
npm run docker:dev  

# View logs
npm run docker:logs

# Stop services
npm run docker:down

# Build image only
npm run docker:build

Environment Configuration

# Use environment file
cp .env.example .env
# Edit .env with your SonicWall details
docker compose up -d

# Or pass environment variables directly
SONICWALL_HOST=192.168.1.1 \
SONICWALL_USERNAME=admin \
SONICWALL_PASSWORD=your_password \
docker compose up -d

Docker Compose Files

• docker-compose.yml - Production configuration.
• docker-compose.dev.yml - Development overrides.
• docker-compose.override.yml - Local customizations (optional).

🧪 Testing & Validation

Quick Health Check

# Server status
curl http://localhost:3000/health

# MCP endpoint test
curl -H "Accept: text/event-stream" http://localhost:3000/mcp/v1/sse

SonicWall Connectivity Test

# Test authentication
curl -k https://YOUR_SONICWALL/api/sonicos/auth \
  -H "Content-Type: application/json" \
  -d '{"user":"admin","password":"your_password"}'

Run Test Suite

# All tests
npm test

# MCP compliance tests
npm run test:mcp

# SonicWall integration tests  
npm run test:integration

🔒 Security

Security Features

• ✅ Transport Security - HTTPS enforcement with comprehensive CORS validation.
• ✅ Authentication - Bearer token support with intelligent rate limiting.
• ✅ Input Validation - JSON Schema validation using AJV with comprehensive sanitization.
• ✅ Container Security - Non-root user execution with read-only filesystem.
• ✅ Data Privacy - Zero sensitive data logging with audit-compliant processing.
• ✅ MCP Compliance - Full protocol security implementation.
• ✅ API Security - SonicWall credential protection with secure session management.

Security Checklist

• [ ] Enable API access only from trusted networks.
• [ ] Use strong passwords for SonicWall admin accounts.
• [ ] Configure MCP_BEARER_TOKEN for additional security.
• [ ] Monitor logs for unusual activity.
• [ ] Keep SonicWall firmware updated.
• [ ] Review firewall rules regularly.

🚨 Common Issues

❌ "Authentication Failed"

Problem: Cannot connect to SonicWall API

# Check API is enabled
# SonicWall: MANAGE > System Setup > Appliance > SonicOS API ✓

# Test connectivity
ping YOUR_SONICWALL_HOST
curl -k https://YOUR_SONICWALL_HOST/api/sonicos/auth

❌ "No logs returned"

Problem: Empty responses from log queries

# Check log levels in SonicWall
# Log > Settings > Categories > Enable required log types

# Verify time synchronization
date

❌ "CORS Error in Browser"

Problem: Browser blocks MCP requests

# Add your domain to CORS_ORIGINS
CORS_ORIGINS=https://claude.ai,https://your-domain.com

📊 Monitoring & Observability

Health Monitoring

# Detailed health status
curl http://localhost:3000/health | jq

# Response includes:
# - Server uptime and status
# - SonicWall connectivity
# - Cache statistics  
# - Memory usage

Performance Metrics

# View performance logs
docker compose logs sonicwall-mcp | grep "executed successfully"

# Example output:
# {"timestamp":"2024-01-01T12:00:00.000Z","level":"info","message":"Tool analyze_logs executed successfully","executionTime":245,"resultSize":15420}

Log Analysis

# Error monitoring
docker compose logs sonicwall-mcp | grep ERROR

# Performance tracking
docker compose logs sonicwall-mcp | grep "execution time"

🤝 Contributing

We welcome contributions! Please read our Contributing Guidelines.

Development Setup

# Fork and clone
git clone https://github.com/your-username/sonicwall-mcp-server.git
cd sonicwall-mcp-server

# Install dependencies  
npm install

# Start development server
npm run dev

# Run tests
npm test

# Submit PR
git checkout -b feature/amazing-feature
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

📄 License

MIT License - see LICENSE file for details.

🆘 Support & Community

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📚 Documentation: Project Wiki
• 📧 Security: security@yourorganization.com

🙏 Acknowledgments

• Model Context Protocol for the excellent specification.
• SonicWall for comprehensive API documentation.
• Claude Code community for feedback and testing.
• All contributors and users who make this project better.