Add LAN device discovery (ping sweep + ARP, known/unknown labeling)

Runs as a host-level systemd timer on CT122 (scripts/discover-devices.sh)
rather than inside the api container, since real ARP entries live in the
host's network namespace, not Docker's bridge network. See
docs/device-discovery.md for the full writeup, including why literal
passive-only ARP reading was dropped (near-empty result in practice).

API reads the resulting JSON file each poll cycle, cross-references
config/hosts.yaml's knownDevices list by IP, and serves /api/devices.
Dashboard gets a new "Network Devices" table.

Closes #9.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

apps/api/src/config/index.ts

@@ -12,12 +12,18 @@ interface RawSshHost {
   diskPaths?: { path: string; label: string }[];
 }
 
+interface RawKnownDevice {
+  ip: string;
+  name: string;
+}
+
 export interface HostsConfig {
   proxmox: {
     host: string;
     node: string;
   };
   sshHosts?: RawSshHost[];
+  knownDevices?: RawKnownDevice[];
 }
 
 export interface AppConfig {
@@ -39,6 +45,8 @@ export interface AppConfig {
     tokenSecret: string;
   };
   sshHosts: SshHostConfig[];
+  knownDevices: Map<string, string>;
+  discoveryFilePath: string;
   hosts: HostsConfig;
 }
 
@@ -80,6 +88,8 @@ export function loadConfig(hostsConfigPath: string): AppConfig {
       tokenSecret: required("PROXMOX_TOKEN_SECRET"),
     },
     sshHosts,
+    knownDevices: new Map((hosts.knownDevices ?? []).map((d) => [d.ip, d.name])),
+    discoveryFilePath: process.env.DISCOVERY_FILE_PATH ?? "./data/devices-raw.json",
     hosts,
   };
 }

apps/api/src/db/index.ts

@@ -36,6 +36,14 @@ export function openDb(path: string): Database.Database {
     );
 
     CREATE INDEX IF NOT EXISTS idx_snapshots_host_ts ON metric_snapshots(host_id, ts);
