SonicWall MCP Server

Professional SonicWall log analysis and threat detection via Model Context Protocol

🧪 Community Testing Needed

⚠️ IMPORTANT: This project needs community testing and validation!
👥 We need your help to test this with real SonicWall devices and environments.

• 🔍 Test it with your SonicWall setup
• 🐛 Report issues via GitHub Issues
• 🔧 Fix bugs and submit PRs
• 📝 Improve documentation based on real-world usage
• 💡 Contribute features and enhancements

Your testing and contributions will help make this production-ready for everyone!

A production-ready MCP server that provides intelligent analysis of SonicWall firewall logs through natural language queries. Fully compliant with MCP 2025-06-18 specification with comprehensive support for both SonicOS 7.x and 8.x including accurate API endpoints and version-specific features.

✨ 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

📋 Quick Start

Prerequisites

• 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"}

🔗 Connect to Claude

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "sonicwall": {
      "transport": "sse",
      "url": "http://localhost:3000/mcp/v1/sse"
    }
  }
}

That's it! Start using SonicWall analysis in Claude:

"Show me blocked connections from the last hour"
"Find critical security threats from today"
"Analyze VPN authentication failures"

🎯 Latest Improvements

⚡ Enhanced SonicOS Support (v1.0.0)

• Accurate API Endpoints: Complete endpoint mapping for both SonicOS 7.x (/api/sonicos) and 8.x (/api/sonicos/v8)
• Version-Aware Features: Automatic detection and utilization of version-specific capabilities
• Advanced Authentication: Enhanced session management with proper token refresh and error handling
• Cloud Integration: Full support for SonicOS 8.x cloud management and NSM integration

🛡️ Security & Compliance Enhancements

• MCP 2024-11-05 Compliance: Full protocol implementation with JSON-RPC 2.0 support
• Enhanced Error Handling: SonicWall-specific error codes with intelligent retry logic
• Advanced Validation: Comprehensive JSON Schema validation using AJV
• Security Hardening: Improved authentication flow with comprehensive audit logging

🚀 Performance & Reliability

• Intelligent Caching: Enhanced TTL management with automatic cleanup
• Endpoint Optimization: Version-specific timeout and rate limiting configurations
• Connection Management: Improved retry logic and failover handling
• Comprehensive Logging: Structured logging with performance metrics and debugging support

🛠️ Available Tools

analyze_logs

Natural language log analysis with intelligent insights

// 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"

get_threats

Real-time threat monitoring and analysis

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

search_connections

Advanced connection search and investigation

// Investigate specific IP
{
  "sourceIp": "192.168.1.100",
  "hoursBack": 24,
  "limit": 500
}

get_stats

Network statistics and security metrics

// Get top blocked IPs
{
  "metric": "top_blocked_ips",
  "limit": 10
}

export_logs

Export filtered logs for compliance and analysis

// Export security events as CSV
{
  "format": "csv",
  "filters": {
    "severity": ["critical", "high"],
    "startTime": "2024-01-01T00:00:00Z"
  }
}

📖 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

🏗️ 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

---