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_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>

## 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

3.1 KiB Raw Blame History