Files
Homelab-manager/server/test/dockerVulns.test.ts
T
bobbanandClaude Sonnet 5.5 3d9a2310bb Runbooks per alert kind, high-vulnerability threshold, wall display extras
A "What to do" note (text and/or link) can be written once for a whole kind of alert and
shows beside every alert of that kind; alerts now carry their kind and source type.
New optional setting: warn when a Docker host has N or more high vulnerabilities (off by
default). The wall display gains tiles (Hetzner and game servers running, critical
vulnerabilities, stuck downloads) and a summary line for each group of integrations,
also in share links. Migration 0074; docs and tests included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-27 21:15:45 +01:00

295 lines
18 KiB
TypeScript

/**
* Dockhand's vulnerability scans: reading what it stored (never starting a scan), what is kept, what is raised (critical only, and only while the setting is on), the health pass, the
* alerts, the page's route and /metrics.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { createServer as createHttpServer, type Server } from "node:http";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
const dir = mkdtempSync(join(tmpdir(), "hm-dockervulns-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
process.env.HEALTH_STARTUP_GRACE_MS = "0";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, integrations, dockhandVulnerabilities } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const adapter = await import("../src/integrations/dockhand/adapter.js");
const dv = await import("../src/services/dockerVulnSync.js");
const { evaluateHealth, collectSnapshot } = await import("../src/services/healthMonitor.js");
const { subjectOfConditionKey } = await import("../src/services/maintenance.js");
const { getAlerts, invalidateAlertsCache } = await import("../src/services/alerts.js");
const { integrationsRouter } = await import("../src/routes/integrations.js");
const { buildMetrics } = await import("../src/services/metrics.js");
const { getSettings, updateSettings, setInternalFlag } = await import("../src/services/settingsStore.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const MIN = 60_000;
const COUNT = (critical: number, scanned = 5, total = 8) => ({ total: critical + 12, summary: { total: critical + 12, critical, high: 7, medium: 4, low: 1, imagesScanned: scanned, totalImages: total }, options: { images: [], containers: [], stacks: [] } });
const finding = (cve: string, imageName: string, fixedVersion: string | null, containers: { id: string; name: string }[] = []) => ({ key: `${cve}:${imageName}`, cve, package: "openssl", severity: "critical", installedVersion: "3.0.1", fixedVersion, imageId: "sha256:x", imageName, containers });
describe("what Dockhand's API says", () => {
test("the summary is under `summary`; no critical count at all is not zero", () => {
assert.deepEqual(adapter.parseVulnSummary(COUNT(3)), { critical: 3, high: 7, medium: 4, low: 1, imagesScanned: 5, totalImages: 8 });
assert.equal(adapter.parseVulnSummary({ total: 0 }), null);
assert.equal(adapter.parseVulnSummary({ summary: { high: 2 } }), null);
assert.equal(adapter.parseVulnSummary("html"), null);
assert.equal(adapter.parseVulnSummary({ summary: { critical: 0 } })?.critical, 0);
});
test("findings: the CVE, where it is, whether there is a fix, and the containers that use the image", () => {
const list = adapter.parseVulnFindings({ findings: [finding("CVE-1", "nginx:1.25", "3.0.2", [{ id: "a", name: "web" }, { id: "b", name: "web2" }]), finding("CVE-2", "redis:7", null), { cve: "CVE-3" }, "junk"] });
assert.deepEqual(list.map((f) => [f.cve, f.imageName, f.fixedVersion, f.containers]), [["CVE-1", "nginx:1.25", "3.0.2", ["web", "web2"]], ["CVE-2", "redis:7", null, []]]);
assert.deepEqual(adapter.parseVulnFindings({ total: 0 }), []);
assert.deepEqual(adapter.parseVulnFindings(null), []);
});
});
describe("the fake Dockhand", () => {
let dockhand: Server;
let url = "";
const seen: string[] = [];
let countStatus: Record<string, number> = {};
let jackieCritical = 3;
before(async () => {
dockhand = createHttpServer((req, res) => {
const u = new URL(req.url ?? "", "http://x");
seen.push(`${req.method} ${u.pathname}${u.search}`);
res.setHeader("content-type", "application/json");
const env = u.searchParams.get("env") ?? "";
if (u.pathname === "/api/environments") return void res.end(JSON.stringify([{ id: 1, name: "Jackie" }, { id: 2, name: "Anna" }, { id: 3, name: "Old" }]));
if (u.pathname === "/api/vulnerabilities/count") {
if (countStatus[env]) {
res.statusCode = countStatus[env];
return void res.end("{}");
}
return void res.end(JSON.stringify(env === "1" ? COUNT(jackieCritical) : COUNT(0, 2, 2)));
}
if (u.pathname === "/api/vulnerabilities" && env === "1") {
const all = [finding("CVE-1", "nginx:1.25", "3.0.2", [{ id: "a", name: "web" }]), finding("CVE-2", "nginx:1.25", null, [{ id: "a", name: "web" }]), finding("CVE-3", "redis:7", "7.0.1")].slice(0, jackieCritical);
return void res.end(JSON.stringify({ findings: all, total: all.length, summary: { critical: all.length } }));
}
res.statusCode = 404;
res.end("{}");
});
await new Promise<void>((r) => dockhand.listen(0, "127.0.0.1", r));
url = `http://127.0.0.1:${(dockhand.address() as AddressInfo).port}`;
});
after(() => dockhand.close());
test("each host's count is read, the critical ones are listed only where there are some, a host that cannot say is unknown, and nothing is scanned", async () => {
seen.length = 0;
countStatus = { "3": 404 };
const read = await adapter.createDockhandAdapter({ url, token: "t" } as never).readVulnerabilities();
assert.deepEqual(read.environments.map((e) => [e.environmentName, e.summary?.critical ?? null, e.critical.length]), [["Jackie", 3, 3], ["Anna", 0, 0], ["Old", null, 0]]);
assert.deepEqual(read.environments[0].critical.map((f) => [f.cve, f.containers]), [["CVE-1", ["web"]], ["CVE-2", ["web"]], ["CVE-3", []]]);
assert.ok(seen.every((s) => s.startsWith("GET ")), "only reads");
assert.ok(!seen.some((s) => s.includes("scan")), "no scan endpoint");
assert.equal(seen.filter((s) => s.startsWith("GET /api/vulnerabilities?")).length, 1, "the list is asked for only where the count is above zero");
assert.match(seen.find((s) => s.startsWith("GET /api/vulnerabilities?"))!, /severity=critical/);
countStatus = {};
});
describe("what is stored and what is wrong", () => {
let id = 0;
before(async () => {
id = (await db.insert(integrations).values({ type: "dockhand", name: "Dockhand", baseUrl: url, config: JSON.stringify({ url, token: "t" }) }).returning({ id: integrations.id }))[0].id;
});
const rows = () => db.select().from(dockhandVulnerabilities).where(eq(dockhandVulnerabilities.integrationId, id));
test("a sync stores each host, replacing the last reading; a host Dockhand no longer lists is dropped", async () => {
const status = await dv.syncDockerVulns(id);
assert.equal(status.ok, true);
const stored = (await rows()).sort((a, b) => a.environmentId - b.environmentId);
assert.deepEqual(stored.map((r) => [r.environmentName, r.critical, r.high, r.imagesScanned, r.totalImages]), [["Jackie", 3, 7, 5, 8], ["Anna", 0, 7, 2, 2], ["Old", 0, 7, 2, 2]]);
assert.equal(dv.findingsOf(stored[0]).length, 3);
await dv.storeRead(id, [{ environmentId: 1, environmentName: "Jackie", summary: { critical: 1, high: 0, medium: 0, low: 0, imagesScanned: 1, totalImages: 1 }, critical: [] }]);
assert.deepEqual((await rows()).map((r) => [r.environmentId, r.critical]), [[1, 1]]);
});
test("a read that failed is said, and what was stored is left alone", async () => {
await dv.syncDockerVulns(id);
const before = await rows();
const failed = await dv.syncDockerVulns(id, new Date(), async () => {
throw new Error("connection refused");
});
assert.deepEqual([failed.ok, failed.error], [false, "connection refused"]);
assert.deepEqual((await rows()).map((r) => r.updatedAt), before.map((r) => r.updatedAt));
assert.equal(dv.isDockerVulnFresh((await dv.dockerVulnSyncStatuses())[id], Date.now()), false);
await dv.syncDockerVulns(id);
});
test("a host whose count could not be read is stored as unknown, not as none", async () => {
countStatus = { "2": 500 };
await dv.syncDockerVulns(id);
const anna = (await rows()).find((r) => r.environmentName === "Anna")!;
assert.deepEqual([anna.critical, anna.high, anna.imagesScanned], [null, null, null]);
assert.deepEqual(dv.dockerVulnProblems(id, [anna]), []);
countStatus = {};
await dv.syncDockerVulns(id);
});
test("critical findings are a warning for the host, naming the images and how many have a fix; high and lower are never raised; zero is nothing", async () => {
const all = await rows();
const jackie = all.find((r) => r.environmentName === "Jackie")!;
const anna = all.find((r) => r.environmentName === "Anna")!;
const p = dv.dockerVulnProblems(id, [jackie, anna]);
assert.deepEqual(p.map((x) => [x.key, x.severity]), [[`docker-vuln:${id}:1`, "warning"]]);
assert.equal(p[0].message, "Jackie: 3 critical vulnerabilities in 2 images: nginx:1.25, redis:7 (2 of the first 3 have a fix)");
assert.deepEqual(dv.dockerVulnProblems(id, [{ ...jackie, critical: 1, findings: JSON.stringify([]) }]).map((x) => x.message), ["Jackie: 1 critical vulnerability"]);
assert.deepEqual(dv.dockerVulnProblems(id, [{ ...jackie, critical: 0, high: 50 }]), []);
});
test("high findings are raised only when a number is set, from that many, and then beside the critical ones", async () => {
const jackie = (await rows()).find((r) => r.environmentName === "Jackie")!;
const many = { ...jackie, critical: 0, high: 12 };
assert.deepEqual(dv.dockerVulnProblems(id, [many], 0), [], "off by default");
assert.deepEqual(dv.dockerVulnProblems(id, [many]), [], "and with no number given");
assert.deepEqual(dv.dockerVulnProblems(id, [many], 13), [], "below the number");
const p = dv.dockerVulnProblems(id, [many], 10);
assert.deepEqual(p.map((x) => [x.key, x.severity]), [[`docker-vuln-high:${id}:1`, "warning"]]);
assert.equal(p[0].message, "Jackie: 12 high vulnerabilities in the scanned images (you asked to hear of 10 or more)");
assert.equal(dv.dockerVulnProblems(id, [{ ...many, high: 12 }], 12).length, 1, "at the number counts");
assert.deepEqual(dv.dockerVulnProblems(id, [{ ...many, high: 1 }], 1).map((x) => x.message), ["Jackie: 1 high vulnerability in the scanned images (you asked to hear of 1 or more)"]);
assert.deepEqual(dv.dockerVulnProblems(id, [{ ...many, high: null }], 1), [], "an unknown count says nothing");
const both = dv.dockerVulnProblems(id, [{ ...jackie, critical: 2, high: 40 }], 10);
assert.deepEqual(both.map((x) => x.key), [`docker-vuln-high:${id}:1`, `docker-vuln:${id}:1`]);
});
describe("the health pass, the Alerts page, the Docker page and /metrics", () => {
let app: Server;
let base = "";
const fresh = () => setInternalFlag("dockerVulnSync", JSON.stringify({ [id]: { at: new Date().toISOString(), ok: true, error: null } }));
const stale = () => setInternalFlag("dockerVulnSync", JSON.stringify({ [id]: { at: new Date(Date.now() - 60 * MIN).toISOString(), ok: true, error: null } }));
const vulnIds = async () => {
invalidateAlertsCache();
return (await getAlerts(true)).alerts.map((x) => x.id).filter((i) => i.includes("docker-vuln:"));
};
before(async () => {
await db.insert(users).values([{ oidcSub: "viewer", name: "Vic", role: "viewer" }]);
await dv.syncDockerVulns(id);
await fresh();
const a = express();
a.use(express.json());
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: "viewer" } };
next();
});
a.use("/api/integrations", integrationsRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/integrations/${id}/dockhand`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("the health pass judges it from what is stored, and holds it when the last read is old", async () => {
let { snapshot, held } = await collectSnapshot();
assert.deepEqual(snapshot.dockerVulns?.map((v) => v.integrationId), [id]);
const list = evaluateHealth(snapshot, { serverOfflineMinutes: 60, diskUsagePercent: 90 }, Date.now(), { skipServers: true });
const c = list.find((x) => x.key === `docker-vuln:${id}:1`)!;
assert.deepEqual([c.severity, c.source], ["warning", `dockhand:${id}:vuln`]);
assert.equal(subjectOfConditionKey(c.key), `integration:${id}`, "maintenance on it silences the alert");
await stale();
({ snapshot, held } = await collectSnapshot());
assert.deepEqual([snapshot.dockerVulns ?? [], held.has(`dockhand:${id}:vuln`)], [[], true]);
await fresh();
});
test("the Alerts page shows it under Services with a link to the Docker page", async () => {
invalidateAlertsCache();
const a = (await getAlerts(true)).alerts.find((x) => x.id === `services:docker-vuln:${id}:1`)!;
assert.ok(a);
assert.deepEqual([a.severity, a.category, a.source, a.link, a.target?.type, a.target?.id], ["warning", "services", "Docker", "/docker", "integration", id]);
});
test("it can be switched off: nothing is raised, nothing is held, and the alert is gone; on again, it is back", async () => {
const checks = (await getSettings()).healthChecks;
assert.equal(checks.vulnerabilityAlerts, true, "on by default");
await updateSettings({ healthChecks: { ...checks, vulnerabilityAlerts: false } });
const { snapshot, held } = await collectSnapshot();
assert.deepEqual([snapshot.dockerVulns, [...held].filter((h) => h.endsWith(":vuln"))], [undefined, []]);
assert.deepEqual(await vulnIds(), []);
await updateSettings({ healthChecks: { ...checks, vulnerabilityAlerts: true } });
assert.deepEqual(await vulnIds(), [`services:docker-vuln:${id}:1`]);
});
test("an old setting without the switch is read as on", async () => {
const { vulnerabilityAlerts: _dropped, ...older } = (await getSettings()).healthChecks;
await updateSettings({ healthChecks: older as never });
assert.equal((await getSettings()).healthChecks.vulnerabilityAlerts, true);
});
test("high findings: off by default (an old setting without the number is read as 0); with a number the host's high count is an alert of its own, under maintenance like the other", async () => {
const checks = (await getSettings()).healthChecks;
assert.equal(checks.vulnerabilityHighThreshold, 0);
const { vulnerabilityHighThreshold: _dropped, ...older } = checks;
await updateSettings({ healthChecks: older as never });
assert.equal((await getSettings()).healthChecks.vulnerabilityHighThreshold, 0);
const highIds = async () => {
invalidateAlertsCache();
return (await getAlerts(true)).alerts.map((x) => x.id).filter((i) => i.includes("docker-vuln-high:"));
};
assert.deepEqual(await highIds(), []);
await updateSettings({ healthChecks: { ...checks, vulnerabilityHighThreshold: 5 } });
assert.ok((await highIds()).includes(`services:docker-vuln-high:${id}:1`), "Jackie has 7 high findings");
const a = (await getAlerts(true)).alerts.find((x) => x.id === `services:docker-vuln-high:${id}:1`)!;
assert.deepEqual([a.severity, a.source, a.link, a.target?.type], ["warning", "Docker", "/docker", "integration"]);
assert.match(a.message, /Jackie: 7 high vulnerabilities/);
assert.equal(subjectOfConditionKey(`docker-vuln-high:${id}:1`), `integration:${id}`);
await updateSettings({ healthChecks: { ...checks, vulnerabilityHighThreshold: 8 } });
assert.ok(!(await highIds()).includes(`services:docker-vuln-high:${id}:1`), "7 is under 8");
await updateSettings({ healthChecks: { ...checks, vulnerabilityAlerts: false, vulnerabilityHighThreshold: 5 } });
assert.deepEqual(await highIds(), [], "the switch for the vulnerability alerts turns this off as well");
await updateSettings({ healthChecks: checks });
});
test("anyone signed in sees each host's counts, the critical findings and how many images are scanned", async () => {
const body = (await (await fetch(`${base}/vulnerabilities`, { headers: { connection: "close" } })).json()) as { alerts: boolean; fresh: boolean; environments: { environmentName: string; critical: number; high: number; imagesScanned: number; totalImages: number; findings: { cve: string }[] }[] };
assert.deepEqual([body.alerts, body.fresh], [true, true]);
const jackie = body.environments.find((e) => e.environmentName === "Jackie")!;
assert.deepEqual([jackie.critical, jackie.high, jackie.imagesScanned, jackie.totalImages, jackie.findings.map((f) => f.cve)], [3, 7, 5, 8, ["CVE-1", "CVE-2", "CVE-3"]]);
assert.equal((await fetch(`${base.replace(`/${id}/`, "/99999/")}/vulnerabilities`, { headers: { connection: "close" } })).status, 404);
});
test("/metrics has the counts by severity and the images scanned — only while the reading is recent", async () => {
let text = await buildMetrics(new Date());
assert.match(text, /homelab_docker_vulnerabilities\{[^}]*host="Jackie"[^}]*severity="critical"[^}]*\} 3/);
assert.match(text, /homelab_docker_vulnerabilities\{[^}]*host="Jackie"[^}]*severity="high"[^}]*\} 7/);
assert.match(text, /homelab_docker_images_scanned\{[^}]*host="Jackie"[^}]*\} 5/);
await stale();
text = await buildMetrics(new Date());
assert.doesNotMatch(text, /homelab_docker_vulnerabilities/);
await fresh();
});
test("taking the integration away takes what was read with it", async () => {
await dv.forgetDockerVulns(id);
assert.equal((await dv.dockerVulnSyncStatuses())[id], undefined);
await db.delete(integrations).where(eq(integrations.id, id));
assert.deepEqual(await rows(), []);
});
});
});
});