chore: archive v1.0 MVP milestone
Archive roadmap and requirements to milestones/, reorganize ROADMAP.md, evolve PROJECT.md with shipped state, create retrospective. 4 phases, 11 plans, 16/16 requirements — all complete. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -0,0 +1,102 @@
|
||||
# Requirements Archive: v1.0 MVP
|
||||
|
||||
**Archived:** 2026-03-26
|
||||
**Status:** SHIPPED
|
||||
|
||||
For current requirements, see `.planning/REQUIREMENTS.md`.
|
||||
|
||||
---
|
||||
|
||||
# Requirements: NetSynth
|
||||
|
||||
**Defined:** 2026-03-24
|
||||
**Core Value:** Network traffic patterns are instantly recognizable as distinct sounds — a ping sounds different from HTTPS noise, which sounds different from a port scan.
|
||||
|
||||
## v1 Requirements
|
||||
|
||||
Requirements for initial release. Each maps to roadmap phases.
|
||||
|
||||
### Packet Capture
|
||||
|
||||
- [x] **CAPT-01**: User can specify network interface via `-i` flag
|
||||
- [x] **CAPT-02**: User can list available network interfaces via `--list-interfaces`
|
||||
- [x] **CAPT-03**: Capture runs until user presses Ctrl+C, then gracefully flushes and saves MP3
|
||||
- [x] **CAPT-04**: User sees a clear actionable error message when lacking capture privileges (sudo/CAP_NET_RAW hint)
|
||||
- [x] **CAPT-05**: User can filter captured traffic using BPF syntax via `--filter` flag
|
||||
- [x] **CAPT-06**: User can sonify a pcap file instead of live traffic via `--read` flag
|
||||
|
||||
### Traffic Classification
|
||||
|
||||
- [x] **CLAS-01**: Known protocols (ICMP, DNS, TCP/443, TCP/other, UDP, SSH) each produce a distinct recognizable sound
|
||||
- [x] **CLAS-02**: Unrecognized traffic is auto-clustered and assigned unique tones automatically
|
||||
- [x] **CLAS-03**: On exit, user sees a summary of packet counts and protocol breakdown (printed to stderr)
|
||||
- [x] **CLAS-04**: User can enable per-window protocol activity log via `--verbose` flag
|
||||
|
||||
### Audio Synthesis
|
||||
|
||||
- [x] **SYNTH-01**: Each traffic class generates a distinct ambient/drone layer (layered sine/harmonic waves)
|
||||
- [x] **SYNTH-02**: Drone layer amplitudes evolve over time windows based on traffic volume per class
|
||||
- [x] **SYNTH-03**: Multiple drone layers are mixed into a single coherent audio stream without distortion
|
||||
|
||||
### Output
|
||||
|
||||
- [x] **OUT-01**: User can specify output file path via `-o` flag (defaults to `netsynth-<timestamp>.mp3`)
|
||||
- [x] **OUT-02**: Output is encoded as a valid MP3 file
|
||||
- [x] **OUT-03**: Empty captures (zero packets) produce a clear error instead of a corrupt file
|
||||
|
||||
## v2 Requirements
|
||||
|
||||
Deferred to future release. Tracked but not in current roadmap.
|
||||
|
||||
### Audio Tuning
|
||||
|
||||
- **TUNE-01**: User can configure time window duration via `--window` flag
|
||||
- **TUNE-02**: User can configure output duration when reading pcap files via `--duration` flag
|
||||
- **TUNE-03**: User can customize sound mappings via configuration file
|
||||
|
||||
### Distribution
|
||||
|
||||
- **DIST-01**: Single static binary with no runtime dependencies
|
||||
|
||||
## Out of Scope
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Real-time audio playback | Platform audio API complexity triples scope; users can pipe MP3 to mpv/afplay |
|
||||
| GUI or web dashboard | Negates single-binary CLI value; doubles scope |
|
||||
| Rhythmic/percussive output | Ambient/drone is the deliberate differentiator |
|
||||
| Deep packet inspection | Massive complexity; header-level classification sufficient for audio fingerprint |
|
||||
| Anomaly detection/alerting | Different user job; stick to audio fingerprint |
|
||||
| Streaming MP3 output | MP3 VBR headers require finalization; buffer-then-encode is correct |
|
||||
|
||||
## Traceability
|
||||
|
||||
Which phases cover which requirements. Updated during roadmap creation.
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| CAPT-01 | Phase 1 | Complete |
|
||||
| CAPT-02 | Phase 1 | Complete |
|
||||
| CAPT-03 | Phase 3 | Complete |
|
||||
| CAPT-04 | Phase 1 | Complete |
|
||||
| CAPT-05 | Phase 4 | Complete |
|
||||
| CAPT-06 | Phase 4 | Complete |
|
||||
| CLAS-01 | Phase 1 | Complete |
|
||||
| CLAS-02 | Phase 3 | Complete |
|
||||
| CLAS-03 | Phase 1 | Complete |
|
||||
| CLAS-04 | Phase 1 | Complete |
|
||||
| SYNTH-01 | Phase 2 | Complete |
|
||||
| SYNTH-02 | Phase 2 | Complete |
|
||||
| SYNTH-03 | Phase 2 | Complete |
|
||||
| OUT-01 | Phase 2 | Complete |
|
||||
| OUT-02 | Phase 2 | Complete |
|
||||
| OUT-03 | Phase 2 | Complete |
|
||||
|
||||
**Coverage:**
|
||||
- v1 requirements: 16 total
|
||||
- Mapped to phases: 16
|
||||
- Unmapped: 0
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-03-24*
|
||||
*Last updated: 2026-03-24 after roadmap creation*
|
||||
@@ -0,0 +1,95 @@
|
||||
# Roadmap: NetSynth
|
||||
|
||||
## Overview
|
||||
|
||||
NetSynth is built in four phases ordered by technical risk. Phase 1 validates the hardest foundation: live packet capture and protocol classification without any audio code. Phase 2 builds the synthesis and encoding engine in isolation against synthetic inputs, resolving audio-specific pitfalls before integration. Phase 3 wires the two pipelines together with coordinated Ctrl+C shutdown and auto-clustering, delivering the complete v1 MVP. Phase 4 adds power-user features (BPF filter, offline pcap input) that extend the core without blocking it.
|
||||
|
||||
## Phases
|
||||
|
||||
**Phase Numbering:**
|
||||
- Integer phases (1, 2, 3): Planned milestone work
|
||||
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
||||
|
||||
Decimal phases appear between their surrounding integers in numeric order.
|
||||
|
||||
- [x] **Phase 1: Capture and Classification** - Live packet capture, protocol identification, and CLI scaffolding — no audio yet (completed 2026-03-25)
|
||||
- [x] **Phase 2: Audio Synthesis Engine** - Oscillators, EMA amplitude smoothing, mixing, and MP3 encoding against synthetic inputs (completed 2026-03-26)
|
||||
- [x] **Phase 3: Pipeline Integration and MVP** - Wire capture into synthesis, Ctrl+C with valid MP3 output, auto-clustering of unknown traffic (completed 2026-03-26)
|
||||
- [x] **Phase 4: Power User Features** - BPF capture filter, offline pcap file input (completed 2026-03-26)
|
||||
|
||||
## Phase Details
|
||||
|
||||
### Phase 1: Capture and Classification
|
||||
**Goal**: Users can run the CLI against a live interface and see a live protocol classification summary — the full capture-to-classify pipeline validated without audio
|
||||
**Depends on**: Nothing (first phase)
|
||||
**Requirements**: CAPT-01, CAPT-02, CAPT-04, CLAS-01, CLAS-03, CLAS-04
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User can run `netsynth -i eth0` and see packets being classified live to stderr
|
||||
2. User can run `netsynth --list-interfaces` and see all available network interfaces listed
|
||||
3. User running without root/CAP_NET_RAW sees a clear error message with a `sudo` hint — not a panic or silent failure
|
||||
4. On exit, user sees a per-protocol packet count summary printed to stderr
|
||||
5. User can pass `--verbose` and see per-window protocol activity lines on stderr
|
||||
**Plans:** 4/4 plans complete
|
||||
|
||||
Plans:
|
||||
- [x] 01-01-PLAN.md — Go 1.24 setup, module init, shared types, config-driven classifier with tests
|
||||
- [x] 01-02-PLAN.md — Capture package: OpenCapture, ListInterfaces, privilege error handling
|
||||
- [x] 01-03-PLAN.md — Aggregation: time-windowed accumulator, exit summary, verbose output
|
||||
- [x] 01-04-PLAN.md — CLI wiring: Cobra commands, signal handling, pipeline assembly, smoke test
|
||||
|
||||
### Phase 2: Audio Synthesis Engine
|
||||
**Goal**: The synthesis and encoding stack produces a valid MP3 from synthetic WindowSnapshot inputs — audio pipeline fully validated before any real traffic flows through it
|
||||
**Depends on**: Phase 1
|
||||
**Requirements**: SYNTH-01, SYNTH-02, SYNTH-03, OUT-01, OUT-02, OUT-03
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Given synthetic traffic snapshots, the tool produces an MP3 file that passes `ffprobe` validation
|
||||
2. Each traffic class (ICMP, DNS, TCP/443, TCP/other, UDP, SSH) produces a perceptually distinct drone tone
|
||||
3. Drone layer amplitude rises and falls with traffic volume over time — sustained traffic sounds louder, quiet periods fade
|
||||
4. User can specify output path via `-o` flag; it defaults to `netsynth-<timestamp>.mp3` when omitted
|
||||
5. An empty (zero-packet) input produces a clear error message instead of a corrupt or zero-byte MP3
|
||||
**Plans:** 3/3 plans complete
|
||||
|
||||
Plans:
|
||||
- [x] 02-01-PLAN.md — Environment setup (gcc, ffprobe, go-lame), synth config table, oscillator, EMA layer with tests
|
||||
- [x] 02-02-PLAN.md — Stereo mixer (constant-power panning), OscillatorBank multi-layer rendering with tests
|
||||
- [x] 02-03-PLAN.md — MP3 encoder package, zero-packet guard, -o CLI flag, ffprobe integration test
|
||||
|
||||
### Phase 3: Pipeline Integration and MVP
|
||||
**Goal**: Live capture flows end-to-end into audio synthesis — the complete v1 MVP: run, capture, Ctrl+C, get an MP3
|
||||
**Depends on**: Phase 2
|
||||
**Requirements**: CAPT-03, CLAS-02
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User runs `netsynth -i eth0 -o out.mp3`, generates traffic, presses Ctrl+C, and receives a valid playable MP3 at `out.mp3`
|
||||
2. Unrecognized traffic patterns are automatically assigned distinct drone tones — unknown traffic is not silent or merged into a single undifferentiated layer
|
||||
3. The MP3 audio reflects the actual traffic mix — a session with mostly DNS sounds different from one with mostly HTTPS
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [x] 03-01-PLAN.md — Extend TrafficClass to 14 classes (hash-bucketed unknown-1 through unknown-4), update synth config with dissonant tones
|
||||
- [x] 03-02-PLAN.md — Wire capture pipeline into RunSynthesis, encoding feedback messages, end-to-end MVP verification
|
||||
|
||||
### Phase 4: Power User Features
|
||||
**Goal**: Users can scope capture with BPF expressions and sonify historical pcap files
|
||||
**Depends on**: Phase 3
|
||||
**Requirements**: CAPT-05, CAPT-06
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User can run `netsynth -i eth0 --filter "port 53"` and only DNS traffic is captured and sonified
|
||||
2. User can run `netsynth --read capture.pcap -o out.mp3` against an existing pcap file and receive a valid MP3
|
||||
3. An invalid BPF filter expression produces a clear error message before any capture begins
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [x] 04-01-PLAN.md — BPF validation, pcap file reading, timestamp-based aggregation (core library functions)
|
||||
- [x] 04-02-PLAN.md — Wire --filter and --read flags into CLI with branching run logic
|
||||
|
||||
## Progress
|
||||
|
||||
**Execution Order:**
|
||||
Phases execute in numeric order: 1 -> 2 -> 3 -> 4
|
||||
|
||||
| Phase | Plans Complete | Status | Completed |
|
||||
|-------|----------------|--------|-----------|
|
||||
| 1. Capture and Classification | 4/4 | Complete | 2026-03-25 |
|
||||
| 2. Audio Synthesis Engine | 3/3 | Complete | 2026-03-26 |
|
||||
| 3. Pipeline Integration and MVP | 2/2 | Complete | 2026-03-26 |
|
||||
| 4. Power User Features | 2/2 | Complete | 2026-03-26 |
|
||||
Reference in New Issue
Block a user