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流量。
• 可重複使用的配置：可以保存和重複使用捕獲/分析配置。

⚠️ 重要提示

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

📦 安裝指南

克隆倉庫

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

安裝依賴

pnpm install

構建項目

pnpm run build

運行服務器

pnpm start

💻 使用示例

可用工具

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

基礎用法

啟動捕獲會話

接口: en0
捕獲過濾器: port 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提供了一個簡單的、專注於本地開發的架構：

┌─────────────────────────────────────────────────────────┐
│                    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服務器。

測試

SharkMCP包含全面的集成測試，用於驗證數據包捕獲功能。

運行測試

# 運行所有測試
pnpm test

開發

項目結構

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 not found”：
  • 確保Wireshark已安裝，且tshark在PATH中。
  • 使用 tshark -v 檢查安裝情況。
• 數據包捕獲權限被拒絕：
  • 在Linux上：將用戶添加到 wireshark 組或使用 sudo 運行。
  • 在macOS上：在系統偏好設置中授予終端網絡訪問權限。
  • 在Windows上：以管理員身份運行。
• 未捕獲到數據包：
  • 驗證網絡接口名稱（Linux上使用 ip link，macOS上使用 ifconfig）。
  • 檢查捕獲過濾器語法。
  • 確保接口上有流量。

🔧 技術細節

SharkMCP通過集成Wireshark/tshark實現網絡數據包的捕獲和分析。其架構分為MCP協議層、tshark集成層和主機系統集成層。MCP協議層提供了啟動和停止捕獲會話、分析PCAP文件以及管理配置等功能。tshark集成層負責跨平臺可執行文件檢測、進程管理和輸出解析。主機系統集成層則處理本地tshark安裝、直接網絡接口訪問和原生文件系統操作。通過這種分層架構，SharkMCP能夠在不同的操作系統上穩定運行，並提供靈活的數據包分析功能。

📄 許可證

本項目採用MIT許可證。

貢獻

非常歡迎大家為項目做出貢獻！貢獻步驟如下：

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

問題與建議

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