+
+    CREATE TABLE IF NOT EXISTS devices (
+      ip TEXT PRIMARY KEY,
+      mac TEXT NOT NULL,
+      known_name TEXT,
+      first_seen TEXT NOT NULL DEFAULT (datetime('now')),
+      last_seen TEXT NOT NULL DEFAULT (datetime('now'))
+    );
   `);
   return db;
 }
@@ -100,3 +108,45 @@ export function pruneOldSnapshots(db: Database.Database, retentionHours: number)
     cutoff: `-${retentionHours} hours`,
   });
 }
+
+export interface DiscoveredDevice {
+  ip: string;
+  mac: string;
+  knownName: string | null;
+}
+
+export function upsertDevices(db: Database.Database, devices: DiscoveredDevice[]): void {
+  const upsert = db.prepare(`
+    INSERT INTO devices (ip, mac, known_name)
+    VALUES (@ip, @mac, @knownName)
+    ON CONFLICT(ip) DO UPDATE SET
+      mac = excluded.mac,
+      known_name = excluded.known_name,
+      last_seen = datetime('now')
+  `);
+  const tx = db.transaction((items: DiscoveredDevice[]) => {
+    for (const d of items) upsert.run(d);
+  });
+  tx(devices);
+}
+
+export interface DeviceRow {
+  ip: string;
+  mac: string;
+  known_name: string | null;
+  first_seen: string;
+  last_seen: string;
+}
+
+// Devices not seen in the last 24h (unplugged, moved, DHCP lease expired) are
+// dropped from the list rather than shown as permanently "known but offline" —
+// there's no persistent per-device up/down state to track like hosts have.
+export function getRecentDevices(db: Database.Database, sinceHours = 24): DeviceRow[] {
+  return db
+    .prepare(
+      `SELECT ip, mac, known_name, first_seen, last_seen FROM devices
+       WHERE last_seen > datetime('now', @cutoff)
+       ORDER BY known_name IS NULL, ip`
+    )
+    .all({ cutoff: `-${sinceHours} hours` }) as DeviceRow[];
+}

apps/api/src/discovery/index.ts

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import type Database from "better-sqlite3";
+import { upsertDevices, type DiscoveredDevice } from "../db/index.js";
+
+interface RawEntry {
+  ip: string;
+  mac: string;
+  state: string;
+}
+
+// Reads the JSON file produced by scripts/discover-devices.sh (a systemd timer
+// on the deploy host, not this process) and labels each entry against the
+// known-device list from config/hosts.yaml. See docs/device-discovery.md.
+export async function refreshDevices(
+  db: Database.Database,
+  filePath: string,
+  knownDevices: Map<string, string>
+): Promise<void> {
+  let raw: RawEntry[];
+  try {
+    raw = JSON.parse(await readFile(filePath, "utf8"));
+  } catch (err) {
+    // Missing file (timer hasn't run yet, or not deployed on this host) isn't
+    // fatal — just means no device data this cycle.
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw err;
+  }
+
+  const devices: DiscoveredDevice[] = raw.map((entry) => ({
+    ip: entry.ip,
+    mac: entry.mac,
+    knownName: knownDevices.get(entry.ip) ?? null,
+  }));
+
+  upsertDevices(db, devices);
+}

apps/api/src/index.ts

@@ -10,6 +10,8 @@ import { SshHostCollector } from "./collectors/sshHost.js";
 import type { Collector } from "./collectors/types.js";
 import { registerAuthRoutes } from "./routes/auth.js";
 import { registerHostRoutes } from "./routes/hosts.js";
+import { registerDeviceRoutes } from "./routes/devices.js";
+import { refreshDevices } from "./discovery/index.js";
 
 const HOSTS_CONFIG_PATH = process.env.HOSTS_CONFIG_PATH ?? "../../config/hosts.yaml";
 
@@ -41,6 +43,12 @@ async function main() {
       }
     }
     pruneOldSnapshots(db, cfg.snapshotRetentionHours);
+
+    try {
+      await refreshDevices(db, cfg.discoveryFilePath, cfg.knownDevices);
+    } catch (err) {
+      app.log.error({ err }, "device discovery refresh failed");
+    }
   }
 
   const app = Fastify({ logger: true });
@@ -53,6 +61,7 @@ async function main() {
 
   registerAuthRoutes(app, db);
   registerHostRoutes(app, db);
+  registerDeviceRoutes(app, db);
 
   await pollOnce();
   setInterval(() => {

apps/api/src/routes/devices.ts

@@ -0,0 +1,25 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import type Database from "better-sqlite3";
+import { getRecentDevices } from "../db/index.js";
+
+async function requireAuth(req: FastifyRequest, reply: FastifyReply) {
+  if (!req.session.username) {
+    reply.code(401).send({ error: "not authenticated" });
+  }
+}
+
+export function registerDeviceRoutes(app: FastifyInstance, db: Database.Database): void {
+  app.get("/api/devices", { preHandler: requireAuth }, async () => {
+    const rows = getRecentDevices(db);
+    return {
+      devices: rows.map((r) => ({
+        ip: r.ip,
+        mac: r.mac,
+        name: r.known_name,
+        known: r.known_name !== null,
+        firstSeen: r.first_seen,
+        lastSeen: r.last_seen,
+      })),
+    };
+  });
+}

apps/web/src/api.ts

@@ -39,3 +39,16 @@ export function me(): Promise<{ username: string }> {
 export function getHosts(): Promise<{ hosts: HostSummary[] }> {
   return request("/api/hosts");
 }
+
+export interface Device {
+  ip: string;
+  mac: string;
+  name: string | null;
+  known: boolean;
+  firstSeen: string;
+  lastSeen: string;
+}
+
+export function getDevices(): Promise<{ devices: Device[] }> {
+  return request("/api/devices");
+}

apps/web/src/components/DeviceTable.tsx

@@ -0,0 +1,50 @@
+import type { Device } from "../api";
+
+function ipSortKey(ip: string): number[] {
+  return ip.split(".").map(Number);
+}
+
+export function DeviceTable({ devices }: { devices: Device[] }) {
+  const sorted = [...devices].sort((a, b) => {
+    if (a.known !== b.known) return a.known ? -1 : 1;
+    const [ak, bk] = [ipSortKey(a.ip), ipSortKey(b.ip)];
+    for (let i = 0; i < 4; i++) if (ak[i] !== bk[i]) return ak[i] - bk[i];
+    return 0;
+  });
+
+  return (
+    <table className="device-table">
+      <thead>
+        <tr>
+          <th>Status</th>
+          <th>IP</th>
+          <th>MAC</th>
+          <th>Name</th>
+          <th>Last seen</th>
+        </tr>
+      </thead>
+      <tbody>
+        {sorted.map((d) => (
+          <tr key={d.ip}>
+            <td>
+              <span className={`device-badge ${d.known ? "known" : "unknown"}`}>
+                {d.known ? "known" : "unknown"}
+              </span>
+            </td>
+            <td>{d.ip}</td>
+            <td className="mono">{d.mac}</td>
+            <td>{d.name ?? "—"}</td>
+            <td>{d.lastSeen}</td>
+          </tr>
+        ))}
+        {sorted.length === 0 && (
+          <tr>
+            <td colSpan={5} className="empty">
+              No devices seen yet — discovery runs every 5 minutes.
+            </td>
+          </tr>
+        )}
+      </tbody>
+    </table>
+  );
+}

apps/web/src/index.css

@@ -159,3 +159,55 @@ body {
   color: #8b949e;
   margin-top: 0.35rem;
 }
+
+.device-count {
+  color: #8b949e;
+  font-weight: 400;
+}
+
+.device-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 1.5rem;
+  font-size: 0.85rem;
+}
+
+.device-table th {
+  text-align: left;
+  color: #8b949e;
+  font-weight: 500;
+  padding: 0.4rem 0.6rem;
+  border-bottom: 1px solid #30363d;
+}
+
+.device-table td {
+  padding: 0.4rem 0.6rem;
+  border-bottom: 1px solid #21262d;
+}
+
+.device-table .mono {
+  font-family: ui-monospace, monospace;
+  color: #8b949e;
+}
+
+.device-table .empty {
+  text-align: center;
+  color: #8b949e;
+  padding: 1rem;
+}
+
+.device-badge {
+  font-size: 0.7rem;
+  padding: 0.1rem 0.5rem;
+  border-radius: 10px;
+}
+
+.device-badge.known {
+  background: #1a4d2e;
+  color: #3fb950;
+}
+
+.device-badge.unknown {
+  background: #4d2a1a;
+  color: #f5a623;
+}

apps/web/src/pages/Dashboard.tsx

@@ -1,24 +1,27 @@
 import { useEffect, useState } from "react";
-import { getHosts, logout, type HostSummary } from "../api";
+import { getHosts, getDevices, logout, type HostSummary, type Device } from "../api";
 import { HostCard } from "../components/HostCard";
+import { DeviceTable } from "../components/DeviceTable";
 
 const POLL_MS = 15000;
 
 export function Dashboard({ username, onLoggedOut }: { username: string; onLoggedOut: () => void }) {
   const [hosts, setHosts] = useState<HostSummary[]>([]);
+  const [devices, setDevices] = useState<Device[]>([]);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
     let cancelled = false;
     async function poll() {
       try {
-        const { hosts } = await getHosts();
+        const [hostsRes, devicesRes] = await Promise.all([getHosts(), getDevices()]);
         if (!cancelled) {
-          setHosts(hosts);
+          setHosts(hostsRes.hosts);
+          setDevices(devicesRes.devices);
           setError(null);
         }
       } catch (err) {
-        if (!cancelled) setError(err instanceof Error ? err.message : "Failed to load hosts");
+        if (!cancelled) setError(err instanceof Error ? err.message : "Failed to load dashboard data");
       }
     }
     void poll();
@@ -58,6 +61,12 @@ export function Dashboard({ username, onLoggedOut }: { username: string; onLogge
           </div>
         </section>
       ))}
+      <section>
+        <h2>
+          Network Devices <span className="device-count">({devices.length})</span>
+        </h2>
+        <DeviceTable devices={devices} />
+      </section>
     </div>
   );
 }