Initial commit: wireframe packet capture/analysis tool

Terminal packet capture and analysis tool built to learn the C++
memory model (byte layout, alignment, endianness, std::span over
unowned buffers) via a real capture pipeline.

- Hand-rolled L2-L4 decoders (Ethernet, IPv4, IPv6 with extension
  header walking, TCP, UDP) over std::span, no struct-casting
- L7 dissector interface with DNS, HTTP, and TLS SNI implementations
- pcapng read/write for Wireshark-compatible capture files
- Bounded capture queue: drop-on-backpressure for live capture,
  blocking push for faithful file replay
- Kernel-level BPF filtering (-f) and a separate display-only search
  (-g / interactive) that doesn't touch what's captured
- Replay mode (-r) reads a saved pcapng file back through the same
  pipeline as live capture, no root or live device needed
- pcap_stats() surfaces kernel/interface drops invisible to the
  capture queue's own counter
- Three frontends sharing one CaptureSession setup path: CLI, TUI
  (FTXUI, primary), GUI (Dear ImGui + SDL3, secondary)
- 89 unit tests (doctest) plus 9 libFuzzer harnesses covering every
  hand-rolled parser; fuzzing found and fixed a real OOM in the
  pcapng reader (unbounded allocation from an untrusted length field)

5 files changed, 362 insertions, 0 deletions

