docs(01): capture phase context
This commit is contained in:
@@ -0,0 +1,82 @@
|
||||
# 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*
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user