Pcap Flow Lab

Flow-based PCAP analyzer for large captures.

Pcap Flow Lab is an open-source C++20 project with a CLI and an optional Qt Quick desktop UI. It is designed for a specific workflow: open large captures quickly, navigate by flow instead of packet-first hunting, save reusable indexes, and inspect only the selected flow in more detail when that deeper work is worth doing.

It is not trying to be a Wireshark replacement. It is trying to be a practical flow-based tool for large-capture exploration that stays fast, bounded, and honest about its limits.

Why this project exists

Large captures are often awkward to revisit when every session starts with a full rescan and packet-by-packet re-orientation. Pcap Flow Lab focuses on a different workflow:

• open captures with a packet-oriented fast path
• persist reusable analysis indexes so large captures do not need to be fully re-imported every time
• browse and filter flows first
• inspect packets, details, statistics, and selected-flow analysis only where needed
• export useful subsets without turning the whole product into a general-purpose protocol workbench

This makes the project especially useful when the first question is not "what does packet 1 contain?" but "which flows matter in this capture, and what is the shape of the one I care about?"

How it differs from Wireshark

Pcap Flow Lab deliberately optimizes for a narrower job than Wireshark.

• It is flow-based rather than packet-first.
• It emphasizes large-capture usability and index-based reopen workflows.
• It keeps deeper work selected-flow-only instead of doing global stream reconstruction during open.
• It aims for practical, bounded inspection rather than maximum protocol breadth.

That also means it intentionally does not compete on every axis:

• it is not a full protocol forensics suite
• it does not try to match Wireshark packet-detail depth
• it does not implement full TCP-correct reconstruction for hostile capture conditions

Key features

• Fast open path for PCAP and PCAPNG captures.
• Reusable analysis indexes for large files.
• Index-only reopen workflow with later source-capture attach for byte-dependent features.
• Flow browsing with filtering, protocol hints, top endpoints, top ports, and protocol statistics.
• Selected-flow Analysis workspace with metadata-first summaries, derived metrics, histograms, timeline, directional ratios, and rate graph.
• Selected-flow Stream inspection for practical TCP, TLS, HTTP, and meaningful bounded QUIC cases.
• Packet details in Summary, Raw, and Protocol views.
• Flow export to classic PCAP, selected-flow sequence export to CSV, and Smart Export workflows including per-flow output.
• Selected-flow Stream construction suppresses retransmitted packets in the current bounded model.
• Smart Export progress and cooperative cancellation for long-running exports.
• Optional checksum validation for the selected packet in Packet Details.
• Constricted packet handling that keeps captured/original length semantics explicit in packet lists, packet details, Analysis, and bounded Stream presentation.
• Conservative behavior on imperfect captures, including bounded fallback paths instead of over-claiming semantic certainty.

Screenshots

Flows overview

Analysis workspace

Statistics summary

Stream and details

Current scope and limitations

The current project direction is suitable for a small public release as long as the core workflows stay solid and the limitations stay explicit.

Current strengths:

• practical flow navigation on large captures
• fast open plus reusable index reopen workflows
• selected-flow Analysis from metadata only
• useful selected-flow Stream behavior for supported TCP, TLS, HTTP, and meaningful bounded QUIC cases
• practical export workflows, including Smart Export and per-flow output for selected scenarios

Current limitations:

• no full TCP-correct stream reconstruction
• no deep TCP recovery after gaps, major reordering, or loss
• Stream results are heuristic and can differ from Wireshark on difficult captures
• HTTP Stream reconstruction is bounded and selected-flow-only; requests and responses, including bodies, may be assembled across multiple TCP segments, but recovery is not transport-complete
• QUIC inspection is meaningful but intentionally bounded; selected-flow Stream and packet details can expose practical frame-level and handshake-aware details for supported cases, but full QUIC session reconstruction and broad decryption coverage remain out of scope
• packet details are intentionally shallower than Wireshark
• index and checkpoint loading currently use an exact-version policy

Supported formats and protocol scope

Current decode and import support includes:

• classic PCAP and current PCAPNG
• Ethernet II
• Linux cooked captures SLL and SLL2
• up to two VLAN tags
• ARP
• IPv4 and IPv6
• ICMP and ICMPv6
• TCP and UDP
• conservative traversal of common IPv6 extension headers
• always-on IP fragmentation detection as diagnostic metadata

Current protocol-aware inspection is strongest in:

• HTTP request and response reconstruction with bounded directional reassembly, including bodies assembled across multiple TCP segments with conservative fallback where needed
• TLS record-oriented Stream parsing with bounded directional reassembly
• narrow TLS detail exposure for complete ClientHello, ServerHello, and Certificate cases
• meaningful selected-flow QUIC inspection with bounded frame-level and handshake-aware details for practical cases such as Initial, Handshake, Retry, Version Negotiation, CRYPTO, ACK, PADDING, and protected payload fallback
• Smart Export with shared packet-selection rules, per-flow output mode, manifest export, progress reporting, and cooperative cancellation
• selected-packet checksum validation for IPv4, TCP, and UDP when enabled in settings
• clearer handling of shortened or truncated packets across packet lists, packet details, Analysis, and bounded Stream views

Near-term work remains focused on reliability, Stream correctness, bounded analysis, and incremental protocol enrichment.

Build and release status

Requirements:

• CMake 3.24+
• a C++20 compiler
• Qt 6.8+ with Quick, Qml, QuickControls2, and Widgets for the desktop UI

The CLI and core library can build without Qt. If Qt 6 is not found, the UI target is skipped.

Current manual release status:

• Windows: a prebuilt UI zip archive is intended for the release.
• Ubuntu: a prebuilt archive should be published only if it is manually built and manually verified for that release; otherwise treat Ubuntu as source-build-only for that tag.
• macOS: source-build-only unless a manually verified binary is prepared for that release.
• Release artifacts are expected to be prepared manually rather than through automated packaging or release infrastructure.

Example configure and build steps:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

If BUILD_TESTING is enabled, the repository defines:

• pcap_flow_lab_core_tests
• pcap_flow_lab_ui_tests when the Qt UI target is available

Example test command:

ctest --test-dir build --output-on-failure --build-config Release

Current checked workflow in the repository is still centered on Windows release packaging, but Linux source builds and manual validation are also part of normal project use. Treat platform guarantees as release-specific: only claim a prebuilt artifact or a verified source-build path for a platform when that exact release was manually checked on that platform.

Quick usage examples

pcap-flow-lab summary sample.pcap --mode fast
pcap-flow-lab flows sample.pcapng --mode deep
pcap-flow-lab summary sample.idx
pcap-flow-lab inspect-packet sample.idx --packet-index 0
pcap-flow-lab export-flow sample.idx --flow-index 0 --out selected-flow.pcap
pcap-flow-lab save-index sample.pcapng --out sample.idx --mode deep
pcap-flow-lab load-index-summary sample.idx
pcap-flow-lab chunked-import sample.pcap --checkpoint sample.ckp --max-packets 100000
pcap-flow-lab resume-import --checkpoint sample.ckp --max-packets 100000
pcap-flow-lab finalize-import --checkpoint sample.ckp --out sample.idx

If the Qt UI target is built, run:

pcap-flow-lab-ui

Related docs

• docs/architecture.md: architecture, persistence boundaries, and runtime paths
• docs/current-state.md: implemented behavior and current gaps
• docs/release-checklist.md: release readiness checklist for the next manual public release
• docs/release-notes-draft.md: draft public release notes for the next manual release
• docs/manual-release-publish-checklist.md: compact final publish checklist for the manual GitHub release
• docs/contributing.md: contribution expectations

License

This project is licensed under the Apache License 2.0. See LICENSE.

Developer note

Creating perf-open.enabled next to the executable or in the current working directory enables append-only open-time CSV logging to perf_open_log.csv for capture_fast, capture_deep, and index_load operations. This is developer-only instrumentation for local regression tracking and has no effect in normal usage.