pcaplens — read a pcap the way an LLM should

Summary first, evidence always. No tshark anywhere in sight.

中文说明

A packet-capture reader written for the two ways people actually consume a pcap today: a human triaging an incident, and a coding agent that has to fit the answer in a context window.

The core is standard-library only. No Wireshark, no tshark, no libpcap, no Npcap, no compiler. pip install pcaplens works on a locked-down Windows laptop with no network share and no admin rights.

Why this exists

Every popular "let your LLM read a pcap" project shells out to tshark. That is two problems wearing one coat:

1. It is not portable. tshark is a ~100 MB install and a PATH entry. On Windows that is where most readers stop.

2. It floods the context window. tshark -r x.pcap -V on a 10 MB capture produces tens of megabytes of text. Piped into an agent it either blows the limit or crowds out everything else the model was told.

So pcaplens does not dump. It hands back a map, then lets you drill in:

summary       ~30 lines: shape of the capture and what is worth looking at
conversations one line per flow, sorted by volume, with retransmit/RST flags
packet N      one frame, fully dissected, with byte offsets and a hexdump

Related MCP server: Wireshark-MCP

Quick start

pip install pcaplens

pcaplens demo traffic.pcap          # no capture handy? synthesise one
pcaplens summary traffic.pcap
pcaplens flows traffic.pcap
pcaplens packet traffic.pcap 10
pcaplens search traffic.pcap --text example.com

Nothing else to install. pcaplens demo writes a real pcap containing a TCP handshake, DNS, HTTP and a TLS ClientHello, so the whole feature set is reachable in one command from an empty directory.

What the output looks like

$ pcaplens summary traffic.pcap
file        : traffic.pcap
format      : pcap  link-layer: ethernet
packets     : 12   bytes: 1.1KB   duration: 2.00s   (6.0 pkt/s)

protocols (packets, bytes):
protocol  packets  bytes
--------  -------  -----
tcp       6        324B
http      3        442B
dns       2        158B
tls       1        152B

worth a look:
  - 10.0.0.2:52344 <-> 93.184.216.34:80: 1 retransmitted segment(s) (evidence: packet 3)
  - 10.0.0.2:52345 <-> 93.184.216.34:443: 1 SYN sent, no SYN/ACK seen (evidence: packet 9)
  - 10.0.0.2:52346 <-> 10.0.0.77:22: 1 SYN sent, no SYN/ACK seen (evidence: packet 11)

Every finding names the packet that supports it, so you can open that packet instead of trusting the summary:

$ pcaplens packet traffic.pcap 10
packet 10  152B  2.010000
  link      : ethernet (file offset 0x3d8)
  summary   : TLS ClientHello SNI=www.example.com TLS1.2

  layers (offset, length):
    ethernet           @0     len=14    ethertype=0x800
    ipv4               @14    len=20    src=10.0.0.2, dst=93.184.216.34, ttl=64, proto=tcp
    tcp                @34    len=20    src_port=52345, dst_port=443, flags=PSH,ACK
    tls-handshake      @54    len=98

  TLS client_hello version=TLS1.2
    SNI: www.example.com
    suites: 0x1301, 0x1302, 0xc02f

Let an AI agent drive it

pip install "pcaplens[mcp]"

{
  "mcpServers": {
    "pcaplens": {
      "command": "pcaplens",
      "args": ["mcp"]
    }
  }
}

Nine tools: pcap_summary, pcap_conversations, pcap_talkers, pcap_protocols, pcap_packet, pcap_search, pcap_dns, pcap_http, pcap_tls.

Each one follows the same discipline as the CLI: no raw dumps, every list is capped and says how many items it dropped, and every claim carries the packet number that proves it. An agent that cannot verify a claim will confabulate, and a confabulated packet analysis is worse than none.

Check what your agent would get without starting the server:

pcaplens mcp --check

What it parses

Parsing is deliberately conservative: a field that cannot be parsed becomes a note ("IPv4 fragment: ports below it may be absent") rather than a plausible guess.

Comparison

Install from source

git clone https://github.com/xuange-hu/pcaplens && cd pcaplens
pip install -e ".[mcp]"
PYTHONPATH=src pytest -q        # 62 tests
PYTHONPATH=src python -m pcaplens.cli demo demo.pcap

Limitations

Stated plainly, because guessing costs more:

• No TCP reassembly — HTTP is parsed per segment, so a large response split across segments shows up as "TCP" rather than "HTTP".

• No IP fragment reassembly; fragments are flagged, not glued.

• TLS is metadata only (SNI, versions, suites). Encrypted traffic is not and will not be decrypted.

• The heuristics are hints. unresolved_handshake means "no SYN/ACK was seen in this capture", which is not the same as "the host is down".

License

MIT — see LICENSE. Traffic in demo is synthesised locally by synth.py; no third-party capture is redistributed.