Wireshark MCP Server

这是一个基于 Model Context Protocol (MCP) 的 Wireshark 流量分析服务器。它将强大的 Wireshark/Tshark 网络分析能力暴露给 AI 助手（如 Claude），使其能够直接进行网络数据包的抓取、解析、统计和安全分析。

🌟 核心功能

• 实时抓包与分析：直接调用 Tshark 进行实时流量捕获，支持 BPF 和显示过滤器。
• 离线 PCAP 分析：读取并深度解析 .pcap/.pcapng 文件，支持 SSL/TLS 解密（需提供 Keylog）。
• 深度协议解码：利用 Wireshark 强大的解码引擎，支持数千种网络协议的解析。
• 一键式自动化威胁扫描 (New)：
  • 提供 scan_network_threats 复合工具，单次调用即可自动完成“接口选择 -> 抓包 -> 分析 -> 查杀 -> 报告”全流程。
  • 无需人工干预，自动识别最佳网络接口。
  • 生成结构化的 Markdown 安全评估报告。
• 安全威胁检测：
  • 集成 AbuseIPDB 多源威胁情报。
  • 多 API Key 智能轮换：支持配置多个 API Key，自动轮换使用，大幅提升查询限额。
  • 三种轮换策略：智能（Smart）、轮询（Round Robin）、加权（Weighted）。
  • 自动速率限制检测与恢复，失败 Key 自动隔离与重试。
  • 多源情报聚合查询架构（支持扩展）。
  • 本地 LRU+TTL 缓存机制，减少 API 调用消耗。
  • 异步并发查询与增强的重试机制。
• 统计与可视化数据：提供协议分布、会话统计、端点统计、错误分析等宏观数据。
• 凭证提取：支持从 HTTP, FTP, SMTP, POP3, IMAP, LDAP, Telnet 流量中提取凭证。

📁 项目结构

Wireshark_mcp/
├── wireshark_mcp/
│   ├── threat_intel/       # 威胁情报核心模块
│   │   ├── core.py         # 聚合引擎与重试逻辑
│   │   ├── sources.py      # 情报源实现 (AbuseIPDB)
│   │   └── cache.py        # 本地 LRU+TTL 缓存
│   ├── tools/              # MCP 工具注册模块
│   ├── capture/            # 抓包功能 (实时/离线)
│   ├── analysis/           # 分析功能 (统计/会话/凭证)
│   ├── schemas/            # Pydantic 数据模型
│   ├── server.py           # 服务器入口
│   ├── config.py           # 配置管理 (Pydantic/YAML)
│   └── logging_config.py   # 日志配置
├── tests/                  # 测试组件
├── config.example.yaml     # 配置文件示例
├── requirements.txt        # 项目依赖
├── main.py                 # 程序入口
├── README.md               # 本文档
└── ...

🚀 快速开始

1. 安装 Wireshark / TShark（必需）

本项目依赖 TShark（Wireshark 的命令行版本）进行所有抓包和协议解析操作。

Windows 安装步骤

1. 下载 Wireshark: 访问 https://www.wireshark.org/download.html，下载 Windows 安装包。

2. 安装时勾选 TShark: 运行安装程序，在组件选择页面确保勾选了 TShark 组件（默认已勾选）。

3. 添加到系统 PATH:

   • 安装完成后，打开"系统属性" → "高级" → "环境变量"。
   • 在"系统变量"中找到 Path，点击"编辑"。
   • 添加 Wireshark 安装目录，通常为：C:\Program Files\Wireshark。
   • 保存并重启终端。

4. 验证安装: 打开 PowerShell，运行以下命令：

   tshark --version
   

   如果看到类似 TShark (Wireshark) 4.x.x 的版本信息，说明安装成功。

手动指定 TShark 路径（可选）

如果您不想修改系统 PATH，可以在 config.yaml 中直接指定 TShark 的完整路径：

wireshark:
  tshark_path: "C:\\Program Files\\Wireshark\\tshark.exe"

2. 安装 Python 依赖

确保您已安装 Python 3.10+，然后运行：

cd YOUR_PROJECT_PATH
pip install -r requirements.txt

3. 创建配置文件

