gurixandClaude Opus 4.6
41e22788fc
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
151 lines
4.7 KiB
Markdown
151 lines
4.7 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
|
|
```
|
|
|
|
## 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"`) |
|
|
| `--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.
|