Sonicwall MCP Server

🚀 SonicWall MCP Server

通过模型上下文协议（MCP）实现专业的SonicWall日志分析和威胁检测

🚀 快速开始

前提条件

• 运行SonicOS 7.x或8.x的SonicWall设备。
• 在SonicWall上启用API访问（MANAGE > System Setup > Appliance > SonicOS API）。
• 推荐使用Docker和Docker Compose，或者安装Node.js 20+。

1. 获取服务器代码

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

2. 配置环境

# 复制示例配置文件
cp .env.example .env

# 使用nano编辑配置文件，填入SonicWall详细信息
nano .env

必需的配置如下：

SONICWALL_HOST=192.168.1.1
SONICWALL_USERNAME=admin
SONICWALL_PASSWORD=your_password
SONICWALL_VERSION=7  # 若使用SonicOS 8.x，则改为8

3. 启动服务器

使用Docker（推荐）：

docker compose up -d
# 或者使用npm脚本
npm run docker:up

使用Node.js：

npm install
npm run build
npm start

4. 验证安装

# 检查服务器健康状态
curl http://localhost:3000/health

# 预期响应：
# {"status":"healthy","protocol":"MCP/2025-06-18","version":"1.0.0"}

✨ 主要特性

• 🔍 自然语言日志分析：使用对话式AI查询防火墙日志。
• 🛡️ 实时威胁检测：先进的威胁关联和行为分析。
• 🌐 全面支持SonicOS：为7.x和8.x版本提供准确的API端点。
• 🎯 版本感知集成：自动解析端点并检测特定版本的功能。
• 🚀 企业级就绪：具备全面安全保障的生产环境部署。
• 📊 高级分析：提供网络情报和安全指标。
• 🔒 符合MCP 2025-06-18标准：遵循最新协议，增强JSON - RPC 2.0支持。
• ⚡ 高性能：采用智能TTL管理的内存缓存。
• 🔐 安全至上：具备身份验证、授权和全面的审计日志记录。

📦 安装指南

Docker部署

前提条件

• Docker Engine 24.0+（最新稳定版）。
• Docker Compose V2（集成插件，随Docker Desktop提供）。 注意：旧版的docker-compose命令已弃用，请使用docker compose。

快速启动命令

# 生产环境部署（后台运行）
docker compose up -d

# 开发模式（支持热重载）
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# 查看日志
docker compose logs -f sonicwall-mcp

# 停止所有服务
docker compose down

# 重建并重启
docker compose up --build -d

NPM脚本快捷方式

# 生产环境部署
npm run docker:up

# 开发模式，支持热重载
npm run docker:dev  

# 查看日志
npm run docker:logs

# 停止服务
npm run docker:down

# 仅构建镜像
npm run docker:build

环境配置

# 使用环境文件
cp .env.example .env
# 编辑.env文件，填入SonicWall详细信息，然后启动容器
docker compose up -d

# 或者直接传递环境变量
SONICWALL_HOST=192.168.1.1 \
SONICWALL_USERNAME=admin \
SONICWALL_PASSWORD=your_password \
docker compose up -d

Docker Compose文件

• docker-compose.yml：生产环境配置。
• docker-compose.dev.yml：开发环境覆盖配置。
• docker-compose.override.yml：本地自定义配置（可选）。

💻 使用示例

基础用法

# 连接到Claude，在Claude桌面配置文件（claude_desktop_config.json）中添加以下内容
{
  "mcpServers": {
    "sonicwall": {
      "transport": "sse",
      "url": "http://localhost:3000/mcp/v1/sse"
    }
  }
}

完成上述配置后，即可在Claude中开始使用SonicWall分析功能，例如：

"Show me blocked connections from the last hour"（显示过去一小时内被阻止的连接） "Find critical security threats from today"（查找今天的关键安全威胁） "Analyze VPN authentication failures"（分析VPN认证失败情况）

高级用法

analyze_logs

使用自然语言进行日志分析并获得智能洞察

// 在Claude中的示例用法
"Show me suspicious network activity from external IPs in the last 2 hours"（显示过去两小时内来自外部IP的可疑网络活动）
"Find brute force attacks on SSH and RDP ports"（查找SSH和RDP端口的暴力攻击）
"Analyze malware detections and their source locations"（分析恶意软件检测情况及其来源位置）

get_threats

实时威胁监控和分析

// 获取关键威胁
{
  "severity": "critical",
  "limit": 20
}

search_connections

高级连接搜索和调查

// 调查特定IP
{
  "sourceIp": "192.168.1.100",
  "hoursBack": 24,
  "limit": 500
}

get_stats

获取网络统计信息和安全指标

// 获取排名前十的被阻止IP
{
  "metric": "top_blocked_ips",
  "limit": 10
}

export_logs

导出过滤后的日志，用于合规性检查和分析

// 以CSV格式导出安全事件
{
  "format": "csv",
  "filters": {
    "severity": ["critical", "high"],
    "startTime": "2024-01-01T00:00:00Z"
  }
}

📚 详细文档

