Your First Capture

This walkthrough takes a packet capture from disk to an inspected request: import, parse, find the session in the workspace, and open a request in the inspector. It assumes Traffic Jam is already running — see /docs/en/getting-started/installation/ for setup.

Import a capture

Open the Captures tab (sidebar → Capture group, or press ⌘/Ctrl+1, or g then c). The Import panel accepts three kinds of input:

• Import files — pick one or more captures and keylogs.
• Import folder — pick a directory; captures and keylogs inside are paired automatically (exact base-name match first, then a single keylog in the same directory).
• Drag and drop anywhere in the window — files are detected by extension.

Keyboard equivalents: u chooses files, Shift+u chooses a folder, n opens manual pairing (assign a keylog to a capture by hand), i imports the manual pairs, and Shift+d clears all captures. A toast summarizes the result (N captures imported, N HAR imported) and reports failures per file.

What happens on import

The backend parses captures in-process with gopacket — capture bytes and key material are never passed to a child process, and TShark is not required for import. For each capture it:

1. Reassembles TCP streams and reconstructs HTTP/1 and HTTP/2 request/response exchanges, keeping ordered headers, body previews (gzip, deflate, brotli, and zstd content-encodings are decoded), and per-exchange timing.
2. Decrypts supported TLS 1.2/1.3 sessions using key material from the attached NSS keylog file or from a pcapng Decryption Secrets Block (DSB) embedded in the capture itself; both sources are merged.
3. Extracts TLS ClientHello fingerprints (JA3/JA3-full, JA4/JA4r, SNI, ALPN, cipher suites, extensions) and server certificates.
4. Persists the parsed session in SQLite (default .traffic-jam/traffic-jam-v2.sqlite3, override with TRAFFIC_JAM_DB_PATH), so imported sessions survive API restarts.

HAR files follow the HAR 1.2 schema and import as sessions the same way, minus packet-level TLS data.

[!NOTE] Some traffic cannot be recovered from a packet capture. If the parser sees QUIC/HTTP3 flows it warns that QUIC cannot be decrypted with TLS keylogs — disable QUIC/HTTP3 in the client and re-capture. WebSocket upgrade handshakes are detected and flagged, but WebSocket message frames are not decoded yet.

The workspace layout

The window is a fixed shell with a left sidebar and a content area:

• Sidebar — tabs grouped into Capture (Captures, Browser capture, Android), Analysis (API lab, Timeline, Compare, TLS), and Tools (Workbench). Each tab has a ⌘/Ctrl+N accelerator and a g-sequence (for example g l for Timeline). The sidebar footer holds Bookmarks, Shortcuts, Settings, and the theme toggle; it collapses to an icon rail.
• Backend status banner — appears at the top only when the API health check fails (“Backend unavailable”) with a Retry button.
• Context bar — names the active tab and its purpose.
• Status bar — bottom of the window; shows per-session load progress while capture details load, with cancel, retry, and exclude controls.

The Timeline tab (⌘/Ctrl+5) is where you read a session: a request list ordered by time with a search box (“Search host, path, headers…”), method/status/protocol/host/stream filters, and a single-capture or side-by-side compare view with Baseline and Candidate capture pickers. Live capture controls (which require mitmdump, tshark, Chrome, and a capture interface) are covered in /docs/en/capture/; the analysis tabs built on top of imported sessions are covered in /docs/en/analysis/.

Open a request

In the Timeline, move the selection with j/k (or arrow keys) and press Enter to open the request inspector dialog. It shows the full exchange: start line, ordered request and response headers, decoded request/response bodies, packet trace, and the attached TLS fingerprint. From the dialog you can:

• switch detail sections with 1–8;
• step through the filtered list with the previous/next arrows;
• bookmark the request (bookmarks are collected in the sidebar Bookmarks panel, g k);
• set the request as Compare Baseline or Candidate, or open its matched pair in the Compare tab;
• jump to the TLS fingerprint view for the exchange.

Press Esc to close. Credential-bearing headers and sensitive values are masked by default; revealing them shows a “Captured secrets are visible” banner and display access expires after 15 minutes. Replays and exports always require their own separate opt-in.

[!TIP] Press the Shortcuts button in the sidebar (or open the Keyboard shortcuts dialog) for the full searchable list — it includes Timeline keys / (focus search), r (reset filters), f (more filters), v (single/compare view), s (swap baseline and compare), a/m (set baseline/candidate from selection), and p (open matched pair in Compare).

[!WARNING] Traffic Jam is for authorized testing of systems you have permission to test. Captures may contain live credentials and session tokens; keep capture files and the SQLite database on machines you control.