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 frontend-driven LLM summaries and packet-context questions through the Electron main process. The frontend also includes a data conversion workspace (Conv), an encryption workspace (Crypt), an aggregate statistics view (Stats), an Internet Heatmap worldmap, 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 the current runtime LLM workflow before running. This checkbox is seeded from Settings → LLM → LLM active by default.

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/derive/decompress conversion values into Conv, follow bidirectional streams into Conv or Crypt, manage keystore entries, build filter expressions (including link/transport/application protocol filters), export packet/Conv outputs, interact with HTTP file bodies, and run LLM context actions. 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.

Recent behavior updates:

• The summary content now uses a preformatted text view for better readability of longer model output.
• Summary generation is stream-aware: when packet navigation settles, the frontend schedules a follow-up summary for the active stream after the configured idle delay and appends non-duplicate findings.
• LLM requests are issued through the Electron main process (ollama:generate IPC), which applies the configured model, bearer token, timeout, and token cap.
• Existing summary text is persisted in saved sessions and restored on load.

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, SIP) to attempt to parse the current conversion input bytes as that protocol and display a human-readable decoded view below.

The context menu can populate Conv from selected/context data, payload bytes, cursor ASCII, decompressed Conv input, HTTP body bytes, or full followed stream data. See context-menu.md for details.

Packet JSON Sub-tab

The Packet JSON sub-tab is just the full JSON structure that PacketSntich uses in memory to tell you about the packets. Every piece of information about a singular packet that the application is aware of, lives here. This pane is also Context Menu “context-aware”, meaning you can right click on an item in the JSON, and easily send it to other places within the PacketSnitch.

Note: If this data looks similar to the hosts.json data, it should, as that is where this data comes from, almost verbetum.

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

The PGP workspace is a fully implemented OpenPGP inspection and decrypt/verify tool.

Successful decrypt/verify operations can also store validated PGP private key/passphrase material into the session keystore for later reuse.

OpenSSH Sub-tab

Reserved workspace for future OpenSSH key and session tooling. For now, PacketSnitch can still recognize SSH/OpenSSH material in Conv decode/detection flows.

Settings Tab

The Settings tab is a persistent configuration workspace with four sub-tabs: General, LLM, Debug, and Backend.

Settings are stored locally at ~/.config/packetsnitch/config/settings.json (Linux) or C:\User\Username\AppData\Roaming\packetsnitch\config\settings.json (Windows).

General Sub-tab

Allowed backend chunk sizes are fixed to: 25, 100, 250, 500, 2000.

The Settings UI also shows the runtime themes directory path so custom theme JSON files can be dropped in place and loaded.

LLM Sub-tab

If the API key field is left blank when saving, the currently stored key is retained.

The LLM panel also exposes runtime diagnostics for local install status, daemon reachability, cloud API reachability, and the last call result code.

Debug Sub-tab

Backend Sub-tab

Actions

• Save settings: normalizes and persists General, LLM, Debug, and Backend values.
• Restore defaults: resets settings to app defaults.
• Theme changes are applied immediately after save.

Theme Engine Summary

• Themes are JSON files in packetsnitch/themes.
• Default bundled themes are mirrored there automatically on startup.
• Theme definitions provide CSS variable overrides and optional custom logo data.

See themes for complete theme schema, variable reference, logo setup, and opacity tuning.

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.

Internet Heatmap / Worldmap

The Stats tab also includes an Internet Heatmap worldmap view for public GeoIP locations.

Private/local addresses are intentionally excluded from the worldmap.

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.

LLM and Backend Bridge

Frontend LLM behavior now lives in the renderer and Electron main process rather than in the Python parser itself.

LLM Flow

• Renderer code decides when to call the model based on runtime settings and local Ollama availability.
• Requests are sent through window.llmapi.generate(...) to the Electron main-process ollama:generate IPC handler.
• The main process applies the configured model, optional bearer token, timeout, and num_predict token cap before calling the Ollama Node client.
• Failed requests can be retried automatically according to the configured retry count.
• LLM-backed features currently include the Summary view, stream-context follow-up summaries, and the Explain this Packet… context-menu submenu with Explain this data…, Ask PS a question…, and Summarize this packet….

Backend Bridge Modes

• HTTP service mode: initializes a long-lived backend service, probes GET /ping, posts capture work to POST /process, and sends control actions through POST /control.
• Service metadata can be queried through GET /version, and runtime parser settings can be updated through POST /control (set-runtime-config) without restarting the backend service.
• HTTP data mode: when enabled, the backend can stream NDJSON progress plus in-memory snapshot payloads back to the renderer.
• Legacy spawn mode: fallback per-run process launch path used when the service is unavailable or explicitly disabled.

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.

The Notes workspace also includes a sanitized live Markdown preview for the selected note, including GitHub-style pipe tables.

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.

The filter history dropdown merges session filter history with user-saved named filters. Right-clicking the filter input lets you save the current query with a label (or remove an exact saved match) via an in-app dialog.

Filter Examples

License

GPL v3

Author

Marshall Whittaker