Offline pcap → .tap conversion¶

friTap can reconstruct a friTap .tap file from a capture you already have on disk — no live target, no Frida attach. This is the offline path: you bring a pcap/pcapng (and, when the traffic is encrypted, the TLS keys), and friTap produces the same rich .tap you would get from a live capture, ready for fritap analyze and the replay TUI.

If you just want the 5-minute happy path, start with the Offline quickstart and come back here for the details, caveats, and the Python API.

What it does¶

The offline pipeline has two distinct modes, chosen automatically from the inputs:

• tshark-decrypt (keyed). When you pass --keylog or the capture is a pcapng carrying an embedded Decryption Secrets Block (DSB), friTap drives tshark to decrypt the TLS and QUIC streams, then feeds the recovered plaintext through friTap's own protocol parsers (HTTP/1.1, HTTP/2, HTTP/3, WebSocket, …) to build flows.
• Plaintext ingest (keyless). When you pass no keys and there is no DSB, friTap treats the capture as already-cleartext and ingests the raw transport payload (tcp.payload / udp.payload) directly. Streams that are genuinely encrypted are detected, skipped, and tallied (see Caveats).

In both modes the result is the same .tap format used everywhere else in friTap — see the .tap format spec.

flowchart TD
    A[pcap / pcapng] --> B{keylog or<br/>embedded DSB?}
    K[--keylog SSLKEYLOGFILE] -.-> B
    B -- yes (keyed) --> C[tshark decrypt<br/>TLS follow + QUIC -T ek]
    B -- no (keyless) --> D[tshark raw payload export<br/>plaintext ingest]
    C --> E[friTap parsers<br/>HTTP/1.1, H2, H3, WebSocket]
    D --> E
    D -.->|encrypted TLS/QUIC<br/>streams detected| X[skipped + tallied as<br/>encrypted_streams_skipped]
    D -.->|keyless 1-RTT QUIC<br/>no handshake plaintext| Y[(silently dropped —<br/>undetectable without keys)]
    E --> F[FlowCollector<br/>+ body de-dup]
    F --> G[(out.tap)]

CLI: --from-pcap¶

The offline pipeline is invoked through the main fritap entry point whenever --from-pcap appears in the arguments. It owns a small, dedicated set of flags:

# requires Wireshark/tshark ≥ 4.x
fritap --from-pcap chrome.pcap --keylog chromekeys.log --tap out.tap

This page documents only the offline sub-flags. For the complete fritap flag reference, see CLI reference.

Manifest sidecar: <pcap>.fritap.json¶

A live friTap capture writes a sidecar manifest next to the pcap so that an offline reconstruction can find the keys and ports automatically. If a file named <pcap>.fritap.json sits beside your capture, friTap reads it and fills in any value you did not pass on the command line.

{
  "keylog": "chromekeys.log",
  "tls_ports": [4433, 8443],
  "quic_ports": [8443]
}

Recognized keys: keylog, tls_ports, quic_ports. A missing or unreadable manifest is treated as empty (no error).

Precedence — explicit always wins:

CLI flag  >  manifest value  >  built-in default

So --keylog other.log overrides the manifest's keylog, but if you omit --keylog the manifest's value is used. The same holds for --tls-port / --quic-port.

Keyed vs keyless behavior¶

The "fail loud" rule matters: if you pass --keylog but the file does not exist (and there is no DSB), friTap stops with NoDecryptionKeysError rather than falling through to the plaintext path and producing a misleading .tap.

MTProto (Telegram)¶

tshark cannot decrypt Telegram's MTProto, so friTap ships its own decryptor (TCP reassembly → AES-CTR transport de-obfuscation → AES-IGE record decryption). It runs alongside the TLS/QUIC passes when you pass --mtproto-keylog:

fritap --from-pcap tg.pcapng --mtproto-keylog tg.keys --tap tg.tap

• --mtproto-keylog is separate from --keylog — the latter is the NSS/TLS key log handed to tshark; the former is friTap's MTProto key log (MTPROTO_AUTH_KEY lines) consumed by friTap's own decryptor. They can be combined on a mixed capture.
• Offline decryption needs the AES backend, which ships in friTap's base install (no extra needed); the optional tgcrypto fast path is pulled in automatically where a wheel exists. On a lean install the backend is absent and the CLI prints Warning: Telegram/MTProto decryption needs an extra dependency … and skips the MTProto streams — the TLS/QUIC passes still complete.
• Decrypted MTProto message bytes land in an MtprotoLayer in the .tap. friTap does not parse the Telegram TL schema; that is left to a pluggable parser (see Telegram (MTProto)).

Graceful-degradation counters¶

When MTProto streams are present, the summary adds counters that tell you what could not be decrypted (the decryptor never emits garbage — it skips and tallies):

  mtproto messages:  128
  mtproto undecryptable records: 4 (no matching auth_key — temp/perm key mismatch?)
  mtproto degraded streams: 1 (capture started mid-stream / unsupported transport)

• mtproto undecryptable records — a record's auth_key_id matched no key in the keylog. Usually a temp/perm key mismatch: the keylog was not recorded during the same session as the pcap (Telegram's PFS rotates the temp key).
• mtproto degraded streams — a stream could not be processed end-to-end: the capture started mid-stream (de-obfuscation needs the first 64 bytes) or used a transport friTap does not yet support (e.g. Fake-TLS, padded intermediate).

Caveats (read before you trust the output)¶

Warning: no plaintext application data was produced; 3 stream(s) look
encrypted (TLS/QUIC) and were skipped. This capture needs keys — pass
--keylog <SSLKEYLOGFILE>, or use a pcapng with an embedded Decryption
Secrets Block (DSB).

Exit codes¶

fritap --from-pcap returns:

Python API: pcap_to_tap()¶

The same conversion is available programmatically. Import it from the friTap package root (it is intentionally not re-exported from friTap.offline, where it would shadow the pcap_to_tap module):

from friTap import pcap_to_tap   # NOT from friTap.offline

result = pcap_to_tap(
    "chrome.pcap",
    keylog_path="chromekeys.log",   # omit for a plaintext / DSB capture
    tap_path="out.tap",             # default: <pcap stem>.tap
    tls_ports=(4433,),              # extra Decode-As TLS ports
    quic_ports=(),                  # extra Decode-As QUIC ports (443 always on)
    extra_decode_as=(),             # raw tshark -d rules
    heuristic=False,                # TLS-over-TCP heuristic dissection
    run_scan=False,                 # run analyzers afterward
    capture_target="",              # label stored in the .tap (default: basename)
    tshark_path=None,               # explicit tshark binary; else auto-discovered
    use_manifest=True,              # honor a <pcap>.fritap.json sidecar
)

print(result.to_dict())

pcap_to_tap() is the manifest-aware wrapper (CLI > manifest > defaults). For a no-manifest core call, use friTap.offline.pcap_to_tap.convert_pcap_to_tap().

It returns a ConvertResult:

ConvertResult.to_dict() gives a JSON-safe view for web/API callers.

pcap_to_tap() raises NoDecryptionKeysError (a ValueError) when the capture is encrypted and no keys are available; other tshark/IO failures propagate as their native exceptions.

See also¶

• Offline quickstart — the 5-minute happy path.
• Telegram (MTProto) — offline --mtproto-keylog decryption.
• Traffic analysis — fritap analyze / --scan.
• Replay TUI — open a .tap interactively.
• .tap format spec — the on-disk format.
• CLI reference — every fritap flag.