# 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**。

```bash
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](https://www.wireshark.org/) 并确保 `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`）中加入：

```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` 段。

也可直接运行入口：

```bash
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。
- **只读优先**：不写回、不改动原始取证文件。

---

## 开发 / 测试

```bash
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](./LICENSE) © 2026 dfir-pcap-mcp contributors