nlink-jp/pcap-analyzer-mcp

# pcap-analyzer-mcp [日本語](README.ja.md) 一个允许 AI 代理分析数据包抓取的 MCP 服务器。 代理无法直接处理 pcap 文件，而简单地封装 tshark 也无济于事： `tshark -V` 为单个数据包生成数百行输出。`pcap-analyzer-mcp` 运行一个**在容器内版本锁定的 tshark**，以**只读**方式挂载抓包文件， 并在内联返回小体积结果的同时，将大体积结果作为 JSONL 写入到 工作区——从而让代理能够逐步缩小 GB 级抓包文件的分析范围， 而不是淹没在它的首次响应中。 ## 为什么使用容器 在镜像构建时锁定 tshark 版本可同时解决三个问题： - **可复现性** — `-T fields` 的字段名称和 `-z` 的统计格式 在不同 tshark 版本之间会发生变化。该镜像固定了版本，无论宿主机上安装了什么， 并且每个结果都会记录生成该结果的 tshark 版本和镜像摘要。 - **隔离性** — Wireshark 解析器会解析由攻击者控制的数据。 容器在 `--network=none` 下运行，以非 root 用户身份运行，并且丢弃了所有的 capabilities。 - **无意外抓包** — `dumpcap` 二进制文件已从镜像中删除， 并且没有网络。实时抓包在构建结构上是不可能的，而不是 依靠策略限制。 抓包文件**从不会被复制**。它的目录以只读方式挂载，因此 原始文件在字节层面保持完全一致——这对于 GB 级的文件既节省资源，又 确保证据处理的正确性。 ## 环境要求 - [Podman](https://podman.io/) (无根模式；无守护进程) - macOS: `podman machine start`，建议分配 8GB 虚拟机内存。抓包文件必须 位于共享路径下 (`/Users`, `/private/tmp`, `/var/folders`)。 ## 安装 ``` git clone https://github.com/nlink-jp/pcap-analyzer-mcp.git cd pcap-analyzer-mcp make build # → dist/pcap-analyzer-mcp make runtime-image # builds the tshark analysis image locally ``` ## 用法 在你的客户端中将该二进制文件注册为 MCP 服务器： ``` { "mcpServers": { "pcap-analyzer": { "command": "/path/to/pcap-analyzer-mcp", "args": ["serve"] } } } ``` 典型的工作流：为一个抓包文件创建工作区，查看其元数据， 找到感兴趣的会话，然后使用显示过滤器缩小范围。 ``` create_workspace(pcap_path, workspace_dir) → workspace_id, sha256, summary describe_workspace(workspace_id) → packet count, time range, snaplen list_conversations(workspace_id) → who talked to whom (+ stream index) query_packets(workspace_id, filter, fields) → rows inline, or a JSONL file follow_stream(workspace_id, ...) → the bytes on the wire extract_objects(workspace_id, "http") → files, defanged, hashed ``` ### 工具 | 工具 | 功能描述 | |---|---| | `get_usage` | 工作区模型、输出契约、错误恢复 | | `create_workspace` | 打开抓包文件。记录 SHA-256、`capinfos`、tshark 版本 | | `describe_workspace` | 缓存的抓包元数据 — 不启动容器 | | `list_workspaces` | 枚举 `workspace_dir` 下的工作区 | | `delete_workspace` | 删除工作区（支持 `dry_run`） | | `describe_runtime` | 镜像摘要、tshark 版本、支持的对象协议 | | `protocol_hierarchy` | 此抓包中包含哪些协议 | | `list_conversations` | 端点对及其字节计数和流索引 | | `query_packets` | 显示过滤器 + 字段选择 — 核心工具 | | `follow_stream` | 重组的流内容，支持范围读取 | | `extract_objects` | 导出 HTTP / SMB / IMF / TFTP / FTP-DATA / DICOM 对象 | | `check_job` | 异步运行的进度和结果 | 重型工具接受 `async: true` 并返回一个 `job_id`；可通过 `check_job` 进行轮询。 对大型抓包文件进行全面扫描需要几分钟时间，否则会触发 MCP 客户端的请求超时。 ### 处理输出 大型结果将写入为 **JSONL** 格式，可以通过 `head` / `grep` 读取， 也可直接由 DuckDB 加载——如果你需要对数据包表格执行 SQL， 甚至可以通过 [data-toolbox-mcp](https://github.com/nlink-jp/data-toolbox-mcp) 进行加载。缩小范围是本工具的职责；而聚合和 连接则是另一款工具的职责。 每次响应都会报告 `matched`（过滤器匹配到的数据包数量）以及 `returned`，从而让用户清楚地知道过滤器是否需要进一步收紧。 ## 处理不受信任的抓包文件 正在调查的抓包文件，顾名思义，是受到攻击者影响的。有两点 值得注意的后果： - **流内容被包裹**在使用 nonce 标记的标记符中，声明其为数据 而非指令。这是一种缓解措施，而非绝对保证。 - **提取的对象会被“缴械”**：保存为 `.bin`，绝不 可执行，绝不作为内联字节返回。清单中的 SHA-256 通常 足以用于关联威胁情报——你根本无需 触碰该文件。 任何日志级别下，数据负载都不会被写入日志文件。 ## 配置 配置是可选的；每个值都有可用的默认值。请参阅 [`config.example.toml`](config.example.toml)。传入 `--config ` 或设置 `PCAP_ANALYZER_MCP_CONFIG`。 ## 文档 - [RFP](docs/en/pcap-analyzer-mcp-rfp.md) — 问题陈述、范围和计划 - [架构](docs/en/reference/architecture.md) — 信任边界、数据流和安全模型 - [ADR](docs/en/adr/) — 每一项设计决策及其成本 - [客户端配置](docs/en/reference/client-setup.md) — 注册服务器，以及在其表现异常时的应对方法 - [提示](docs/en/reference/tips.md) — 如何实际进行调查：调查的形态、各协议的过滤方案及常见陷阱 - [实战笔记](docs/en/reference/field-notes.md) — 分析包含真实恶意软件的抓包文件：杀毒软件的干扰、AV 排除项的风险，以及 `ftp-data` 的限制 - [示例抓包](samples/README.md) — 四个合成抓包文件和分级演练 - [第一阶段计划](docs/en/reference/phase1-plan.md) — 任务轨道与开放性问题 ## 许可证 MIT

标签：AI代理工具, EVTX分析, MCP服务, NIDS, tshark, 容器化, 日志审计, 时序数据库, 网络协议分析, 防御绕过