Backend

Backend Documentation

Table of Contents

• Overview
• Features
• Requirements
• Usage
• Output Structure
• HTTP Service Mode
• Crypt tab / 802.11 (Wi-Fi) decryption
• Searchable Attributes
• Notes
• License
• Author

Overview

PacketSnitch is a Python tool for extracting payloads and rich metadata from network packet capture (.pcap) files. It generates testcases for fuzzing, protocol analysis, and research by saving raw packet data and detailed information about each packet, including protocol, entropy, geoip, banners, and more. The tool optionally performs active reconnaissance to enrich output with server banners, SSL certificate info, and web page titles.

In the desktop app, this parser is wrapped by an Electron bridge that can either spawn the backend per capture run or launch snitch.py in HTTP service mode and stream incremental results to the renderer.

Features

• Extracts TCP, UDP, ICMP, ICMPv6, and SCTP payloads from .pcap files (over IPv4 and IPv6) and saves them as binary testcase files.
• Generates JSON info files for each testcase, containing:
  • Packet metadata (timestamps, MAC/IP addresses, ports, flags, checksums)
  • MIME type and magic description
  • Shannon entropy and character statistics
  • GeoIP lookup for source/destination IPs
  • Port descriptions (ICANN database)
  • MAC vendor lookup
  • Protocol-specific fields for link/WAN (ARP/RARP/PPP families, IEEE 802.11 / Wi-Fi), network (IPv4 and IPv6, ICMP/ICMPv6/IGMP), transport (TCP/UDP/SCTP), and application protocols including DNS, HTTP/HTTP2, SNMP, DHCP, DHCPv6, NTP, SIP, FTP, SMTP, POP3, IMAP, Telnet, IRC, SMB, MQTT, RTSP, TFTP, BGP, XMPP, LDAP, MySQL, PostgreSQL, NNTP, MTP/MMS, RADIUS, WebSocket, NFS, Kerberos, SSH, SMPP, Soulseek, and BitTorrent
  • Active recon: server banners, SSL certificate info, web page titles (optional)
  • IEEE 802.11 (Wi-Fi) link-layer metadata and decryption — the wireless_80211.py decoder surfaces SSID, BSSID, frame type/subtype, channel, cipher, RSN/IE info, and RadioTap signal/noise/rate on every 802.11 frame, and decrypts WEP / WPA-PSK (AES-CCMP) / pre-computed PMK payloads when the renderer supplies matching keys via the --wifi-keys-file flag. See the Crypt tab / 802.11 (Wi-Fi) decryption section below for the full contract.
• Consolidates all testcase info into hosts.json.
• Supports incremental chunk snapshots (hosts-<N>.json) for progressive frontend loading.
• Supports an HTTP service mode used by the Electron bridge for status/stats, ping, version, process, and control requests.
• Supports filtering by source/destination port.
• Handles compressed payloads (gzip/zlib).
• Verbose/debug output modes.

Requirements

• Python 3.7+
• Dependencies:
  • scapy
  • numpy
  • requests
  • pyyaml
  • python-magic
  • chardet
  • geoip2
  • beautifulsoup4
  • scipy
• Databases:
  • GeoIP database (MaxMind .mmdb)
  • MAC vendor CSV
  • ICANN port description CSV

Usage

python3 snitch.py traffic.pcap -o output_dir [-s SRC_PORT] [-d DST_PORT] [-T TIMEOUT] [-a] [-c conf.yaml] [--host-chunk-size N] [--worker-threads N] [--server --server-host HOST --server-port PORT] [-v]

python3 snitch.py --version

Arguments

Example

python3 snitch.py traffic.pcap -o output_dir -T 5 -a -v

Output Structure

• output_dir/<dest_port>/pcap.data_packet.<index>.dat: Raw payloads
• output_dir/<dest_port>/pcap.info_packet.<index>.json: Metadata for each testcase
• hosts.json: Consolidated info for all testcases
• hosts-<N>.json: Progressive chunk snapshots emitted during long capture processing for the desktop bridge/UI

HTTP Service Mode

When the Electron bridge has access to the Python backend, it can request long-lived HTTP service mode instead of spawning a fresh process for each capture.

Current bridge-facing endpoints:

