Sharkmcp

🚀 SharkMCP - 網絡數據包分析MCP服務器

SharkMCP是一個模型上下文協議（MCP）服務器，通過與Wireshark/tshark集成，提供網絡數據包捕獲和分析功能。它專為AI助手進行網絡安全分析、故障排除和數據包檢查而設計。

該服務器適用於需要讓代理調試發送請求的程序並驗證數據包流量的場景，支持以下工作流程：

• 開始記錄數據包
• 運行工具或執行請求
• 停止記錄並分析結果

🚀 快速開始

前提條件

系統要求

• Wireshark/tshark：必須安裝且可訪問
• Node.js：版本18+
• pnpm：包管理器（推薦）

安裝Wireshark/tshark

macOS（使用Homebrew）：

brew install wireshark

Ubuntu/Debian：

sudo apt update
sudo apt install tshark wireshark-common

Windows：從 wireshark.org 下載

安裝步驟

1. 克隆倉庫：

git clone https://github.com/kriztalz/SharkMCP.git
cd SharkMCP

2. 安裝依賴：

pnpm install

3. 構建項目：

pnpm run build

4. 運行服務器：

pnpm start

✨ 主要特性

• 異步數據包捕獲：可使用可配置的過濾器和超時時間啟動後臺捕獲會話。
• PCAP文件分析：能夠分析現有的數據包捕獲文件。
• 靈活的輸出格式：支持JSON、自定義字段或傳統文本輸出。
• SSL/TLS解密：支持使用SSL密鑰日誌文件解密HTTPS流量。
• 可重複使用的配置：可以保存和重複使用捕獲/分析配置。

⚠️ 重要提示

數據包信息可能非常多。請確保使用範圍顯示過濾器，以免使對話上下文過載。

📚 詳細文檔

架構

SharkMCP提供了一個簡單的、專注於本地開發的架構：

┌─────────────────────────────────────────────────────────┐
│                    SharkMCP Server                      │
├─────────────────────────────────────────────────────────┤
│  MCP協議層                                              │
│  ├─ start_capture_session                               │
│  ├─ stop_capture_session                                │
│  ├─ analyze_pcap_file                                   │
│  └─ manage_config                                       │
├─────────────────────────────────────────────────────────┤
│  tshark集成層                                           │
│  ├─ 跨平臺可執行文件檢測                                │
│  ├─ 進程管理                                            │
│  └─ 輸出解析（JSON/字段/文本）                          │
├─────────────────────────────────────────────────────────┤
│  主機系統集成                                           │
│  ├─ 本地tshark安裝                                      │
│  ├─ 直接網絡接口訪問                                    │
│  └─ 原生文件系統操作                                    │
└─────────────────────────────────────────────────────────┘

配置

MCP客戶端設置

{
  "mcpServers": {
    "sharkmcp": {
      "command": "node",
      "args": ["/path/to/SharkMCP/dist/index.js"],
    }
  }
}

SSL/TLS解密（可選）

要解密HTTPS流量，請導出 SSLKEYLOGFILE 環境變量：

export SSLKEYLOGFILE=/path/to/sslkeylog.log

然後配置應用程序將SSL密鑰記錄到該文件。許多應用程序在設置了環境變量後會自動支持此功能。 之後，在 stop_capture_session 工具中將日誌文件路徑名傳遞給MCP服務器。

使用方法

可用工具

1. start_capture_session：啟動後臺數據包捕獲
2. stop_capture_session：停止捕獲並分析結果
3. analyze_pcap_file：分析現有的PCAP文件
4. manage_config：保存/加載可重複使用的配置

基本示例

啟動捕獲會話：

接口：en0
捕獲過濾器：端口443
超時時間：30秒

分析捕獲的流量：

顯示過濾器：tls.handshake.type == 1
輸出格式：json

保存配置：

{
  "name": "https-monitoring",
  "description": "監控HTTPS流量",
  "captureFilter": "port 443",
  "displayFilter": "tls.handshake.type == 1",
  "outputFormat": "json",
  "timeout": 60,
  "interface": "en0"
}

開發

項目結構

SharkMCP/
├── src/
│   ├── index.ts              # 主服務器設置
│   ├── types.ts              # TypeScript接口
│   ├── utils.ts              # 實用函數
│   └── tools/                # 單個工具實現
│       ├── start-capture-session.ts
│       ├── stop-capture-session.ts
│       ├── analyze-pcap-file.ts
│       └── manage-config.ts
├── test/                     # 測試文件
│   └── integration.test.js   # 集成測試
├── package.json
└── README.md

開發命令

# 開發模式，自動重新加載
pnpm run dev

# 生產環境構建
pnpm run build

# 運行測試
pnpm run test

# 類型檢查
pnpm run build

安全注意事項

• 網絡權限：數據包捕獲需要提升的權限。
• 文件訪問：臨時文件會在 /tmp/ 中創建。
• Docker安全：容器以非root用戶身份運行。
• SSL密鑰日誌：敏感的SSL密鑰應安全處理。

故障排除

常見問題

“tshark未找到”：

• 確保已安裝Wireshark，並且tshark在PATH中。
• 使用 tshark -v 檢查安裝情況。

數據包捕獲權限被拒絕：

• 在Linux上：將用戶添加到 wireshark 組或使用 sudo 運行。
• 在macOS上：在系統偏好設置中授予終端網絡訪問權限。
• 在Windows上：以管理員身份運行。

未捕獲到數據包：

• 驗證網絡接口名稱（Linux上使用 ip link，macOS上使用 ifconfig）。
• 檢查捕獲過濾器語法。
• 確保接口上有流量。

貢獻代碼（非常歡迎！）

1. 分叉倉庫
2. 創建功能分支
3. 按照現有代碼風格進行更改
4. 為新功能添加測試
5. 提交拉取請求

📄 許可證

本項目採用MIT許可證。

問題反饋與建議

如果您有任何問題或建議，請隨時創建一個issue。