From 494385b5280a4b150c5e0fff49fd76d6232076e6 Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Fri, 27 Mar 2026 16:48:53 +0100 Subject: [PATCH] =?UTF-8?q?chore:=20archive=20v1.2=20milestone=20=E2=80=94?= =?UTF-8?q?=20Extended=20Protocol=20Coverage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 35 traffic classes across 9 protocol families shipped. Archives ROADMAP, REQUIREMENTS, and phase directories to milestones/v1.2-*. Updates README with new protocol families, sound design table, and [groups] TOML config documentation. Co-Authored-By: Claude Opus 4.6 (1M context) --- .planning/MILESTONES.md | 15 +++ .planning/PROJECT.md | 43 ++++--- .planning/RETROSPECTIVE.md | 51 ++++++-- .planning/ROADMAP.md | 87 +++----------- .planning/STATE.md | 76 ++++-------- .../v1.2-REQUIREMENTS.md} | 9 ++ .planning/milestones/v1.2-ROADMAP.md | 113 ++++++++++++++++++ .../08-01-PLAN.md | 0 .../08-01-SUMMARY.md | 0 .../08-CONTEXT.md | 0 .../08-DISCUSSION-LOG.md | 0 .../08-RESEARCH.md | 0 .../08-VALIDATION.md | 0 .../08-VERIFICATION.md | 0 .../09-01-PLAN.md | 0 .../09-01-SUMMARY.md | 0 .../09-02-PLAN.md | 0 .../09-02-SUMMARY.md | 0 .../09-CONTEXT.md | 0 .../09-DISCUSSION-LOG.md | 0 .../09-RESEARCH.md | 0 .../09-VALIDATION.md | 0 .../09-VERIFICATION.md | 0 .../10-classification-layer/10-01-PLAN.md | 0 .../10-classification-layer/10-01-SUMMARY.md | 0 .../10-classification-layer/10-02-PLAN.md | 0 .../10-classification-layer/10-02-SUMMARY.md | 0 .../10-classification-layer/10-CONTEXT.md | 0 .../10-DISCUSSION-LOG.md | 0 .../10-classification-layer/10-RESEARCH.md | 0 .../10-classification-layer/10-VALIDATION.md | 0 .../10-VERIFICATION.md | 0 .../11-01-PLAN.md | 0 .../11-01-SUMMARY.md | 0 .../11-02-PLAN.md | 0 .../11-02-SUMMARY.md | 0 .../11-CONTEXT.md | 0 .../11-DISCUSSION-LOG.md | 0 .../11-RESEARCH.md | 0 .../11-VALIDATION.md | 0 .../11-VERIFICATION.md | 0 README.md | 62 +++++++--- 42 files changed, 290 insertions(+), 166 deletions(-) rename .planning/{REQUIREMENTS.md => milestones/v1.2-REQUIREMENTS.md} (96%) create mode 100644 .planning/milestones/v1.2-ROADMAP.md rename .planning/{phases => milestones/v1.2-phases}/08-test-and-constant-cleanup/08-01-PLAN.md (100%) rename .planning/{phases => milestones/v1.2-phases}/08-test-and-constant-cleanup/08-01-SUMMARY.md (100%) rename .planning/{phases => milestones/v1.2-phases}/08-test-and-constant-cleanup/08-CONTEXT.md (100%) rename .planning/{phases => milestones/v1.2-phases}/08-test-and-constant-cleanup/08-DISCUSSION-LOG.md (100%) rename .planning/{phases => milestones/v1.2-phases}/08-test-and-constant-cleanup/08-RESEARCH.md (100%) rename .planning/{phases => milestones/v1.2-phases}/08-test-and-constant-cleanup/08-VALIDATION.md (100%) rename .planning/{phases => milestones/v1.2-phases}/08-test-and-constant-cleanup/08-VERIFICATION.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-01-PLAN.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-01-SUMMARY.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-02-PLAN.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-02-SUMMARY.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-CONTEXT.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-DISCUSSION-LOG.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-RESEARCH.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-VALIDATION.md (100%) rename .planning/{phases => milestones/v1.2-phases}/09-frequency-design-and-group-architecture/09-VERIFICATION.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-01-PLAN.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-01-SUMMARY.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-02-PLAN.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-02-SUMMARY.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-CONTEXT.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-DISCUSSION-LOG.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-RESEARCH.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-VALIDATION.md (100%) rename .planning/{phases => milestones/v1.2-phases}/10-classification-layer/10-VERIFICATION.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-01-PLAN.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-01-SUMMARY.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-02-PLAN.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-02-SUMMARY.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-CONTEXT.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-DISCUSSION-LOG.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-RESEARCH.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-VALIDATION.md (100%) rename .planning/{phases => milestones/v1.2-phases}/11-synthesis-and-config-layer/11-VERIFICATION.md (100%) diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md index e7f1282..f2e8142 100644 --- a/.planning/MILESTONES.md +++ b/.planning/MILESTONES.md @@ -1,5 +1,20 @@ # Milestones +## v1.2 Extended Protocol Coverage (Shipped: 2026-03-27) + +**Phases completed:** 4 phases, 7 plans, 14 tasks + +**Key accomplishments:** + +- Removed stale constants and future-proofed test bounds (Nyquist-based validation) to unblock all v1.2 work +- Rebalanced all ClassFreqConfigs to major-second ladder in family frequency bands (65-3250 Hz) with Group field on FreqConfig +- Added 21 new TrafficClass constants and 30 port-matching rules across 7 protocol families (Mail, File Transfer, Remote Access, Database, Discovery, VoIP, Infrastructure) +- Full classification test coverage: 28 new subtests covering all new port/protocol/transport combinations +- Added 21 ClassFreqConfigs entries with family-coherent sound design (shared waveform and frequency register per group) +- Group-ordered `--print-config` output with section headers and `[groups]` TOML support for user-defined protocol-to-group reassignment + +--- + ## v1.1 Custom Sound Mappings (Shipped: 2026-03-26) **Phases completed:** 3 phases, 6 plans, 3 tasks diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index cc47df7..0a26124 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -10,11 +10,11 @@ Network traffic patterns are instantly recognizable as distinct sounds — a pin ## Current State -**v1.2 complete.** Phase 11 (Synthesis and Config Layer) complete 2026-03-27 — all 35 traffic classes have ClassFreqConfigs entries with family-coherent sound design. --print-config outputs classes grouped by family with section headers. Users can reassign protocols to different sound families via [groups] TOML config. Full test suite green. ~6,000 lines of Go across 7 packages. +**v1.2 shipped.** 35 built-in traffic classes across 9 protocol families (Infrastructure, Web, Mail, Remote Access, File Transfer, Database, Discovery, VoIP, Unknown). Major-second frequency ladder (65-3250 Hz) with family-coherent sound design. Group-ordered `--print-config` with section headers. `[groups]` TOML config for reassigning protocols to different sound families. ~6,000 lines of Go across 7 packages, full test suite green. Tech stack: gopacket/gopacket v1.5.0, packetcap/go-pcap (pure Go capture), sjzar/go-lame v0.0.9 (embedded LAME), spf13/cobra v1.10.2, BurntSushi/toml v1.6.0. -All 16 v1.0 requirements + 11 v1.1 requirements + CLEAN-01 validated. Full pipeline with customizable sound mappings: capture -> classify -> aggregate -> synthesize -> MP3. +All v1.0 + v1.1 + v1.2 requirements validated (45 total). Full pipeline: capture -> classify -> aggregate -> synthesize -> MP3. ## Requirements @@ -44,9 +44,19 @@ All 16 v1.0 requirements + 11 v1.1 requirements + CLEAN-01 validated. Full pipel - Auto-frequency assignment for custom class names (no silent gaps) - `--print-config` outputs effective config as commented TOML +### Validated (v1.2) + +- Removed stale constants and future-proofed test bounds for extensibility +- 21 new protocol classifications: Mail (IMAP, POP3, SMTP-sub), File Transfer (FTP, SMB, TFTP), Remote Access (RDP, Telnet, VNC), Database (MySQL, PostgreSQL, Redis, MongoDB), Discovery (mDNS, SSDP, SNMP), VoIP (SIP), Web (QUIC/HTTP3), Infrastructure (LDAP, Kerberos, Syslog) +- No regression in existing 14 protocol classifications +- Major-second frequency ladder with family-coherent waveforms and group field on FreqConfig +- Auto-assign frequency range moved to 2500-4000 Hz (collision-free with built-ins) +- Group-ordered `--print-config` output with section headers +- `[groups]` TOML config for protocol-to-group reassignment + ### Active -(See REQUIREMENTS.md for v1.2 requirements) +(No active requirements — planning next milestone) ### Out of Scope @@ -61,8 +71,8 @@ All 16 v1.0 requirements + 11 v1.1 requirements + CLEAN-01 validated. Full pipel - Packet capture requires root/CAP_NET_RAW on Linux - Pure Go capture layer (no libpcap dependency) - MP3 encoding embeds LAME C source (no system library needed) -- 35 built-in traffic classes: 10 original protocols + 21 new protocol families + 4 hash-bucketed unknowns (extensible via custom rules) -- TOML config with partial overrides, unknown-key validation, auto-discovery +- 35 built-in traffic classes across 9 families: Infrastructure, Web, Mail, Remote Access, File Transfer, Database, Discovery, VoIP, Unknown (extensible via custom rules) +- TOML config with partial overrides, unknown-key validation, auto-discovery, and `[groups]` protocol-to-group reassignment ## Constraints @@ -83,6 +93,8 @@ All 16 v1.0 requirements + 11 v1.1 requirements + CLEAN-01 validated. Full pipel | go-lame (embedded C) over shine-mp3 | Better quality, smaller files, acceptable CGo tradeoff | Good | | Hand-rolled synthesis over audio libraries | 20 lines of oscillator code, no unnecessary dependencies | Good | | Hash-bucketed unknowns over k-means | Deterministic, zero-config, sufficient for v1 audio distinction | Good | +| Major-second frequency ladder | Musical interval spacing prevents critical band masking between family members | Good | +| Group field as string (not enum) | Extensible for new family names without code changes | Good | | Ordered []Rule classifier over switch | Configurable, extensible, first-match-wins semantics | Good | | 500ms window duration | Balances temporal resolution against snapshot frequency for synthesis | Good | | BurntSushi/toml over manual parsing | Industry-standard Go TOML library, Undecoded() catches typos | Good | @@ -92,20 +104,15 @@ All 16 v1.0 requirements + 11 v1.1 requirements + CLEAN-01 validated. Full pipel | LoadResult struct over tuple return | Clean single return value, extensible for future fields | Good | | --print-config as flag (not subcommand) | Consistent with --list-interfaces pattern, simpler CLI surface | Good | -## Current Milestone: v1.2 Extended Protocol Coverage - -**Goal:** Expand traffic classification with grouped protocol families that share recognizable sound signatures - -**Target features:** -- Research common network protocols and identify missing ones beyond the current 10 -- Group related protocols into families (Mail, Web, Remote Access, Database, Discovery, File Transfer, VoIP) -- Within-group sound design: shared base frequency, different waveforms or slight detuning -- Frequency rebalancing to accommodate new classes without overcrowding the spectrum -- New classification rules for all identified protocols -- Updated --print-config output reflecting groups - ## Shipped Milestones +
+v1.2 Extended Protocol Coverage (shipped 2026-03-27) + +35 built-in traffic classes across 9 protocol families with major-second frequency ladder, group-ordered print-config, and [groups] TOML reassignment. + +
+
v1.1 Custom Sound Mappings (shipped 2026-03-26) @@ -139,4 +146,4 @@ This document evolves at phase transitions and milestone boundaries. 4. Update Context with current state --- -*Last updated: 2026-03-27 after Phase 11 completion* +*Last updated: 2026-03-27 after v1.2 milestone* diff --git a/.planning/RETROSPECTIVE.md b/.planning/RETROSPECTIVE.md index dbea3c6..087ba8f 100644 --- a/.planning/RETROSPECTIVE.md +++ b/.planning/RETROSPECTIVE.md @@ -74,12 +74,49 @@ - Manual string building beats TOML encoder when you need inline comments/annotations - Config extension is smooth when the original Load() was designed with clean boundaries +## Milestone: v1.2 — Extended Protocol Coverage + +**Shipped:** 2026-03-27 +**Phases:** 4 | **Plans:** 7 | **Timeline:** 1 day (2026-03-27) +**LOC:** ~6,000 Go (+1,325 from v1.1) | **Files:** 19 modified + +### What Was Built +- Removed stale constants and future-proofed test bounds (Nyquist-based validation) +- Rebalanced all ClassFreqConfigs to major-second ladder in family frequency bands (65-3250 Hz) with Group field +- 21 new TrafficClass constants and 30 port-matching rules across 7 protocol families +- 28 new classification subtests covering all new port/protocol/transport combinations +- 21 ClassFreqConfigs entries with family-coherent sound design +- Group-ordered --print-config with section headers and [groups] TOML reassignment + +### What Worked +- Cleanup-first approach (Phase 8) prevented cascading test failures throughout the milestone +- Design-before-code (Phase 9 frequency table locked before any protocol code) avoided retroactive rebalancing +- Strict phase ordering (constants -> rules -> config) kept three-location atomicity tests green +- Musical interval spacing (major second ratio 1.122) produced perceptually distinct yet family-coherent sounds +- Oscillator normalization bug caught and fixed during frequency rebalancing (math.Abs for alternating-sign harmonics) + +### What Was Inefficient +- Phase 9 plan 09-01 ROADMAP checkbox wasn't updated after execution — milestone readiness check showed incomplete +- REQUIREMENTS.md traceability wasn't updated for Phase 9 completions (FREQ-01 through GRP-04 still showed Pending) +- STATE.md accumulated merge conflict markers from earlier worktree operations, persisted unnoticed + +### Patterns Established +- Group field as string (not enum) on FreqConfig — extensible without code changes +- Major-second ladder pattern for family-band frequency allocation +- groupOrder canonical slice for deterministic section ordering in config output +- rawConfig Groups map for TOML [groups] table parsing + +### Key Lessons +- Musical interval ratios are better than fixed Hz steps for frequency allocation — prevents critical band masking +- Group-based config output requires building from effective (post-reassignment) groups, not defaults +- Cleanup phases are high-ROI when they prevent test failures in every subsequent phase + ## Cross-Milestone Trends -| Metric | v1.0 | v1.1 | -|--------|------|------| -| Phases | 4 | 3 | -| Plans | 11 | 6 | -| Days | 3 | 1 | -| LOC | 3,254 | 4,675 | -| Avg plan duration | ~8 min | ~5 min | +| Metric | v1.0 | v1.1 | v1.2 | +|--------|------|------|------| +| Phases | 4 | 3 | 4 | +| Plans | 11 | 6 | 7 | +| Days | 3 | 1 | 1 | +| LOC | 3,254 | 4,675 | ~6,000 | +| Avg plan duration | ~8 min | ~5 min | ~4 min | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 4a1835e..d66bb72 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -2,14 +2,14 @@ ## Milestones -- **v1.0 MVP** — Phases 1-4 (shipped 2026-03-26) -- **v1.1 Custom Sound Mappings** — Phases 5-7 (shipped 2026-03-26) -- **v1.2 Extended Protocol Coverage** — Phases 8-11 (in progress) +- ✅ **v1.0 MVP** — Phases 1-4 (shipped 2026-03-26) +- ✅ **v1.1 Custom Sound Mappings** — Phases 5-7 (shipped 2026-03-26) +- ✅ **v1.2 Extended Protocol Coverage** — Phases 8-11 (shipped 2026-03-27) ## Phases
-v1.0 MVP (Phases 1-4) — SHIPPED 2026-03-26 +✅ v1.0 MVP (Phases 1-4) — SHIPPED 2026-03-26 - [x] **Phase 1: Capture and Classification** - 4/4 plans — completed 2026-03-25 - [x] **Phase 2: Audio Synthesis Engine** - 3/3 plans — completed 2026-03-26 @@ -21,7 +21,7 @@ Full details: `.planning/milestones/v1.0-ROADMAP.md`
-v1.1 Custom Sound Mappings (Phases 5-7) — SHIPPED 2026-03-26 +✅ v1.1 Custom Sound Mappings (Phases 5-7) — SHIPPED 2026-03-26 - [x] **Phase 5: Waveform Types and Bank Decoupling** - 2/2 plans — completed 2026-03-26 - [x] **Phase 6: Config Package and Sound Overrides** - 2/2 plans — completed 2026-03-26 @@ -31,70 +31,17 @@ Full details: `.planning/milestones/v1.1-ROADMAP.md`
-### v1.2 Extended Protocol Coverage (In Progress) +
+✅ v1.2 Extended Protocol Coverage (Phases 8-11) — SHIPPED 2026-03-27 -**Milestone Goal:** Expand traffic classification with grouped protocol families that share recognizable sound signatures — from 14 classes to ~35, organized into frequency bands by family. +- [x] **Phase 8: Test and Constant Cleanup** - 1/1 plans — completed 2026-03-27 +- [x] **Phase 9: Frequency Design and Group Architecture** - 2/2 plans — completed 2026-03-27 +- [x] **Phase 10: Classification Layer** - 2/2 plans — completed 2026-03-27 +- [x] **Phase 11: Synthesis and Config Layer** - 2/2 plans — completed 2026-03-27 -- [x] **Phase 8: Test and Constant Cleanup** - 1 plan — Remove stale constants and update test bounds that would block all subsequent v1.2 work (completed 2026-03-27) -- [ ] **Phase 9: Frequency Design and Group Architecture** - 2 plans — Design complete Hz allocation for all ~35 classes in family bands and add Group field to FreqConfig -- [x] **Phase 10: Classification Layer** - 2 plans — Add 21 new TrafficClass constants, 30 port rules, and test coverage for all new protocol families (completed 2026-03-27) -- [x] **Phase 11: Synthesis and Config Layer** - Add ClassFreqConfigs entries for all new classes, update auto-assign range, and add group-header output to --print-config (completed 2026-03-27) +Full details: `.planning/milestones/v1.2-ROADMAP.md` -## Phase Details - -### Phase 8: Test and Constant Cleanup -**Goal**: Pre-existing test assertions and a stale exported constant that would block or mislead all subsequent v1.2 work are removed -**Depends on**: Phase 7 -**Requirements**: CLEAN-01 -**Success Criteria** (what must be TRUE): - 1. `go test ./...` passes on main with no modifications to the new v1.2 code path - 2. The stale `NumLayers`/`GainPerLayer` exported constant no longer exists in the synth package — callers cannot accidentally use it - 3. `TestFrequenciesInRange` accepts the new extended Hz range without manual test surgery when new classes are added in Phase 10 -**Plans:** 1/1 plans complete -Plans: -- [x] 08-01-PLAN.md — Delete stale constants, future-proof test bounds, rename/consolidate tests - -### Phase 9: Frequency Design and Group Architecture -**Goal**: A complete, documented frequency allocation table for all ~35 traffic classes exists and the FreqConfig struct carries a Group field — design decisions are locked in before any protocol code is written -**Depends on**: Phase 8 -**Requirements**: FREQ-01, FREQ-02, FREQ-03, FREQ-04, GRP-01, GRP-04 -**Success Criteria** (what must be TRUE): - 1. A written frequency allocation table (in a planning doc or code comment) lists every built-in class, its Hz value, waveform, and group — no class is TBD - 2. Every within-family pair of frequencies satisfies at least a major second interval (ratio 1.122), verifiable by inspection of the table - 3. The `autoAssignFreq` base for user-defined custom classes is set above all built-in frequencies, with no collision possible - 4. `FreqConfig` has a `Group` string field and all existing `ClassFreqConfigs` entries compile with the new struct shape -**Plans:** 1/2 plans executed -Plans: -- [ ] 09-01-PLAN.md — Add Group field to FreqConfig, rebalance ClassFreqConfigs to major-second ladder -- [x] 09-02-PLAN.md — Update auto-assign range from [1200,2350] to [2500,4000] Hz - -### Phase 10: Classification Layer -**Goal**: All new protocol families are classified — ~21 new TrafficClass constants exist, AllClasses() covers them, and DefaultRules maps all new ports to their classes -**Depends on**: Phase 9 -**Requirements**: PROTO-01, PROTO-02, PROTO-03, PROTO-04, PROTO-05, PROTO-06, PROTO-07, PROTO-08, PROTO-09 -**Success Criteria** (what must be TRUE): - 1. A packet arriving on any new protocol port (e.g., TCP 143, TCP 3389, TCP 3306, UDP 5353, TCP 5060) is classified into the correct named TrafficClass, not into other-TCP or other-UDP - 2. All existing 10 protocol classifications continue to match as before — no regression in rule order or port assignments - 3. Multiple ports mapping to the same family class (e.g., IMAP port 143 and IMAPS port 993 both classify as the same Mail-IMAP class) behave identically in the classifier output - 4. `go test ./classify/...` passes with no new test failures -**Plans:** 2/2 plans complete -Plans: -- [x] 10-01-PLAN.md — Add 21 TrafficClass constants and 30 port-matching rules -- [x] 10-02-PLAN.md — Add 28 classification subtests and update TestAllClassesCount - -### Phase 11: Synthesis and Config Layer -**Goal**: Every new traffic class produces a distinct, family-coherent sound and --print-config shows all classes organized by group with section headers -**Depends on**: Phase 9, Phase 10 -**Requirements**: GRP-02, GRP-03 -**Success Criteria** (what must be TRUE): - 1. Running `netsynth --print-config` shows all ~35 classes grouped by family with section header comments (e.g., `# Mail`, `# Database`) — no class is listed without a group - 2. A pcap or live capture that triggers Mail traffic produces tones that are audibly in the same timbral family — same waveform type, similar frequency register — while still being distinguishable from each other - 3. Users can define `[groups]` in their TOML config to reassign a protocol to a different sound family, and --print-config reflects the reassignment - 4. `go test ./...` passes and a listening test on a representative pcap confirms family identity is perceptually clear -**Plans:** 2/2 plans complete -Plans: -- [x] 11-01-PLAN.md — Add 21 ClassFreqConfigs entries, update AllClasses() to 35, fix all count tests -- [x] 11-02-PLAN.md — Refactor PrintConfig for group headers, add [groups] TOML support +
## Progress @@ -107,7 +54,7 @@ Plans: | 5. Waveform Types and Bank Decoupling | v1.1 | 2/2 | Complete | 2026-03-26 | | 6. Config Package and Sound Overrides | v1.1 | 2/2 | Complete | 2026-03-26 | | 7. Custom Rules and Print-Config | v1.1 | 2/2 | Complete | 2026-03-26 | -| 8. Test and Constant Cleanup | v1.2 | 1/1 | Complete | 2026-03-27 | -| 9. Frequency Design and Group Architecture | v1.2 | 1/2 | In Progress| | -| 10. Classification Layer | v1.2 | 2/2 | Complete | 2026-03-27 | -| 11. Synthesis and Config Layer | v1.2 | 2/2 | Complete | 2026-03-27 | +| 8. Test and Constant Cleanup | v1.2 | 1/1 | Complete | 2026-03-27 | +| 9. Frequency Design and Group Architecture | v1.2 | 2/2 | Complete | 2026-03-27 | +| 10. Classification Layer | v1.2 | 2/2 | Complete | 2026-03-27 | +| 11. Synthesis and Config Layer | v1.2 | 2/2 | Complete | 2026-03-27 | diff --git a/.planning/STATE.md b/.planning/STATE.md index 778dbf2..6fc481d 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,16 +2,16 @@ gsd_state_version: 1.0 milestone: v1.2 milestone_name: Extended Protocol Coverage -status: executing -stopped_at: Completed 11-02-PLAN.md -last_updated: "2026-03-27T15:41:48.129Z" +status: complete +stopped_at: Milestone v1.2 archived +last_updated: "2026-03-27T16:00:00.000Z" last_activity: 2026-03-27 progress: total_phases: 4 completed_phases: 4 total_plans: 7 completed_plans: 7 - percent: 0 + percent: 100 --- # Project State @@ -21,66 +21,39 @@ progress: See: .planning/PROJECT.md (updated 2026-03-27) **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. -<<<<<<< Updated upstream -**Current focus:** Phase 11 — synthesis-and-config-layer +**Current focus:** Planning next milestone ## Current Position -Phase: 11 -Plan: Not started -Status: Ready to execute +Phase: All v1.2 phases complete +Plan: All plans complete +Status: Milestone v1.2 shipped Last activity: 2026-03-27 -======= -**Current focus:** Phase 06 — config-package-and-sound-overrides -## Current Position - -Phase: 06 (config-package-and-sound-overrides) — EXECUTING -Plan: 1 of 2 -Status: Executing Phase 06 -Last activity: 2026-03-26 -- Phase 06 execution started ->>>>>>> Stashed changes - -Progress: [░░░░░░░░░░] 0% +Progress: [██████████] 100% ## Performance Metrics -**Velocity (v1.1 baseline):** +**Velocity (v1.2):** -- Total plans completed: 6 -- Average duration: ~3 min -- Total execution time: ~18 min +- Total plans completed: 7 +- Phases: 4 (8-11) +- Timeline: 1 day (2026-03-27) -**By Phase (v1.1):** +**By Phase (v1.2):** -| Phase | Plans | Total | Avg/Plan | -|-------|-------|-------|----------| -| 05 | 2 | ~7min | 3.5min | -| 06 | 2 | ~4min | 2min | -| 07 | 2 | ~6min | 3min | - -**Recent Trend:** Stable -| Phase 08 P01 | 1 | 2 tasks | 2 files | -| Phase 09 P02 | 3 | 2 tasks | 2 files | -| Phase 10 P02 | 2 | 2 tasks | 1 files | -| Phase 11 P02 | 5min | 2 tasks | 2 files | +| Phase | Plans | Duration | Files | +|-------|-------|----------|-------| +| 08 | 1 | ~1min | 2 | +| 09 | 2 | ~10min | 7 | +| 10 | 2 | ~5min | 3 | +| 11 | 2 | ~13min | 7 | ## Accumulated Context ### Decisions -- [v1.2 Roadmap]: Phase 8 before everything — stale NumLayers/GainPerLayer constant and hardcoded TestFrequenciesInRange bounds cause false CI failures throughout milestone if not removed first -- [v1.2 Roadmap]: Phase 9 is design-only (no protocol code) — Hz allocation must be locked before ClassFreqConfigs entries are written; retroactive rebalancing touches every entry -- [v1.2 Roadmap]: Phase 10 before Phase 11 — TrafficClass constants must exist before ClassFreqConfigs can reference them (three-location atomicity enforced by existing test) -- [v1.2 Roadmap]: GRP-02 and GRP-03 deferred to Phase 11 — PrintConfig group headers and TOML [groups] config depend on both Group field (Phase 9) and new class constants (Phase 10) -- [Phase 07]: addAutoFreqEntries runs before merge so [sounds.X] overrides apply to user-defined classes -- [Phase 07]: LoadResult struct chosen over tuple return for config.Load() — cleaner API contract -- [Phase 08]: NumLayers and GainPerLayer deleted — dead code since NewBank computes gain dynamically as 1/N -- [Phase 08]: TestFrequenciesInRange now validates against Nyquist (22050 Hz) — any new BaseHz in (0, 22050) is accepted without test surgery -- [Phase 09]: autoAssignFreq range moved to [2500, 4000] Hz with numSteps=31 to guarantee no collision with built-in frequencies (max 2449 Hz) -- [Phase 10]: TestAllClassesCount updated to 32 (14 existing + 18 new; LDAP/Kerberos/Syslog excluded until Phase 11 adds ClassFreqConfigs) -- [Phase 11]: Non-canonical group names (user-invented via [groups]) emitted after canonical groups in alphabetical order -- [Phase 11]: builtinByGroup built from result.FreqCfgs[cls].Group (effective group after reassignment) not from synth defaults +See .planning/milestones/v1.2-ROADMAP.md for full decision log. ### Pending Todos @@ -88,11 +61,10 @@ Progress: [░░░░░░░░░░] 0% ### Blockers/Concerns -- [v1.2 pre-work]: autoAssignFreq range [1200, 2350] Hz will collide with new built-in frequencies unless pushed above all new entries (addressed in Phase 9 design) -- [v1.2 pre-work]: Frequency rebalancing may silently invalidate v1.1 user TOML configs with explicit Hz overrides — mitigation: assign all new protocols above 1047 Hz to leave existing layout frozen +None — milestone complete. ## Session Continuity -Last session: 2026-03-27T15:37:08.965Z -Stopped at: Completed 11-02-PLAN.md +Last session: 2026-03-27 +Stopped at: Milestone v1.2 archived Resume file: None diff --git a/.planning/REQUIREMENTS.md b/.planning/milestones/v1.2-REQUIREMENTS.md similarity index 96% rename from .planning/REQUIREMENTS.md rename to .planning/milestones/v1.2-REQUIREMENTS.md index 3174190..9b4fd8c 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/milestones/v1.2-REQUIREMENTS.md @@ -1,3 +1,12 @@ +# Requirements Archive: v1.2 Extended Protocol Coverage + +**Archived:** 2026-03-27 +**Status:** SHIPPED + +For current requirements, see `.planning/REQUIREMENTS.md`. + +--- + # Requirements: NetSynth **Defined:** 2026-03-27 diff --git a/.planning/milestones/v1.2-ROADMAP.md b/.planning/milestones/v1.2-ROADMAP.md new file mode 100644 index 0000000..4a1835e --- /dev/null +++ b/.planning/milestones/v1.2-ROADMAP.md @@ -0,0 +1,113 @@ +# Roadmap: NetSynth + +## Milestones + +- **v1.0 MVP** — Phases 1-4 (shipped 2026-03-26) +- **v1.1 Custom Sound Mappings** — Phases 5-7 (shipped 2026-03-26) +- **v1.2 Extended Protocol Coverage** — Phases 8-11 (in progress) + +## Phases + +
+v1.0 MVP (Phases 1-4) — SHIPPED 2026-03-26 + +- [x] **Phase 1: Capture and Classification** - 4/4 plans — completed 2026-03-25 +- [x] **Phase 2: Audio Synthesis Engine** - 3/3 plans — completed 2026-03-26 +- [x] **Phase 3: Pipeline Integration and MVP** - 2/2 plans — completed 2026-03-26 +- [x] **Phase 4: Power User Features** - 2/2 plans — completed 2026-03-26 + +Full details: `.planning/milestones/v1.0-ROADMAP.md` + +
+ +
+v1.1 Custom Sound Mappings (Phases 5-7) — SHIPPED 2026-03-26 + +- [x] **Phase 5: Waveform Types and Bank Decoupling** - 2/2 plans — completed 2026-03-26 +- [x] **Phase 6: Config Package and Sound Overrides** - 2/2 plans — completed 2026-03-26 +- [x] **Phase 7: Custom Rules and Print-Config** - 2/2 plans — completed 2026-03-26 + +Full details: `.planning/milestones/v1.1-ROADMAP.md` + +
+ +### v1.2 Extended Protocol Coverage (In Progress) + +**Milestone Goal:** Expand traffic classification with grouped protocol families that share recognizable sound signatures — from 14 classes to ~35, organized into frequency bands by family. + +- [x] **Phase 8: Test and Constant Cleanup** - 1 plan — Remove stale constants and update test bounds that would block all subsequent v1.2 work (completed 2026-03-27) +- [ ] **Phase 9: Frequency Design and Group Architecture** - 2 plans — Design complete Hz allocation for all ~35 classes in family bands and add Group field to FreqConfig +- [x] **Phase 10: Classification Layer** - 2 plans — Add 21 new TrafficClass constants, 30 port rules, and test coverage for all new protocol families (completed 2026-03-27) +- [x] **Phase 11: Synthesis and Config Layer** - Add ClassFreqConfigs entries for all new classes, update auto-assign range, and add group-header output to --print-config (completed 2026-03-27) + +## Phase Details + +### Phase 8: Test and Constant Cleanup +**Goal**: Pre-existing test assertions and a stale exported constant that would block or mislead all subsequent v1.2 work are removed +**Depends on**: Phase 7 +**Requirements**: CLEAN-01 +**Success Criteria** (what must be TRUE): + 1. `go test ./...` passes on main with no modifications to the new v1.2 code path + 2. The stale `NumLayers`/`GainPerLayer` exported constant no longer exists in the synth package — callers cannot accidentally use it + 3. `TestFrequenciesInRange` accepts the new extended Hz range without manual test surgery when new classes are added in Phase 10 +**Plans:** 1/1 plans complete +Plans: +- [x] 08-01-PLAN.md — Delete stale constants, future-proof test bounds, rename/consolidate tests + +### Phase 9: Frequency Design and Group Architecture +**Goal**: A complete, documented frequency allocation table for all ~35 traffic classes exists and the FreqConfig struct carries a Group field — design decisions are locked in before any protocol code is written +**Depends on**: Phase 8 +**Requirements**: FREQ-01, FREQ-02, FREQ-03, FREQ-04, GRP-01, GRP-04 +**Success Criteria** (what must be TRUE): + 1. A written frequency allocation table (in a planning doc or code comment) lists every built-in class, its Hz value, waveform, and group — no class is TBD + 2. Every within-family pair of frequencies satisfies at least a major second interval (ratio 1.122), verifiable by inspection of the table + 3. The `autoAssignFreq` base for user-defined custom classes is set above all built-in frequencies, with no collision possible + 4. `FreqConfig` has a `Group` string field and all existing `ClassFreqConfigs` entries compile with the new struct shape +**Plans:** 1/2 plans executed +Plans: +- [ ] 09-01-PLAN.md — Add Group field to FreqConfig, rebalance ClassFreqConfigs to major-second ladder +- [x] 09-02-PLAN.md — Update auto-assign range from [1200,2350] to [2500,4000] Hz + +### Phase 10: Classification Layer +**Goal**: All new protocol families are classified — ~21 new TrafficClass constants exist, AllClasses() covers them, and DefaultRules maps all new ports to their classes +**Depends on**: Phase 9 +**Requirements**: PROTO-01, PROTO-02, PROTO-03, PROTO-04, PROTO-05, PROTO-06, PROTO-07, PROTO-08, PROTO-09 +**Success Criteria** (what must be TRUE): + 1. A packet arriving on any new protocol port (e.g., TCP 143, TCP 3389, TCP 3306, UDP 5353, TCP 5060) is classified into the correct named TrafficClass, not into other-TCP or other-UDP + 2. All existing 10 protocol classifications continue to match as before — no regression in rule order or port assignments + 3. Multiple ports mapping to the same family class (e.g., IMAP port 143 and IMAPS port 993 both classify as the same Mail-IMAP class) behave identically in the classifier output + 4. `go test ./classify/...` passes with no new test failures +**Plans:** 2/2 plans complete +Plans: +- [x] 10-01-PLAN.md — Add 21 TrafficClass constants and 30 port-matching rules +- [x] 10-02-PLAN.md — Add 28 classification subtests and update TestAllClassesCount + +### Phase 11: Synthesis and Config Layer +**Goal**: Every new traffic class produces a distinct, family-coherent sound and --print-config shows all classes organized by group with section headers +**Depends on**: Phase 9, Phase 10 +**Requirements**: GRP-02, GRP-03 +**Success Criteria** (what must be TRUE): + 1. Running `netsynth --print-config` shows all ~35 classes grouped by family with section header comments (e.g., `# Mail`, `# Database`) — no class is listed without a group + 2. A pcap or live capture that triggers Mail traffic produces tones that are audibly in the same timbral family — same waveform type, similar frequency register — while still being distinguishable from each other + 3. Users can define `[groups]` in their TOML config to reassign a protocol to a different sound family, and --print-config reflects the reassignment + 4. `go test ./...` passes and a listening test on a representative pcap confirms family identity is perceptually clear +**Plans:** 2/2 plans complete +Plans: +- [x] 11-01-PLAN.md — Add 21 ClassFreqConfigs entries, update AllClasses() to 35, fix all count tests +- [x] 11-02-PLAN.md — Refactor PrintConfig for group headers, add [groups] TOML support + +## Progress + +| Phase | Milestone | Plans Complete | Status | Completed | +|-------|-----------|----------------|--------|-----------| +| 1. Capture and Classification | v1.0 | 4/4 | Complete | 2026-03-25 | +| 2. Audio Synthesis Engine | v1.0 | 3/3 | Complete | 2026-03-26 | +| 3. Pipeline Integration and MVP | v1.0 | 2/2 | Complete | 2026-03-26 | +| 4. Power User Features | v1.0 | 2/2 | Complete | 2026-03-26 | +| 5. Waveform Types and Bank Decoupling | v1.1 | 2/2 | Complete | 2026-03-26 | +| 6. Config Package and Sound Overrides | v1.1 | 2/2 | Complete | 2026-03-26 | +| 7. Custom Rules and Print-Config | v1.1 | 2/2 | Complete | 2026-03-26 | +| 8. Test and Constant Cleanup | v1.2 | 1/1 | Complete | 2026-03-27 | +| 9. Frequency Design and Group Architecture | v1.2 | 1/2 | In Progress| | +| 10. Classification Layer | v1.2 | 2/2 | Complete | 2026-03-27 | +| 11. Synthesis and Config Layer | v1.2 | 2/2 | Complete | 2026-03-27 | diff --git a/.planning/phases/08-test-and-constant-cleanup/08-01-PLAN.md b/.planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-01-PLAN.md similarity index 100% rename from .planning/phases/08-test-and-constant-cleanup/08-01-PLAN.md rename to .planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-01-PLAN.md diff --git a/.planning/phases/08-test-and-constant-cleanup/08-01-SUMMARY.md b/.planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-01-SUMMARY.md similarity index 100% rename from .planning/phases/08-test-and-constant-cleanup/08-01-SUMMARY.md rename to .planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-01-SUMMARY.md diff --git a/.planning/phases/08-test-and-constant-cleanup/08-CONTEXT.md b/.planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-CONTEXT.md similarity index 100% rename from .planning/phases/08-test-and-constant-cleanup/08-CONTEXT.md rename to .planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-CONTEXT.md diff --git a/.planning/phases/08-test-and-constant-cleanup/08-DISCUSSION-LOG.md b/.planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-DISCUSSION-LOG.md similarity index 100% rename from .planning/phases/08-test-and-constant-cleanup/08-DISCUSSION-LOG.md rename to .planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-DISCUSSION-LOG.md diff --git a/.planning/phases/08-test-and-constant-cleanup/08-RESEARCH.md b/.planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-RESEARCH.md similarity index 100% rename from .planning/phases/08-test-and-constant-cleanup/08-RESEARCH.md rename to .planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-RESEARCH.md diff --git a/.planning/phases/08-test-and-constant-cleanup/08-VALIDATION.md b/.planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-VALIDATION.md similarity index 100% rename from .planning/phases/08-test-and-constant-cleanup/08-VALIDATION.md rename to .planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-VALIDATION.md diff --git a/.planning/phases/08-test-and-constant-cleanup/08-VERIFICATION.md b/.planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-VERIFICATION.md similarity index 100% rename from .planning/phases/08-test-and-constant-cleanup/08-VERIFICATION.md rename to .planning/milestones/v1.2-phases/08-test-and-constant-cleanup/08-VERIFICATION.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-01-PLAN.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-01-PLAN.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-01-PLAN.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-01-PLAN.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-01-SUMMARY.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-01-SUMMARY.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-01-SUMMARY.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-01-SUMMARY.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-02-PLAN.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-02-PLAN.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-02-PLAN.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-02-PLAN.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-02-SUMMARY.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-02-SUMMARY.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-02-SUMMARY.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-02-SUMMARY.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-CONTEXT.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-CONTEXT.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-CONTEXT.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-CONTEXT.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-DISCUSSION-LOG.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-DISCUSSION-LOG.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-DISCUSSION-LOG.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-DISCUSSION-LOG.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-RESEARCH.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-RESEARCH.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-RESEARCH.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-RESEARCH.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-VALIDATION.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-VALIDATION.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-VALIDATION.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-VALIDATION.md diff --git a/.planning/phases/09-frequency-design-and-group-architecture/09-VERIFICATION.md b/.planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-VERIFICATION.md similarity index 100% rename from .planning/phases/09-frequency-design-and-group-architecture/09-VERIFICATION.md rename to .planning/milestones/v1.2-phases/09-frequency-design-and-group-architecture/09-VERIFICATION.md diff --git a/.planning/phases/10-classification-layer/10-01-PLAN.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-01-PLAN.md similarity index 100% rename from .planning/phases/10-classification-layer/10-01-PLAN.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-01-PLAN.md diff --git a/.planning/phases/10-classification-layer/10-01-SUMMARY.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-01-SUMMARY.md similarity index 100% rename from .planning/phases/10-classification-layer/10-01-SUMMARY.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-01-SUMMARY.md diff --git a/.planning/phases/10-classification-layer/10-02-PLAN.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-02-PLAN.md similarity index 100% rename from .planning/phases/10-classification-layer/10-02-PLAN.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-02-PLAN.md diff --git a/.planning/phases/10-classification-layer/10-02-SUMMARY.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-02-SUMMARY.md similarity index 100% rename from .planning/phases/10-classification-layer/10-02-SUMMARY.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-02-SUMMARY.md diff --git a/.planning/phases/10-classification-layer/10-CONTEXT.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-CONTEXT.md similarity index 100% rename from .planning/phases/10-classification-layer/10-CONTEXT.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-CONTEXT.md diff --git a/.planning/phases/10-classification-layer/10-DISCUSSION-LOG.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-DISCUSSION-LOG.md similarity index 100% rename from .planning/phases/10-classification-layer/10-DISCUSSION-LOG.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-DISCUSSION-LOG.md diff --git a/.planning/phases/10-classification-layer/10-RESEARCH.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-RESEARCH.md similarity index 100% rename from .planning/phases/10-classification-layer/10-RESEARCH.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-RESEARCH.md diff --git a/.planning/phases/10-classification-layer/10-VALIDATION.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-VALIDATION.md similarity index 100% rename from .planning/phases/10-classification-layer/10-VALIDATION.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-VALIDATION.md diff --git a/.planning/phases/10-classification-layer/10-VERIFICATION.md b/.planning/milestones/v1.2-phases/10-classification-layer/10-VERIFICATION.md similarity index 100% rename from .planning/phases/10-classification-layer/10-VERIFICATION.md rename to .planning/milestones/v1.2-phases/10-classification-layer/10-VERIFICATION.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-01-PLAN.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-01-PLAN.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-01-PLAN.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-01-PLAN.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-01-SUMMARY.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-01-SUMMARY.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-01-SUMMARY.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-01-SUMMARY.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-02-PLAN.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-02-PLAN.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-02-PLAN.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-02-PLAN.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-02-SUMMARY.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-02-SUMMARY.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-02-SUMMARY.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-02-SUMMARY.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-CONTEXT.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-CONTEXT.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-CONTEXT.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-CONTEXT.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-DISCUSSION-LOG.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-DISCUSSION-LOG.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-DISCUSSION-LOG.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-DISCUSSION-LOG.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-RESEARCH.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-RESEARCH.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-RESEARCH.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-RESEARCH.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-VALIDATION.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-VALIDATION.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-VALIDATION.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-VALIDATION.md diff --git a/.planning/phases/11-synthesis-and-config-layer/11-VERIFICATION.md b/.planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-VERIFICATION.md similarity index 100% rename from .planning/phases/11-synthesis-and-config-layer/11-VERIFICATION.md rename to .planning/milestones/v1.2-phases/11-synthesis-and-config-layer/11-VERIFICATION.md diff --git a/README.md b/README.md index 3084ceb..d843006 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **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. +NetSynth captures live network traffic (or reads pcap files), classifies packets into 35 protocol families, 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. @@ -133,7 +133,19 @@ waveform = "square" ### Available Traffic Classes -`ICMP`, `DNS`, `HTTPS`, `HTTP`, `SSH`, `SMTP`, `NTP`, `DHCP`, `OtherTCP`, `OtherUDP`, `Unknown1`, `Unknown2`, `Unknown3`, `Unknown4` +35 built-in classes organized by protocol family: + +| Family | Classes | +|--------|---------| +| Infrastructure | `ICMP`, `DNS`, `NTP`, `DHCP`, `mDNS`, `SSDP`, `SNMP`, `LDAP`, `Kerberos`, `Syslog` | +| Web | `HTTPS`, `HTTP`, `QUIC` | +| Mail | `SMTP`, `IMAP`, `POP3`, `SMTP-Sub` | +| Remote Access | `SSH`, `RDP`, `Telnet`, `VNC` | +| File Transfer | `FTP`, `SMB`, `TFTP` | +| Database | `MySQL`, `PostgreSQL`, `Redis`, `MongoDB` | +| Discovery | `mDNS`, `SSDP`, `SNMP` | +| VoIP | `SIP` | +| Unknown | `OtherTCP`, `OtherUDP`, `Unknown1`-`Unknown4` | ### Available Waveforms @@ -168,7 +180,7 @@ frequency = 1500.0 waveform = "sawtooth" ``` -Custom classes that don't have a `[sounds.*]` entry automatically get a unique frequency in the 1200-2350 Hz range. +Custom classes that don't have a `[sounds.*]` entry automatically get a unique frequency in the 2500-4000 Hz range. ### Print Config @@ -185,7 +197,19 @@ netsynth --config my-sounds.toml --print-config netsynth --print-config > template.toml ``` -The output includes `(default)`, `(override)`, and `(auto-assigned)` annotations so you can see what's customized. +The output includes `(default)`, `(override)`, and `(auto-assigned)` annotations so you can see what's customized. Classes are grouped by protocol family with section headers. + +### Group Reassignment + +You can reassign protocols to different sound families using the `[groups]` table: + +```toml +[groups] +DNS = "Web" # Move DNS from Infrastructure to Web family +SIP = "Infrastructure" # Move SIP from VoIP to Infrastructure +``` + +Reassigned protocols inherit the waveform character of their new family in `--print-config` output. ### Validation @@ -203,7 +227,7 @@ 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 protocol rules (ICMP, DNS, HTTPS, SSH, HTTP, SMTP, NTP, DHCP, etc.) plus any user-defined rules from the config file. User rules fire first. Unrecognized traffic is deterministically hash-bucketed into 4 "unknown" classes so it still produces distinct sounds. +2. **Classify** — Each packet is matched against 35 built-in protocol rules across 9 families (Infrastructure, Web, Mail, Remote Access, File Transfer, Database, Discovery, VoIP) plus any user-defined rules from the config file. User rules fire first. 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. @@ -211,21 +235,21 @@ Capture -> Classify -> Aggregate -> Synthesize -> MP3 ### 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 | +Protocols are grouped into families that share a waveform type and frequency register, making related traffic sound cohesive while remaining distinguishable. Frequencies follow a major-second ladder within each family. -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). +| Family | Waveform | Frequency Range | Protocols | +|--------|----------|----------------|-----------| +| Infrastructure | Triangle | 65-133 Hz | ICMP, NTP, DHCP, mDNS, SSDP, SNMP, DNS | +| Web | Sawtooth | 150-190 Hz | HTTPS, HTTP, QUIC | +| Mail | Triangle | 214-305 Hz | SMTP, IMAP, POP3, SMTP-Sub | +| Remote Access | Square | 343-485 Hz | SSH, RDP, Telnet, VNC | +| File Transfer | Square | 545-687 Hz | FTP, SMB, TFTP | +| Unknown | Custom | 771-1375 Hz | Unknown1-4, OtherTCP, OtherUDP | +| Database | Sawtooth | 1543-2182 Hz | MySQL, PostgreSQL, Redis, MongoDB | +| VoIP | Sine | 2449 Hz | SIP | +| Infrastructure (ext.) | Triangle | 2950-3250 Hz | LDAP, Kerberos, Syslog | + +Sustained traffic sounds louder; quiet periods fade to silence. The result is a unique audio fingerprint of your network activity. All frequencies, waveforms, and group assignments can be overridden via the [config file](#custom-sound-configuration). ## Project Structure