• GET / and GET /status: backend runtime status/statistics payload (uptime, runtime config, active job metadata)
• GET /ping: readiness probe used before capture work is submitted
• GET /version: reports backend service/app version metadata
• POST /process: parse a PCAP and emit either accumulated JSON or NDJSON progress events
• POST /control: control actions such as stop-processing, shutdown, and runtime config updates (set-runtime-config/set-config/configure)

Lookup/enrichment endpoints used by frontend tooling (including Conv Analyze Subnet):

• GET /geoip?ip=<addr>&side=src|dst: GeoIP lookup
• GET /whois?ip=<addr>: WHOIS lookup
• GET /ipsum?ip=<addr>: IP reputation lookup
• GET /tor?ip=<addr>: Tor exit-node presence lookup
• GET /shodan?ip=<addr>: Shodan InternetDB lookup

Important behavior:

• Progress events may include filesystem snapshot paths or full in-memory capture payloads.
• NDJSON mode is used for incremental progress streaming.
• If service mode is unavailable, the Electron bridge falls back to legacy spawn mode.

Crypt tab / 802.11 (Wi-Fi) decryption

The backend ships an end-to-end 802.11 frame decoder and decryptor in src/backend/decoders/wireless_80211.py (with the WPA2 4-way PTK derivation in src/backend/decoders/wpa2_ptk.py). The frontend surfaces it as the Crypt → Wireless sub-tab; the backend contract is documented here so both halves of the round-trip stay in sync.

Decoder responsibilities

• Frame recognition: auto-detects Dot11 / RadioTap frames, walks management (Beacon, Probe Req/Resp, Auth, Assoc Req/Resp, Reassoc, Disassoc, Deauth, Action), control (RTS, CTS, ACK, Block Ack, PS-Poll, CF-End), and data sub-types. A4 / QoS / ToDS / FromDS layout is resolved to recover BSSID, source MAC (SA), destination MAC (DA), and station MAC.
• Metadata: every 802.11 frame populates the link.proto = "IEEE 802.11" field plus a Wireless sub-section (see the 802.11 fields table below).
• Decryption candidates: the decoder recognises Dot11CCMP, Dot11TKIP, Dot11WEP, and the generic Dot11Encrypted layers and tries each path in turn with the active Wi-Fi key set.

Key delivery (--wifi-keys-file)

Keys are pushed in by the renderer’s setBackendWifiKeys IPC, which stages them on disk in testcaseOutputDir/wifi-keys-<jobId>.json (a sibling of the per-job jobOutputDir so the spawn-path fs.rmSync(jobOutputDir) cleanup cannot drop the file mid-run). The file is removed in the bridge’s backendProc.on('close', ...) handler. The CLI / spawn argv is:

python3 snitch.py traffic.pcap -o output_dir --wifi-keys-file <path>

The file is a JSON array; each element is one candidate key. At least one of psk, pmkHex, or wepKeyHex must be set; ssid and bssid are optional filters and can be omitted for “try this key against every frame”:

[
  {
    "ssid": "Coherer",
    "bssid": "00:0c:41:82:b2:55",
    "psk": "Induction"
  },
  {
    "bssid": "c0:4a:00:80:76:e4",
    "wepKeyHex": "A48153B4CF"
  },
  {
    "ssid": "Lab-5G",
    "bssid": "aa:bb:cc:dd:ee:ff",
    "pmkHex": "a288fcf0caaacda9a9f58633ff35e8992a01d9c10ba5e02efdf8cb5d730ce7bc"
  }
]

WPA2 / AES-CCMP decryption

