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
+39
-49
@@ -2,40 +2,39 @@
|
||||
|
||||
## What This Is
|
||||
|
||||
A Go CLI tool that captures live network traffic on an interface, clusters and classifies the packets by protocol/pattern, and synthesizes an ambient MP3 soundscape where each traffic type produces a distinct harmonic drone or tone. Run it, let it listen, hit Ctrl+C, and get an audio fingerprint of your network.
|
||||
A Go CLI tool that captures live network traffic on an interface, classifies packets by protocol, and synthesizes an ambient MP3 soundscape where each traffic type produces a distinct harmonic drone or tone. Supports live capture with BPF filtering and offline pcap file sonification.
|
||||
|
||||
## 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.
|
||||
|
||||
## Current State
|
||||
|
||||
**v1.0 MVP shipped 2026-03-26.** 3,254 lines of Go across 6 packages.
|
||||
|
||||
Tech stack: gopacket/gopacket v1.5.0, packetcap/go-pcap (pure Go capture), sjzar/go-lame v0.0.9 (embedded LAME), spf13/cobra v1.10.2.
|
||||
|
||||
All 16 v1 requirements validated. Full pipeline working: capture -> classify -> aggregate -> synthesize -> MP3.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
### Validated (v1.0)
|
||||
|
||||
- [x] Capture live packets from a specified network interface until interrupted (Ctrl+C) — Validated in Phase 1
|
||||
- [x] Classify packets by known protocols (ICMP, TCP/HTTPS, DNS, SSH, etc.) using predefined rules — Validated in Phase 1
|
||||
- [x] Aggregate traffic into time windows to drive amplitude and tonal evolution — Validated in Phase 1
|
||||
- [x] CLI interface with flags for interface selection and output file path — Validated in Phase 1 (interface flags; output flag in Phase 2)
|
||||
|
||||
### Validated in Phase 4
|
||||
|
||||
- [x] BPF capture filter — users can scope live capture with tcpdump-syntax expressions — Validated in Phase 4
|
||||
- [x] Offline pcap file input — users can sonify historical pcap files without live capture — Validated in Phase 4
|
||||
- Capture live packets from a specified network interface until Ctrl+C
|
||||
- Classify packets by known protocols (ICMP, DNS, HTTPS, SSH, etc.) with 12 predefined rules
|
||||
- Auto-cluster unrecognized traffic into 4 hash-bucketed unknown classes with distinct tones
|
||||
- Aggregate traffic into 500ms time windows driving amplitude evolution
|
||||
- End-to-end pipeline: capture -> classify -> synthesize -> MP3 output
|
||||
- Map each traffic class to a distinct ambient/drone layer (sine oscillators + EMA smoothing)
|
||||
- Stereo mixing with constant-power panning, no distortion
|
||||
- MP3 encoding via embedded LAME, zero-packet guard
|
||||
- CLI with `-i`, `-o`, `--list-interfaces`, `--verbose`, `--filter`, `--read` flags
|
||||
- BPF capture filter for scoping live traffic
|
||||
- Offline pcap file sonification with timestamp-based windowing
|
||||
|
||||
### Active
|
||||
|
||||
(None — all requirements validated through Phase 4)
|
||||
|
||||
### Validated in Phase 3
|
||||
|
||||
- [x] Auto-cluster unrecognized traffic patterns and assign them unique tones — Validated in Phase 3 (hash-bucketed into 4 unknown classes with distinct dissonant tones)
|
||||
- [x] End-to-end pipeline: capture → classify → synthesize → MP3 output — Validated in Phase 3
|
||||
|
||||
### Validated in Phase 2
|
||||
|
||||
- [x] Map each traffic class to a distinct harmonic/drone sound layer — Validated in Phase 2
|
||||
- [x] Synthesize ambient/drone audio from the layered sound mappings — Validated in Phase 2
|
||||
- [x] Encode and save output as MP3 file — Validated in Phase 2
|
||||
(None — next milestone requirements TBD)
|
||||
|
||||
### Out of Scope
|
||||
|
||||
@@ -46,46 +45,37 @@ Network traffic patterns are instantly recognizable as distinct sounds — a pin
|
||||
|
||||
## Context
|
||||
|
||||
- Built in Go for single-binary distribution and performance
|
||||
- Needs packet capture (likely pcap/gopacket) — may require elevated privileges
|
||||
- Audio synthesis in Go is less common than Python; will need to evaluate libraries
|
||||
- MP3 encoding requires an encoder library or CGo bindings (e.g., LAME)
|
||||
- The "ambient/drone" style means layered sine/harmonic waves that evolve slowly based on traffic volume and mix, not discrete note triggers
|
||||
- Built in Go (CGO_ENABLED=1 for LAME), single binary output
|
||||
- Packet capture requires root/CAP_NET_RAW on Linux
|
||||
- Pure Go capture layer (no libpcap dependency)
|
||||
- MP3 encoding embeds LAME C source (no system library needed)
|
||||
- 14 traffic classes: 10 known protocols + 4 hash-bucketed unknowns
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Language**: Go — user preference, single binary output
|
||||
- **Privileges**: Packet capture requires root/CAP_NET_RAW on Linux
|
||||
- **Audio format**: MP3 output (not WAV or raw PCM)
|
||||
- **Interaction model**: Non-interactive capture (run → Ctrl+C → file saved)
|
||||
- **Interaction model**: Non-interactive capture (run -> Ctrl+C -> file saved)
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| Go over Python/Rust | User preference, single binary, good perf | — Pending |
|
||||
| Ambient/drone style | Layered tones better represent continuous traffic patterns | — Pending |
|
||||
| Predefined + auto-cluster | Known protocols get recognizable sounds; unknown traffic still represented | — Pending |
|
||||
| File output only | Simpler v1, avoids real-time audio complexity | — Pending |
|
||||
| Go over Python/Rust | User preference, single binary, good perf | Good |
|
||||
| Ambient/drone style | Layered tones better represent continuous traffic patterns | Good |
|
||||
| Predefined + auto-cluster | Known protocols get recognizable sounds; unknown traffic still represented | Good |
|
||||
| File output only | Simpler v1, avoids real-time audio complexity | Good |
|
||||
| go-pcap over libpcap | Pure Go, no CGo for capture, cross-compilation friendly | Good |
|
||||
| go-lame (embedded C) over shine-mp3 | Better quality, smaller files, acceptable CGo tradeoff | Good |
|
||||
| Hand-rolled synthesis over audio libraries | 20 lines of oscillator code, no unnecessary dependencies | Good |
|
||||
| Hash-bucketed unknowns over k-means | Deterministic, zero-config, sufficient for v1 audio distinction | Good |
|
||||
| Ordered []Rule classifier over switch | Configurable, extensible, first-match-wins semantics | Good |
|
||||
| 500ms window duration | Balances temporal resolution against snapshot frequency for synthesis | Good |
|
||||
|
||||
## Evolution
|
||||
|
||||
This document evolves at phase transitions and milestone boundaries.
|
||||
|
||||
Last updated: 2026-03-26 — Phase 4 (Power User Features) complete. All v1.0 milestone phases delivered.
|
||||
|
||||
**After each phase transition** (via `/gsd:transition`):
|
||||
1. Requirements invalidated? → Move to Out of Scope with reason
|
||||
2. Requirements validated? → Move to Validated with phase reference
|
||||
3. New requirements emerged? → Add to Active
|
||||
4. Decisions to log? → Add to Key Decisions
|
||||
5. "What This Is" still accurate? → Update if drifted
|
||||
|
||||
**After each milestone** (via `/gsd:complete-milestone`):
|
||||
1. Full review of all sections
|
||||
2. Core Value check — still the right priority?
|
||||
3. Audit Out of Scope — reasons still valid?
|
||||
4. Update Context with current state
|
||||
|
||||
---
|
||||
*Last updated: 2026-03-26 after Phase 4 completion*
|
||||
*Last updated: 2026-03-26 after v1.0 milestone*
|
||||
|
||||
Reference in New Issue
Block a user