diff --git a/.planning/phases/01-capture-and-classification/01-CONTEXT.md b/.planning/phases/01-capture-and-classification/01-CONTEXT.md new file mode 100644 index 0000000..aac3522 --- /dev/null +++ b/.planning/phases/01-capture-and-classification/01-CONTEXT.md @@ -0,0 +1,82 @@ +# Phase 1: Capture and Classification - Context + +**Gathered:** 2026-03-25 +**Status:** Ready for planning + + +## Phase Boundary + +Live packet capture from a network interface, protocol classification into named traffic classes, CLI scaffolding with interface selection and verbose output. No audio synthesis — this phase validates the capture-to-classify pipeline only. + + + + +## Implementation Decisions + +### Protocol mapping +- **D-01:** Deep port map with 10+ classes: ICMP, DNS (53), HTTPS (443), HTTP (80), SSH (22), SMTP (25), NTP (123), DHCP (67/68), other-TCP, other-UDP +- **D-02:** Classification rules stored in a config-driven Go map/struct (not hardcoded switch statements) — designed so rules could later be loaded from a config file +- **D-03:** All unrecognized traffic grouped as a single "unknown" class until Phase 3 adds auto-clustering + +### Privilege model +- **D-04:** Support Linux and macOS (not Windows) +- **D-05:** On permission failure, detect the OS and show platform-specific guidance: `sudo setcap cap_net_raw+ep ...` on Linux, `sudo ...` on macOS +- **D-06:** Prefer static binary with no runtime libpcap dependency — use pure-Go pcap backend (go-pcap) where possible + +### Claude's Discretion +- CLI output formatting during capture (stderr layout, colors, table width) +- Default time window duration for aggregation buckets +- Default network interface selection when `-i` is omitted +- Verbose output format and level of detail + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +No external specs — requirements fully captured in decisions above and in: +- `.planning/PROJECT.md` — Project context, constraints, key decisions +- `.planning/REQUIREMENTS.md` — CAPT-01 through CAPT-04, CLAS-01, CLAS-03, CLAS-04 +- `.planning/research/STACK.md` — Go library recommendations (gopacket fork, go-pcap, cobra) +- `.planning/research/PITFALLS.md` — CAP_NET_RAW silently fails on nosuid mounts, packet buffer overflow, gopacket fork status +- `.planning/research/ARCHITECTURE.md` — Pipeline architecture, component boundaries + + + + +## Existing Code Insights + +### Reusable Assets +- None — greenfield project, no existing code + +### Established Patterns +- None yet — Phase 1 establishes the patterns + +### Integration Points +- Phase 2 will consume classified traffic data (WindowSnapshot structs) from this phase's pipeline +- The classifier's output format directly shapes the synthesis engine's input contract + + + + +## Specific Ideas + +- The tool should feel like tcpdump in its CLI conventions (`-i`, `--list-interfaces`, stderr for stats) +- Protocol classification should be granular enough that the eventual audio output has clear sonic variety — 10+ distinct classes +- Error messages for privilege issues should be immediately actionable, not just "permission denied" + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 01-capture-and-classification* +*Context gathered: 2026-03-25* diff --git a/.planning/phases/01-capture-and-classification/01-DISCUSSION-LOG.md b/.planning/phases/01-capture-and-classification/01-DISCUSSION-LOG.md new file mode 100644 index 0000000..40eaaef --- /dev/null +++ b/.planning/phases/01-capture-and-classification/01-DISCUSSION-LOG.md @@ -0,0 +1,95 @@ +# Phase 1: Capture and Classification - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-03-25 +**Phase:** 1-capture-and-classification +**Areas discussed:** Protocol mapping, Privilege model + +--- + +## Protocol mapping + +### Q1: How granular should protocol classification be? + +| Option | Description | Selected | +|--------|-------------|----------| +| Port-aware | ICMP, DNS (53), HTTPS (443), HTTP (80), SSH (22), other-TCP, other-UDP — 7 classes | | +| Protocol-only | ICMP, TCP, UDP, DNS — 4 broad classes, simpler but less distinctive | | +| Deep port map | ICMP, DNS, HTTPS, HTTP, SSH, SMTP, NTP, DHCP, other-TCP, other-UDP — 10+ classes | ✓ | + +**User's choice:** Deep port map +**Notes:** User wants maximum sonic variety from the classification layer. + +### Q2: Should the classifier be extensible or hardcoded? + +| Option | Description | Selected | +|--------|-------------|----------| +| Hardcoded table | Map in code: port/proto → class name. Simple, fast | | +| Config-driven | Rules in a Go map/struct that could later be loaded from file | ✓ | +| You decide | Claude picks the approach | | + +**User's choice:** Config-driven +**Notes:** Extensibility for future custom mappings. + +### Q3: How should unknown traffic be labeled before Phase 3 auto-clustering? + +| Option | Description | Selected | +|--------|-------------|----------| +| Single "unknown" | All unrecognized traffic grouped as one class | ✓ | +| Unknown by proto | "unknown-tcp" and "unknown-udp" as separate buckets | | +| You decide | Claude picks | | + +**User's choice:** Single "unknown" +**Notes:** None. + +--- + +## Privilege model + +### Q1: Which platforms should be supported? + +| Option | Description | Selected | +|--------|-------------|----------| +| Linux only | Simplest — CAP_NET_RAW or sudo | | +| Linux + macOS | macOS uses BPF devices, different privilege model | ✓ | +| All major | Linux + macOS + Windows — significantly more work | | + +**User's choice:** Linux + macOS +**Notes:** None. + +### Q2: How should the tool handle insufficient privileges? + +| Option | Description | Selected | +|--------|-------------|----------| +| Detect and guide | Detect OS, show platform-specific fix instructions | ✓ | +| Just suggest sudo | Simple 'try running with sudo' message | | +| You decide | Claude picks | | + +**User's choice:** Detect and guide +**Notes:** Platform-specific actionable error messages. + +### Q3: Static or dynamic linking? + +| Option | Description | Selected | +|--------|-------------|----------| +| Static preferred | Single binary, no libpcap needed at runtime | ✓ | +| Dynamic is fine | Users install libpcap-dev | | +| You decide | Claude picks based on what's practical | | + +**User's choice:** Static preferred +**Notes:** Aligns with single-binary distribution goal. + +--- + +## Claude's Discretion + +- CLI output formatting (stderr layout, colors, table width) +- Default time window duration +- Default interface selection when `-i` omitted +- Verbose output format and detail level + +## Deferred Ideas + +None — discussion stayed within phase scope.