Add optional Fingerbank device fingerprinting to deep-check
CI / web (push) Successful in 16s
CI / api (push) Successful in 21s

Folded into the existing on-demand Deep check button: queries
Fingerbank's interrogate API with the device's MAC plus the SSDP
SERVER header when deep-check-device.sh finds one, showing the
confidence band alongside the result. Runs directly from the API
container (no host-level access needed, just an outbound HTTPS call),
unlike the SSDP/mDNS steps.

Confirmed via direct testing: without DHCP fingerprint data (which we
structurally don't have, not being the DHCP server), MAC-only queries
often can't get past manufacturer-level confidence -- same info the
free OUI lookup already provides. Documented honestly in
docs/device-discovery.md rather than overselling it. Still worth
having as opt-in enrichment for devices that do expose richer signals.

Gated behind optional FINGERBANK_API_KEY -- missing key, API errors,
or no match all degrade gracefully without affecting the rest of
deep-check's local findings.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-12 23:35:35 -06:00
parent ee9b6d15cd
commit d0d6ae95f1
11 changed files with 183 additions and 13 deletions
+25
View File
@@ -79,6 +79,31 @@ Requires `avahi-utils` and `miniupnpc` installed on the CT122 host (`apt-get ins
avahi-utils miniupnpc` — a one-time host package install, not part of any deploy
script, so re-provisioning CT122 from scratch would need to redo this step).
### Fingerbank enrichment (optional)
When `FINGERBANK_API_KEY` is set, the deep-check route (`apps/api/src/routes/devices.ts`)
also queries [Fingerbank](https://fingerbank.org)'s `/api/v2/combinations/interrogate`
with the device's MAC plus, if found, the SSDP `SERVER` header as an `upnp_user_agents`
signal (`apps/api/src/discovery/fingerbank.ts`). Unlike the other deep-check steps this
runs directly from the API container — no multicast/raw-socket access needed, just a
normal outbound HTTPS call — so no host-level or SSH changes were needed for this part.
**Honest limitation, confirmed by testing against a real device**: without a DHCP
fingerprint (which requires being the DHCP server — we're not, and have no way to
intercept that traffic from CT122), MAC-only or MAC+UPnP-signal queries often can't get
past manufacturer-level identification. A Nintendo device on this LAN queried as
`{"mac": "..."}` returned `device_name: "Hardware Manufacturer/Nintendo"` at
`score: 29` ("very little confidence" per Fingerbank's own bands) — no more specific
than the free OUI lookup already gives for free. The UI shows the confidence band
alongside the result (`confidenceLabel()` in `DeviceTable.tsx`) precisely so a
manufacturer-only guess at low confidence isn't mistaken for a confirmed ID. Still worth
having as opt-in enrichment — some devices *do* expose richer signals (a real DHCP
fingerprint, a distinctive UPnP string) that push the score meaningfully higher — but
don't expect it to reliably answer "what specific model is this" on its own.
Optional and gated: missing key, a Fingerbank API error, or no match all degrade
gracefully — the rest of deep-check's local findings (mDNS/SSDP/ports) are unaffected.
## Deploying/updating
```bash