• The backend scans every EAPOL-Key frame once via populateWifiHandshakeCache and buckets the captured (ANonce, SNonce) pairs by (BSSID, client MAC). ToDS / FromDS / WDS addressing is resolved per IEEE 802.11 §9.3.2.1.
• The cache is then queried with the data frame’s (BSSID, client MAC) tuple. When both nonces are present and a psk / pmkHex entry exists for the BSSID, populatePtkForBssid derives the 64-byte PTK per IEEE 802.11i §8.5.1.1 (PRF-384 over the six-field canonical input Min(AA,SA) || Max(AA,SA) || Min(ANonce,SNonce) || Max(ANonce,SNonce) || BSSID || ANonce) and stores the TK portion.
• The CCMP frame is then decrypted using the same per-block AES-CCM primitive that airdecap-ng uses (manual RFC 3610 implementation so the output is byte-compatible with Wireshark). AAD layout, PN endianness, and CTR counter construction all match the airdecap-ng / libnl80211 reference.
• When a frame decrypts successfully, the inner LLC/SNAP+IP packet is spliced back into the regular packet loop and re-decoded as if it had been a normal Ethernet/IP frame. The host loop’s link.proto for that packet becomes "IEEE 802.11", the source/destination MAC addresses are added to link.src.mac.addr / link.dst.mac.addr, the wireless metadata is included under Wireless, and wifi.decrypt.ok = true plus wifi.decrypt.algorithm = "CCMP" are set. Link-layer protocol names (WIFI, IEEE 802.11, …) are never prepended to packet.decoded_protocols so the renderer’s App Protocol column always reports the real application-layer protocol of the decrypted payload.

WEP decryption

• _wepDecrypt(weKey, wepBody) takes the raw WEP body (3-byte IV + 1-byte KeyID + ciphertext + 4-byte ICV) and RC4-decrypts it. The decryptor pulls ARC4 from cryptography.hazmat.decrepit.ciphers.algorithms (with a fallback to the legacy cryptography.hazmat.primitives.ciphers.algorithms path so the code keeps working on cryptography < 43).
• The WEP ICV (CRC-32 of the plaintext, little-endian) is verified leniently — real WEP pcaps in the wild often have a corrupt or zeroed ICV, so the ICV is reported (icv_ok) but not used to gate the verdict. The “ok” verdict instead comes from _wepPlaintextLooksValid, which requires the plaintext to look like an 802.2 LLC / SNAP header (DSAP=0xAA SSAP=0xAA Control=0x03, I/G and C/R bits stripped) plus an IANA-assigned EtherType, or a raw Ethernet-II header with a known EtherType. A wrong key therefore never produces a false positive.
• When scapy’s Dot11WEP layer is not present but the FC protected bit is set, the WEP body is sliced out of the raw frame using the 802.11 MAC header length (24 bytes for non-QoS, 26 for QoS, 30 for 4-address ToDS+FromDS frames).

Decryption status attributes

Every 802.11 frame that was a decryption candidate (CCMP / TKIP / WEP / generic Dot11Encrypted) carries the following attributes in packet.info so the renderer can render a per-frame decrypt status pill:

End-to-end decrypt result shape

decryptWifiPayload returns the same dict shape for every algorithm so the renderer’s crypt-wifi-decrypt-preview / Send to Conv path can be algorithm-agnostic:

{
  "ok": true,
  "plaintextHex": "aaaa03000000080045000054...",
  "algorithm": "CCMP",
  "ssid": "Coherer",
  "bssid": "00:0c:41:82:b2:55"
}

Sample captures

The repo ships two ready-to-use Wi-Fi captures for end-to-end smoke testing:

Searchable Attributes

Each testcase JSON contains the following dot-notation keys as leaf nodes, which can be used to search, filter, or query testcase data in the frontend or via hosts.json. The filter syntax uses key:value notation with optional comparison operators (==, !=, >, >=, <, <=) and boolean combinators (&&, ||) with parentheses for grouping.

Core Packet Fields

Ethernet Fields

Note: Ethernet frame attributes (ether.*) are only populated when both source and destination IPs resolve to the local network.

IP Fields

IPv6 Address Fields

IPv6 packets share the same IP JSON section as IPv4 packets. The parser detects IPv6 via packet.haslayer("IPv6") and writes the same ip.src.addr / ip.dst.addr / ip.chksum / ip.len keys, distinguishing the family with network.proto. There is no separate ip6.* prefix at the JSON level — the ip.* keys are reused so a filter expression such as ip.src.addr:2001:db8::1 works for both families.

TCP Fields

UDP Fields

ICMP Fields

Wire / Payload Fields

GeoIP / Location Fields

Note: GeoIP attributes (loc.*) are only populated for non-private/routable IP addresses.

Active Recon Fields

Note: host.banner is only populated when the -a (active recon) flag is used.

DNS Fields (UDP/TCP port 53)

HTTP Fields (TCP port 80/443/8080/8443)

SNMP Fields (UDP/TCP port 161/162)

