Frontend Documentation

Overview

The PacketSnitch frontend is an Electron-based desktop application that provides an interactive interface for loading, browsing, and filtering the JSON output produced by the backend (snitch.py). It visualizes packet metadata, payloads, protocol details, and GeoIP information, and supports LLM-powered analysis summaries. The frontend also includes a data conversion workspace (Conv), an encryption/certificate workspace (Crypt), an aggregate statistics view (Stats), a sortable packet list (List), an encrypted local key and credential store (Keystore), a session notes workspace (Notes), and a persistent activity log (Log).

Requirements

• NodeJS 16.4+
• Electron Forge 7.11+
• Dependencies:
  • electron-forge
  • webpack
  • fs-extra
  • electron-squirrel-startup
  • copy-webpack-plugin
  • ollama

Loading Data

1. Click Load JSON to open either a backend hosts.json capture or a previously saved PacketSnitch session file.
2. Click Load PCAP to run the backend directly on a .pcap file from within the app.
3. Toggle Use LLM to enable or disable Ollama-powered analysis summaries before running.

Output Frames

The PacketSnitch UI is divided into several panels that together provide a full view of each captured packet.

Left Sidebar

The left sidebar contains navigation controls and file metadata.

Toolbar / Tab Bar

The toolbar at the top of the content area contains navigation and view-switching controls.

When right-clicking in packet/data views, PacketSnitch shows a context menu with shortcuts to copy text and payload views, load convertible values into the Conv tab, manage keystore entries, build filter expressions, export data, and interact with HTTP file bodies. See context-menu.md for full details.

Summary Frame

The Summary Frame displays the LLM-generated analysis report for the loaded capture. This frame is shown by clicking the Summary button in the toolbar and is only populated when the backend was run with LLM support enabled (via conf.yaml).

Packet Info Pane

The Packet Info Pane is the main left-centre panel. It displays structured metadata for the currently selected packet, broken into several sub-sections.

IP-to-IP Routing

Displays source and destination IP addresses in a src → dst format for quick identification of the packet flow.

Network Information

Shows source and destination protocol/port details, including the ICANN service name and port description for the destination port.

Data Type List

Lists the detected MIME type, character set, content encoding, and magic-identified data types found in the payload.

Active Recon

Populated only when the backend was run with the -a (active recon) flag. Contains:

Packet Payload Pane

The Packet Payload Pane sits below/beside the Packet Info Pane and displays the raw payload bytes for the current packet.

ASCII View

Displays consecutive runs of printable ASCII characters extracted from the payload. Non-printable bytes are skipped, making it easy to spot human-readable strings embedded in binary data.

Hex Grid

An interactive hex dump of the full raw payload. Clicking a cell in the hex grid highlights the corresponding bytes and displays any printable ASCII sequence starting at that offset in the ASCII view.

Conv Tab (Data Conversion)

The Conv tab is a self-contained data conversion workspace accessible at any time by clicking Conv in the toolbar. It has three sub-tabs: Conversions, Hashes, and Decodes.

Conversions Sub-tab

Input

Converted Output

After clicking Convert, the following representations are shown simultaneously:

Data Insights

Hashes Sub-tab

The Hashes sub-tab computes cryptographic hash digests of any input text. Type or paste text into the Hashed Input field; hashes are computed automatically and displayed in read-only fields below.

The Hashed Input field accepts escape sequences (\n, \r, \t, \\, \xNN) so exact byte sequences can be hashed without pasting raw binary data. Clicking Convert on the Conversions sub-tab also populates the Hashed Input field automatically from the current conversion input bytes.

Decodes Sub-tab

The Decodes sub-tab is a protocol decoder. Select a protocol from the Protocol dropdown (Auto-detect, HTTP, Telnet, SSH / OpenSSH, POP3, IMAP, SMTP) to attempt to parse the current conversion input bytes as that protocol and display a human-readable decoded view below.

The context menu’s Convert to… options can automatically populate the Conv tab input from packet data or the current selection. See context-menu.md for details.

Crypt Tab (Encryption Workspace)

