93 lines
4.7 KiB
Markdown
93 lines
4.7 KiB
Markdown
|
# NetworkCity
|
||
|
|
|
||
|
|
A macOS network monitor that renders live traffic as a top-down **city map** —
|
||
|
|
remote hosts become buildings, and your traffic becomes cars driving to them
|
||
|
|
(SimCity-style). This repo currently contains **Phase 1: the proven data layer**.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
ConnectionSource (protocol) ← the seam: "where bytes come from"
|
||
|
|
│
|
||
|
|
├─ NettopSource ← Phase 1: shells out to /usr/bin/nettop (no privileges)
|
||
|
|
└─ (libpcap source) ← Phase 2: real packets (needs privilege / helper tool)
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
ConnectionSnapshot ← list of Connection, with cumulative byte counts
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
SpriteKit "city" (Phase 3) ← buildings + cars; never knows the data source
|
||
|
|
```
|
||
|
|
|
||
|
|
The renderer depends only on `NetworkCityCore`, so the data backend can be
|
||
|
|
swapped without touching the visuals.
|
||
|
|
|
||
|
|
## Layout
|
||
|
|
|
||
|
|
- `Sources/NetworkCityCore/` — models, the `ConnectionSource` protocol, the
|
||
|
|
`nettop` parser (`NettopParser`, pure/testable) and poller (`NettopSource`).
|
||
|
|
- `Sources/nettop-probe/` — Phase-1 CLI proof of concept. Prints live KB/s.
|
||
|
|
- `Tests/` — parser tests pinned to real captured `nettop` output.
|
||
|
|
|
||
|
|
## Try it
|
||
|
|
|
||
|
|
```sh
|
||
|
|
swift test # parser tests against real fixtures
|
||
|
|
swift run nettop-probe # live traffic, busiest external flows as KB/s
|
||
|
|
```
|
||
|
|
|
||
|
|
## Key design facts (learned from real output)
|
||
|
|
|
||
|
|
- **nettop format**: process rows are `Name.PID,bytes_in,bytes_out`; the
|
||
|
|
connection sub-rows beneath inherit that process. IPv4 ports use `:`, IPv6
|
||
|
|
uses `.` and may carry a `%zone` suffix.
|
||
|
|
- **Rates by diffing**: byte counts are lifetime-cumulative, so we keep the last
|
||
|
|
snapshot and subtract. Robust to nettop quirks; works across fresh invocations.
|
||
|
|
- **Process names are unreliable** — nettop truncates/mangles them (it reported
|
||
|
|
`claude` as `2.1.177`). The **pid is trustworthy**; enrich the real name via
|
||
|
|
`proc_pidpath`/`ps` keyed on pid. (Phase-2 polish.)
|
||
|
|
- **`isExternal`** filters listeners, loopback, and link-local so only real
|
||
|
|
off-box destinations become buildings.
|
||
|
|
|
||
|
|
## Roadmap
|
||
|
|
|
||
|
|
1. ✅ Data layer + live probe (nettop, no privileges)
|
||
|
|
2. ✅ SpriteKit city — SwiftUI window, glowing buildings, cars of light
|
||
|
|
(`swift run NetworkCityApp`): cyan cars inbound = downloads, amber outbound
|
||
|
|
= uploads; deterministic building placement; drag to pan, scroll to zoom.
|
||
|
|
3. ✅ Enrichment — real process names (`proc_pidpath`), reverse-DNS + a curated
|
||
|
|
CIDR table so hosts group into named **districts** (Apple, Google, AWS,
|
||
|
|
Telegram, Local Network…). PTR is primary; the CIDR table catches the
|
||
|
|
no-PTR giants (all of `17.0.0.0/8` is Apple). Run with `NC_DEBUG=1` to log
|
||
|
|
each host→district resolution to stderr.
|
||
|
|
4. ✅ Hub-and-spoke — busy districts auto-expand into their endpoints
|
||
|
|
(`This Mac → OneDrive → its many servers`); cars route the full two-segment
|
||
|
|
path. Expansion is a pure, tested `ExpansionPolicy` (≥2 endpoints, top-K by
|
||
|
|
bytes, TTL tail to avoid flicker). A single client downloading from a CDN
|
||
|
|
pins to one IP, so fan-out is driven by apps that genuinely spread
|
||
|
|
connections (sync clients, browsers).
|
||
|
|
5. ✅ Traffic differentiation — cars coloured by protocol class (DNS gold,
|
||
|
|
HTTPS cyan, HTTP orange, QUIC violet, Other slate) since direction is already
|
||
|
|
read from motion. Behaviour reinforces it: DNS = tiny fast sparks, QUIC =
|
||
|
|
streaks, heavy flows = big slow "freight" comets. Classifier is a pure tested
|
||
|
|
`TrafficClass`; HUD shows a legend.
|
||
|
|
6. ✅ Label anti-overlap (`LayoutSolver`).
|
||
|
|
7. ✅ Click-to-inspect — click a district hub to open a live panel: total
|
||
|
|
down/up, every endpoint with its reverse-DNS name + per-endpoint rate +
|
||
|
|
protocol-colour dot, and the owning process(es). Click empty space or ✕ to
|
||
|
|
close. A pulsing ring marks the selection. Click vs drag is disambiguated by
|
||
|
|
movement distance.
|
||
|
|
8. ✅ Latency as distance — distance from downtown = measured round-trip time
|
||
|
|
(unprivileged TCP-connect probe, cached), not geography. GeoIP was rejected
|
||
|
|
because anycast makes it assert a physical fiction; latency is measured so it
|
||
|
|
can't lie. Districts glide to their true distance as probes complete; the
|
||
|
|
inspector shows per-endpoint ms. Pure `LatencyLayout` (log curve) is tested;
|
||
|
|
`LatencyProber` uses Network.framework. Our own pid is filtered out so we
|
||
|
|
don't render our own probes.
|
||
|
|
9. `MenuBarExtra` shell; optional libpcap source via privileged helper.
|
||
|
|
|
||
|
|
### Env flags (opt-in diagnostics)
|
||
|
|
- `NC_DEBUG=1` — log host→district resolution, per-tick top districts, and fan-outs to stderr.
|
||
|
|
- `NC_DEMO=1` — offline demo: feeds a synthetic 8-endpoint "OneDrive" through the
|
||
|
|
real scene so the hub-and-spoke fan-out runs without nettop.
|