From 76a45f445daa9032bb66016209a1cca68f8bb0c4 Mon Sep 17 00:00:00 2001 From: Thom Date: Wed, 3 Jun 2026 19:15:51 -0700 Subject: [PATCH 1/6] chore: ignore dist/, drop unused agent ignores --- .gitignore | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 3fbf9aa..637bb7e 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ DEV_NOTES/ /umberrelay *.exe *.tar +dist/ # Database files *.db @@ -33,7 +34,3 @@ coverage.out # Docker .env - -# Agents -.claude/ -.codex From 74d8bd59ee5767faa55bf121a2994e41bf1b94e9 Mon Sep 17 00:00:00 2001 From: Thom Date: Wed, 3 Jun 2026 19:18:47 -0700 Subject: [PATCH 2/6] docs: fix go version drift, note govulncheck --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8bfe1dd..24ac210 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ Thanks for your interest in contributing. Umberrelay is a small Raspberry Pi and ## Getting Started 1. Fork the repo and clone your fork -2. Make sure you have Go 1.26.1+ installed +2. Make sure you have the Go version required by `go.mod` installed 3. Run `go test ./...` to verify everything passes 4. Create a branch for your change @@ -39,6 +39,7 @@ The script: - Keep changes focused — one feature or fix per PR - Include tests for any new functionality - Make sure `go build ./...`, `go test ./...`, and `go vet ./...` pass before submitting +- CI also runs `govulncheck`; you can check locally with `go run golang.org/x/vuln/cmd/govulncheck@latest ./...` ## Reporting Bugs From 33710489e2f3d6a14084a58c434f4c8aa1d13f0a Mon Sep 17 00:00:00 2001 From: Thom Date: Wed, 3 Jun 2026 19:25:42 -0700 Subject: [PATCH 3/6] docs: tighten README language --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 079172d..0a873fe 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ ## What It Does -Umberrelay is a forwarding DNS server that logs every query, identifies which network actor made it, and classifies domains against community-maintained tracking lists. It gives you an attribution-focused picture of where your network traffic is going — and how much of it is talking to trackers. +Umberrelay is a forwarding DNS server that logs every query, identifies which network actor made it, and classifies domains against community-maintained tracking lists. It gives you an attribution-focused picture of where your network traffic is going, and how much of it is talking to trackers. ## Features @@ -63,7 +63,7 @@ Then point your router's DNS to the host running Umberrelay. ## Deployment Model -Umberrelay works best when it is the DNS server your network actually uses. In the common setup, that means pointing your router's LAN DNS setting at the host running Umberrelay so client devices send their queries through it. +Umberrelay works best when it is the DNS server your network uses. In the common setup, that means pointing your router's LAN DNS setting at the host running Umberrelay so client devices send their queries through it. ### Works With Pi-hole / AdGuard Home @@ -93,7 +93,7 @@ Caveats: ## Configuration -Umberrelay needs minimal bootstrap config — everything else is managed through the web UI. +Umberrelay needs minimal bootstrap config. Everything else is managed through the web UI. ```toml # config.toml @@ -112,7 +112,7 @@ http_port = 8080 | `http_listen` | `0.0.0.0` | Web UI and API bind address (host/interface only) | | `http_port` | `8080` | Web UI and API port | -All fields are optional — Umberrelay runs with sane defaults if no config file exists. +All fields are optional. Umberrelay runs with sane defaults if no config file exists. ### Runtime Settings @@ -134,7 +134,7 @@ Umberrelay uses four passive methods to build and maintain a device inventory: | **mDNS** | Hostnames from PTR/SRV records on `224.0.0.251:5353` | | **SSDP** | Device presence from announcements on `239.255.255.250:1900` | -All discovery is passive — Umberrelay never sends probes or scans your network. +All discovery is passive. Umberrelay never sends probes or scans your network. ## Classification @@ -283,9 +283,9 @@ Filter precedence is `actor`, then `source`, then `device`. ## Docker Deployment -The checked-in [`docker-compose.yml`](docker-compose.yml) builds from source and is aimed at local development and simple local Docker runs. It uses `network_mode: host` so Umberrelay can see DNS traffic and the ARP table, mounts config read-only, and stores `/data` in a named volume. +The checked-in [`docker-compose.yml`](docker-compose.yml) builds from source and is aimed at local development and simple Docker runs. It uses `network_mode: host` so Umberrelay can see DNS traffic and the ARP table, mounts config read-only, and stores `/data` in a named volume. -For Raspberry Pi deployment — building an ARM64 image on a faster machine and transferring it to the Pi — see the workflow in [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). The Pi runs its own compose file pinned to the prebuilt image. +For Raspberry Pi deployment (building an ARM64 image on a faster machine and transferring it to the Pi), see the workflow in [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). The Pi runs its own compose file pinned to the prebuilt image. ### Runtime Requirements @@ -307,7 +307,7 @@ The Dockerfile uses a two-stage build: compile in `golang:1.26-alpine`, run in ` - **A device is missing** — confirm the device is actually using Umberrelay for DNS; devices with hardcoded resolvers or encrypted DNS may never appear - **A bypass signal is unexpected** — `/api/bypass` is best-effort, not packet-level proof; validate with direct DNS tests (`dig @ ...`) and your router DNS policy - **Routed client is unattributed** — across subnets/VLANs, Umberrelay may only have source IP (no MAC); verify the client appears as a source fallback actor in the Devices page or `/api/actors` -- **Devices appear but names are generic** — hostname enrichment depends on passive DHCP, mDNS, and SSDP traffic; some devices simply do not advertise much +- **Devices appear but names are generic** — hostname enrichment depends on passive DHCP, mDNS, and SSDP traffic; some devices do not advertise much - **Tracker labels look wrong** — classifications come from community blocklists; use domain overrides when a list is too broad or out of date - **Some traffic is invisible** — Umberrelay does not see direct IP traffic or DNS that bypasses it, so partial visibility is an expected limitation in some networks From d4c0d95d38859d7f9537eab68b5aa37d0fdc10fc Mon Sep 17 00:00:00 2001 From: Thom Date: Wed, 3 Jun 2026 19:27:48 -0700 Subject: [PATCH 4/6] docs: tighten deployment language --- docs/DEPLOYMENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 14bf227..40b82d4 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -11,7 +11,7 @@ ## Deployment Model -Umberrelay is not just a dashboard. A live deployment means the Pi is running the DNS server your clients actually query. +Umberrelay is more than a dashboard. A live deployment means the Pi is running the DNS server your clients query. That has a few consequences: @@ -169,7 +169,7 @@ If that works but normal browsing does not show up, the client may be using encr ### Queries are visible, but attribution is weak -Umberrelay depends on passive signals from the host network namespace. Host networking is required for the provided Docker deployment, and some devices simply do not expose much identity information. Across routed VLANs, source-IP fallback actors are expected when MAC attribution is unavailable. +Umberrelay depends on passive signals from the host network namespace. Host networking is required for the provided Docker deployment, and some devices do not expose much identity information. Across routed VLANs, source-IP fallback actors are expected when MAC attribution is unavailable. For deeper network-path troubleshooting and VLAN validation workflows, see [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md). From 9d563e93972e385f2b418b46e31f0522cb265077 Mon Sep 17 00:00:00 2001 From: Thom Date: Wed, 3 Jun 2026 19:33:54 -0700 Subject: [PATCH 5/6] docs: reword paired em dash in troubleshooting --- docs/TROUBLESHOOTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index d2de9b3..689769d 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -30,7 +30,7 @@ docker compose restart umberrelay ### Where data lives -The SQLite database lives at `/data/umberrelay.db` inside the container, which maps to whatever host path your compose file bind-mounts (or names a volume for) at `/data`. When debugging persistence — "did my queries survive a restart?" or "is the DB the size I expect?" — check that host path directly, not the path inside the container. +The SQLite database lives at `/data/umberrelay.db` inside the container, which maps to whatever host path your compose file bind-mounts (or names a volume for) at `/data`. When debugging persistence (did my queries survive a restart? is the DB the size I expect?), check that host path directly, not the path inside the container. ## DNS Path Validation From 7a2ffea27c9a8965e39c7e5fdaa32a02cf1aa72b Mon Sep 17 00:00:00 2001 From: Thom Date: Wed, 3 Jun 2026 20:02:15 -0700 Subject: [PATCH 6/6] docs: trim roadmap wording, make conduct reports private --- .github/CODE_OF_CONDUCT.md | 2 +- ROADMAP.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index bb55263..d9043e3 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -21,7 +21,7 @@ We are committed to making participation in this project a harassment-free exper ## Enforcement -Project maintainers may remove, edit, or reject comments, commits, issues, and other contributions that violate this code of conduct. Instances of abusive behavior may be reported by opening an issue or contacting the maintainer directly. +Project maintainers may remove, edit, or reject comments, commits, issues, and other contributions that violate this code of conduct. Instances of abusive behavior may be reported privately by contacting the maintainer directly. Please do not report violations in a public issue. ## Attribution diff --git a/ROADMAP.md b/ROADMAP.md index 690f033..ae2c98a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,7 +2,7 @@ Last updated: April 19, 2026 -Umberrelay is actively evolving, and this roadmap is here to share where the project is headed next. Priorities may shift as we learn from real-world use, and items are intentionally not tied to fixed release dates. +Umberrelay is actively evolving, and this roadmap shows where the project is headed next. Priorities may shift as we learn from real-world use, and items are intentionally not tied to fixed release dates. This is more of a directional guide, not a delivery contract.