RFC: transparency & opt-in improvements #11

New Issue

2026-03-23T03:57:32+08:00

razvandimescu commented

2026-03-23 03:57:32 +08:00

(Migrated from github.com)

Context

Based on community feedback from j4c11, two specific concerns were raised:

Ad blocking adds a debugging variable — "when something breaks, I have to wonder if your ad blocking is interfering"
LAN discovery triggers IPS alerts — custom multicast on a non-standard port with unknown JSON payloads is flagged by corporate security tooling, generating tickets and alerts

Rather than removing features, the response is transparency and user control — make everything visible and opt-in.

Changes (all shipped in #12)

1. LAN discovery → opt-in ✅

[lan] enabled defaults to false. Zero multicast traffic unless explicitly enabled:

numa lan on          # one command, writes numa.toml
numa lan off         # disable

Or manually in numa.toml:

[lan]
enabled = true

2. Ad blocking — transparent and easy to disable ✅

# Check if a specific domain is blocked
curl -s localhost:5380/blocking/check/sentry-cdn.com | jq

# Full diagnostic — walks the entire resolution pipeline
curl -s localhost:5380/diagnose/sentry-cdn.com | jq

# See recently blocked queries
curl -s 'localhost:5380/query-log?path=BLOCKED&limit=10' | jq '.[] | {domain, path}'

# Live monitoring
watch -n1 'curl -s "localhost:5380/query-log?path=BLOCKED&limit=5" | jq -r ".[] | .domain"'

`numa.toml` now includes a commented `[blocking]` section showing how to disable:
```toml
[blocking]
enabled = false

On the roadmap: numa blocking on/off CLI command (matching numa lan on/off).```

3. mDNS migration ✅

Replaced custom multicast (239.255.70.78:5390 with JSON) with standard mDNS (_numa._tcp.local on port 5353):

IPS sees "mDNS/Bonjour" instead of "unknown protocol" — silently dropped if blocked, no alerts
Built minimal mDNS advertiser/browser reusing Numa's existing DNS packet parser
Instance ID in TXT record for multi-instance self-filtering
Interoperable: dns-sd -B _numa._tcp / avahi-browse can discover Numa services
Spike validated port 5353 coexistence with macOS mDNSResponder

4. Path-based routing ✅

One .numa domain, routes split by URL path to different local ports:

[[services]]
name = "app"
target_port = 3000
routes = [
    { path = "/auth", port = 5001 },
    { path = "/api", port = 5019, strip = true },
]

Longest prefix match with segment-boundary enforcement (/api won't match /apiary)
Optional strip = true removes matched prefix before forwarding
REST API: GET/POST/DELETE /services/{name}/routes
Dashboard shows route lines per service

5. Security hardening ✅

API binds 127.0.0.1 by default (was 0.0.0.0 — any LAN host could create overrides, disable blocking, read query log)
Proxy binds 127.0.0.1 by default, auto 0.0.0.0 when LAN enabled
Configurable via api_bind_addr and proxy bind_addr

6. Config visibility ✅

Startup banner shows resolved config path, data dir, and services path
Warns when config file not found, shows where to create one
Config search: tries ./numa.toml, then ~/.config/numa/numa.toml, then /usr/local/var/numa/numa.toml
/stats API exposes config_path and data_dir for dashboard
Dashboard footer shows config and data paths dynamically
GET /ca.pem endpoint serves the CA certificate for cross-device TLS trust

Status

Item	Status
LAN opt-in + `numa lan on/off`	Done
Ad blocking config & diagnostics	Done
mDNS migration	Done
Path-based routing	Done
Security hardening	Done
Config visibility	Done

All changes shipped in PR #12.

## Context Based on [community feedback](https://www.reddit.com/r/programare/) from [j4c11](https://www.reddit.com/user/j4c11/), two specific concerns were raised: 1. **Ad blocking adds a debugging variable** — "when something breaks, I have to wonder if your ad blocking is interfering" 2. **LAN discovery triggers IPS alerts** — custom multicast on a non-standard port with unknown JSON payloads is flagged by corporate security tooling, generating tickets and alerts Rather than removing features, the response is **transparency and user control** — make everything visible and opt-in. --- ## Changes (all shipped in #12) ### 1. LAN discovery → opt-in ✅ `[lan] enabled` defaults to `false`. Zero multicast traffic unless explicitly enabled: ```bash numa lan on # one command, writes numa.toml numa lan off # disable ``` Or manually in `numa.toml`: ```toml [lan] enabled = true ``` ### 2. Ad blocking — transparent and easy to disable ✅ ```bash # Check if a specific domain is blocked curl -s localhost:5380/blocking/check/sentry-cdn.com | jq # Full diagnostic — walks the entire resolution pipeline curl -s localhost:5380/diagnose/sentry-cdn.com | jq # See recently blocked queries curl -s 'localhost:5380/query-log?path=BLOCKED&limit=10' | jq '.[] | {domain, path}' # Live monitoring watch -n1 'curl -s "localhost:5380/query-log?path=BLOCKED&limit=5" | jq -r ".[] | .domain"' `numa.toml` now includes a commented `[blocking]` section showing how to disable: ```toml [blocking] enabled = false ``` On the roadmap: `numa blocking on/off` CLI command (matching `numa lan on/off`).``` ### 3. mDNS migration ✅ Replaced custom multicast (`239.255.70.78:5390` with JSON) with standard mDNS (`_numa._tcp.local` on port 5353): - IPS sees "mDNS/Bonjour" instead of "unknown protocol" — silently dropped if blocked, no alerts - Built minimal mDNS advertiser/browser reusing Numa's existing DNS packet parser - Instance ID in TXT record for multi-instance self-filtering - Interoperable: `dns-sd -B _numa._tcp` / `avahi-browse` can discover Numa services - Spike validated port 5353 coexistence with macOS mDNSResponder ### 4. Path-based routing ✅ One `.numa` domain, routes split by URL path to different local ports: ```toml [[services]] name = "app" target_port = 3000 routes = [ { path = "/auth", port = 5001 }, { path = "/api", port = 5019, strip = true }, ] ``` - Longest prefix match with segment-boundary enforcement (`/api` won't match `/apiary`) - Optional `strip = true` removes matched prefix before forwarding - REST API: `GET/POST/DELETE /services/{name}/routes` - Dashboard shows route lines per service ### 5. Security hardening ✅ - API binds `127.0.0.1` by default (was `0.0.0.0` — any LAN host could create overrides, disable blocking, read query log) - Proxy binds `127.0.0.1` by default, auto `0.0.0.0` when LAN enabled - Configurable via `api_bind_addr` and proxy `bind_addr` ### 6. Config visibility ✅ - Startup banner shows resolved config path, data dir, and services path - Warns when config file not found, shows where to create one - Config search: tries `./numa.toml`, then `~/.config/numa/numa.toml`, then `/usr/local/var/numa/numa.toml` - `/stats` API exposes `config_path` and `data_dir` for dashboard - Dashboard footer shows config and data paths dynamically - `GET /ca.pem` endpoint serves the CA certificate for cross-device TLS trust --- ## Status | Item | Status | |------|--------| | LAN opt-in + `numa lan on/off` | **Done** | | Ad blocking config & diagnostics | **Done** | | mDNS migration | **Done** | | Path-based routing | **Done** | | Security hardening | **Done** | | Config visibility | **Done** | All changes shipped in PR #12.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dearsky/numa#11