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/ > 常见安装位置。

---

架构

分层清晰，单一职责：

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）按需调用：

检测器	位置	入口	说明
detect_beacons	analytics	工具 detect_beacon	C2 信标（周期性外联）
detect_dns_tunnel	analytics	工具 detect_dns_tunnel	DNS 隧道（长域名 / 高熵 / 大响应）
analyze_exfil	analytics	工具 analyze_exfil	外泄量分析（上传/下载体积异常）
detect_web_attacks	analytics	工具 detect_web_attacks	Web 攻击（含 Java 反序列化特征）
detect_suspicious_dns	analytics	编排器调用	可疑域名（恶意域名清单 + 算法生成域名）
detect_bruteforce	analytics	编排器调用	暴力破解（认证失败聚集）
detect_lateral_depth	analytics	编排器调用	横向移动深度（SMB/RDP/WinRM 跳板）
detect_tls_issues	analytics	编排器调用	TLS 指纹异常（JA3 / JA4 偏离基线）
detect_recon	analytics	编排器调用	侦察扫描（端口 / 主机扫描）
profile_hosts	analytics	编排器调用	主机画像（角色 / 服务 / 活跃度）
_exploit_log4j	investigate	工具 analyze_exploit	Log4j2 (CVE-2021-44228) 利用链
_exploit_shiro	investigate	工具 analyze_exploit	Apache Shiro 反序列化利用

---

安装

要求 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）。

---

配置（环境变量）

变量	作用	默认
TSHARK_PATH	显式指定 tshark 可执行文件路径	自动探测
DFIR_WORKDIR	pcap 工作目录（会话路径 jail 的根）	无限制（仍受路径穿越校验）

其余运行参数（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 个）

工具	说明
list_pcaps	列出工作区内的 pcap 文件
load_pcap	加载 pcap 建立会话（受路径 jail 约束）
close_session	关闭当前会话，释放资源
triage	快速分级：轻量概览，先判断是否需要深究
hunt_threats	威胁狩猎：多检测器编排，产出 findings + ATT&CK
extract_artifacts	提取凭据 / IOC / 可疑文件
follow_stream	重组 TCP/UDP 流并解码 HTTP 载荷
timeline	按时间线还原关键事件
detect_beacon	C2 信标检测
detect_dns_tunnel	DNS 隧道检测
analyze_exfil	外泄量分析（上传/下载体积异常）
detect_web_attacks	Web 攻击检测（含 Java 反序列化）
analyze_pcap	一键全套自动分析：编排器，单次调用跑完所有检测
decrypt_webshell	webshell 加密流量解密
analyze_exploit	漏洞利用分析（log4j2 / shiro）
ir_analyze_all	告警研判：解析目录下 xlsx 告警 + threat_event.csv，对匹配的前 2 个 pcap 跑全套检测并合并报告（需 openpyxl）
bigdata_query	大数据 / Zeek 后端查询
run_tshark	受限逃生舱：仅开放 display_filter / fields / limit，底层走白名单构造命令（不暴露任意 tshark 开关）

---

安全护栏

• 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