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)

4 files changed, 405 insertions, 0 deletions

diff --git a/include/wireframe/l7/dissector.hpp b/include/wireframe/l7/dissector.hpp
new file mode 100644
index 0000000..9b2cc32
--- /dev/null
+++ b/include/wireframe/l7/dissector.hpp
@@ -0,0 +1,45 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <span>
+#include <string>
+#include <vector>
+
+// Small interface/vtable for L7 dissectors (PLAN.md's architecture
+// sketch), so protocols can be registered and added incrementally
+// without touching the L2-L4 decode path or main.cpp's dispatch logic.
+namespace wireframe::net {
+
+class L7Dissector {
+public:
+    virtual ~L7Dissector() = default;
+
+    // The transport port this dissector claims (e.g. 53 for DNS). A
+    // single fixed port is enough for the protocols in scope so far;
+    // dissectors needing a port range or heuristic sniffing can widen
+    // this later without changing the registry's shape.
+    virtual std::uint16_t port() const = 0;
+
+    // A one-line summary of the payload, or nullopt if it doesn't look
+    // like this protocol (e.g. truncated/malformed).
+    virtual std::optional<std::string> summarize(std::span<const unsigned char> payload) const = 0;
+};
+
+class L7Registry {
+public:
+    void add(const L7Dissector* dissector) { dissectors_.push_back(dissector); }
+
+    std::optional<std::string> dissect(std::uint16_t port,
+                                        std::span<const unsigned char> payload) const {
+        for (const auto* dissector : dissectors_) {
+            if (dissector->port() == port) return dissector->summarize(payload);
+        }
+        return std::nullopt;
+    }
+
+private:
+    std::vector<const L7Dissector*> dissectors_;
+};
+
+}  // namespace wireframe::net
diff --git a/include/wireframe/l7/dns.hpp b/include/wireframe/l7/dns.hpp
new file mode 100644
index 0000000..5c1ab36
--- /dev/null
+++ b/include/wireframe/l7/dns.hpp
@@ -0,0 +1,108 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <span>
+#include <string>
+#include <utility>
+
+#include "wireframe/byteio.hpp"
+#include "wireframe/l7/dissector.hpp"
+
+// Hand-rolled DNS message parsing: header + the first question record.
+// Answer/authority/additional records aren't decoded (not needed for a
+// one-line summary), so name-compression pointers there are never
+// followed - a pointer in the question section itself is rejected
+// rather than chased, keeping this a pure forward scan with no risk of
+// a pointer loop.
+namespace wireframe::net {
+
+inline constexpr std::uint16_t kDnsPort = 53;
+
+struct DnsHeader {
+    std::uint16_t id;
+    bool is_response;
+    std::uint8_t opcode;
+    std::uint8_t rcode;
+    std::uint16_t qdcount;
+    std::uint16_t ancount;
+};
+
+struct DnsQuestion {
+    std::string name;
+    std::uint16_t qtype;
+};
+
+struct DnsMessage {
+    DnsHeader header;
+    std::optional<DnsQuestion> question;  // first question only
+};
+
+// Reads a (possibly multi-label) dotted name starting at offset.
+// Returns the name and the offset just past it, or nullopt on
+// truncation or a compression pointer (0xC0 prefix - valid in
+// answer/authority records, not supported here).
+inline std::optional<std::pair<std::string, std::size_t>> read_dns_name(
+    std::span<const unsigned char> bytes, std::size_t offset) {
+    std::string name;
+    while (true) {
+        if (offset >= bytes.size()) return std::nullopt;
+        std::uint8_t len = bytes[offset];
+        if (len == 0) {
+            ++offset;
+            break;
+        }
+        if ((len & 0xC0) == 0xC0) return std::nullopt;  // compression pointer: unsupported
+        ++offset;
+        if (offset + len > bytes.size()) return std::nullopt;
+        if (!name.empty()) name += '.';
+        for (std::uint8_t i = 0; i < len; ++i) name += static_cast<char>(bytes[offset + i]);
+        offset += len;
+    }
+    return std::make_pair(std::move(name), offset);
+}
+
+inline std::optional<DnsMessage> parse_dns(std::span<const unsigned char> bytes) {
+    if (bytes.size() < 12) return std::nullopt;
+
+    DnsHeader header{};
+    header.id = read_be16(bytes, 0);
+    std::uint16_t flags = read_be16(bytes, 2);
+    header.is_response = (flags & 0x8000) != 0;
+    header.opcode = static_cast<std::uint8_t>((flags >> 11) & 0x0F);
+    header.rcode = static_cast<std::uint8_t>(flags & 0x0F);
+    header.qdcount = read_be16(bytes, 4);
+    header.ancount = read_be16(bytes, 6);
+
+    DnsMessage msg{header, std::nullopt};
+    if (header.qdcount >= 1) {
+        if (auto result = read_dns_name(bytes, 12)) {
+            auto& [name, next_offset] = *result;
+            if (next_offset + 4 <= bytes.size()) {
+                msg.question = DnsQuestion{std::move(name), read_be16(bytes, next_offset)};
+            }
+        }
+    }
+    return msg;
+}
+
+class DnsDissector : public L7Dissector {
+public:
+    std::uint16_t port() const override { return kDnsPort; }
+
+    std::optional<std::string> summarize(std::span<const unsigned char> payload) const override {
+        auto msg = parse_dns(payload);
+        if (!msg) return std::nullopt;
+
+        std::string out = "DNS ";
+        out += msg->header.is_response ? "response" : "query";
+        out += " id=" + std::to_string(msg->header.id);
+        if (msg->header.is_response) out += " ancount=" + std::to_string(msg->header.ancount);
+        if (msg->question) {
+            out += " " + msg->question->name + " type=" + std::to_string(msg->question->qtype);
+        }
+        return out;
+    }
+};
+
+}  // namespace wireframe::net
diff --git a/include/wireframe/l7/http.hpp b/include/wireframe/l7/http.hpp
new file mode 100644
index 0000000..4780b23
--- /dev/null
+++ b/include/wireframe/l7/http.hpp
@@ -0,0 +1,113 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <span>
+#include <string>
+#include <string_view>
+
+#include "wireframe/l7/dissector.hpp"
+
+// Best-effort, single-segment HTTP/1.x request/status-line parsing (plus
+// the Host: header for requests). No TCP stream reassembly, so a
+// message split across multiple packets is only partially visible here
+// - the same scope DNS already has (single UDP datagram, no
+// reassembly). Good enough for a one-line summary, not a full dissector.
+namespace wireframe::net {
+
+inline constexpr std::uint16_t kHttpPort = 80;
+
+struct HttpMessage {
+    bool is_request;
+    std::string method_or_version;  // request: method (GET); response: "HTTP/1.1"
+    std::string target_or_status;   // request: target path; response: status code
+    std::optional<std::string> host;  // request only, from a Host: header if present
+};
+
+inline std::optional<HttpMessage> parse_http(std::span<const unsigned char> payload) {
+    std::string_view text(reinterpret_cast<const char*>(payload.data()), payload.size());
+
+    std::size_t line_end = text.find("\r\n");
+    std::size_t term_len = 2;
+    if (line_end == std::string_view::npos) {
+        line_end = text.find('\n');
+        term_len = 1;
+        if (line_end == std::string_view::npos) return std::nullopt;
+    }
+    std::string_view first_line = text.substr(0, line_end);
+
+    std::size_t sp1 = first_line.find(' ');
+    if (sp1 == std::string_view::npos) return std::nullopt;
+    std::size_t sp2 = first_line.find(' ', sp1 + 1);
+    if (sp2 == std::string_view::npos) return std::nullopt;
+
+    std::string_view field1 = first_line.substr(0, sp1);
+    std::string_view field2 = first_line.substr(sp1 + 1, sp2 - sp1 - 1);
+
+    HttpMessage msg;
+
+    if (field1.substr(0, 5) == "HTTP/") {
+        msg.is_request = false;
+        msg.method_or_version = std::string(field1);
+        msg.target_or_status = std::string(field2);
+        return msg;
+    }
+
+    static constexpr std::string_view kMethods[] = {"GET",     "POST",  "PUT",     "DELETE",
+                                                      "HEAD",    "OPTIONS", "PATCH", "CONNECT",
+                                                      "TRACE"};
+    bool known_method = false;
+    for (auto method : kMethods) {
+        if (field1 == method) {
+            known_method = true;
+            break;
+        }
+    }
+    if (!known_method) return std::nullopt;
+
+    msg.is_request = true;
+    msg.method_or_version = std::string(field1);
+    msg.target_or_status = std::string(field2);
+
+    // Best-effort Host: header scan, bounded by whatever this one
+    // packet contains and terminated at the first blank line (end of
+    // headers) or the end of the payload - never loops past text.size().
+    std::size_t pos = line_end + term_len;
+    while (pos < text.size()) {
+        std::size_t next_end = text.find("\r\n", pos);
+        std::size_t header_len = (next_end == std::string_view::npos) ? text.size() - pos
+                                                                        : next_end - pos;
+        std::string_view header_line = text.substr(pos, header_len);
+        if (header_line.empty()) break;  // blank line: end of headers
+
+        if (header_line.size() > 5 &&
+            (header_line.substr(0, 5) == "Host:" || header_line.substr(0, 5) == "host:")) {
+            std::size_t value_start = 5;
+            while (value_start < header_line.size() && header_line[value_start] == ' ') {
+                ++value_start;
+            }
+            msg.host = std::string(header_line.substr(value_start));
+        }
+
+        if (next_end == std::string_view::npos) break;
+        pos = next_end + 2;
+    }
+
+    return msg;
+}
+
+class HttpDissector : public L7Dissector {
+public:
+    std::uint16_t port() const override { return kHttpPort; }
+
+    std::optional<std::string> summarize(std::span<const unsigned char> payload) const override {
+        auto msg = parse_http(payload);
+        if (!msg) return std::nullopt;
+
+        std::string out = "HTTP " + msg->method_or_version + " " + msg->target_or_status;
+        if (msg->host) out += " Host: " + *msg->host;
+        return out;
+    }
+};
+
+}  // namespace wireframe::net
diff --git a/include/wireframe/l7/tls.hpp b/include/wireframe/l7/tls.hpp
new file mode 100644
index 0000000..1c6dc57
--- /dev/null
+++ b/include/wireframe/l7/tls.hpp
@@ -0,0 +1,139 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <span>
+#include <string>
+
+#include "wireframe/byteio.hpp"
+#include "wireframe/l7/dissector.hpp"
+
+// TLS ClientHello -> SNI extension parsing. Most web traffic is TLS
+// today, so HTTP alone covers a shrinking fraction of it - SNI is what
+// makes a packet analyzer useful against that traffic without
+// decrypting anything: the server name is sent in cleartext in the
+// ClientHello, before any encryption starts, in every TLS version this
+// parses (the ClientHello/extension wire format hasn't changed across
+// versions - only what happens after it has).
+//
+// Same scope as the other L7 dissectors: single-segment, best-effort.
+// A ClientHello padded across multiple TCP segments (large cookie/PSK
+// extensions, unusual but possible) is only partially visible here.
+// Every length field is bounds-checked against what's actually left in
+// the buffer before use - this is exactly the kind of nested,
+// attacker-influenced TLV structure the project's decoders are meant
+// to get right.
+namespace wireframe::net {
+
+inline constexpr std::uint16_t kTlsPort = 443;
+inline constexpr std::uint8_t kTlsContentTypeHandshake = 0x16;
+inline constexpr std::uint8_t kTlsHandshakeTypeClientHello = 0x01;
+inline constexpr std::uint16_t kTlsExtensionServerName = 0x0000;
+
+struct TlsClientHello {
+    std::optional<std::string> server_name;  // SNI, if the extension was present and well-formed
+};
+
+inline std::optional<TlsClientHello> parse_tls_client_hello(std::span<const unsigned char> bytes) {
+    // Record header: ContentType(1) ProtocolVersion(2) Length(2)
+    if (bytes.size() < 5) return std::nullopt;
+    if (bytes[0] != kTlsContentTypeHandshake) return std::nullopt;
+    std::uint16_t record_len = read_be16(bytes, 3);
+    if (bytes.size() < static_cast<std::size_t>(5) + record_len) return std::nullopt;
+
+    std::span<const unsigned char> handshake = bytes.subspan(5);
+
+    // Handshake header: HandshakeType(1) Length(3, 24-bit BE)
+    if (handshake.size() < 4) return std::nullopt;
+    if (handshake[0] != kTlsHandshakeTypeClientHello) return std::nullopt;
+    std::uint32_t hs_len = (static_cast<std::uint32_t>(handshake[1]) << 16) |
+                            (static_cast<std::uint32_t>(handshake[2]) << 8) |
+                            static_cast<std::uint32_t>(handshake[3]);
+
+    std::span<const unsigned char> body = handshake.subspan(4);
+    if (body.size() < hs_len) return std::nullopt;
+    body = body.first(hs_len);  // never read past the declared handshake body
+
+    std::size_t offset = 0;
+
+    // client_version(2) + random(32)
+    if (body.size() < offset + 34) return std::nullopt;
+    offset += 34;
+
+    // legacy_session_id: length(1) + data
+    if (body.size() < offset + 1) return std::nullopt;
+    std::uint8_t session_id_len = body[offset];
+    offset += 1;
+    if (body.size() < offset + session_id_len) return std::nullopt;
+    offset += session_id_len;
+
+    // cipher_suites: length(2) + data
+    if (body.size() < offset + 2) return std::nullopt;
+    std::uint16_t cipher_suites_len = read_be16(body, offset);
+    offset += 2;
+    if (body.size() < static_cast<std::size_t>(offset) + cipher_suites_len) return std::nullopt;
+    offset += cipher_suites_len;
+
+    // legacy_compression_methods: length(1) + data
+    if (body.size() < offset + 1) return std::nullopt;
+    std::uint8_t compression_len = body[offset];
+    offset += 1;
+    if (body.size() < offset + compression_len) return std::nullopt;
+    offset += compression_len;
+
+    TlsClientHello hello;
+    if (offset == body.size()) return hello;  // no extensions block: no SNI, still a valid hello
+
+    // extensions: length(2) + data
+    if (body.size() < offset + 2) return std::nullopt;
+    std::uint16_t extensions_len = read_be16(body, offset);
+    offset += 2;
+    if (body.size() < static_cast<std::size_t>(offset) + extensions_len) return std::nullopt;
+    std::size_t extensions_end = offset + extensions_len;
+
+    while (offset + 4 <= extensions_end) {
+        std::uint16_t ext_type = read_be16(body, offset);
+        std::uint16_t ext_len = read_be16(body, offset + 2);
+        std::size_t ext_data_start = offset + 4;
+        std::size_t ext_data_end = ext_data_start + ext_len;
+        if (ext_data_end > extensions_end) break;  // malformed: stop, keep what we have
+
+        if (ext_type == kTlsExtensionServerName && ext_len >= 2) {
+            // ServerNameList: list_len(2) + entries; only the first
+            // entry is used, matching every real client's behavior of
+            // sending exactly one host_name entry.
+            std::uint16_t list_len = read_be16(body, ext_data_start);
+            std::size_t list_start = ext_data_start + 2;
+            std::size_t list_end = list_start + list_len;
+            if (list_end <= ext_data_end && list_start + 3 <= list_end) {
+                std::uint8_t name_type = body[list_start];
+                std::uint16_t name_len = read_be16(body, list_start + 1);
+                std::size_t name_start = list_start + 3;
+                if (name_type == 0 && name_start + name_len <= list_end) {
+                    hello.server_name = std::string(
+                        reinterpret_cast<const char*>(body.data() + name_start), name_len);
+                }
+            }
+        }
+
+        offset = ext_data_end;
+    }
+
+    return hello;
+}
+
+class TlsSniDissector : public L7Dissector {
+public:
+    std::uint16_t port() const override { return kTlsPort; }
+
+    std::optional<std::string> summarize(std::span<const unsigned char> payload) const override {
+        auto hello = parse_tls_client_hello(payload);
+        if (!hello) return std::nullopt;
+
+        std::string out = "TLS ClientHello";
+        if (hello->server_name) out += " SNI=" + *hello->server_name;
+        return out;
+    }
+};
+
+}  // namespace wireframe::net