gurix/yoloyolo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: create roadmap (4 phases)

Browse Source
This commit is contained in:
gurix
2026-03-24 22:43:51 +01:00
parent 4e4bc6ce0f
commit 012791cb6f
4 changed files with 290 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/REQUIREMENTS.md
+19 -19
View File
@@ -66,28 +66,28 @@ Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status | | Requirement | Phase | Status |
|-------------|-------|--------| |-------------|-------|--------|
| CAPT-01 | — | Pending | | CAPT-01 | Phase 1 | Pending |
| CAPT-02 | — | Pending | | CAPT-02 | Phase 1 | Pending |
| CAPT-03 | — | Pending | | CAPT-03 | Phase 3 | Pending |
| CAPT-04 | — | Pending | | CAPT-04 | Phase 1 | Pending |
| CAPT-05 | — | Pending | | CAPT-05 | Phase 4 | Pending |
| CAPT-06 | — | Pending | | CAPT-06 | Phase 4 | Pending |
| CLAS-01 | — | Pending | | CLAS-01 | Phase 1 | Pending |
| CLAS-02 | — | Pending | | CLAS-02 | Phase 3 | Pending |
| CLAS-03 | — | Pending | | CLAS-03 | Phase 1 | Pending |
| CLAS-04 | — | Pending | | CLAS-04 | Phase 1 | Pending |
| SYNTH-01 | — | Pending | | SYNTH-01 | Phase 2 | Pending |
| SYNTH-02 | — | Pending | | SYNTH-02 | Phase 2 | Pending |
| SYNTH-03 | — | Pending | | SYNTH-03 | Phase 2 | Pending |
| OUT-01 | — | Pending | | OUT-01 | Phase 2 | Pending |
| OUT-02 | — | Pending | | OUT-02 | Phase 2 | Pending |
| OUT-03 | — | Pending | | OUT-03 | Phase 2 | Pending |
**Coverage:** **Coverage:**
- v1 requirements: 16 total - v1 requirements: 16 total
- Mapped to phases: 0 - Mapped to phases: 16
- Unmapped: 16 ⚠️ - Unmapped: 0
--- ---
*Requirements defined: 2026-03-24* *Requirements defined: 2026-03-24*
*Last updated: 2026-03-24 after initial definition* *Last updated: 2026-03-24 after roadmap creation*
.planning/ROADMAP.md
+77
View File
@@ -0,0 +1,77 @@
# 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.
- [ ] **Phase 1: Capture and Classification** - Live packet capture, protocol identification, and CLI scaffolding — no audio yet
- [ ] **Phase 2: Audio Synthesis Engine** - Oscillators, EMA amplitude smoothing, mixing, and MP3 encoding against synthetic inputs
- [ ] **Phase 3: Pipeline Integration and MVP** - Wire capture into synthesis, Ctrl+C with valid MP3 output, auto-clustering of unknown traffic
- [ ] **Phase 4: Power User Features** - BPF capture filter, offline pcap file input
## 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**: TBD
### 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**: TBD
**UI hint**: no
### 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**: TBD
### 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**: TBD
## Progress
**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Capture and Classification | 0/? | Not started | - |
| 2. Audio Synthesis Engine | 0/? | Not started | - |
| 3. Pipeline Integration and MVP | 0/? | Not started | - |
| 4. Power User Features | 0/? | Not started | - |
.planning/STATE.md
+65
View File
@@ -0,0 +1,65 @@
# Project State
## Project Reference
See: .planning/PROJECT.md (updated 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.
**Current focus:** Phase 1 — Capture and Classification
## Current Position
Phase: 1 of 4 (Capture and Classification)
Plan: 0 of ? in current phase
Status: Ready to plan
Last activity: 2026-03-24 — Roadmap created, ready to plan Phase 1
Progress: [░░░░░░░░░░] 0%
## Performance Metrics
**Velocity:**
- Total plans completed: 0
- Average duration: —
- Total execution time: —
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |
**Recent Trend:**
- Last 5 plans: —
- Trend: —
*Updated after each plan completion*
## Accumulated Context
### Decisions
Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:
- Use `github.com/gopacket/gopacket` v1.5.0 (community fork) — NOT `google/gopacket` which is unmaintained
- Use `github.com/packetcap/go-pcap` for live capture (pure Go, no CGo for capture layer)
- Use `github.com/sjzar/go-lame` v0.0.9 for MP3 encoding (embeds LAME C source, CGo required at build time only)
- Audio synthesis: hand-rolled additive sine oscillators + EMA amplitude smoothing (no external audio library)
- Frequency table: register-separated harmonics (low drones = bulk traffic, mid = control, high = interactive)
### Pending Todos
None yet.
### Blockers/Concerns
- Phase 2: Frequency mapping requires subjective listening validation — specific Hz values not determined by research; must test during Phase 2
- Phase 3: Auto-clustering algorithm choice (hash-bucketing vs k-means) deferred until synthesis engine exists to evaluate perceptual results
- macOS privilege model (BPF device vs CAP_NET_RAW) not verified by research — flag if macOS is a target during Phase 1
## Session Continuity
Last session: 2026-03-24
Stopped at: Roadmap written, REQUIREMENTS.md traceability updated — next step is /gsd:plan-phase 1
Resume file: None
CLAUDE.md
+129
View File
@@ -0,0 +1,129 @@
<!-- GSD:project-start source:PROJECT.md -->
## Project
**NetSynth**
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.
**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.
### 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)
<!-- GSD:project-end -->
<!-- GSD:stack-start source:research/STACK.md -->
## Technology Stack
## Recommended Stack
### Core Technologies
| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| `github.com/gopacket/gopacket` | v1.5.0 | Packet capture, protocol decoding | The canonical Go packet library. Community fork (`gopacket/gopacket`) supersedes the original Google repo (`google/gopacket`) as of 2024; released v1.5.0 in November 2025, minimum Go 1.24. 14.5k dependents; has ICMP, TCP, UDP, DNS, TLS layer decoders built in. |
| `github.com/packetcap/go-pcap` | v0.0.0-20251215 | Pure-Go live packet capture backend | Replaces CGo libpcap dependency for live capture. 100% native Go, Linux + macOS, mmap-based kernel ring buffer for performance. Implements the `gopacket.PacketDataSource` interface so gopacket decodes packets on top of it. Enables CGO_ENABLED=0 builds and cross-compilation. |
| `github.com/sjzar/go-lame` | v0.0.9 | MP3 encoding | Embeds libmp3lame C source directly via CGo — no external `libmp3lame` system package required. Published April 2025. Exposes sample rate, channels, quality control. Produces LAME-quality MP3, unlike the pure-Go shine-mp3 port which produces larger, lower-quality output. Tradeoff: requires CGo, so `CGO_ENABLED=1` and a C compiler at build time. |
| `github.com/spf13/cobra` | v1.10.2 | CLI flag parsing and command structure | The industry standard for Go CLIs (Kubernetes, Docker, Hugo, etc.). v1.10.2 released December 2025. Handles `--interface`, `--output` flags, Ctrl+C signal plumbing, and `--help` generation automatically. No alternatives worth considering for this scope. |
### Supporting Libraries
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| `github.com/muesli/kmeans` | v0.3.1 | K-means clustering for unrecognized traffic patterns | Use to auto-cluster packets that don't match known protocol rules. Feed feature vectors: [port, protocol_num, packet_size_bin, direction]. Last release July 2022 but mathematically stable; the algorithm doesn't change. Alternatively, implement a simple incremental classifier directly (see Architecture notes below). |
| `github.com/go-audio/wav` | latest | WAV file I/O as intermediate format | Use to write synthesized PCM as WAV before MP3 encoding pass. "Battle tested" per maintainer. Simplifies the PCM → encoder pipeline: synthesize float64 samples → write WAV → re-read as PCM → LAME encode. |
| `golang.org/x/sys/unix` | stdlib | Raw socket / CAP_NET_RAW privilege checks | Use for detecting if the process has required privileges and for signaling (SIGINT for clean shutdown). Part of Go extended stdlib — no external version pinning needed. |
### Development Tools
| Tool | Purpose | Notes |
|------|---------|-------|
| `go build -ldflags="-s -w"` | Stripped binary production builds | Reduces binary size significantly; combine with `upx` if size is critical |
| `goreleaser` | Cross-platform release builds | Handles CGo cross-compilation complexity with Docker-based build matrix; useful for distributing Linux x86_64 + ARM64 binaries |
| `golangci-lint` | Static analysis | Catches nil pointer dereferences common in packet-handling code |
| Wireshark / `tcpdump` | Manual verification of packet capture | Essential for confirming gopacket is decoding the right protocols before plugging into audio synthesis |
## Installation
# Initialize module
# Core dependencies
# Supporting
# Build (CGo required for go-lame)
# OR: grant capability instead of running as root
## Alternatives Considered
| Recommended | Alternative | When to Use Alternative |
|-------------|-------------|-------------------------|
| `gopacket/gopacket` (community fork) | `google/gopacket` (original) | Never for new projects — original repo has 270 open issues, community fork actively merges fixes |
| `packetcap/go-pcap` (pure Go) | `gopacket/pcap` (CGo + libpcap) | Use libpcap path only if you need advanced BPF filter syntax or BSD/Windows support — it requires `libpcap-dev` system package |
| `sjzar/go-lame` (embedded C source) | `braheezy/shine-mp3` (pure Go) | Use shine-mp3 if CGo is truly impossible (e.g., WASM target) — but accept that output quality and file size are worse |
| `sjzar/go-lame` (embedded C source) | `viert/go-lame` (dynamic link) | Never — viert/go-lame requires libmp3lame installed on the target system, defeating single-binary distribution |
| Hand-rolled additive synthesis | `dasa.cc/snd`, `bspaans/bleep` | Use a library only if you need MIDI scheduling or real-time playback; for file output, the synthesis math is simple enough to own directly (see Architecture notes) |
| `muesli/kmeans` | `mpraski/clusters` | Use mpraski if you need online (incremental) clustering — it supports add-one-point updates vs muesli's batch-only approach |
## What NOT to Use
| Avoid | Why | Use Instead |
|-------|-----|-------------|
| `google/gopacket` (original) | Effectively unmaintained since 2022; 270 open issues, PRs not merged | `github.com/gopacket/gopacket` (community fork, v1.5.0) |
| `viert/go-lame` or `sunicy/go-lame` | Dynamic-links against system `libmp3lame` — breaks single-binary distribution, fails on machines without the library | `github.com/sjzar/go-lame` (embeds C source statically) |
| `braheezy/shine-mp3` (pure Go MP3) | Last commit 2023, explicitly not production-ready per its own README, produces larger lower-quality files, no bitrate control | `sjzar/go-lame` for quality, or WAV output if you must avoid CGo |
| `go-audio/generator` | **Archived February 2026, read-only** — do not take a new dependency on it | Write your own oscillator (20 lines of Go) or use `dasa.cc/snd` |
| `faiface/beep` | Designed for real-time audio playback via PortAudio/oto; pulls in platform audio drivers that are irrelevant for file output | Roll a minimal additive synthesizer directly (see below) |
| `dasa.cc/snd` | Plays audio through hardware; brings in real-time audio scheduling complexity unnecessary for batch file output | Roll a minimal additive synthesizer directly |
| urfave/cli | Fine for simpler tools, but Cobra's flag validation, help generation, and signal handling are better for a tool with multiple flags and clean shutdown semantics | `github.com/spf13/cobra` |
## Stack Patterns by Variant
- Use `sjzar/go-lame` for real MP3 quality
- Use `packetcap/go-pcap` for the capture layer (pure Go on Linux/macOS)
- Build with `CGO_ENABLED=1`; single binary is still self-contained because LAME C source is embedded
- Use `braheezy/shine-mp3` for MP3 — accept lower quality and larger files
- Use `packetcap/go-pcap` for capture — already pure Go
- Build with `CGO_ENABLED=0`; truly static binary
- Consider `packetcap/go-pcap`'s mmap ring buffer mode for high-traffic interfaces (default on Linux)
- Privilege: `CAP_NET_RAW` setcap is cleaner than running as root
## Version Compatibility
| Package | Compatible With | Notes |
|---------|-----------------|-------|
| `gopacket/gopacket@v1.5.0` | Go 1.24+ | v1.5.0 bumped minimum Go to 1.24; use Go 1.24.x toolchain |
| `packetcap/go-pcap` | Linux, macOS (Darwin) | No Windows support; this is acceptable per project constraints |
| `sjzar/go-lame@v0.0.9` | Any Go + C compiler; CGO_ENABLED=1 | Embeds LAME C source; no system library dependency |
| `spf13/cobra@v1.10.2` | Go 1.20+ | No issues with Go 1.24 |
| `muesli/kmeans@v0.3.1` | Go 1.12+ | Stable; no compatibility concerns |
## Audio Synthesis Architecture Note
## Sources
- `github.com/gopacket/gopacket` releases page — v1.5.0 confirmed, November 2025
- `pkg.go.dev/github.com/packetcap/go-pcap` — v0.0.0-20251215, pure Go, Linux/macOS confirmed
- `pkg.go.dev/github.com/sjzar/go-lame` — v0.0.9, April 2025, embedded C source confirmed
- `pkg.go.dev/github.com/spf13/cobra` — v1.10.2, December 2025
- `github.com/go-audio/generator` — archived February 2026 (read-only), do not use
- `braheezy.github.io/posts/what-i-learned-about-mp3-encoding/` — author's first-hand account of Go MP3 encoding options, concluded shine-mp3 is not production-grade
- `github.com/google/gopacket/issues/1016` — maintenance status discussion confirming community fork is preferred
- WebSearch: muesli/kmeans v0.3.1 last release July 2022 — LOW confidence on ongoing maintenance, but algorithm is stable
- WebSearch: cobra v1.9.1/v1.10.2 — MEDIUM confidence, confirmed via pkg.go.dev
<!-- GSD:stack-end -->
<!-- GSD:conventions-start source:CONVENTIONS.md -->
## Conventions
Conventions not yet established. Will populate as patterns emerge during development.
<!-- GSD:conventions-end -->
<!-- GSD:architecture-start source:ARCHITECTURE.md -->
## Architecture
Architecture not yet mapped. Follow existing patterns found in the codebase.
<!-- GSD:architecture-end -->
<!-- GSD:workflow-start source:GSD defaults -->
## GSD Workflow Enforcement
Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
Use these entry points:
- `/gsd:quick` for small fixes, doc updates, and ad-hoc tasks
- `/gsd:debug` for investigation and bug fixing
- `/gsd:execute-phase` for planned phase work
Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
<!-- GSD:workflow-end -->
<!-- GSD:profile-start -->
## Developer Profile
> Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile.
> This section is managed by `generate-claude-profile` -- do not edit manually.
<!-- GSD:profile-end -->