srdusr
aboutsummaryrefslogtreecommitdiffstats
path: root/PLAN.md
diff options
context:
space:
mode:
authorsrdusr <[email protected]>2024-05-27 22:00:00 +0200
committersrdusr <[email protected]>2024-05-27 22:00:00 +0200
commitb565d7d9c47ca1ec5af0effd828431ee96027d60 (patch)
treefbe0c9c897e78f507443507354d5b1d8fb851099 /PLAN.md
parentfbedc55d5aa861c381701c9f913b34ee7ab57ec4 (diff)
downloadpacketeer-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.md42
1 files changed, 21 insertions, 21 deletions
diff --git a/PLAN.md b/PLAN.md
index 6defe1d..20450d1 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -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