diff options
| author | srdusr <[email protected]> | 2024-05-27 22:00:00 +0200 |
|---|---|---|
| committer | srdusr <[email protected]> | 2024-05-27 22:00:00 +0200 |
| commit | b565d7d9c47ca1ec5af0effd828431ee96027d60 (patch) | |
| tree | fbe0c9c897e78f507443507354d5b1d8fb851099 /PLAN.md | |
| parent | fbedc55d5aa861c381701c9f913b34ee7ab57ec4 (diff) | |
| download | packeteer-b565d7d9c47ca1ec5af0effd828431ee96027d60.tar.gz packeteer-b565d7d9c47ca1ec5af0effd828431ee96027d60.zip | |
Rename project from wireframe to packeteer
Decided on the name after weighing alternatives in NAMES.md: packeteer
(packet + -eer, "one who wields packets") fit the project's actual
scope better than the wire/frame pun once it had grown into full
L2-L7 dissection, reassembly, checksums, privilege dropping, and dual
TUI/GUI frontends. No existing packet-capture project uses the name;
the one real-world collision (Packeteer, Inc., a networking company
acquired and folded into Blue Coat/Symantec by 2008) is long defunct.
Mechanical rename throughout: CMake project/target names, the
wireframe:: namespace and include/wireframe/ directory (git mv,
history preserved), every #include path, CLI/GUI help text, and the
project's own working directory. NAMES.md rewritten to record the
decision instead of leaving stale self-referential etymology behind
from the blind rename pass.
Verified after every step: full rebuild (all four targets, no
warnings) and the full test suite (128/128 cases, 366/366 assertions)
both from a fresh reconfigure and again after the directory move.
Diffstat (limited to 'PLAN.md')
| -rw-r--r-- | PLAN.md | 42 |
1 files changed, 21 insertions, 21 deletions
@@ -1,4 +1,4 @@ -# wireframe - Packet Analyzer / Network TUI +# packeteer - Packet Analyzer / Network TUI ## Overview Terminal packet capture and analysis tool. Primary goal: learn the C++ @@ -31,7 +31,7 @@ unowned buffers) via a real-world capture pipeline. 4. [done] Bounded channel + drop-on-backpressure between capture and render 5. [in progress] L7 dissector interface, add protocols incrementally -- interface + DNS + HTTP + TLS SNI + mDNS + SSH banner done - (wireframe/l7/); more protocols can still be added incrementally, + (packeteer/l7/); more protocols can still be added incrementally, by design 6. [done] Filtering (-f <expr>, libpcap's own BPF compiler - see Decisions) 7. [done] Drop privileges after opening the capture handle (see Decisions) @@ -55,20 +55,20 @@ None currently open. OpenGL3 - avoids needing a separate GL function loader as another dependency, which matters more here than raw rendering performance does. src/gui_main.cpp; parity with the CLI/TUI is structural, not - incidental - all three go through the same wireframe::CaptureSession - (wireframe/capture_session.hpp) for device-open/datalink-validate/ + incidental - all three go through the same packeteer::CaptureSession + (packeteer/capture_session.hpp) for device-open/datalink-validate/ filter/pcapng/signal-handler setup, so the GUI can't silently skip a step (e.g. the DLT_RAW check) the way two hand-copied setups would eventually drift. -- Tests: doctest (v2.5.3, FetchContent), tests/ mirrors include/wireframe/. +- Tests: doctest (v2.5.3, FetchContent), tests/ mirrors include/packeteer/. Every module gets unit tests as it's built, not backfilled later -- - `cmake --build build && ./build/wireframe_tests` (or `ctest`) should + `cmake --build build && ./build/packeteer_tests` (or `ctest`) should stay green at every commit. - Filtering: libpcap's own pcap_compile()/pcap_setfilter() (tcpdump syntax, kernel-level via BPF), not a hand-rolled parser - the parser/compiler already exists, is correct, and reimplementing it has no bearing on this project's actual goal (the C++ memory model). - wireframe/filter.hpp wraps compilation; testable without root via + packeteer/filter.hpp wraps compilation; testable without root via pcap_open_dead(). Verified live: -f "tcp port N" and -f icmp each correctly suppressed non-matching traffic that was actually present. - pcap_stats(): CaptureSession::stats() surfaces kernel/interface-level @@ -79,7 +79,7 @@ None currently open. kernel had already received but that were never dispatched to our callback before shutdown, with queue-side drops at 0 throughout. - Fuzzing: libFuzzer harnesses (fuzz/, clang + ASan/UBSan, opt-in via - -DWIREFRAME_ENABLE_FUZZING=ON -DCMAKE_CXX_COMPILER=clang++, separate + -DPACKETEER_ENABLE_FUZZING=ON -DCMAKE_CXX_COMPILER=clang++, separate build-fuzz/ dir) for every hand-rolled decoder plus the pcapng reader and the full summarize_packet() pipeline - the highest-value tests in the repo given the project's actual goal (byte layout/alignment/ @@ -93,7 +93,7 @@ None currently open. in with both a unit test and a passing re-fuzz of the exact crashing input. ~23M total fuzz executions across all 8 harnesses this session, one bug found and fixed, zero remaining crashes. -- HTTP L7 dissector (wireframe/l7/http.hpp): best-effort single-segment +- HTTP L7 dissector (packeteer/l7/http.hpp): best-effort single-segment request/status-line parse (+ Host: header for requests), same scope DNS already has - no TCP stream reassembly, so a message split across packets is only partially visible. This is the first @@ -106,7 +106,7 @@ None currently open. (fuzz_http.cpp, 5.3M runs, no crashes) since the string_view request- line/header scanning is new hand-rolled logic distinct from anything fuzz_summarize's binary-format parsers already cover. -- TLS SNI L7 dissector (wireframe/l7/tls.hpp): parses a ClientHello's +- TLS SNI L7 dissector (packeteer/l7/tls.hpp): parses a ClientHello's record/handshake/extensions structure (nested TLVs, every length bounds-checked against attacker-influenced fields at every level -- the most structurally complex hand-rolled parser in the project) to @@ -134,7 +134,7 @@ None currently open. (extended fuzz_ipv6.cpp, 6.3M runs; fuzz_summarize.cpp indirectly covers it too, 4.3M more) - no crashes. This was the last item on the known-gaps list; none remain. -- Post-capture search: wireframe/search.hpp's matches_search() is a +- Post-capture search: packeteer/search.hpp's matches_search() is a display filter, deliberately distinct from -f's capture filter -- -f decides what's captured (and written to -w); search decides what's shown, without touching either, same distinction Wireshark draws @@ -189,7 +189,7 @@ None currently open. now-static list, and 'q' closes it; Xvfb confirmed the same for the GUI, including a live process check across a multi-second wait to rule out a delayed auto-close. -- Privilege dropping (wireframe/privileges.hpp): after pcap_open_live() +- Privilege dropping (packeteer/privileges.hpp): after pcap_open_live() succeeds - the only operation that actually needs CAP_NET_RAW - and before the datalink check or a -w file is even created, drop from root to the invoking user via sudo's SUDO_UID/SUDO_GID. setuid() to a @@ -213,7 +213,7 @@ None currently open. whole point of "drop after open"). Separately verified the setcap-without-sudo path works with zero privilege escalation at any point in the process's life. -- AF_PACKET/mmap ring buffer (src/afpacket_capture.cpp, wireframe_afpacket_demo, +- AF_PACKET/mmap ring buffer (src/afpacket_capture.cpp, packeteer_afpacket_demo, Linux-only): PLAN.md's originally-listed alternative capture backend, built as a standalone artifact rather than swapped into CaptureSession - the existing pipeline has real, tested value riding on libpcap's @@ -232,7 +232,7 @@ None currently open. ICMPv6 all decoded correctly across a large volume of genuine traffic, no crashes, no leaked sockets/mappings after exit, tests and the rest of the build entirely unaffected by its addition. -- ICMP decoding (wireframe/net/icmp.hpp): previously every ICMPv4 +- ICMP decoding (packeteer/net/icmp.hpp): previously every ICMPv4 packet just showed "proto=1" with nothing further - no dissector existed at all - despite ICMP being most of this session's own test traffic (every ping). ICMPv6 was labeled but not decoded either. @@ -248,12 +248,12 @@ None currently open. and ::1 (proto=58) - request/reply pairs decoded correctly on both, including matching identifier/sequence numbers between each request and its reply. -- -h/--help: both wireframe and wireframe_gui now print real usage +- -h/--help: both packeteer and packeteer_gui now print real usage text (each binary's actual flag set - the GUI never had -x/-t/-g, so its help doesn't claim it does) and exit 0 before touching a device or any privilege at all. Previously -x -t -w -f -g -r all existed with zero discoverability outside reading the source. -- Checksum validation (wireframe/net/checksum.hpp): RFC 1071 Internet +- Checksum validation (packeteer/net/checksum.hpp): RFC 1071 Internet checksum, plus IPv4-header/TCP/UDP verification built on it (IPv6 checksums use a different pseudo-header and different optionality rules - not done here, a reasonable follow-on if wanted). UDP's @@ -279,7 +279,7 @@ None currently open. hardware, not a gap in the reasoning: most real NICs ship tx-checksum offload on by default, which is exactly the scenario -c's opt-in-ness is meant to keep from reading as false positives. -- TCP stream reassembly (wireframe/net/tcp_reassembly.hpp): in-order-only +- TCP stream reassembly (packeteer/net/tcp_reassembly.hpp): in-order-only - out-of-order segments and retransmissions are dropped, not buffered for later reordering. A real limitation, but an honest one for a learning tool captured directly on an endpoint (lo/wlp1s0/tailscale0, @@ -295,7 +295,7 @@ None currently open. TcpReassembler instance lives in main(), and render_packet() does its own minimal Ethernet/IPv4/TCP walk (mirroring checksum_status()) to feed segments in and, when new contiguous bytes come back, re-runs - parse_http() (wireframe/l7/http.hpp) against the joined stream and + parse_http() (packeteer/l7/http.hpp) against the joined stream and prints the result as a distinct "[reassembled ...]" line, not folded into the per-packet summary. Deliberately calls parse_http() directly rather than going through L7Registry, so it isn't gated to port 80 the @@ -315,8 +315,8 @@ None currently open. bounded memory use. - GUI parity for -c/-a: checksum_status() and reassembled_http_status() moved out of main.cpp into a new shared header - (wireframe/packet_diagnostics.hpp) rather than duplicated into - gui_main.cpp - the same reasoning wireframe::CaptureSession exists + (packeteer/packet_diagnostics.hpp) rather than duplicated into + gui_main.cpp - the same reasoning packeteer::CaptureSession exists for at the setup layer, applied here to the diagnostics layer. GUI's hex dump was already always-on for the selected row (no -x-equivalent flag needed); checksum status is computed lazily when a row is @@ -336,7 +336,7 @@ None currently open. a bug - Linux's loopback receive path typically never computes a real TCP checksum at all (CHECKSUM_UNNECESSARY), which is exactly the false-positive scenario -c's opt-in-ness exists to guard against. -- mDNS (wireframe/l7/mdns.hpp) and SSH banner (wireframe/l7/ssh.hpp) +- mDNS (packeteer/l7/mdns.hpp) and SSH banner (packeteer/l7/ssh.hpp) dissectors, registered alongside DNS/HTTP/TLS in l7_registry(). mDNS reuses parse_dns() outright - RFC 6762 keeps DNS's exact wire format, just over UDP 5353 instead of 53 - and deliberately omits |