The Crypt tab provides a multi-panel workspace for inspecting cryptographic material encountered in a capture or loaded from files. It has three sub-tabs: SSL, PGP, and OpenSSH.

SSL Sub-tab

PGP Sub-tab

Reserved workspace for future PGP key import and decryption tooling.

OpenSSH Sub-tab

Reserved workspace for future OpenSSH key and session tooling.

Stats Tab

The Stats tab shows aggregate statistics computed across the entire loaded capture (all hosts, all packets). Statistics are presented as labelled tag-cloud sections. Clicking any tag pre-fills the filter bar with a suggested filter expression for that value.

List Tab

The List tab shows all packets across all hosts as a searchable, sortable table.

Search Bar

Columns

Click any column header to sort by that column; click again to reverse direction. Click any row to navigate to that packet in the Host Data view.

Keystore Tab (Local Keychain)

The Keystore tab provides a local encrypted credential store. It has two keychains: a Session keychain (in-memory only, reset when the app closes) and a Persistent keychain (encrypted with AES-GCM, stored in IndexedDB, and unlocked with a passphrase each session).

First-time setup

On first use, clicking Keystore or adding an entry to the persistent keychain opens the Set Keychain Password dialog. Enter and confirm a password (minimum 8 characters). This password encrypts all persistent entries; it is never stored in plain text.

On subsequent launches, the Unlock Keychain dialog prompts for the password before revealing persistent entries.

Create / Update Entry

Saved Entries

Auto-population

PacketSnitch automatically populates the Session keychain from packet data when a capture is loaded:

• HTTP form credential fields (usernames, passwords) extracted by the backend.
• Cookie/Set-Cookie header values extracted from HTTP payloads.

These auto-entries appear with a source of session-auto and can be promoted to the persistent keychain via Send to persistent.

Manual URI/URL Entry

The context menu’s Add to Keystore… → Manual URI options open a dialog to manually enter any http:// or https:// URL. The entered URL is saved as a url type entry in the selected keychain. Entries of this type can be opened directly in the system browser via Open link. See context-menu.md for more on keystore context menu options.

Notes Tab

The Notes tab is a session notes workspace for creating and editing freeform text notes tied to the current session. Click Notes in the toolbar to open it.

Notes Sidebar (right panel)

Notes Editor (main area)

The main content area shows a full-width editable text area for the currently selected note. Edits are reflected immediately in the notes list preview. The editor is disabled when no note is selected.

Notes Context Menu

Right-clicking in packet or Conv views while notes are active shows a Send to Notes… submenu. See context-menu.md for details on context menu items.

Notes are saved as part of the session file when Save Session is used.

Log Tab

Clicking Log in the toolbar toggles the Activity Log panel, which slides in from the bottom of the window. The log records all significant GUI actions, backend events, and console output with ISO 8601 timestamps.

Log Entry Formats

The log is written to a persistent log file on disk. The file path is shown at the top of the log panel.

Log Search

The Search log entries input filters the visible entries in real time (case-insensitive substring match). The log file on disk is not modified by the search.

Right Sidebar (Datagram Frame)

The right sidebar provides three contextual data panels that update with each packet.

Datagram Frame

A protocol-specific table of lower-level packet fields. The table content varies depending on the detected protocol:

Location

Displays a GeoIP table for the source and/or destination IP addresses, including country, city, postal code, and time zone. For local-network addresses, shows a Localnet indicator.

Payload Entropy

Visualizes the Shannon entropy of the payload as a numeric value and graphical indicator. High entropy typically indicates encrypted or compressed content; low entropy suggests plain text or structured data.

Filtering

Packets can be filtered using an expression in the filter bar. The syntax is:

attribute:value
attribute:value==<val>
attribute:value>=<val>

Multiple conditions can be combined using && (AND), || (OR), and parentheses for grouping:

ip.src.addr:192.168.1.1 && tcp.dst.port:443
(payload.mime:text/html || payload.mime:application/json) && payload.entropy>=4.0

Filter keys use the same dot-notation names as the searchable attributes documented in the Backend docs. Keys are normalized to lowercase with spaces replaced by hyphens.

Filter Examples

License

GPL v3

Author

Marshall Whittaker