DHCP Fields (UDP port 67/68)

DHCPv6 Fields (UDP port 546/547)

DHCPv6 is parsed by the same Conv decoder family as DHCPv4 and is exposed in the frontend’s Conv → Decodes sub-tab. The dot-notation keys below are populated by the backend’s dhcp decoder when the conversation runs on UDP/546 or UDP/547.

NTP Fields (UDP port 123)

SIP Fields (UDP/TCP port 5060/5061)

IEEE 802.11 (Wi-Fi) Fields

The following dot-notation keys are populated for every IEEE 802.11 frame detected in the capture. Decryption-related fields are only present on frames that were decryption candidates (CCMP / TKIP / WEP / generic Dot11Encrypted); see the Crypt tab / 802.11 (Wi-Fi) decryption section above for the algorithm-specific contracts.

IPv6 Support

The backend parses IPv6 end-to-end. IPv6 packets populate the standard ip.*, tcp.*, udp.*, and icmp.* fields where the transport protocol is the same, and the network section is disambiguated with network.proto. The contract is:

• Network-layer detection — getPacketNetworkLayer(p) returns the IPv6 layer when present (and falls back to IPv4 when not). network.proto is set to "IPv6" for IPv6 packets and stays "IPv4" for IPv4 packets, so the renderer’s App Protocol column produces accurate groupings.
• Class label — getNetclass(ip) returns "IPv6" for IPv6 addresses (no IPv4 class mapping) and the standard IPv4 class labels (Localnet, A, B, C, D, E) for IPv4. The result is written to ip.src.class / ip.dst.class.
• IPv6 protocol number — getPacketNetworkProtocolNumber(networkLayer) reads the IPv6 nh (next header) field. The numeric value is propagated into the ip.proto.num attribute and the wire protocol number is used to drive transport dispatch (TCP=6, UDP=17, ICMPv6=58).
• ICMPv6 — the existing ICMP decoder is reused for ICMPv6 because the wire and field names match (icmp.type, icmp.code, icmp.chksum, icmp.id, icmp.seq). ICMPv6 packets are reachable on ip.proto.num == 58 and the regular auto-detect heuristic correctly maps them to the ICMP decoder.
• Extract path — TCP/UDP/ICMP extraction works over IPv6 because buildFallbackPacketEntry uses getPacketNetworkLayer(p) to discover the source/destination. The ip.src.addr / ip.dst.addr keys are populated with the IPv6 address verbatim (compressed form).
• Front-end handoff — the renderer receives the same ip.* keys for IPv4 and IPv6 packets, so the filter bar, the right-sidebar Datagram Frame, and the List panel all show IPv6 values without any per-protocol switch. network.proto is used to detect the family at display time.
• Lookup endpoints — /geoip, /whois, /tor, /shodan, and VirusTotal all accept IPv6 addresses. The response envelope always includes a version field (4 or 6) so the renderer can format the icon and CLI correctly. WHOIS responses for IPv6 reuse the v6prefix CIDR mechanism; Tor exit-list matching strips the optional […] brackets (_extractTorIpFromAddress).
• IPSum — explicitly IPv4-only. The /ipsum endpoint returns { "supported": false } for any IPv6 address, and the renderer’s Conv → Analyze Subnet disables the Use analyzed IP IPSum button when the address is IPv6.

IPv6-aware test cases

The IPv6 path is exercised end-to-end by the following backend tests, which build IPv6 packets at runtime via scapy.wrpcap and run them through the parser:

• tests/test_backend_json.py::test_packet_loop_decodes_ipv6_tcp_packet — verifies that an IPv6/TCP packet round-trips through packetLoop and produces IP.network.proto == "IPv6" with ip.src.addr / ip.dst.addr set to the IPv6 addresses.
• tests/test_backend_json.py::test_backend_fallback_preserves_ipv6_packet_protocol — checks the buildFallbackPacketEntry path preserves the IPv6 protocol label when the SUT falls back to the lighter decoder.

Notes

• Active recon (-a) may take longer and requires network access.
• Ensure database files are present and paths are correct in conf.yaml.
• The tool will prompt before overwriting output directories.
• LLM summaries are now handled by the Electron frontend/main-process bridge, not by the Python parser itself.

License

GPL v3

Author

Marshall Whittaker