Frontend

Frontend Documentation

The PacketSnitch frontend is the Electron half of the app — the desktop UI that turns the backend’s protocol-aware packet intelligence into workspaces for browsing, filtering, converting, and investigating captures. It is what makes PacketSnitch a usable Wireshark alternative desktop app, and it hosts the optional LLM-powered network analysis flows via Ollama. The backend it talks to is documented in the backend documentation; the filter bar is covered by the filter reference. New here? See the decoder reference for modular protocol decoder authoring, the Features list, or the FAQ.

Table of Contents

• Overview
• Requirements
• Loading Data
• Output Frames
• Analysis / Summary Tab
• Host Data Tab
• Conv Tab
• Crypt Tab
• Artifacts Tab
• Notes Tab
• Settings Tab
• Stats Tab
• List Tab
• Compare Workspace
• Activity Log Tab
• Keyboard Shortcuts
• Filtering
• Protocol Decoders
• License
• Author

Overview

The PacketSnitch frontend is an Electron-based desktop application that provides an interactive interface for loading, browsing, and filtering capture data 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 Analysis, Host Data, Conv, Compare, Crypt, Artifacts, Stats, List, Notes, Settings, Help, and Activity Log workspaces.

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 (see the backend Output Structure) 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.
4. Once a capture finishes loading, PacketSnitch opens the workspace selected under Settings → General → Open after capture load (general.defaultTab) — Host Data, Stats (default), or List. A previously saved session still restores into its remembered tab; the preference only takes effect when there is no saved tab to fall back on.

The frontend is organized around persistent workspaces rather than a single packet view. Navigation between workspaces preserves the active capture, filter, packet cursor, comparison selections, notes, and investigation state. The Host Data, List, Stats, Compare, Conv, Crypt, Artifacts, Notes, Settings, and Log workspaces can be reached from the toolbar, context menus, or the keyboard shortcut system.

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, add artifacts, 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 for full details.

Compare Workspace

The Compare workspace has three subtabs:

• Captures compares the currently loaded capture state and provides the multi-source comparison overview.
• Sources compares capture sources across application, network/transport, link, decoded protocols, hosts, hostnames, locations, ports, MAC vendors, MIME types, data types, and traffic buckets. This is useful after loading or merging multiple captures to identify what changed between sources.
• Compare Packets compares the current Host Data packet with a candidate from the active filtered packet set. The current packet is Packet A; Packet B is selected from the candidate list.

Packet comparison supports:

• Same protocol only candidate filtering and candidate search by protocol, source, packet key, or index.
• Payload or full-frame byte comparison, including headers when frame bytes are available.
• Payload-only or headers-plus-payload decoded comparison scope.
• Independent Decoder A and Decoder B selections, including auto-detection.
• Field-by-field decoded comparison with changed values highlighted on both sides in the comparison table.
• Byte lengths, changed-byte counts, similarity, changed ranges, MD5, SHA-256, and SSDEEP-style similarity metrics.

Missing bytes, unavailable decoder results, incompatible protocols, and different field shapes are reported explicitly rather than being silently treated as equal. Navigating Host Data updates Packet A so the comparison always follows the packet currently under investigation.

Keyboard Shortcuts

Keyboard shortcuts are enabled by default and can be configured in Settings → Keyboard Shortcuts. The settings panel lets users enable or disable shortcuts, change the prefix trigger, record bindings, reset defaults, and review conflicts.

Character bindings use the prefix trigger (default Alt+P) followed by the configured key. Direct bindings, such as function keys and Escape, run in a single keystroke. Character shortcuts remain available while normal controls have focus without stealing text-entry input; dialogs, menus, and other non-character controls continue to receive their direct bindings.

Default actions include:

The prefix sequence expires after a short timeout. If multiple actions share the same chord, PacketSnitch reports a shortcut conflict and runs none of them. Keyboard actions use the same allowlisted action registry as other frontend action callers, including the Ask PacketSnitch routing surface.

Summary Frame