• 完整使用指南：详细示例和用例。
• 配置参考：所有设置说明。
• API文档：完整工具规范。
• 故障排除指南：常见问题及解决方案。
• 安全指南：安全最佳实践。
• MCP合规性：协议合规性详细信息。

🔧 技术细节

架构

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

关键组件：

• MCP协议层：完全符合MCP 2024 - 11 - 05标准，采用SSE传输。
• 增强型API客户端：准确的SonicOS 7.x/8.x端点，具备会话管理功能。
• 智能日志解析器：支持多格式解析，针对不同版本进行优化。
• 分析引擎：基于AI的自然语言处理和威胁关联。
• 性能缓存：高性能内存缓存，具备TTL管理。
• 安全框架：全面的身份验证和输入验证。

配置

基本配置

# SonicWall连接配置
SONICWALL_HOST=your.firewall.ip
SONICWALL_USERNAME=admin
SONICWALL_PASSWORD=secure_password
SONICWALL_VERSION=7

# 服务器设置
PORT=3000
LOG_LEVEL=info
CACHE_TTL_SECONDS=300

高级配置

# 身份验证（可选）
MCP_BEARER_TOKEN=your_secret_token

# 性能调优
CACHE_MAX_SIZE=1000
API_TIMEOUT=30000
MAX_RETRIES=3

# 安全设置
CORS_ORIGINS=https://claude.ai,https://localhost:3000
RATE_LIMIT_MAX=100

🧪 测试与验证

快速健康检查

# 检查服务器状态
curl http://localhost:3000/health

# 测试MCP端点
curl -H "Accept: text/event-stream" http://localhost:3000/mcp/v1/sse

SonicWall连接测试

# 测试身份验证
curl -k https://YOUR_SONICWALL/api/sonicos/auth \
  -H "Content-Type: application/json" \
  -d '{"user":"admin","password":"your_password"}'

运行测试套件

# 运行所有测试
npm test

# 运行MCP合规性测试
npm run test:mcp

# 运行SonicWall集成测试
npm run test:integration

🔒 安全

安全特性

• ✅ 传输安全：强制使用HTTPS，并进行全面的CORS验证。
• ✅ 身份验证：支持Bearer令牌，具备智能速率限制。
• ✅ 输入验证：使用AJV进行JSON Schema验证，并进行全面清理。
• ✅ 容器安全：以非root用户身份运行，使用只读文件系统。
• ✅ 数据隐私：不记录敏感数据，处理过程符合审计要求。
• ✅ MCP合规性：全面实现协议安全。
• ✅ API安全：保护SonicWall凭证，具备安全的会话管理。

安全检查清单

• [ ] 仅从受信任的网络启用API访问。
• [ ] 为SonicWall管理账户使用强密码。
• [ ] 配置MCP_BEARER_TOKEN以增强安全性。
• [ ] 监控日志以发现异常活动。
• [ ] 保持SonicWall固件更新。
• [ ] 定期审查防火墙规则。

🚨 常见问题

❌ "Authentication Failed"（身份验证失败）

问题：无法连接到SonicWall API。

# 检查API是否已启用
# SonicWall: MANAGE > System Setup > Appliance > SonicOS API ✓

# 测试网络连接
ping YOUR_SONICWALL_HOST
curl -k https://YOUR_SONICWALL_HOST/api/sonicos/auth

❌ "No logs returned"（未返回日志）

问题：日志查询返回空响应。

# 检查SonicWall中的日志级别
# Log > Settings > Categories > Enable required log types

# 验证时间同步
date

❌ "CORS Error in Browser"（浏览器中出现CORS错误）

问题：浏览器阻止MCP请求。

# 将你的域名添加到CORS_ORIGINS
CORS_ORIGINS=https://claude.ai,https://your-domain.com

📊 监控与可观测性

健康监控

# 获取详细的健康状态
curl http://localhost:3000/health | jq

# 响应内容包括：
# - 服务器正常运行时间和状态
# - SonicWall连接状态
# - 缓存统计信息
# - 内存使用情况

性能指标

# 查看性能日志
docker compose logs sonicwall-mcp | grep "executed successfully"

# 示例输出：
# {"timestamp":"2024-01-01T12:00:00.000Z","level":"info","message":"Tool analyze_logs executed successfully","executionTime":245,"resultSize":15420}

日志分析

# 监控错误日志
docker compose logs sonicwall-mcp | grep ERROR

# 跟踪性能日志
docker compose logs sonicwall-mcp | grep "execution time"

🤝 贡献代码

我们欢迎大家贡献代码！请阅读我们的贡献指南。

开发环境设置

# Fork项目并克隆到本地
git clone https://github.com/your-username/sonicwall-mcp-server.git
cd sonicwall-mcp-server

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 运行测试
npm test

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

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

🆘 支持与社区

• 🐛 问题反馈：GitHub Issues
• 💬 讨论交流：GitHub Discussions
• 📚 文档资料：项目Wiki
• 📧 安全问题：security@yourorganization.com

🙏 致谢

• 模型上下文协议提供了优秀的规范。
• SonicWall提供了全面的API文档。
• Claude Code社区提供了反馈和测试。
• 所有为项目做出贡献的人员和用户，让这个项目变得更好。