@noorfatima123456/packet-chef-mcp

Zero-dependency, pure-JavaScript PCAP & PCAPng network forensics engine for AI agents.
Built for Claude Code, Cursor, Strix, and Windsurf, with dual-transport support (Local stdio & Cloud HTTP/SSE).

⚡ Why packet-chef-mcp v2.0?

Traditional network analysis utilities (tshark, libpcap, Python scapy) were designed for human network engineers, not autonomous AI agents:

1. They require heavy native toolchains and C bindings that frequently fail to compile or install on minimal Docker containers, serverless environments, or restricted cloud runners.

2. They dump hundreds of megabytes of raw hex and verbose protocol trees into agent context windows, causing massive context bloat and catastrophic token exhaustion.

packet-chef-mcp v2.0 is built from first principles as an AI-First Network Triage Sensor:

• Zero Native Dependencies: 100% pure Node.js Buffer arithmetic. Runs anywhere Node.js runs without root permissions.

• Strict Context Economy: Converts raw binary captures into compact, bounded (<2KB) JSON summaries and paginated views (default limit 20, maximum 100), preserving agent reasoning budget.

• High-Signal Threat Decoders: Focuses on the top 90% of cloud/web attack indicators: DNS exfiltration, HTTP verbs, TLS SNI, JA3/JA4 fingerprints, C2 beacon periodicity, WebSockets, and QUIC handshakes.

• Dual Transport Security: Local stdio mode permits local file analysis (filePath), while remote HTTP/SSE mode strictly blocks filesystem access, accepting only isolated Base64 streams (up to 10MB).

📋 Capabilities, Scope & Limitations Matrix

Related MCP server: Wireshark MCP Server

🚀 Quick Start

1. Run with npx (stdio mode)

Add to your AI agent harness configuration (e.g. Claude Code, Cursor, Windsurf, or Strix):

{
  "mcpServers": {
    "packet-chef": {
      "command": "npx",
      "args": ["-y", "@noorfatima123456/packet-chef-mcp@latest"]
    }
  }
}

2. Local Installation

git clone https://github.com/noorfatima123456/packet-chef-mcp.git
cd packet-chef-mcp
npm install
npm test

3. Running as Remote HTTP / SSE Server (Azure / Docker / Cloud)

# Launch on port 8080 (or specify PORT environment variable)
node server.js --http --port 8080

Accessible endpoints:

• GET / — Cyber-Dark status dashboard & interactive forensic sandbox

• GET /health — Health and liveness probe ({"status":"ok","tools":15})

• GET /.well-known/mcp/server-card.json — Model Context Protocol discovery metadata

• GET /sse — Server-Sent Events MCP endpoint

• POST /messages — JSON-RPC message gateway

🛠️ MCP Tools (15 Production Forensics Operations)

🛡️ Forensic Guardrails & Security

• Truth-in-Triage Coverage Envelope: Automatically reports inspectionCoverageRatio, uninspectedVolumeRatio, analyzedProtocols, and uninspectedCategories to eliminate silent false negatives for autonomous AI agents.

• HTTP/2 Fail-Fast Detection: Detects RFC 7540 client connection preface (PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n) and provides surgical native tshark command line strings.

• RFC 7692 WebSocket Compression Flagging: Identifies permessage-deflate and RSV1 bits, flagging compressed binary frames with explicit handoff recommendations to cyberchef_gunzip.

• IPv6 Extension Header 44 Fragment Guard: Parses fragment offset and flags continuation slices to suppress corrupt L4 payload parsing.

• Global Stream Memory Ceiling: Enforces a strict 32MB global ceiling across all concurrent reassembled TCP streams with proactive LRU eviction to prevent memory exhaustion under attack.

• PCAPng Auto-Detection: Seamlessly parses Section Header Blocks (0x0A0D0D0A), Interface Description Blocks (0x00000001), Enhanced Packet Blocks (0x00000006), and Simple Packet Blocks (0x00000003) with microsecond/nanosecond timestamps.

• Linux Cooked SLL (LinkType 113) Support: Captures created via tcpdump -i any are natively parsed without requiring tcprewrite normalization.

• Crash Hardening: Isolated try-catch boundaries per packet frame and verified with 100-round random fuzzing payloads to safeguard agent execution against corrupted captures.

• Dual Transport Guardrails: Council-certified security prevents Local File Inclusion (LFI). When running over remote HTTP/SSE, filesystem access via filePath is strictly blocked.

• Council Benign Infrastructure Tagging: Automatic recognition and down-ranking of legitimate cloud pulses (169.254.169.254 IMDS, NTP port 123, public resolvers) to prevent false alerts.

🧪 Testing

Run the comprehensive unit, integration, and fuzz test suite:

npm test

Test coverage includes 94 automated tests across 34 categories:

• Little-endian and Big-endian PCAP headers (microsecond & nanosecond)

• Native PCAPng block reader (SHB, IDB, EPB, SPB)

• Multi-Link Layer decoders (Ethernet II, Linux Cooked SLL 113, Loopback 0, Raw IP 12)

• 802.1Q single and 802.1ad QinQ double VLAN encapsulation

• Fragmented IPv4 packet detection & IPv6 RFC 5952 :: address zero-compression

• TCP flag decoding & UDP datagram validation

• Transport security (LFI prevention in HTTP mode)

• Full TCP stream reassembly (in-order, out-of-order, deduplication, overlapping segment trimming, state lifecycle tracking)

• RFC 1035 DNS parsing (A, AAAA, TXT records, label compression pointer resolution, loop protection)

• HTTP/1.x parsing (GET/POST, Content-Length, Chunked encoding, response statuses, body previews, automated forensic hints)

• TLS ClientHello SNI extraction and metadata parsing

• JA3, JA3S & JA4 TLS fingerprinting with RFC 8701 GREASE filtering and signature attribution

• RFC 6455 WebSocket frame unmasking and JSON payload decoding

• QUIC & HTTP/3 Initial Packet SNI extraction on UDP 443

• C2 beacon detection (Coefficient of Variation, jitter %, median interval, benign service tagging)

• DNS tunneling detection (Shannon character entropy, label lengths, hex/base32/base64 profiling, CDN filtering)

• Cleartext credential hunting (HTTP Basic, Digest, query params, POST bodies, FTP USER/PASS, SMTP AUTH)

• Shannon entropy payload randomness classification (0.0 to 8.0 bits/byte)

• Filtered PCAP binary generator (packet_filter_export)

• Standardized Zeek TSV log generator (packet_to_zeek_logs)

• Enterprise protocol triage banners (SMB, Kerberos handoff hints)

• RFC 791 IPv4 defragmentation engine

• Capture safety guardrails & truncation limits

• HTTP/2 connection preface detection & fail-fast triage

• RFC 7692 WebSocket compression flagging (permessage-deflate)

• IPv6 Extension Header 44 fragment guard

• Truth-in-Triage coverage envelope (inspectionCoverageRatio)

• Global 32MB stream buffer memory ceiling

• DNS-over-TCP 2-byte prefix handling (RFC 1035 §4.2.2 & RFC 7766)

• Mid-stream inverted capture orientation recovery (auto-detect request/response swap)

• Duplicate / retransmitted SYN stream sequence immunity

• Chained IPv6 extension header traversal (Hop-by-Hop, Routing, Destination Options)

• URLSearchParams & JSON multi-word credential extraction

• 100-round pseudo-random byte fuzzing (zero crashes)

📄 License

Apache-2.0 © 2026 Noor Fatima