The Analysis workspace displays the generated analysis report for the loaded capture. It is opened with the Analysis button in the toolbar; internal DOM and state identifiers retain some historical summary names.

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 (llm:generate IPC, with the legacy ollama:generate alias retained for compatibility), which applies the configured provider, model, bearer token, timeout, and token cap.
• Existing summary text is persisted in saved sessions and restored on load.
• Notes integration: every note created on the Notes tab is automatically mirrored on the Summary report under a dedicated heading so the analyst never has to copy/paste observations between the two tabs.
  • By default each note is rendered under ## Inferred Data (from Notes) and treated as analyst inference / hypothesis rather than as a concrete observed fact.
  • When the note’s Mark as verified data (concrete) checkbox in the Notes editor is on, the note is instead rendered under ## Verified Notes (from Notes) and the Summary report treats it as a concrete data point.
  • The concrete/inferred flag is persisted in the saved session 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 and analysis workspace accessible at any time by clicking Conv in the toolbar. It has seven sub-tabs: Conversions, Hashes, Extraction, Decodes, Analyze Subnet, Threat Intel, and Packet JSON.

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.

The Hashes sub-tab also provides a Cross Reference Hash button. When a hash output is focused or has a text selection, the button cross-references that hash; otherwise it sends the current SHA-256 output to the Threat Intel sub-tab, sets the query type to hash, and runs a VirusTotal lookup.

Extraction Sub-tab

The Extraction sub-tab detects compression and archive formats in the current Conv input. Extraction is explicit: detection alone does not modify the input. Depending on the detected format, the analyst can decompress data, browse an archive tree, select one entry, preview its metadata, load it back into Conv, save it to a file, hash it, or send it to Threat Intel. Decompressed output has separate load and save actions. Extracted files can also be added to the Artifacts store and later rescanned for embedded secrets.

Decodes Sub-tab

The Decodes sub-tab is a registry-backed protocol decoder. Select a protocol from the Protocol dropdown or leave it on Auto-detect. The current registry includes HTTP, FTP, SMB / Samba, Telnet, SSH / OpenSSH, POP3, IMAP, SMTP, JSON, XML, HTML, YAML, Protobuf, MessagePack, BSON, ASN.1 BER, ASN.1 DER, LDAP, SIP, SMPP, Soulseek, BitTorrent, Kerberos, ISO 8583, JPEG, PNG, GIF, WebP, and additional bundled or user-installed decoder specs. The same dispatch path is used for conversion input, followed streams, and loaded carved files.

For the decoder registry, drop-in decoder locations, DECODER_SPEC contract, auto-detection hints, and authoring examples, see the dedicated Modular Decoder Reference.

• The Kerberos (krb5) decoder disassembles AS-REQ/AS-REP/TGS-REQ/TGS-REP/AP-REQ/AP-REP/KRB-ERROR/KRB-PRIV/KRB-CRED messages, showing pvno, msg-type, realm, cname/sname, KDC options (with the RFC 4120 bit-numbered flags), till, nonce, etype list, ticket (tkt-vno/realm), and an EncryptedData etype + cipher preview. Auto-detect and the protocol/port hints (krb5, kerberos, ports 88/464/750) route matching traffic to it.
• The ISO 8583 (Financial) decoder disassembles the standard ISO 8583 message structure: MTI (4 ASCII digits or 2 BCD bytes), primary/secondary bitmap (ASCII-hex or binary), and data elements per the ISO 8583:1987/1993 field definitions. It supports LLVAR/LLLVAR length prefixes in both ASCII and binary modes, transparently strips 2- or 4-byte TPDU/message-length framing prefixes common in ISO 8583 over TCP, and rejects false positives (e.g. HTTP text that happens to start with 4 ASCII digits) by validating the BCD MTI against the known MTI table and requiring the first data field to parse. Auto-detect and the protocol/port hints (iso8583, iso-8583, ports 8583/5000/5001/14401) route matching traffic to it. Field values that are BCD-packed or otherwise non-printable render as hex in the decoded view via the readAsciiOrHex helper and the data-tools-proto-hex CSS class.
• The SMB / Samba decoder has a dedicated follow-stream mode that walks SMB2 read/write transactions and renders a per-message tree of headers, file content, and offsets. Single-block streams are now fed through the decoder pipeline correctly, and the inline decoder switch in the Host Data view honours the same selection.

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 for details.

Analyze Subnet Sub-tab

The Analyze Subnet sub-tab is a host and subnet enrichment workspace for IPv4/IPv6 addresses and CIDR/netmask input.

IPv6-specific helper functions

The Analyze Subnet sub-tab uses a dedicated IPv6 math path (src/ui/panels/subnet-calculator-panel.js) so it can operate on 128-bit addresses without precision loss:

• parseIpv6Address(value) — RFC 5952 parser that handles :: compression, embedded IPv4 (::ffff:192.0.2.1), and zone-id (%eth0) suffixes.
• ipv6GroupsToBigInt / ipv6BigIntToGroups — BigInt conversions between 8-hex-group and 128-bit integer representations.
• formatIpv6Expanded / formatIpv6Compressed — produce the canonical expanded / compressed display strings.
• classifyIpv6Address — returns the IPv6 scope class (Global unicast, Unspecified, Loopback, Unique local, Link-local, Multicast, Documentation range) and an exposure tag (Public, Private, Special use) for the Analyze Subnet and Subnet cards.
• analyzeIpv6 — full subnet analysis (prefix, total hosts, host range, binary breakdown) for the packet under inspection.

IPv6 in Datagram Frame and Packet Info

The right-sidebar Datagram Frame panel and the Packet Info pane render IPv6 addresses and endpoint pairs natively:

• Endpoint format — IPv6 endpoints are rendered in RFC 3986 bracket form to disambiguate the trailing port: [2001:db8::10]:443. The formatNetworkEndpointDisplay(host, port) helper in src/ui/main-frontend.js chooses the bracket form for IPv6 and the plain host:port form for IPv4.
• Packet-context summary — buildPacketContextSummary uses the same bracket form when an IPv6 address is involved so the LLM context payload is unambiguous.
• Stats / Heatmap — IPv6 addresses flow through the same host aggregation as IPv4: stats.hosts lists every observed IPv4/IPv6 literal, stats.hostnames lists resolved DNS hostnames, and the Stats panel strips surrounding brackets ([2001:db8::10] → 2001:db8::10) so an IPv6 literal and its hostname-bracket form are de-duplicated. The Analyze Subnet sub-tab applies classifyIpv6Address to attach the IPv6 scope/exposure when an IPv6 address is analyzed.
• App Protocol column — the column shows IPv6 (with the transport protocol stacked: TCP / IPv6, UDP / IPv6, ICMPv6 / IPv6) so the decompose flow doesn’t conflate IPv4 and IPv6 sessions.

Filter and bookmark keys for IPv6

• Bookmark keys — saved-bookmark packet keys use a $ separator between the host string and the packet index to avoid collisions with the IPv6 colon. The key for packet index 11 of 2001:db8::10 is 2001:db8::10$11. Parsing splits on the last $ so an IPv6 address is recovered verbatim. Both IPv4 and IPv6 go through the same code path.
• Filter values — IPv6 address filter values are parsed at the filter-expression level without truncation: the entire 128-bit value is retained up to the $ separator (index) or the comparison operator.
• Filter keys — IPv6 addresses are stored under the same ip.* keys as IPv4 (ip.src.addr, ip.dst.addr, ip.proto.num, network.proto, …). The family is detected via ip.proto.num (the IPv6 next-header field) and network.proto. See the Filter Key Reference for the full table.

Nmap service enumeration is gated by Settings → General → Enable Conv Subnet internet-host Nmap service scans and is disabled by default.

Threat Intel Sub-tab

The Threat Intel sub-tab performs IP, URL, and hash reputation lookups using the backend HTTP service. It is also the destination for the Hashes sub-tab Cross Reference Hash action.

When the Analyze Subnet sub-tab runs an analysis, the threat-intel input is automatically seeded with the inspected IP, the query type is set to ip, and IPsum, Tor, and VirusTotal results are fetched alongside the subnet cards. Those results are then displayed in the Threat Intel sub-tab. The dedicated subtab replaces the previous inline reputation card in Analyze Subnet. The lookups are served by the backend enrichment endpoints (/ipsum, /tor, /shodan, /whois, /geoip) documented under HTTP Service Mode.

Packet JSON Sub-tab

The Packet JSON sub-tab displays the full normalized JSON structure for the selected packet as held by the renderer. It is context-menu aware, so selected values can be copied, converted, filtered, added to Artifacts, sent to Notes, or passed to other workspaces.

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 five sub-tabs: Hashes, SSL, PGP, OpenSSH, and Wireless (IEEE 802.11). Switching between them keeps the rest of the workspace state, including the filter bar, packet cursor, and Artifacts store, intact.

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 in the session Artifacts store 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.

Wireless Sub-tab (IEEE 802.11 / Wi-Fi)

