83 lines
3.1 KiB
Markdown
83 lines
3.1 KiB
Markdown
|
# Phase 1: Capture and Classification - Context
|
||
|
|
|
||
|
|
**Gathered:** 2026-03-25
|
||
|
|
**Status:** Ready for planning
|
||
|
|
|
||
|
|
<domain>
|
||
|
|
## 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.
|
||
|
|
|
||
|
|
</domain>
|
||
|
|
|
||
|
|
<decisions>
|
||
|
|
## 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
|
||
|
|
|
||
|
|
</decisions>
|
||
|
|
|
||
|
|
<canonical_refs>
|
||
|
|
## 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
|
||
|
|
|
||
|
|
</canonical_refs>
|
||
|
|
|
||
|
|
<code_context>
|
||
|
|
## 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
|
||
|
|
|
||
|
|
</code_context>
|
||
|
|
|
||
|
|
<specifics>
|
||
|
|
## 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"
|
||
|
|
|
||
|
|
</specifics>
|
||
|
|
|
||
|
|
<deferred>
|
||
|
|
## Deferred Ideas
|
||
|
|
|
||
|
|
None — discussion stayed within phase scope
|
||
|
|
|
||
|
|
</deferred>
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
*Phase: 01-capture-and-classification*
|
||
|
|
*Context gathered: 2026-03-25*
|