dfir-pcap-mcp

网络流量事件响应与取证 MCP 服务器。基于 tshark（Wireshark CLI）对 pcap 做只读优先的威胁检测与取证分析，供 AI Agent（Claude Code / opencode / Codex 等 MCP 客户端）在 IR 场景下一键调用。

纯 IR 定位，只读优先，底层依赖 tshark（Wireshark CLI），检测以统计特征为主，即使 HTTPS 加密流量也可靠。

作者 / Author： bae

特性

• 只读优先：永不修改原始 pcap；所有操作在会话副本 / 流式读取上进行。

• 18 个 MCP 工具：从会话管理、快速分级、威胁狩猎到流重组、解密、批量报告。

• 数据驱动检测：签名 / 指纹 / 恶意域名以 JSON / TXT 存放于 data/，运维可直接改、可扩展。

• 跨 tshark 构建兼容：字段名漂移由 FIELD_MAP + 字段缓存治理，并支持 Zeek 后端降级。

• 安全护栏：tshark 参数硬白名单 + 路径 jail（realpath + commonpath 校验）+ 无 shell 调用 + 错误不泄露 traceback。

• 可移植 tshark：TSHARK_PATH > PATH > 项目内 bin/tshark/ > 常见安装位置。

Related MCP server: Wireshark MCP

架构

分层清晰，单一职责：

tools/       每工具一文件，只做「取参数 → 取会话 → 调 service → 格式化」
   ↓
services/    重活：tshark 调用、解析、解密、编排、检测算法
   ↓
core/        安全（tshark 白名单 / 路径 jail）、格式化、会话、ATT&CK 映射
   ↓
config.py    全局配置（环境变量注入，不硬编码绝对路径）
data/        签名 / 指纹 / 提示词（源码数据，随仓库提交）

检测能力 = services/analytics.py 的 10 个统计/行为检测器 + services/investigate.py 的 2 个漏洞利用链检测器（共 12 个）。其中 4 个统计检测器有独立工具入口，其余由编排器（hunt_threats / analyze_pcap / triage / ir_analyze_all）按需调用：

安装

要求 Python ≥ 3.10，且系统已安装 Wireshark / tshark。

git clone <your-repo-url> dfir-pcap-mcp
cd dfir-pcap-mcp
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate
pip install -e .

tshark 获取（三选一）

1. 安装 Wireshark 并确保 tshark 在 PATH 中；

2. 或设置环境变量 TSHARK_PATH 指向 tshark 可执行文件；

3. 或直接使用项目内 bin/tshark/（已通过 Git LFS 随仓库分发，克隆时自动拉取 tshark 及其依赖 DLL）。

配置（环境变量）

其余运行参数（exec_timeout=300s、max_packets=200000、session_ttl=3600s、max_filter_len=2000、max_fields=40）为代码默认值，可按需在 dfir_pcap_mcp/config.py 的 Settings 中调整。

MCP 接入

在 MCP 客户端的配置文件（如 WorkBuddy 的 mcp.json、Claude 的 claude_desktop_config.json）中加入：

{
  "mcpServers": {
    "dfir-pcap-mcp": {
      "command": "python",
      "args": ["-m", "dfir_pcap_mcp"],
      "cwd": "/abs/path/to/dfir-pcap-mcp",
      "env": {
        "TSHARK_PATH": "/usr/bin/tshark",
        "DFIR_WORKDIR": "/abs/path/to/your/pcaps"
      }
    }
  }
}

用 python -m dfir_pcap_mcp + cwd 指向仓库根，避免硬编码虚拟环境路径，他人克隆后即可直接用。 若 tshark 已在 PATH 中，可省略 env 段。

也可直接运行入口：

python -m dfir_pcap_mcp        # 等价于 server.py

工具清单（18 个）

安全护栏

• tshark 参数白名单：仅允许安全字段 -r -Y -T -e -z -q -c --export-objects -o -d -V -O -l -n -J -j，且 -o / -d 取值经二次校验；禁止任意参数注入。

• 路径 jail：标准 per-pcap 工具的所有路径经 realpath + commonpath 校验（core.security.safe_path），杜绝目录穿越（../、符号链接、NTFS 流）。

• 例外：ir_analyze_all 操作的是用户显式指定的告警研判目录，按设计不强加路径 jail（目录本身由用户控制）。

• 无 shell 调用：subprocess 列表式调用，shell=False，避免命令注入。

• 不泄露内部错误：异常统一被 core.decorators.protect 捕获，返回结构化错误信封，不含 traceback。

• 只读优先：不写回、不改动原始取证文件。

开发 / 测试

pip install -e ".[dev]"      # 或直接 pip install pytest openpyxl
pytest                        # 87 个测试用例

测试覆盖会话管理、字段映射、检测器、护栏（路径 jail / 参数白名单）等。

扩展检测

• 签名 / 指纹 / 恶意域名：直接编辑 data/signatures/、data/fingerprints/、data/signatures/bad_domains.txt，无需改代码。

• 新检测器：在 services/analytics.py 或 services/investigate.py 中实现 detect_* / _exploit_*，由编排器 investigate() 调用。

• 提示词：data/prompts/ 下的分析报告模板可按需微调。

文档

• INDEX.md — 项目结构索引（目录树 / 工具 / 检测器 / 依赖 / 测试 / LOC）。

• docs/OPENSOURCE_AUDIT.md — 开源就绪报告（发布前就绪状态与已知项）。

License

MIT © 2026 dfir-pcap-mcp contributors