The Wireless sub-tab is the frontend home of the 802.11 frame decoder and decryptor in src/backend/decoders/wireless_80211.py. It surfaces every 802.11 frame observed in the capture, lets the analyst push Wi-Fi keys (WPA/WPA2-PSK, WEP, or pre-computed PMK) to the backend, and re-runs the capture with decryption enabled so the decrypted inner packets flow into the rest of the workspace.

The full backend contract (key file format, --wifi-keys-file flag, decrypt status attributes, end-to-end result shape) is documented in the Crypt tab / 802.11 (Wi-Fi) decryption section of the Backend docs; the Wireless sub-tab is the renderer-side counterpart of that contract.

Saved sessions round-trip the Wi-Fi key artifacts; on session restore the bridge re-sends them to the backend so re-opening a Wi-Fi capture still decrypts 802.11 frames without manual re-entry.

Settings Tab

The Settings tab is a persistent configuration workspace with twelve sub-tabs: Storefront, General, Backend, LLM, API Keys, Debug, Merge, Plugins, Themes, Privacy, Keyboard Shortcuts, and About.

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, 8000.

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

The Backend sub-tab also contains the configured VirusTotal and Hashes.com API keys. See the API Keys sub-tab below.

API Keys Sub-tab

The API Keys sub-tab is a focused location for the secrets used by the renderer’s outbound API calls. Storing the keys here keeps the Backend sub-tab uncluttered and gives each provider its own input + test surface.

If an API key field is left blank when saving, the currently stored key is retained so re-saving the form does not wipe a configured secret.

Plugins Sub-tab

The Plugins sub-tab lists discovered PacketSnitch plugins and lets you install, enable, disable, and uninstall them. Each plugin declares the capabilities it needs (file.read, net.outbound, ui.menu, etc.) and the runtime enforces them.

Capabilities are gated by config/plugin-capabilities.json; entries in that file are the only keys the runtime will ever grant. Plugins requesting undeclared capabilities are rejected at install time.

See plugins for the complete plugin format, lifecycle, and authoring tutorial.

Themes Sub-tab

The Themes sub-tab is the home of the theme engine. It shows a 400×250 preview for every theme on disk plus the contents of the theme catalog, so purchased themes are available offline.

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

Privacy Sub-tab

The Privacy sub-tab houses the opt-in anonymous metrics system, install identifier, and related consent state.

The renderer enforces a strict SAFE_PROP_KEYS allowlist and per-key length caps on every event, so no PCAP paths, IPs, prompts, or other user content ever leave the renderer.

The bundled src/metrics/server.py is a self-hostable NDJSON-on-disk sink with a /healthz liveness probe and API-key-gated sensitive endpoints. It is ready to deploy behind any reverse proxy for self-hosted setups.

Merge Sub-tab

The Merge sub-tab controls per-source color coding for captures that span multiple source files or captures. When enabled, packets are tinted in the List, Stats, and Host Data tabs according to the source they came from, making it easy to visually distinguish traffic origins in merged sessions.

Changes to sourceColorCodingEnabled or sourceColors clear the LLM diagnostics cache and force a re-render of all color-coded panels.

About Sub-tab

The About sub-tab provides release-note refresh and direct download actions for newer releases, and is also used when startup release checks detect an available update.

The top toolbar Help button opens the PacketSnitch documentation hub at https://packetsnitch.com/docu/ in PacketSnitch’s own in-app browser window (the same child BrowserWindow that window.open triggers). The main-process did-create-window handler in src/main.js locks that child window to whitelisted docs hosts (packetsnitch.com, buymeacoffee.com, virustotal.com), resizes it to 1200×900, strips the menu bar, and tags it with the desktop user-agent. Help is the only in-app link that stays anchored inside PacketSnitch — every other external link (release notes, donate, theme catalog, VirusTotal card, etc.) is routed to the user’s default system browser via shell.openExternal so the user keeps their existing browser session, and the help window likewise keeps PacketSnitch-anchored navigation separate from the user’s browser profile.

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.

By default PacketSnitch opens this tab right after a capture finishes loading so the analyst gets an at-a-glance overview (Capture Overview / Map / Anomalies) before drilling into individual packets. Change the post-load workspace from Settings → General → Open after capture load (general.defaultTab); saved sessions still restore into their remembered tab, so the preference only affects fresh captures.

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.

PacketSnitch can be configured to open the List tab right after a capture finishes loading. Pick List under Settings → General → Open after capture load (general.defaultTab) if you prefer pcap-ordered browsing over the default Stats overview. Saved sessions still restore into their remembered tab, so the preference only affects fresh captures.

