gurixandClaude Opus 4.6
dddfb1b444
Add custom sound configuration section covering TOML config files, auto-discovery, available waveforms, and validation behavior. Update flags table, project structure, dependencies, and sound design table with accurate frequencies. Add README update step to evolution checklist. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
217 lines
7.0 KiB
Markdown
217 lines
7.0 KiB
Markdown
# 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-<timestamp>.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
|
||
|
||
# Use a custom sound config
|
||
sudo netsynth -i eth0 --config my-sounds.toml
|
||
```
|
||
|
||
## 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-<timestamp>.mp3`) |
|
||
| `--filter` | BPF filter expression, tcpdump syntax (e.g. `"port 53"`) |
|
||
| `--config` | Path to a TOML config file for custom sound mappings |
|
||
| `--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
|
||
|
||
# Use a custom sound config
|
||
sudo netsynth -i eth0 --config ~/my-sounds.toml
|
||
```
|
||
|
||
## Custom Sound Configuration
|
||
|
||
NetSynth supports TOML config files to override the default sound mappings per traffic class. You can change the frequency and waveform for any class without affecting the others.
|
||
|
||
### Config File Discovery
|
||
|
||
NetSynth looks for config files in this order (first found wins):
|
||
|
||
1. `--config <path>` flag (error if file does not exist)
|
||
2. `./netsynth.toml` in the current working directory
|
||
3. `~/.config/netsynth/config.toml`
|
||
|
||
If no config is found, NetSynth starts silently with built-in defaults.
|
||
|
||
### Config File Format
|
||
|
||
```toml
|
||
# Override sound settings per traffic class.
|
||
# Only the fields you set are changed — everything else keeps its default.
|
||
|
||
[sounds.ICMP]
|
||
frequency = 80.0 # Hz (default: 65.0)
|
||
waveform = "triangle" # sine, square, sawtooth, or triangle
|
||
|
||
[sounds.HTTPS]
|
||
frequency = 200.0
|
||
|
||
[sounds.DNS]
|
||
waveform = "square"
|
||
```
|
||
|
||
### Available Traffic Classes
|
||
|
||
`ICMP`, `DNS`, `HTTPS`, `HTTP`, `SSH`, `SMTP`, `NTP`, `DHCP`, `OtherTCP`, `OtherUDP`, `Unknown1`, `Unknown2`, `Unknown3`, `Unknown4`
|
||
|
||
### Available Waveforms
|
||
|
||
| Waveform | Character |
|
||
|----------|-----------|
|
||
| `sine` | Pure, clean fundamental tone |
|
||
| `square` | Hollow, buzzy (odd harmonics) |
|
||
| `sawtooth` | Bright, rich (all harmonics) |
|
||
| `triangle` | Soft, mellow (odd harmonics, fast rolloff) |
|
||
|
||
All waveforms use bandlimited additive synthesis to prevent aliasing artifacts.
|
||
|
||
### Validation
|
||
|
||
- **Unknown keys** are rejected at startup with an error naming the bad key (catches typos like `frequncy`)
|
||
- **Unknown class names** produce a warning but do not prevent startup
|
||
- **Invalid waveform values** are rejected with a clear error
|
||
|
||
## 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 an oscillator at a specific frequency, waveform, 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 | Character |
|
||
|--------------|-----------|-----------|
|
||
| ICMP (Ping) | 65 Hz | Deep, distinctive ping tone |
|
||
| DNS | 110 Hz | Quick lookup sound |
|
||
| HTTPS/TLS | 175 Hz | Steady drone (bulk traffic) |
|
||
| HTTP | 220 Hz | Warm web traffic hum |
|
||
| SSH | 330 Hz | Distinct interactive tone |
|
||
| SMTP | 440 Hz | Mail delivery tone |
|
||
| NTP | 520 Hz | Time sync pulse |
|
||
| DHCP | 600 Hz | Network setup sound |
|
||
| Other TCP | 700 Hz | Generic TCP hum |
|
||
| Other UDP | 780 Hz | Generic UDP hum |
|
||
| Unknown 1-4 | 862–1047 Hz | Dissonant, attention-grabbing |
|
||
|
||
Sustained traffic sounds louder; quiet periods fade to silence. The result is a unique audio fingerprint of your network activity. All frequencies and waveforms can be overridden via the [config file](#custom-sound-configuration).
|
||
|
||
## 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, waveforms, EMA layers, stereo mixer, tone bank
|
||
config/ TOML config loading, validation, and partial merge
|
||
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 |
|
||
| [BurntSushi/toml](https://github.com/BurntSushi/toml) | TOML config parsing |
|
||
|
||
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.
|