From 6d3e255de3930f3c5e7f87a885ef69d3e68f830e Mon Sep 17 00:00:00 2001 From: jhodgkin Date: Sun, 12 Jul 2026 23:19:14 -0600 Subject: [PATCH] docs: update CLAUDE.md for device identification feature Co-Authored-By: Claude Sonnet 5 --- CLAUDE.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 77ff93e..24b5ab1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -54,7 +54,20 @@ One login instead of logging into Proxmox, Zabbix, OMV, and every service separa - **Device discovery** (done, separate from the collector system above — it's inventory, not per-host metrics): `scripts/discover-devices.sh` runs via systemd timer **on the CT122 host**, not in Docker (real ARP entries live in the host's network namespace, not Docker's bridge network). API reads the - resulting JSON each poll cycle. Full reasoning in `docs/device-discovery.md`. + resulting JSON each poll cycle. Sortable by every column in the UI (click a header, click again to + reverse). Full reasoning in `docs/device-discovery.md`. +- **Identifying unknown devices** (done): four layers — MAC OUI vendor lookup (`mac-oui-lookup`, + computed on read), mDNS hostname (added to the discovery sweep), manual labels (new `device_labels` + table keyed by MAC, inline-editable in the dashboard, takes priority), and an admin-triggered + **on-demand deep check** per unknown device (mDNS + targeted SSDP/UPnP + curated port scan + HTTP + title grab, runs on the CT122 host via a *parameterized* SSH forced-command reading + `$SSH_ORIGINAL_COMMAND`, strictly validated). Full writeup in `docs/device-discovery.md`. Already + resolved ~59/71 devices including "Ring LLC" and multiple "Amazon Technologies Inc." entries. + Two real bugs hit while building this: `mac-oui-lookup`'s named export crashed the whole process at + startup under Node ESM/CJS interop (works fine under `require()`, fails under `import { x } from`, + confirmed by running the built output with `node`, not just `tsc`); and SQLite's `ALTER TABLE ADD + COLUMN` has no `IF NOT EXISTS` clause (conflated with `CREATE TABLE`'s support for it) — check + `pragma table_info` first instead. ## Infrastructure this project owns @@ -90,6 +103,12 @@ One login instead of logging into Proxmox, Zabbix, OMV, and every service separa - **Vaultwarden**: three items saved — "Homelab Monitor (dashboard admin)" (local admin login), "Homelab Monitor - Authentik OIDC client (homelab-monitor provider)" (client_id/secret, secure note), and "Homelab Monitor - Authentik test account (playwright-test)" (the e2e test account's login). +- **Deep-check SSH key entry**: `monitor_ed25519`'s public key also has a **second, separate + `authorized_keys` entry on CT122's own root user** (not just omv/ripper) — forced command + `deep-check-device.sh`, parameterized via `$SSH_ORIGINAL_COMMAND` instead of the fixed-script pattern + used elsewhere. `deepCheck:` in `config/hosts.yaml` declares the target (CT122's own LAN IP). +- **Host packages** (one-time, not in any deploy script — a from-scratch CT122 re-provision would need + to redo this): `avahi-utils` and `miniupnpc`, installed via `apt-get` for mDNS/SSDP support. ## Zabbix: intentionally skipped, not blocked @@ -110,8 +129,11 @@ both above), fixed, and now covered by `e2e/oidc-login.spec.ts` as regression co OIDC login are Playwright-verified passing (5 consecutive runs) as of this writing. e2e coverage expanded beyond the happy path (invalid credentials, session persistence, unauthenticated -API rejection) — 9 tests, stable across repeated full-suite runs with parallel workers. All credentials -this project generated are now in Vaultwarden. +API rejection, device labeling, deep-check) — 13 tests across 6 spec files, stable across repeated +full-suite runs with parallel workers. All credentials this project generated are in Vaultwarden. + +Unknown-device identification (issue #15) shipped after the OIDC work: OUI vendor lookup, mDNS, +manual labels, on-demand deep check. See the "Identifying unknown devices" architecture note above. If picking this up again with no specific ask from the user, there's no queued work — check in with them for what's next rather than inventing scope. Remaining known gaps, none blocking: @@ -119,3 +141,5 @@ for what's next rather than inventing scope. Remaining known gaps, none blocking - `diskPaths` in `hosts.yaml` vs. the remote forced-command scripts on omv/ripper is a manual-sync point (documented, not automated — only 2 hosts, hasn't been worth it). - `e2e/` isn't wired into CI — run by hand (`cd e2e && npm test`) after any auth-related change. +- The two `avahi-utils`/`miniupnpc` host packages on CT122 aren't in any deploy script — see + "Infrastructure this project owns" above.