From 41e22788fc3619356ad865cad1105dcefe910da3 Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Thu, 26 Mar 2026 15:29:14 +0100 Subject: [PATCH] docs: add README with usage, architecture, and build instructions Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..94d64ca --- /dev/null +++ b/README.md @@ -0,0 +1,150 @@ +# NetSynth + +**Turn network traffic into ambient sound.** + +NetSynth captures live network traffic (or reads pcap files), classifies packets by protocol, and synthesizes an ambient MP3 soundscape where each traffic type produces a distinct harmonic drone. A ping sounds different from HTTPS noise, which sounds different from a port scan. + +Run it, let it listen, press Ctrl+C, get an audio fingerprint of your network. + +## Quick Start + +```bash +# Live capture on eth0 (requires root or CAP_NET_RAW) +sudo netsynth -i eth0 + +# Press Ctrl+C after a few seconds → saves netsynth-.mp3 + +# Sonify a pcap file (no privileges needed) +netsynth --read capture.pcap -o output.mp3 + +# Filter to DNS traffic only +sudo netsynth -i eth0 --filter "port 53" -o dns.mp3 +``` + +## Installation + +### Prerequisites + +- Go 1.24+ +- C compiler (GCC or Clang) — required for MP3 encoding (CGo) + +### Build from Source + +```bash +git clone https://codeberg.org/gurix/yoloyolo.git +cd yoloyolo +go build -o netsynth ./cmd/netsynth +``` + +For a smaller binary: + +```bash +go build -ldflags="-s -w" -o netsynth ./cmd/netsynth +``` + +### Privileges + +Live packet capture requires elevated privileges on Linux: + +```bash +# Option A: run as root +sudo ./netsynth -i eth0 + +# Option B: grant capability (preferred) +sudo setcap cap_net_raw=eip ./netsynth +./netsynth -i eth0 +``` + +## Usage + +``` +netsynth [flags] +``` + +| Flag | Description | +|------|-------------| +| `-i`, `--interface` | Network interface to capture on | +| `--read` | Read packets from a pcap file instead of live capture | +| `-o`, `--output` | Output MP3 file path (default: `netsynth-.mp3`) | +| `--filter` | BPF filter expression, tcpdump syntax (e.g. `"port 53"`) | +| `--verbose` | Print per-window protocol activity to stderr | +| `--list-interfaces` | List available network interfaces and exit | + +### Examples + +```bash +# Capture all traffic, verbose per-window output +sudo netsynth -i wlan0 --verbose + +# Only HTTPS traffic +sudo netsynth -i eth0 --filter "tcp port 443" -o https.mp3 + +# Sonify a Wireshark capture (output derived: capture.pcap -> capture.mp3) +netsynth --read capture.pcap + +# Filter a pcap file to UDP only +netsynth --read traffic.pcap --filter "udp" -o udp-only.mp3 +``` + +## How It Works + +NetSynth processes traffic through a four-stage pipeline: + +``` +Capture -> Classify -> Aggregate -> Synthesize -> MP3 +``` + +1. **Capture** — Packets are read from a live interface (via [go-pcap](https://github.com/packetcap/go-pcap)) or a pcap file. Optional BPF filtering reduces the stream to traffic of interest. + +2. **Classify** — Each packet is matched against 12 protocol rules (ICMP, DNS, HTTPS, SSH, HTTP, SMTP, NTP, DHCP, etc.). Unrecognized traffic is deterministically hash-bucketed into 4 "unknown" classes so it still produces distinct sounds. + +3. **Aggregate** — Classified packets are grouped into 500ms time windows. Each window records per-protocol packet counts that drive synthesis amplitudes. + +4. **Synthesize & Encode** — Each traffic class maps to a sine oscillator at a specific frequency and stereo position. Amplitudes rise and fall via EMA smoothing based on traffic volume. All layers are mixed and encoded to MP3 via [LAME](https://github.com/sjzar/go-lame). + +### Sound Design + +| Traffic Class | Frequency Range | Character | +|--------------|----------------|-----------| +| ICMP (Ping) | High register | Bright, distinctive ping tone | +| DNS | Mid-high | Quick lookup sound | +| HTTPS/TLS | Low register | Deep, steady drone (bulk traffic) | +| SSH | Mid register | Distinct interactive tone | +| HTTP | Low-mid | Warm web traffic hum | +| Unknown 1-4 | Dissonant | Eerie, attention-grabbing | + +Sustained traffic sounds louder; quiet periods fade to silence. The result is a unique audio fingerprint of your network activity. + +## Project Structure + +``` +cmd/netsynth/ CLI entry point (Cobra) +capture/ Packet capture, BPF validation, pcap file reading +classify/ Protocol classification rules and types +aggregate/ Time-window aggregation and summary output +synth/ Oscillators, EMA layers, stereo mixer, tone bank +encode/ MP3 encoding via embedded LAME +``` + +## Dependencies + +| Library | Purpose | +|---------|---------| +| [gopacket/gopacket](https://github.com/gopacket/gopacket) | Packet decoding | +| [packetcap/go-pcap](https://github.com/packetcap/go-pcap) | Pure Go live capture (no libpcap) | +| [sjzar/go-lame](https://github.com/sjzar/go-lame) | MP3 encoding (embedded LAME C source) | +| [spf13/cobra](https://github.com/spf13/cobra) | CLI framework | + +No runtime dependencies beyond the compiled binary. CGo is required at build time only (for LAME). + +## Testing + +```bash +go test ./... -v +``` + +All tests run without root privileges (capture tests use mock data and programmatically generated pcap files). + +## License + +See [LICENSE](LICENSE) for details.