# SonicWall MCP Server - API Documentation
This document provides complete technical specifications for all MCP tools available in the SonicWall MCP Server.
## 🚀 Recent Updates (v1.0.0)
### Enhanced SonicOS Integration
- **Accurate API Endpoints**: Complete endpoint mapping for SonicOS 7.x and 8.x
- **Version-Aware Processing**: Automatic adaptation to version-specific features
- **Improved Authentication**: Enhanced session management with proper error handling
- **Advanced Threat Detection**: Support for SonicOS 8.x Advanced Threat Protection
### MCP Protocol Compliance
- **Full MCP 2024-11-05 Support**: Complete protocol implementation
- **JSON Schema Validation**: Comprehensive input/output validation using AJV
- **Enhanced Error Handling**: Detailed error responses with troubleshooting guidance
- **Performance Optimization**: Intelligent caching and request management
## Table of Contents
- [Tool Overview](#tool-overview)
- [Common Parameters](#common-parameters)
- [Tool Specifications](#tool-specifications)
- [Response Formats](#response-formats)
- [Error Handling](#error-handling)
- [Rate Limits & Performance](#rate-limits--performance)
## Tool Overview
The SonicWall MCP Server provides 5 main tools for comprehensive firewall log analysis:
| Tool | Purpose | Input Type | Output Type |
|------|---------|------------|-------------|
| `analyze_logs` | Natural language log analysis | Query + Filters | Analysis + Insights |
| `get_threats` | Current threat monitoring | Filters | Threat List + Summary |
| `search_connections` | Connection investigation | Network Filters | Connection List + Analysis |
| `get_stats` | Network statistics | Metric Type | Statistics + Trends |
| `export_logs` | Log data export | Filters + Format | Raw Data + Metadata |
## Common Parameters
### Time Range Parameters
```typescript
hoursBack?: number; // 1-168 (1 hour to 7 days), default: 24
startTime?: string; // ISO 8601 format: "2024-01-01T00:00:00Z"
endTime?: string; // ISO 8601 format: "2024-01-01T23:59:59Z"
```
### Filter Parameters
```typescript
severity?: string[]; // ["critical", "high", "medium", "low", "info"]
logType?: string; // "firewall" | "vpn" | "ips" | "antivirus" | "system" | "all"
action?: string; // "allow" | "deny" | "drop" | "reset" | "all"
sourceIp?: string; // IPv4 format: "192.168.1.1"
destIp?: string; // IPv4 format: "10.0.0.1"
port?: number; // 1-65535
limit?: number; // Result limit (varies by tool)
```
## Tool Specifications
### 1. `analyze_logs`
**Purpose**: Analyze SonicWall logs using natural language queries with intelligent pattern matching.
#### Input Schema
```json
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural language query to analyze logs",
"minLength": 3,
"maxLength": 500,
"examples": [
"show blocked connections from last hour",
"find critical security threats from today",
"analyze VPN authentication failures"
]
},
"hoursBack": {
"type": "number",
"description": "Number of hours to look back",
"minimum": 1,
"maximum": 168,
"default": 24
},
"logType": {
"type": "string",
"enum": ["firewall", "vpn", "ips", "antivirus", "system", "all"],
"description": "Type of logs to analyze",
"default": "all"
}
},
"required": ["query"],
"additionalProperties": false
}
```
#### Response Schema
```json
{
"type": "object",
"properties": {
"summary": {
"type": "string",
"description": "Human-readable analysis summary"
},
"totalCount": {
"type": "number",
"description": "Total number of log entries analyzed"
},
"matchedLogs": {
"type": "array",
"description": "Relevant log entries (limited to 50 for readability)",
"items": {
"$ref": "#/definitions/LogEntry"
}
},
"insights": {
"type": "array",
"description": "Key findings and patterns identified",
"items": {
"type": "string"
}
},
"recommendations": {
"type": "array",
"description": "Security recommendations based on analysis",
"items": {
"type": "string"
}
}
}
}
```
#### Example Request
```json
{
"name": "analyze_logs",
"arguments": {
"query": "show blocked connections from external IPs to administrative ports in last 4 hours",
"hoursBack": 4,
"logType": "firewall"
}
}
```
#### Example Response
```json
{
"summary": "Found 23 blocked connections from 8 external IPs targeting SSH (port 22) and RDP (port 3389) in the last 4 hours",
"totalCount": 1842,
"matchedLogs": [
{
"id": "log_001",
"timestamp": "2024-01-01T14:30:15Z",
"severity": "high",
"category": "firewall",
"action": "deny",
"sourceIp": "203.0.113.45",
"destIp": "192.168.1.10",
"destPort": 22,
"protocol": "TCP",
"message": "Connection blocked by firewall rule"
}
],
"insights": [
"Peak attack activity at 14:00 (35% of blocked attempts)",
"Most targeted IP: 192.168.1.10 (12 attempts)",
"Coordinated attack from 203.0.113.0/24 subnet"
],
"recommendations": [
"Consider blocking entire 203.0.113.0/24 subnet",
"Implement fail2ban for IP-based blocking",
"Review SSH key-based authentication setup"
]
}
```
### 2. `get_threats`
**Purpose**: Retrieve current security threats with detailed analysis and recommendations.
#### Input Schema
```json
{
"type": "object",
"properties": {
"severity": {
"type": "string",
"enum": ["critical", "high", "medium", "low", "all"],
"description": "Filter by threat severity level",
"default": "all"
},
"limit": {
"type": "number",
"description": "Maximum number of threats to return",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"includeBlocked": {
"type": "boolean",
"description": "Include blocked threats in results",
"default": true
}
},
"additionalProperties": false
}
```
#### Response Schema
```json
{
"type": "object",
"properties": {
"threats": {
"type": "array",
"items": {
"$ref": "#/definitions/ThreatInfo"
}
},
"summary": {
"type": "object",
"properties": {
"total": {"type": "number"},
"bySeverity": {
"type": "object",
"additionalProperties": {"type": "number"}
},
"byType": {
"type": "object",
"additionalProperties": {"type": "number"}
},
"blocked": {"type": "number"},
"allowed": {"type": "number"}
}
},
"recommendations": {
"type": "array",
"items": {"type": "string"}
}
}
}
```
#### Example Request
```json
{
"name": "get_threats",
"arguments": {
"severity": "critical",
"limit": 20
}
}
```
### 3. `search_connections`
**Purpose**: Search and analyze network connections by IP address, port, or action with security insights.
#### Input Schema
```json
{
"type": "object",
"properties": {
"sourceIp": {
"type": "string",
"description": "Source IP address (IPv4 format)",
"pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
},
"destIp": {
"type": "string",
"description": "Destination IP address (IPv4 format)",
"pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
},
"port": {
"type": "number",
"description": "Port number",
"minimum": 1,
"maximum": 65535
},
"action": {
"type": "string",
"enum": ["allow", "deny", "drop", "reset", "all"],
"description": "Filter by connection action",
"default": "all"
},
"hoursBack": {
"type": "number",
"description": "Number of hours to look back",
"minimum": 1,
"maximum": 168,
"default": 24
},
"limit": {
"type": "number",
"description": "Maximum number of results",
"minimum": 1,
"maximum": 5000,
"default": 100
}
},
"additionalProperties": false
}
```
#### Response Schema
```json
{
"type": "object",
"properties": {
"connections": {
"type": "array",
"items": {"$ref": "#/definitions/LogEntry"}
},
"summary": {
"type": "object",
"properties": {
"total": {"type": "number"},
"allowed": {"type": "number"},
"blocked": {"type": "number"},
"byProtocol": {
"type": "object",
"additionalProperties": {"type": "number"}
},
"topPorts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"port": {"type": "number"},
"count": {"type": "number"}
}
}
},
"timeRange": {
"type": "object",
"properties": {
"start": {"type": "string"},
"end": {"type": "string"}
}
}
}
},
"insights": {
"type": "array",
"items": {"type": "string"}
}
}
}
```
### 4. `get_stats`
**Purpose**: Retrieve comprehensive network statistics and security metrics.
#### Input Schema
```json
{
"type": "object",
"properties": {
"metric": {
"type": "string",
"enum": [
"top_blocked_ips",
"top_allowed_ips",
"port_summary",
"threat_summary",
"protocol_breakdown",
"hourly_traffic"
],
"description": "Type of statistics to retrieve"
},
"limit": {
"type": "number",
"description": "Maximum number of results",
"minimum": 1,
"maximum": 100,
"default": 10
},
"hoursBack": {
"type": "number",
"description": "Number of hours to analyze",
"minimum": 1,
"maximum": 168,
"default": 24
}
},
"required": ["metric"],
"additionalProperties": false
}
```
#### Response Schema
```json
{
"type": "object",
"properties": {
"metric": {"type": "string"},
"data": {
"type": "array",
"items": {"type": "object"}
},
"summary": {"type": "string"},
"period": {"type": "string"},
"recommendations": {
"type": "array",
"items": {"type": "string"}
}
}
}
```
#### Available Metrics
**top_blocked_ips**: Most frequently blocked source IPs
```json
{
"data": [
{
"ip": "203.0.113.10",
"count": 145,
"percentage": 23,
"lastSeen": "2024-01-01T15:30:00Z"
}
]
}
```
**top_allowed_ips**: Most active allowed source IPs
```json
{
"data": [
{
"ip": "192.168.1.100",
"count": 2341,
"dataTransferred": 1048576,
"percentage": 15,
"lastSeen": "2024-01-01T15:45:00Z"
}
]
}
```
**port_summary**: Port usage and security analysis
```json
{
"data": [
{
"port": 443,
"protocol": "TCP",
"count": 5678,
"allowed": 5432,
"blocked": 246,
"service": "HTTPS",
"riskLevel": "low",
"blockRate": 4
}
]
}
```
**threat_summary**: Threat types and statistics
```json
{
"data": [
{
"type": "malware",
"count": 23,
"blocked": 21,
"critical": 3,
"high": 8,
"medium": 12,
"low": 0,
"recentCount": 5,
"blockRate": 91,
"severity": "critical"
}
]
}
```
### 5. `export_logs`
**Purpose**: Export filtered logs in multiple formats with comprehensive metadata.
#### Input Schema
```json
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": ["json", "csv"],
"description": "Export format"
},
"filters": {
"type": "object",
"properties": {
"startTime": {
"type": "string",
"format": "date-time",
"description": "Start time (ISO 8601)"
},
"endTime": {
"type": "string",
"format": "date-time",
"description": "End time (ISO 8601)"
},
"severity": {
"type": "array",
"items": {
"type": "string",
"enum": ["critical", "high", "medium", "low", "info"]
},
"minItems": 1,
"maxItems": 5
},
"logType": {
"type": "string",
"enum": ["firewall", "vpn", "ips", "antivirus", "system", "all"],
"default": "all"
},
"sourceIp": {
"type": "string",
"pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
},
"destIp": {
"type": "string",
"pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
},
"action": {
"type": "string",
"enum": ["allow", "deny", "drop", "reset", "all"],
"default": "all"
}
},
"additionalProperties": false
},
"limit": {
"type": "number",
"description": "Maximum number of entries",
"minimum": 1,
"maximum": 100000,
"default": 10000
}
},
"required": ["format"],
"additionalProperties": false
}
```
#### Response Schema
```json
{
"type": "object",
"properties": {
"format": {"type": "string"},
"data": {
"type": "string",
"description": "Exported data (JSON string or CSV)"
},
"metadata": {
"type": "object",
"properties": {
"totalRecords": {"type": "number"},
"exportedRecords": {"type": "number"},
"timeRange": {
"type": "object",
"properties": {
"start": {"type": "string"},
"end": {"type": "string"}
}
},
"filters": {"type": "object"},
"exportTime": {"type": "string"}
}
}
}
}
```
## Response Formats
### Common Data Types
#### LogEntry
```json
{
"id": "string",
"timestamp": "ISO 8601 datetime",
"severity": "critical|high|medium|low|info",
"category": "firewall|vpn|ips|antivirus|system",
"action": "allow|deny|drop|reset",
"sourceIp": "IPv4 address",
"sourcePort": "number (optional)",
"destIp": "IPv4 address",
"destPort": "number (optional)",
"protocol": "TCP|UDP|ICMP|OTHER",
"rule": "string (optional)",
"message": "string",
"raw": "string (original log entry)",
"cloudId": "string (SonicOS 8.x only)",
"tenantId": "string (SonicOS 8.x only)"
}
```
#### ThreatInfo
```json
{
"id": "string",
"timestamp": "ISO 8601 datetime",
"severity": "critical|high|medium|low",
"type": "malware|intrusion|botnet|spam|suspicious",
"sourceIp": "IPv4 address",
"destIp": "IPv4 address",
"description": "string",
"action": "string",
"blocked": "boolean"
}
```
## Error Handling
### MCP Error Codes
The server returns standard MCP error codes:
- **-32700**: Parse error (invalid JSON)
- **-32600**: Invalid Request (invalid JSON-RPC)
- **-32601**: Method not found (unknown tool)
- **-32602**: Invalid params (schema validation failed)
- **-32603**: Internal error (server error)
### Tool-Specific Errors
#### Validation Errors
```json
{
"code": -32602,
"message": "Invalid arguments: /sourceIp must match pattern",
"data": {
"validationErrors": [
"/sourceIp must match pattern"
]
}
}
```
#### SonicWall Connection Errors
```json
{
"content": [
{
"type": "text",
"text": "Tool execution failed: Authentication failed with SonicWall device"
}
],
"isError": true
}
```
#### Rate Limiting
```json
{
"code": -32603,
"message": "Rate limit exceeded",
"data": {
"retryAfter": 60
}
}
```
## Rate Limits & Performance
### Request Limits
- **analyze_logs**: 10 requests/minute
- **get_threats**: 20 requests/minute
- **search_connections**: 15 requests/minute
- **get_stats**: 30 requests/minute
- **export_logs**: 5 requests/minute (due to data size)
### Performance Guidelines
#### Response Times (Typical)
- **analyze_logs**: 2-5 seconds
- **get_threats**: 1-3 seconds
- **search_connections**: 1-4 seconds
- **get_stats**: 1-2 seconds
- **export_logs**: 5-30 seconds (depends on data size)
#### Optimization Tips
**Use specific time ranges:**
```json
// ✅ Optimal
{"hoursBack": 6}
// ❌ Slow
{"hoursBack": 168}
```
**Leverage caching:**
```json
// ✅ Cache-friendly (standard intervals)
{"hoursBack": 24}
// ❌ Cache-unfriendly (custom ranges)
{"startTime": "2024-01-01T13:27:00Z"}
```
**Limit result sets:**
```json
// ✅ Efficient
{"limit": 100}
// ❌ Resource intensive
{"limit": 10000}
```
### Memory Usage
- **Cache Size**: ~100MB typical, 500MB maximum
- **Request Memory**: 10-50MB per request
- **Export Memory**: Up to 200MB for large exports
## Authentication
### Bearer Token (Optional)
```http
Authorization: Bearer your_token_here
```
### CORS Headers
```http
Origin: https://claude.ai
Access-Control-Allow-Origin: https://claude.ai
```
## Examples Collection
### Security Operations Center (SOC) Queries
```javascript
// Morning threat briefing
{
"name": "get_threats",
"arguments": {
"severity": "high",
"limit": 50
}
}
// Incident investigation
{
"name": "search_connections",
"arguments": {
"sourceIp": "203.0.113.10",
"hoursBack": 48,
"limit": 1000
}
}
// Weekly security report
{
"name": "export_logs",
"arguments": {
"format": "csv",
"filters": {
"severity": ["critical", "high"],
"startTime": "2024-01-01T00:00:00Z",
"endTime": "2024-01-07T23:59:59Z"
}
}
}
```
### Network Analysis
```javascript
// Bandwidth analysis
{
"name": "get_stats",
"arguments": {
"metric": "top_allowed_ips",
"limit": 50,
"hoursBack": 168
}
}
// Service monitoring
{
"name": "get_stats",
"arguments": {
"metric": "port_summary",
"limit": 100
}
}
// Traffic patterns
{
"name": "get_stats",
"arguments": {
"metric": "hourly_traffic",
"hoursBack": 72
}
}
```
---
**💡 Pro Tip**: Use the schema validation to ensure your requests are properly formatted. All tools include comprehensive input validation to prevent errors and ensure optimal performance.