Pcap Analyzer

日本語

An MCP server that lets an AI agent analyse packet captures.

Agents cannot work with pcap files, and wrapping tshark thinly does not help: tshark -V produces hundreds of lines for a single packet. pcap-analyzer-mcp runs a version-pinned tshark inside a container, mounts the capture read-only, and returns results in the response under explicit bounds, counting whatever they leave out — so an agent can narrow down a GB-scale capture step by step instead of drowning in its first response.

Status: v0.1.0. Twelve tools, driven end to end against a real container and validated from an MCP client. An independent security review has been through the tree. See known limitations.

Why a container

Pinning tshark at image build time solves three problems at once:

• Reproducibility — -T fields field names and -z statistic formats drift between tshark versions. The image fixes the version regardless of what is installed on the host, and every result records the tshark version and image digest that produced it.
• Isolation — Wireshark dissectors parse attacker-controlled data. The container runs with --network=none, as a non-root user, with all capabilities dropped.
• No accidental capture — the dumpcap binary is deleted from the image, which also has no network. Live capture is impossible by construction, not by policy.

The capture is never copied. Its directory is mounted read-only, so the original stays byte-identical — cheap for GB-scale files, and correct for evidence handling.

Requirements

• Podman (rootless; no daemon)
• macOS: podman machine start, 8GB VM memory recommended. The capture must live under a shared path (/Users, /private/tmp, /var/folders).

Install

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

The base image is pinned by digest, so the image never changes on its own. To take a Debian security update for tshark or a library it uses, rebuild it:

dist/pcap-analyzer-mcp build-runtime --force

Every build starts from scratch, without podman's layer cache, and upgrades the base image's own packages before installing tshark, so everything in the image comes from Debian's current archive. Through v0.6.2 a rebuild reused the cached layer and kept the old packages; rebuild once with v0.6.3 or later. The previous image stays behind untagged; podman image prune removes it.

Usage

Register the binary as an MCP server in your client:

{
  "mcpServers": {
    "pcap-analyzer": {
      "command": "/path/to/pcap-analyzer-mcp",
      "args": ["serve"]
    }
  }
}

A typical session: create a workspace for a capture, look at its metadata, find the interesting conversations, then narrow down with a display filter.

create_workspace(pcap_path, work_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, bounded and counted
follow_stream(workspace_id, ...)            →  the bytes on the wire
extract_objects(workspace_id, "http")       →  files, defanged, hashed

Every call also names work_dir: the absolute path of a directory you can read back, usually your session or working directory. The workspace is <work_dir>/<workspace_id>/, extracted objects are written there, and the pair (work_dir, workspace_id) is a workspace's whole address — this server keeps nothing across restarts. It is required and has no default.

A work_dir naming a system location, your home directory itself, a credential or agent-control location, or one of this server's own config directories is refused with work_dir_denied, subdirectories included, under any spelling (nlink-jp/pathguard makes that judgement). Those are ~/.config/pcap-analyzer-mcp and, when --config or PCAP_ANALYZER_MCP_CONFIG names a config file, the directory holding it — so give the config file a directory of its own rather than one you also work in.

The capture itself may live anywhere you can read; it is mounted read-only and never copied. The only refused locations are credential and agent-control directories such as ~/.ssh and ~/.aws, refused whether or not a file is there, with the same answer either way. Two spellings still get past it — a name in another Unicode normalisation and a hard link; the limits are listed in ADR-0010.

Tools

Tool	What it does
get_usage	Workspace model, output contract, error recovery
create_workspace	Open a capture. Records SHA-256, capinfos, tshark version
describe_workspace	Cached capture metadata — starts no container
list_workspaces	Enumerate workspaces under a work_dir
delete_workspace	Remove a workspace (dry_run available)
describe_runtime	Image digest, tshark version, supported object protocols
protocol_hierarchy	What protocols are in this capture
list_conversations	Endpoint pairs with byte counts and stream indices
query_packets	Display filter + field selection — the workhorse
follow_stream	Reassembled stream content, with ranged reads
extract_objects	Export HTTP / SMB / IMF / TFTP / FTP-DATA / DICOM objects
check_job	Progress and result of an async run

Heavy tools accept async: true and return a job_id; poll with check_job. A full pass over a large capture takes minutes and would otherwise hit the MCP client's request timeout.

Working with the output

Rows come back in the response, bounded by limit (rows) and by a byte budget (max_bytes). What the bounds leave out is reported — truncated, omitted_rows, and a note naming the bound that stopped it — and matched stays exact, so a bounded answer is still an answer about the whole capture.

This server does not write results to a file it chose. It cannot know the caller's context window, and an agent runtime that needs a large response on disk already puts it there. Narrowing down is this tool's job; if you want SQL over a packet table, narrow first and hand the rows to data-toolbox-mcp.

Every response reports matched (how many packets the filter hit) alongside returned, so it is always clear whether a filter needs tightening.

Handling untrusted captures

Captures under investigation are, by definition, attacker-influenced. Two consequences worth knowing about:

• Stream content is wrapped in nonce-tagged markers declaring it as data rather than instructions. This is a mitigation, not a guarantee.
• Extracted objects are defanged: saved as <sha256>.bin, never executable, never returned as inline bytes. The SHA-256 in the manifest is usually all you need to pivot to threat intelligence — you rarely have to touch the file at all.

Payload never reaches the log file, at any log level.

Configuration

Configuration is optional; every value has a working default. See config.example.toml.

The config file is looked for in this order, and the first one found wins:

1. --config <path>
2. PCAP_ANALYZER_MCP_CONFIG
3. ~/.config/pcap-analyzer-mcp/config.toml

A path you name in (1) or (2) that cannot be read is an error, because a typo there should not read as "use the defaults". (3) is consulted, not demanded: no file means the built-in defaults. The working directory is not searched — this server is started by an agent runtime that chooses its own cwd, so a ./config.toml would make the configuration depend on who launched it.

Documentation

• RFP — problem statement, scope, plan
• Architecture — trust boundaries, data flow, security model
• ADRs — every design decision and its cost
• Client setup — registering the server, and what to do when it misbehaves
• Tips — how to actually run an investigation: the shape of one, per-protocol filter recipes, and common snags
• Field notes — analysing captures that carry real malware: antivirus interference, the risk of AV exclusions, and the ftp-data limitation
• Sample captures — four synthetic captures and a graded walkthrough
• Phase 1 plan — tracks and open questions

License

MIT