Search Bar

Columns

The Columns control opens a column chooser. Columns can be shown or hidden, dragged into a custom order, and resized; preferences persist in the user settings. Source Color and Source are hidden by default so single-PCAP sessions remain compact. Enable them for merged or multi-source captures to see each row’s source and configured color. Click any row to navigate to that packet in Host Data.

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 llm:generate IPC handler; the legacy ollama:generate channel remains as a compatibility alias.
• 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 Ask PacketSnitch… context-menu submenu with Ask a question…, Explain this data…, 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. The full endpoint list (including the enrichment lookups used by the Conv Analyze Subnet sub-tab) is documented under HTTP Service Mode in the Backend docs.
• 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.

Artifacts Tab

The Artifacts tab is the investigation artifact store. It replaces the old Keystore tab as the primary user-facing workspace and brings together secrets, extracted files, URLs, certificates, credentials, and other useful values discovered during capture analysis. The implementation retains some legacy keystore names internally for session compatibility and plugin APIs, but users should look for Artifacts and Artifact Store in the UI.

Artifact categories

Use the category selector and filter field to narrow the current artifact list:

• All — every artifact in the active store.
• Secrets — passwords, private keys, cookies, API keys, OAuth/JWT tokens, cloud credentials, and other authentication material.
• Items — certificates, email addresses, URLs, and URIs.
• Files — downloaded, carved, or extracted files with their original bytes and metadata.
• Misc — unclassified or plugin-provided artifacts and useful capture values that do not fit another category.

Unknown and legacy artifact types remain visible under Misc rather than being discarded.

Session and persistent artifacts

• Session auto keychain holds artifacts discovered from the active capture, Conv/Crypt workflows, file extraction, decoder output, and context-menu actions. It is rebuilt or refreshed as capture data changes and is cleared when the application session ends.
• Persistent keychain stores analyst-selected artifacts in the local application database so they can be reused across sessions. The UI now automatically unlocks this local store for the application session; the Wipe persistent store action removes its saved entries.
• Saved PacketSnitch sessions preserve the relevant artifact state, including file artifacts and session-derived entries, so an investigation can be resumed without re-carving every object.

Artifact actions

Artifacts can also be added from the context menu as passwords/secrets, private keys, certificates, cookies, or manual URLs. Packet-derived sources include HTTP authentication and cookies, FTP/SMTP/IMAP/SIP/RDP credentials, hostnames, IPs, email addresses, URLs, hashes, and extracted file content.

File artifacts

Downloaded, carved, and extracted files appear under Files with protocol, filename, byte length, source details, and raw bytes. File artifacts are persisted locally and included in session state. They can be loaded into Conv, sent to the decoder workspace, previewed or saved through context-menu actions, and rescanned for embedded secrets after archive extraction or decompression.

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. Every note is also automatically mirrored on the Analysis / Summary tab so observations and conclusions stay in sync (see the Summary Frame section).

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.

Verified Data Flag

The editor footer includes a Mark as verified data (concrete) checkbox. The flag controls how the note is treated by the Summary tab:

• Off (default): the note is treated as analyst inference / hypothesis and is rendered on the Summary report under ## Inferred Data (from Notes).
• On: the note is treated as a concrete, analyst-confirmed fact and is rendered under ## Verified Notes (from Notes).

The flag is persisted alongside the note body in the saved session file and restored on load.

Notes Context Menu

Right-clicking in packet or Conv views while notes are active shows a Send to Notes… submenu. See context-menu 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.

IPv6 packets share the same ip.* keys as IPv4 (ip.src.addr, ip.dst.addr, ip.chksum, ip.len, ip.src.class, ip.dst.class, ip.proto.num). Examples:

ip.src.addr:2001:db8::1 && tcp.dst.port:443
network.proto:IPv6
ip.proto.num:58 && icmp.type:Echo Request

IPv6 filter values are parsed without truncation: the full 128-bit address is retained up to the comparison operator or the bookmark $ separator. See the Filter Key Reference for the full key table and parsing rules.

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

See also

• Backend documentation — the Python/TShark parser that produces the data the frontend surfaces.
• Filter reference — the filter bar keys and search syntax used across the frontend workspaces.
• Context menu reference — every right-click action available in the frontend.
• Plugins documentation — themes and plugin engine for extending the frontend.
• Features — the full feature list.
• FAQ — frequently asked questions.