复制示例配置文件：

copy config.example.yaml config.yaml

根据需要编辑 config.yaml，填入您的威胁情报 API Key（可选）。

4. 配置 Claude Desktop

编辑 Claude Desktop 配置文件：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "wireshark": {
      "command": "python",
      "args": [
        "YOUR_PROJECT_PATH/main.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

注意: 请将 YOUR_PROJECT_PATH 替换为实际项目路径（例如 C:\Users\YourName\Wireshark_mcp 或 /Users/YourName/Wireshark_mcp）。

5. 配置

1. 环境变量 (推荐，符合 MCP 标准)
2. 配置文件 (config.json)
3. 默认值

方法 A: MCP 客户端配置 (推荐)

在 Claude Desktop 配置文件中直接注入环境变量。

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "wireshark": {
      "command": "python",
      "args": [
        "YOUR_PROJECT_PATH/main.py",
        "--transport", "stdio"
      ],
      "env": {
        "THREATBOOK_API_KEY": "YOUR_API_KEY_HERE",
        "WIRESHARK_DEFAULT_INTERFACE": "1",
        "WIRESHARK_TSHARK_PATH": "tshark"
      }
    }
  }
}

配置字段说明：

• wireshark: 服务唯一标识符，您可以自定义此名称。
• command: 启动服务的可执行程序命令（如 python 或 uv）。
• args: 传递给启动命令的参数列表。
• 脚本路径: main.py 的绝对路径（请根据实际部署位置修改）。
• --transport stdio: 指定使用标准输入/输出作为通信信道（必须保留）。
• env: 注入到服务进程的环境变量（优先级最高）。
• THREATBOOK_API_KEY: 微步在线 API Key，用于威胁情报查询（单个Key）。
• WIRESHARK_DEFAULT_INTERFACE: 默认抓包网卡索引（建议使用数字索引以避免乱码）。
• WIRESHARK_TSHARK_PATH: tshark 可执行文件的路径或命令（默认 "tshark"）。

🆕 多 API Key 配置（提升使用量）

如果您有多个 API Key，可以通过配置文件实现智能轮换，大幅提升查询限额：

步骤 1：创建 config.json 文件（与 main.py 同目录）

{
  "threat_intel": {
    "threatbook_api_keys": [
      {
        "key": "YOUR_FIRST_API_KEY",
        "name": "primary",
        "enabled": true,
        "weight": 100
      },
      {
        "key": "YOUR_SECOND_API_KEY",
        "name": "secondary",
        "enabled": true,
        "weight": 80
      },
      {
        "key": "YOUR_THIRD_API_KEY",
        "name": "tertiary",
        "enabled": true,
        "weight": 60
      }
    ],
    "api_key_rotation": {
      "strategy": "smart",
      "failure_threshold": 3,
      "rate_limit_backoff": 3600,
      "health_check_interval": 300
    }
  },
  "wireshark": {
    "default_interface": "1",
    "min_version": "3.0.0",
    "tshark_path": "tshark"
  }
}

配置说明：

• threatbook_api_keys: API Key 列表
  • key: API Key 字符串
  • name: Key 的名称（用于日志和统计）
  • enabled: 是否启用该 Key
  • weight: 权重值（用于加权轮换策略）
• api_key_rotation: 轮换策略配置
  • strategy: 轮换策略（smart/round_robin/weighted）
  • failure_threshold: 连续失败次数阈值（超过则禁用）
  • rate_limit_backoff: 速率限制后的退避时间（秒）
  • health_check_interval: 健康检查间隔（秒）

步骤 2：更新 MCP 客户端配置（移除单个 API Key）

{
  "mcpServers": {
    "wireshark": {
      "command": "python",
      "args": [
        "YOUR_PROJECT_PATH/main.py",
        "--transport", "stdio"
      ],
      "env": {
        "WIRESHARK_DEFAULT_INTERFACE": "1",
        "WIRESHARK_TSHARK_PATH": "tshark"
      }
    }
  }
}

🛠️ MCP 工具列表

1. 基础工具

• verify_environment (New)

  • 功能：一键检查 TShark 环境、版本兼容性、API Key 状态及网络接口识别情况。
  • 用途：排查配置问题。

