Skip to content
→ All work

Case study 34 / 37

PacketLens

A packet inspector that decodes Ethernet, IP, TCP, UDP, DNS and TLS, tracks connections, and explains each flow in one plain-English sentence.

Status
In development
Period
2026
Domain
Security · Tools
Language
Rust
Last push
26 OCT 2026
License
MIT
Source of claims
README.md, CHANGELOG.md, docs/PRODUCTION_READINESS.md, src/live.rs, tests/fuzz.rs, .github/workflows/ci.yml

A Rust CLI whose decode → connection-tracking → explanation pipeline is pure and file-driven: bytes in, typed data out, no sockets. The full test suite runs against generated pcap fixtures on Linux, macOS and Windows with no capture privileges; live capture is a separate, feature-gated Linux layer.

01/The problem

Wireshark shows every field of every header. Most of the time the question is simpler: what is this flow doing: a completed request, a half-open scan, a DNS lookup, a TLS handshake to which host?

02/The system

A Rust CLI whose decode → connection-tracking → explanation pipeline is pure and file-driven: bytes in, typed data out, no sockets. The full test suite runs against generated pcap fixtures on Linux, macOS and Windows with no capture privileges; live capture is a separate, feature-gated Linux layer.

Pure pipeline (README)6 components
  • pcap::parse to decode_packet
  • live.rs to decode_packet
  • decode_packet to FlowTracker
  • FlowTracker to explain_flow
  • explain_flow to Output

03/Implementation

  1. 01Ethernet (with VLAN), IPv4/IPv6, TCP, UDP and ICMP decoding with IPv4/TCP/UDP checksum verification.
  2. 02Bidirectional connection tracking with TCP handshake and close state, byte and packet counters, and a best-effort peek at DNS and the TLS ClientHello (SNI, ALPN).
  3. 03One sentence per flow, plus a heuristic half-open-SYN scan detector (≥ 4 unanswered ports from one source).
  4. 04Text, --json and an optional ratatui viewer; Linux live capture over an AF_PACKET raw socket behind a feature flag.

04/Engineering

One decoder for every source

Files and live capture feed the same decode_packet and FlowTracker, so a new platform needs a capture loop, not a second parser. Windows and macOS return an explicit “not supported” error.

Fixtures that cannot drift

The pcap fixtures are built byte-for-byte by an example program; CI regenerates them on every run and fails if the committed copies are stale.

Captures are untrusted input

Parsers are bounds-checked and fuzzed, and names taken from packets (SNI, DNS) are escaped before they reach the terminal or JSON output.

05/Interface

No product screenshots are published for this project. The visual above is a code-driven representation of how it behaves, built from the repository source — not a screenshot.

06/Tech stack

  • Rust
  • Classic pcap
  • ratatui (optional TUI)
  • AF_PACKET (Linux)
  • GitHub Actions

07/Result

Verified outcomes

  • Unit, fixture and deterministic fuzz tests (50, or 53 with the TUI feature, per the README) on Linux, macOS and Windows CI.

Known limitations

  • Live capture is Linux-only and keeps every flow in memory for the whole run.
  • Not a Wireshark replacement: no dissector plugins and no TLS decryption.

08/Links

GitHub repository ↗

Related work

Next case study

DocAtlas →