dsct

dsct is a packet dissector CLI for LLMs and large captures.

It is built around two ideas:

• machine-readable output by default
• predictable memory use on big pcap / pcapng files

dsct read streams packet records as JSONL, dsct stats scans captures in a single pass, and the optional TUI opens large files with memory mapping and on-demand dissection instead of decoding the whole capture up front.

Why dsct

LLM-friendly by default

• dsct read emits JSONL packet records
• dsct stats, dsct list, dsct fields, dsct version, and dsct schema emit JSON
• errors, warnings, and progress updates are structured JSON on stderr
• capabilities and schemas can be discovered from the CLI itself

Works well on large captures

• read and stats process captures one packet at a time
• stdin is supported, so tcpdump -w - | dsct ... works naturally
• no human-oriented table parsing is required before automation can start

MCP server built in

dsct mcp starts a Model Context Protocol server over stdio. AI agents can call tools like dsct_read_packets and dsct_get_stats directly, without shelling out to the CLI.

Low-memory TUI for large files

The optional TUI is designed for large captures too:

• capture files are opened with memory-mapped I/O
• indexing starts from packet headers instead of fully decoding every packet
• packet list rows are dissected on demand for visible rows
• the selected packet is decoded in detail only when needed
• the hex view reads directly from the mapped file

Claude Code / Copilot CLI plugin

Install as a plugin via the marketplace to get the MCP server and the analyze-packets skill automatically:

Claude Code

claude plugin marketplace add higebu/dsct
claude plugin install dsct@dsct

GitHub Copilot CLI

copilot plugin marketplace add higebu/dsct
copilot plugin install dsct@dsct

Installation

CLI only:

cargo install --path .

With the optional TUI:

cargo install --path . --features tui

Quick start

Get a capture overview:

dsct stats capture.pcap

Read packets as JSONL:

dsct read capture.pcap

By default, dsct read outputs at most 1 000 packets. Use --count to change the limit or --no-limit to remove it:

dsct read capture.pcap --count 50
dsct read capture.pcap --no-limit

Filter packets:

dsct read capture.pcap -f dns --count 10
dsct read capture.pcap -f "dns AND dns.qr = 'Query'"

Filter expressions use SQL syntax with AND, OR, NOT, parentheses, and comparison operators (=, !=, >, <, >=, <=):

dsct read capture.pcap -f "dns OR (tcp AND ipv4.src = '10.0.0.1')"
dsct read capture.pcap -f "tcp.dst_port > 1024 AND NOT dns"

Sample evenly across the capture:

dsct read capture.pcap --sample-rate 100
dsct read capture.pcap -f dns --sample-rate 10 --count 50

Read from a pipe:

tcpdump -w - -c 1000 | dsct read -
tcpdump -w - -i eth0 udp port 53 | dsct read - -f dns

Inspect available fields and schemas:

dsct fields dns
dsct schema read

Open the TUI for a large file (when built with --features tui):

dsct tui capture.pcap

In the TUI, press ? to open the built-in help overlay and q to quit.

Typical workflow

# 1. Discover supported protocols
dsct list

# 2. Inspect available filter fields
dsct fields dns

# 3. Read matching packets as JSONL
dsct read capture.pcap -f "dns AND dns.qr = 'Query'" --count 20

# 4. Get capture-wide statistics
dsct stats capture.pcap --top-talkers

Commands

Run --help on any command for the full option list.

MCP tools

dsct mcp exposes the following tools over the Model Context Protocol:

Key parameters

dsct_read_packets: file (required), filter, count, offset, packet_number, decode_as, esp_sa, verbose

dsct_get_stats: file (required), protocol, top_talkers, stream_summary, top, decode_as, esp_sa

dsct_list_fields: protocol

dsct_get_schema: command ("read" or "stats")

Configuration example

Add dsct to your MCP client (e.g. Claude Desktop):

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

Default limits

When count is omitted, dsct_read_packets returns at most 1 000 packets (configurable via DSCT_MCP_DEFAULT_COUNT). dsct_get_stats processes the entire capture by default. All tool calls are subject to a per-execution timeout; on timeout the server returns a JSON-RPC error and no partial output is sent.

Environment variables

Resource limits can be tuned via environment variables:

Output

dsct read emits one JSON object per line:

{"number":1,"timestamp":"2024-01-15T10:30:00.123456Z","length":74,"original_length":74,"stack":"Ethernet:IPv4:UDP:DNS","layers":[{"protocol":"Ethernet","fields":{"dst_mac":"ff:ff:ff:ff:ff:ff","src_mac":"00:11:22:33:44:55","ethertype":"IPv4(2048)"}},{"protocol":"IPv4","fields":{"src":"10.0.0.1","dst":"10.0.0.2","protocol":"UDP(17)"}},{"protocol":"UDP","fields":{"src_port":12345,"dst_port":53}},{"protocol":"DNS","fields":{"id":4660,"qr":"Query","opcode":"QUERY(0)","questions":[{"name":"example.com","type":"A(1)","class":"IN(1)"}]}}]}

The other commands emit a single JSON object or array on stdout.

Supported protocols

The default build currently includes 50+ protocol dissectors across link, network, transport, tunneling, and application layers.

Use dsct list to see the exact protocol set in your build.

Errors

Errors and warnings are emitted as structured JSON on stderr.

Example:

{"error":{"code":"file_not_found","message":"failed to open capture file: test.pcap"}}

Exit codes:

License

Licensed under either of Apache License 2.0 or MIT License at your option.