92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# NetSynth
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## Requirements
|
|
|
|
### Validated
|
|
|
|
- [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
|
|
|
|
### 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
|
|
|
|
### Out of Scope
|
|
|
|
- Real-time audio playback — v1 is file output only
|
|
- GUI or web interface — CLI only
|
|
- Custom sound mapping configuration — predefined + auto-cluster only
|
|
- Rhythmic/percussive output — ambient/drone style only
|
|
|
|
## 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
|
|
|
|
## 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)
|
|
|
|
## 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 |
|
|
|
|
## 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*
|