• list_interfaces

  • 功能：列出所有可用的网络接口及其索引。
  • 特性：输出包含智能推荐的最佳接口。

• get_protocols

  • 功能：获取 Wireshark 支持的所有协议列表。

2. 抓包工具

• capture_live

  • 功能：简易实时抓包。
  • 参数：interface (可选, 默认自动选择最佳接口), duration (秒), filter (BPF过滤), max_packets (最大包数)。
  • 特性：若不指定接口，工具会自动识别流量最活跃的物理网卡。

• capture_packets (高级)

  • 功能：高级实时抓包，支持 SSL Keylog 和 TLS 重组。
  • 参数：interface (可选, 默认自动选择), duration, bpf_filter (捕获前过滤), display_filter (捕获后过滤), limit, ssl_keylog_file (解密密钥文件路径), enable_reassembly (是否重组TCP流)。

3. 自动化与复合工具 (New)

• scan_network_threats
  • 功能：一键式网络威胁扫描与评估。
  • 流程：自动选择接口 -> 抓取实时流量 -> 提取公网 IP -> 查询威胁情报 -> 生成 Markdown 报告。
  • 参数：
    • duration: 扫描持续时间（秒，默认 30）。
    • max_packets: 最大分析包数（默认 1000）。
  • 用途：AI Agent 可直接调用此工具进行“自主安全审计”，无需分步操作。

4. 分析工具

• analyze_pcap

  • 功能：简易 PCAP 文件分析。
  • 参数：file_path, filter, max_packets.

• analyze_pcap_full (高级)

  • 功能：高级 PCAP 分析，支持解密和重组。
  • 参数：file_path, display_filter, limit, ssl_keylog_file, enable_reassembly.

• extract_fields

  • 功能：从 PCAP 文件中提取特定字段信息。
  • 参数：file_path, fields (列表), filter, max_packets.

• analyze_protocols

  • 功能：分析特定协议的数据包分布与详情。
  • 参数：file_path, protocol (如 "http"), max_packets.

• analyze_errors

  • 功能：分析数据包中的 TCP 错误（重传、乱序等）。
  • 参数：file_path, error_type (all/malformed/tcp/duplicate_ack/lost_segment).

5. 统计工具

• get_packet_statistics

  • 功能：获取 PCAP 文件的基础统计信息 (IO, 时间, 大小)。
  • 参数：file_path, filter.

• get_summary_stats

  • 功能：获取协议分层统计概览。
  • 参数：file_path, display_filter, limit.

• get_conversations

  • 功能：识别并统计 TCP/UDP 会话列表。
  • 参数：file_path, proto (tcp/udp).

6. 安全与情报工具

• check_ip_threats

  • 功能：查询单个 IP 的威胁情报（支持微步在线）。
  • 参数：ip.
  • 特性：自动缓存结果，支持失败重试。

• check_threats

  • 功能：批量扫描 PCAP 文件中的所有 IP，识别恶意主机。
  • 参数：file_path.
  • 特性：异步并发查询，快速生成报告。

• extract_credentials

  • 功能：从流量中提取明文凭证（HTTP Basic, FTP, SMTP 等）。
  • 参数：file_path, protocol, limit.

⚠️ 已知问题与解决方案

1. 接口名称乱码：

   • 现象：在中文 Windows 环境下，接口描述可能包含乱码。
   • 解决：工具已内置处理逻辑，但强烈建议在配置或参数中直接使用接口索引号（如 "1", "9" 等），不要使用中文名称。

2. TLS 重组参数警告：

   • 说明：旧版 tls.desegment_tls_records 参数已弃用。
   • 解决：新版代码已自动处理此参数，无需人工干预。

⚙️ 高级配置

项目支持通过 config.yaml 或 config.json 进行深度配置。详细配置项请参考 config.example.yaml。

主要配置项包括：

• threat_intel: 配置 ThreatBook, VirusTotal, AbuseIPDB 的 API Key 及轮换策略。
• wireshark: 设置默认网卡接口、TShark 路径。
• server: HTTP 服务器监听地址（仅 SSE 模式）。