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社區提供了反饋和測試。
• 所有為項目做出貢獻的人員和用戶，讓這個項目變得更好。