diff --git a/include/wireframe/net/ethernet.hpp b/include/wireframe/net/ethernet.hpp
new file mode 100644
index 0000000..2da4cc8
--- /dev/null
+++ b/include/wireframe/net/ethernet.hpp
@@ -0,0 +1,44 @@
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <span>
+
+#include "wireframe/byteio.hpp"
+
+namespace wireframe::net {
+
+inline constexpr std::size_t kEthernetHeaderLen = 14;
+inline constexpr std::uint16_t kEthertypeIPv4 = 0x0800;
+inline constexpr std::uint16_t kEthertypeIPv6 = 0x86DD;
+inline constexpr std::uint16_t kEthertypeArp = 0x0806;
+
+struct MacAddress {
+    std::array<unsigned char, 6> bytes;
+};
+
+struct EthernetHeader {
+    MacAddress dst;
+    MacAddress src;
+    std::uint16_t ethertype;
+};
+
+struct EthernetFrame {
+    EthernetHeader header;
+    std::span<const unsigned char> payload;
+};
+
+inline std::optional<EthernetFrame> parse_ethernet(std::span<const unsigned char> bytes) {
+    if (bytes.size() < kEthernetHeaderLen) return std::nullopt;
+
+    EthernetHeader header{};
+    std::copy_n(bytes.begin(), 6, header.dst.bytes.begin());
+    std::copy_n(bytes.begin() + 6, 6, header.src.bytes.begin());
+    header.ethertype = read_be16(bytes, 12);
+
+    return EthernetFrame{header, bytes.subspan(kEthernetHeaderLen)};
+}
+
+}  // namespace wireframe::net
diff --git a/include/wireframe/net/ipv4.hpp b/include/wireframe/net/ipv4.hpp
new file mode 100644
index 0000000..f53b4f2
--- /dev/null
+++ b/include/wireframe/net/ipv4.hpp
@@ -0,0 +1,56 @@
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <span>
+
+#include "wireframe/byteio.hpp"
+
+namespace wireframe::net {
+
+inline constexpr std::uint8_t kProtoIcmp = 1;
+inline constexpr std::uint8_t kProtoTcp = 6;
+inline constexpr std::uint8_t kProtoUdp = 17;
+
+struct Ipv4Address {
+    std::array<unsigned char, 4> bytes;
+};
+
+struct Ipv4Header {
+    std::uint8_t version;
+    std::uint8_t ihl;  // header length in 32-bit words
+    std::uint16_t total_length;
+    std::uint8_t ttl;
+    std::uint8_t protocol;
+    Ipv4Address src;
+    Ipv4Address dst;
+};
+
+struct Ipv4Packet {
+    Ipv4Header header;
+    std::span<const unsigned char> payload;
+};
+
+inline std::optional<Ipv4Packet> parse_ipv4(std::span<const unsigned char> bytes) {
+    if (bytes.size() < 20) return std::nullopt;
+
+    std::uint8_t version = static_cast<std::uint8_t>(bytes[0] >> 4);
+    std::uint8_t ihl = bytes[0] & 0x0F;
+    std::size_t header_len = static_cast<std::size_t>(ihl) * 4;
+    if (version != 4 || header_len < 20 || bytes.size() < header_len) return std::nullopt;
+
+    Ipv4Header header{};
+    header.version = version;
+    header.ihl = ihl;
+    header.total_length = read_be16(bytes, 2);
+    header.ttl = bytes[8];
+    header.protocol = bytes[9];
+    std::copy_n(bytes.begin() + 12, 4, header.src.bytes.begin());
+    std::copy_n(bytes.begin() + 16, 4, header.dst.bytes.begin());
+
+    return Ipv4Packet{header, bytes.subspan(header_len)};
+}
+
+}  // namespace wireframe::net
diff --git a/include/wireframe/net/ipv6.hpp b/include/wireframe/net/ipv6.hpp
new file mode 100644
index 0000000..4b6b28a
--- /dev/null
+++ b/include/wireframe/net/ipv6.hpp
@@ -0,0 +1,173 @@
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+#include <cstdio>
+#include <optional>
+#include <span>
+#include <string>
+
+#include "wireframe/byteio.hpp"
+
+namespace wireframe::net {
+
+inline constexpr std::size_t kIpv6HeaderLen = 40;
+inline constexpr std::uint8_t kNextHeaderHopByHop = 0;
+inline constexpr std::uint8_t kNextHeaderRouting = 43;
+inline constexpr std::uint8_t kNextHeaderFragment = 44;
+inline constexpr std::uint8_t kNextHeaderEsp = 50;
+inline constexpr std::uint8_t kNextHeaderAh = 51;
+inline constexpr std::uint8_t kNextHeaderIcmpv6 = 58;
+inline constexpr std::uint8_t kNextHeaderDestOptions = 60;
+
+struct Ipv6Address {
+    std::array<unsigned char, 16> bytes;
+};
+
+struct Ipv6Header {
+    std::uint8_t version;
+    std::uint8_t traffic_class;
+    std::uint32_t flow_label;
+    std::uint16_t payload_length;
+    std::uint8_t next_header;  // transport protocol, or an extension header type
+    std::uint8_t hop_limit;
+    Ipv6Address src;
+    Ipv6Address dst;
+};
+
+struct Ipv6Packet {
+    Ipv6Header header;
+    std::span<const unsigned char> payload;
+};
+
+// Only the fixed 40-byte header is decoded here - header.next_header
+// may name an extension header rather than a transport protocol.
+// walk_ipv6_extension_headers() (below) resolves that; parse_ipv6()
+// itself stays a direct, unconditional decode of exactly the fixed
+// header, nothing more.
+inline std::optional<Ipv6Packet> parse_ipv6(std::span<const unsigned char> bytes) {
+    if (bytes.size() < kIpv6HeaderLen) return std::nullopt;
+
+    std::uint8_t version = static_cast<std::uint8_t>(bytes[0] >> 4);
+    if (version != 6) return std::nullopt;
+
+    Ipv6Header header{};
+    header.version = version;
+    std::uint32_t first_word = read_be32(bytes, 0);
+    header.traffic_class = static_cast<std::uint8_t>((first_word >> 20) & 0xFF);
+    header.flow_label = first_word & 0x000FFFFF;
+    header.payload_length = read_be16(bytes, 4);
+    header.next_header = bytes[6];
+    header.hop_limit = bytes[7];
+    std::copy_n(bytes.begin() + 8, 16, header.src.bytes.begin());
+    std::copy_n(bytes.begin() + 24, 16, header.dst.bytes.begin());
+
+    return Ipv6Packet{header, bytes.subspan(kIpv6HeaderLen)};
+}
+
+struct Ipv6ExtensionWalkResult {
+    std::uint8_t final_next_header;  // a transport protocol, or an extension type we stopped at
+    std::span<const unsigned char> payload;  // bytes after every extension header walked
+    bool stopped_at_esp;  // true if ESP was hit - see walk_ipv6_extension_headers()
+};
+
+// Walks Hop-by-Hop, Routing, Destination Options, Fragment, and AH
+// extension headers to find the real transport protocol underneath
+// them, so e.g. TCP/UDP wrapped in a Hop-by-Hop options header is still
+// decoded instead of silently stopping at "next_header=0". Each header
+// carries its own length, so this never needs to understand a header
+// type's *meaning* to skip over it correctly - only Hop-by-Hop/
+// Routing/Dest-Options (length in 8-byte units from a trailing byte),
+// Fragment (fixed 8 bytes), and AH (length in 4-byte units, RFC 4302)
+// have different encodings, all handled explicitly below.
+//
+// ESP is a hard stop, not a bug: its own next-header field lives in a
+// trailer *after* the encrypted payload, at an offset this code has no
+// way to know without decrypting first. Reported as stopped_at_esp
+// rather than guessed at.
+//
+// Bounded to a handful of iterations as defense in depth against a
+// hostile/corrupt chain - not strictly needed for termination (every
+// header is at least 8 bytes, so payload.size() strictly decreases
+// each iteration and the loop can't actually run forever), but a
+// pathological chain of many tiny headers would otherwise still cost
+// real work for no legitimate reason.
+inline Ipv6ExtensionWalkResult walk_ipv6_extension_headers(std::uint8_t next_header,
+                                                             std::span<const unsigned char> payload) {
+    constexpr int kMaxExtensionHeaders = 8;
+
+    for (int i = 0; i < kMaxExtensionHeaders; ++i) {
+        if (next_header == kNextHeaderEsp) {
+            return {next_header, payload, /*stopped_at_esp=*/true};
+        }
+
+        std::size_t ext_len;
+        if (next_header == kNextHeaderFragment) {
+            if (payload.size() < 8) return {next_header, payload, false};
+            ext_len = 8;
+        } else if (next_header == kNextHeaderAh) {
+            if (payload.size() < 2) return {next_header, payload, false};
+            ext_len = (static_cast<std::size_t>(payload[1]) + 2) * 4;
+        } else if (next_header == kNextHeaderHopByHop || next_header == kNextHeaderRouting ||
+                   next_header == kNextHeaderDestOptions) {
+            if (payload.size() < 2) return {next_header, payload, false};
+            ext_len = (static_cast<std::size_t>(payload[1]) + 1) * 8;
+        } else {
+            break;  // TCP/UDP/ICMPv6/anything else we don't chain through: stop here
+        }
+
+        if (payload.size() < ext_len) return {next_header, payload, false};  // truncated: stop
+
+        std::uint8_t this_next_header = payload[0];
+        payload = payload.subspan(ext_len);
+        next_header = this_next_header;
+    }
+
+    return {next_header, payload, false};
+}
+
+// RFC 5952 canonical text form: lowercase hex, and the longest run of
+// two-or-more consecutive zero groups (leftmost wins a tie) collapsed to
+// "::". A lone zero group is left as "0", not compressed, per 5952 4.2.2.
+inline std::string ipv6_to_string(const Ipv6Address& addr) {
+    std::array<std::uint16_t, 8> groups{};
+    for (std::size_t i = 0; i < 8; ++i) {
+        groups[i] = static_cast<std::uint16_t>((addr.bytes[i * 2] << 8) | addr.bytes[i * 2 + 1]);
+    }
+
+    int best_start = -1;
+    int best_len = 0;
+    int cur_start = -1;
+    int cur_len = 0;
+    for (int i = 0; i < 8; ++i) {
+        if (groups[i] == 0) {
+            if (cur_start < 0) cur_start = i;
+            ++cur_len;
+            if (cur_len > best_len) {
+                best_start = cur_start;
+                best_len = cur_len;
+            }
+        } else {
+            cur_start = -1;
+            cur_len = 0;
+        }
+    }
+    if (best_len < 2) best_start = -1;  // don't compress a lone zero group
+
+    std::string out;
+    char buf[6];
+    for (int i = 0; i < 8; ++i) {
+        if (i == best_start) {
+            out += "::";
+            i += best_len - 1;  // the for-loop's ++i advances past the run
+            continue;
+        }
+        if (!out.empty() && out.back() != ':') out += ':';
+        std::snprintf(buf, sizeof(buf), "%x", groups[i]);
+        out += buf;
+    }
+    return out;
+}
+
+}  // namespace wireframe::net
diff --git a/include/wireframe/net/tcp.hpp b/include/wireframe/net/tcp.hpp
new file mode 100644
index 0000000..f691a7f
--- /dev/null
+++ b/include/wireframe/net/tcp.hpp
@@ -0,0 +1,54 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <span>
+
+#include "wireframe/byteio.hpp"
+
+namespace wireframe::net {
+
+// Lower 6 bits of the flags byte: URG ACK PSH RST SYN FIN. CWR/ECE (the
+// top 2 bits) are masked off - not needed for now.
+inline constexpr std::uint8_t kTcpFin = 0x01;
+inline constexpr std::uint8_t kTcpSyn = 0x02;
+inline constexpr std::uint8_t kTcpRst = 0x04;
+inline constexpr std::uint8_t kTcpPsh = 0x08;
+inline constexpr std::uint8_t kTcpAck = 0x10;
+inline constexpr std::uint8_t kTcpUrg = 0x20;
+
+struct TcpHeader {
+    std::uint16_t src_port;
+    std::uint16_t dst_port;
+    std::uint32_t seq;
+    std::uint32_t ack;
+    std::uint8_t data_offset;  // header length in 32-bit words
+    std::uint8_t flags;
+    std::uint16_t window;
+};
+
+struct TcpSegment {
+    TcpHeader header;
+    std::span<const unsigned char> payload;
+};
+
+inline std::optional<TcpSegment> parse_tcp(std::span<const unsigned char> bytes) {
+    if (bytes.size() < 20) return std::nullopt;
+
+    std::uint8_t data_offset = static_cast<std::uint8_t>(bytes[12] >> 4);
+    std::size_t header_len = static_cast<std::size_t>(data_offset) * 4;
+    if (header_len < 20 || bytes.size() < header_len) return std::nullopt;
+
+    TcpHeader header{};
+    header.src_port = read_be16(bytes, 0);
+    header.dst_port = read_be16(bytes, 2);
+    header.seq = read_be32(bytes, 4);
+    header.ack = read_be32(bytes, 8);
+    header.data_offset = data_offset;
+    header.flags = bytes[13] & 0x3F;
+    header.window = read_be16(bytes, 14);
+
+    return TcpSegment{header, bytes.subspan(header_len)};
+}
+
+}  // namespace wireframe::net
diff --git a/include/wireframe/net/udp.hpp b/include/wireframe/net/udp.hpp
new file mode 100644
index 0000000..07664c2
--- /dev/null
+++ b/include/wireframe/net/udp.hpp
@@ -0,0 +1,35 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <span>
+
+#include "wireframe/byteio.hpp"
+
+namespace wireframe::net {
+
+inline constexpr std::size_t kUdpHeaderLen = 8;
+
+struct UdpHeader {
+    std::uint16_t src_port;
+    std::uint16_t dst_port;
+    std::uint16_t length;
+};
+
+struct UdpDatagram {
+    UdpHeader header;
+    std::span<const unsigned char> payload;
+};
+
+inline std::optional<UdpDatagram> parse_udp(std::span<const unsigned char> bytes) {
+    if (bytes.size() < kUdpHeaderLen) return std::nullopt;
+
+    UdpHeader header{};
+    header.src_port = read_be16(bytes, 0);
+    header.dst_port = read_be16(bytes, 2);
+    header.length = read_be16(bytes, 4);
+
+    return UdpDatagram{header, bytes.subspan(kUdpHeaderLen)};
+}
+
+}  // namespace wireframe::net