diff --git a/server/src/index.ts b/server/src/index.ts index d4fd531..1ade1a8 100644 --- a/server/src/index.ts +++ b/server/src/index.ts @@ -32,6 +32,7 @@ import { tagsRouter } from "./routes/tags.js"; import { portsRouter } from "./routes/ports.js"; import { alertsRouter } from "./routes/alerts.js"; import { generatorRouter } from "./routes/generator.js"; +import { apiErrorHandler } from "./utils/apiErrorHandler.js"; import { initSecretExpiryScheduler } from "./services/secretExpiryScheduler.js"; import { initTailscaleKeyExpiryScheduler } from "./services/tailscaleKeyExpiryScheduler.js"; import { initLogRetentionScheduler } from "./services/logRetentionScheduler.js"; @@ -66,6 +67,8 @@ mkdirSync(sessionDir, { recursive: true }); const app = express(); app.set("trust proxy", 1); +// The agent endpoint comes first: it reads its own (larger) body, only after checking the token, and an agent has no use for a session. +app.use("/api/agent/report", agentReportRouter); app.use(express.json()); app.use( session({ @@ -100,7 +103,6 @@ app.use("/api/ipam", ipamRouter); app.use("/api/dns", dnsRouter); app.use("/api/servers", serversRouter); app.use("/api/tasks", tasksRouter); -app.use("/api/agent/report", agentReportRouter); app.use("/api/integrations", integrationsRouter); app.use("/api/settings", settingsRouter); app.use("/api/search", searchRouter); @@ -119,10 +121,7 @@ if (existsSync(webDist)) { app.get("*", (_req, res) => res.sendFile(join(webDist, "index.html"))); } -app.use((err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => { - console.error(err); - res.status(500).json({ error: "internal_error" }); -}); +app.use(apiErrorHandler); app.listen(env.port, () => { console.log(`homelab-manager listening on port ${env.port}`); diff --git a/server/src/routes/agentReport.ts b/server/src/routes/agentReport.ts index 329e897..1957c52 100644 --- a/server/src/routes/agentReport.ts +++ b/server/src/routes/agentReport.ts @@ -1,4 +1,4 @@ -import { Router } from "express"; +import express, { Router, type NextFunction, type Request, type Response } from "express"; import { z } from "zod"; import { db } from "../db/client.js"; import { hashToken } from "../services/tokens.js"; @@ -7,18 +7,30 @@ import { asyncHandler } from "../utils/asyncHandler.js"; export const agentReportRouter = Router(); +// A host with a lot of listening sockets and cron entries sends a big report, so this endpoint takes far more than the +// 100 KB the rest of the API does. It's only safe to read that much from someone who has proved they're an agent, so the +// token is checked before the body is — and this route is mounted ahead of the app-wide JSON parser (see index.ts). +const AGENT_BODY_LIMIT = "4mb"; + +/** Text from an agent is trimmed to a sane length rather than rejected: a report that's refused over one long line costs the host its whole report. */ +const text = (max: number) => z.string().transform((s) => (s.length > max ? s.slice(0, max) : s)); +const cap = (max: number) => (items: T[]) => (items.length > max ? items.slice(0, max) : items); + const listeningPortSchema = z.object({ protocol: z.enum(["tcp", "udp"]), port: z.number().int().min(1).max(65535), - address: z.string().max(100), - process: z.string().max(100).optional(), + address: text(100), + process: text(100).optional(), }); const systemSchema = z.object({ - ip_addresses: z.array(z.string()).optional(), - cpu: z.object({ model: z.string().optional(), cores: z.number().optional(), load_percent: z.number().nullable().optional() }).optional(), + ip_addresses: z.array(text(100)).transform(cap(200)).optional(), + cpu: z.object({ model: text(200).optional(), cores: z.number().optional(), load_percent: z.number().nullable().optional() }).optional(), memory: z.object({ total_bytes: z.number().optional(), used_bytes: z.number().optional() }).optional(), - disks: z.array(z.object({ mount: z.string(), size_bytes: z.number(), used_bytes: z.number() })).optional(), + disks: z + .array(z.object({ mount: text(500), size_bytes: z.number(), used_bytes: z.number() })) + .transform(cap(500)) + .optional(), // Deliberately lenient: one odd line from `ss` must never cost the agent its whole report (tasks included), // so entries are validated one by one and bad ones dropped rather than failing the request. listening_ports: z @@ -31,39 +43,50 @@ const systemSchema = z.object({ })), }); +// What a task's free-form metadata may weigh once written out; more than this is dropped, the task itself kept. +const MAX_METADATA_JSON = 50_000; + const reportSchema = z.object({ - hostname: z.string().max(255).optional(), - os_type: z.string().optional(), - reported_at: z.string().optional(), + hostname: text(255).optional(), + os_type: text(50).optional(), + reported_at: text(50).optional(), system: systemSchema.nullable().optional(), - tasks: z.array( - z.object({ - schedule_type: z.enum(["cron", "systemd_timer", "windows_task"]), - name: z.string().min(1), - command: z.string().optional(), - schedule_expression: z.string().optional(), - source: z.string().optional(), - enabled: z.boolean().optional(), - next_run_at: z.string().optional(), - metadata: z.unknown().optional(), - }), - ), + tasks: z + .array( + z.object({ + schedule_type: z.enum(["cron", "systemd_timer", "windows_task"]), + name: z.string().min(1).transform((s) => (s.length > 500 ? s.slice(0, 500) : s)), + command: text(8000).optional(), + schedule_expression: text(500).optional(), + source: text(500).optional(), + enabled: z.boolean().optional(), + next_run_at: text(100).optional(), + metadata: z + .unknown() + .optional() + .transform((m) => (m !== undefined && (JSON.stringify(m) ?? "").length > MAX_METADATA_JSON ? undefined : m)), + }), + ) + .transform(cap(5000)), }); -agentReportRouter.post("/", asyncHandler(async (req, res) => { - const authHeader = req.header("authorization") ?? ""; - const match = authHeader.match(/^Bearer\s+(.+)$/i); - if (!match) { - return res.status(401).json({ error: "missing_token" }); - } +/** Who's calling: the server a bearer token belongs to. Runs before the body is read. */ +async function authenticateAgent(req: Request, res: Response, next: NextFunction) { + const match = (req.header("authorization") ?? "").match(/^Bearer\s+(.+)$/i); + if (!match) return res.status(401).json({ error: "missing_token" }); const tokenHash = hashToken(match[1]); const server = await db.query.servers.findFirst({ where: (s, { eq }) => eq(s.apiTokenHash, tokenHash), }); - if (!server) { - return res.status(401).json({ error: "invalid_token" }); - } + if (!server) return res.status(401).json({ error: "invalid_token" }); + + res.locals.agentServer = server; + next(); +} + +agentReportRouter.post("/", asyncHandler(authenticateAgent), express.json({ limit: AGENT_BODY_LIMIT }), asyncHandler(async (req, res) => { + const server = res.locals.agentServer as { id: number }; const parsed = reportSchema.safeParse(req.body); if (!parsed.success) { diff --git a/server/src/services/domainLookup.ts b/server/src/services/domainLookup.ts index 722d080..373dbb5 100644 --- a/server/src/services/domainLookup.ts +++ b/server/src/services/domainLookup.ts @@ -1,5 +1,6 @@ import * as net from "node:net"; import { domainToASCII } from "node:url"; +import { resolveTarget } from "../utils/networkGuard.js"; /** * Looks up when a domain registration expires. RDAP (the JSON successor to WHOIS) is used wherever the TLD @@ -40,9 +41,14 @@ export const defaultDeps: LookupDeps = { } return { status: res.status, json }; }, - whoisQuery(server, query) { + async whoisQuery(server, query) { + // The WHOIS server is named in a plain-text reply on port 43, which anyone on the path could rewrite — so it has to look like a + // hostname and must not be this machine, a cloud metadata address or anything on a private network. Connect to the address + // that passed, not to the name again. + if (!/^[A-Za-z0-9.-]{1,253}$/.test(server)) throw new Error(`Refusing to query "${server}": not a hostname.`); + const address = await resolveTarget(server, { allowPrivate: false }); return new Promise((resolve, reject) => { - const socket = net.connect({ host: server, port: 43 }); + const socket = net.connect({ host: address, port: 43 }); let out = ""; socket.setTimeout(12_000, () => { socket.destroy(); diff --git a/server/src/services/portScan.ts b/server/src/services/portScan.ts index 7d7c3f1..f870685 100644 --- a/server/src/services/portScan.ts +++ b/server/src/services/portScan.ts @@ -1,5 +1,6 @@ import * as net from "node:net"; import * as dns from "node:dns/promises"; +import { classifyAddress } from "../utils/networkGuard.js"; export const MAX_SCAN_SPAN = 20_000; @@ -102,6 +103,9 @@ export async function resolveScanTarget(address: string): Promise { throw new Error(`Couldn't resolve "${trimmed}".`); } } + if (ips.some((a) => classifyAddress(a) === "metadata")) { + throw new Error(`"${trimmed}" is a cloud metadata address, which can't be scanned.`); + } const ip = ips.find(isPrivateAddress); if (!ip) { throw new Error( diff --git a/server/src/services/tlsCheck.ts b/server/src/services/tlsCheck.ts index 5b4fc77..6e08c73 100644 --- a/server/src/services/tlsCheck.ts +++ b/server/src/services/tlsCheck.ts @@ -3,6 +3,7 @@ import { isIP } from "node:net"; import { eq, isNotNull } from "drizzle-orm"; import { db } from "../db/client.js"; import { secrets } from "../db/schema.js"; +import { resolveTarget } from "../utils/networkGuard.js"; /** * Opens a real TLS connection and returns the server certificate's expiry as @@ -12,12 +13,17 @@ import { secrets } from "../db/schema.js"; * commonly present self-signed or internal-CA certificates that a verifying * connection would refuse before ever exposing the dates — including an * already-expired one, which is exactly the case worth reporting. + * + * The host is typed in by an operator, so it can't be just anything: loopback, link-local (cloud metadata) and similar + * addresses are refused, and the connection goes to the one address that passed the check rather than to the name again + * (see utils/networkGuard.ts). LAN and public hosts are fine — those are what certificates are checked on. */ -export function fetchCertExpiry(host: string, port: number, timeoutMs = 10_000): Promise { +export async function fetchCertExpiry(host: string, port: number, timeoutMs = 10_000): Promise { + const address = await resolveTarget(host, { allowPrivate: true }); return new Promise((resolve, reject) => { const socket = tls.connect( { - host, + host: address, port, // SNI must be a hostname — Node warns (and some servers reject) when an IP is sent as the server name. servername: isIP(host) === 0 ? host : undefined, diff --git a/server/src/utils/apiErrorHandler.ts b/server/src/utils/apiErrorHandler.ts new file mode 100644 index 0000000..71d8dee --- /dev/null +++ b/server/src/utils/apiErrorHandler.ts @@ -0,0 +1,14 @@ +import type { NextFunction, Request, Response } from "express"; + +/** + * The app's last-resort error handler. A body that's too large or isn't valid JSON is the caller's doing, so it's answered + * as such (413 / 400) rather than as a server error — an agent whose report is too big then sees "payload_too_large", not a + * vague 500. + */ +export function apiErrorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction) { + const status = (err as { status?: unknown } | null)?.status; + if (status === 413) return res.status(413).json({ error: "payload_too_large" }); + if (status === 400 && (err as { type?: unknown }).type === "entity.parse.failed") return res.status(400).json({ error: "invalid_json" }); + console.error(err); + res.status(500).json({ error: "internal_error" }); +} diff --git a/server/src/utils/networkGuard.ts b/server/src/utils/networkGuard.ts new file mode 100644 index 0000000..ac461d3 --- /dev/null +++ b/server/src/utils/networkGuard.ts @@ -0,0 +1,106 @@ +/** + * Where the server itself may be pointed. + * + * A few features make the server connect to a host a person typed in: the certificate check on a secret, the WHOIS server a + * registry names, a port scan. Left open, each is a way to ask "what can the server reach?" from the server's own position — + * its loopback services, the cloud metadata address that hands out instance credentials, whatever sits behind it. This module + * is the one place that says which addresses are off limits, and resolves a name to the single address it will then connect to, + * so a name can't pass the check and be pointed somewhere else a moment later (DNS rebinding). + * + * Always refused: loopback, "this host" (0.0.0.0), link-local (169.254/16, fe80::/10 — where metadata services live), + * multicast/reserved, and the known cloud metadata addresses wherever they sit. Private LAN ranges are allowed or not + * depending on the caller: a homelab's own services are private, a registry's WHOIS server never is. + */ +import net from "node:net"; +import dns from "node:dns/promises"; + +export type AddressClass = "public" | "private" | "loopback" | "unspecified" | "link-local" | "multicast" | "metadata"; + +function list(...subnets: [string, number, "ipv4" | "ipv6"][]): net.BlockList { + const l = new net.BlockList(); + for (const [address, prefix, family] of subnets) l.addSubnet(address, prefix, family); + return l; +} + +const METADATA = list( + ["169.254.169.254", 32, "ipv4"], // AWS, Azure, GCP, most others + ["169.254.170.2", 32, "ipv4"], // AWS ECS task credentials + ["100.100.100.200", 32, "ipv4"], // Alibaba Cloud (inside the CGNAT range that Tailscale also uses) + ["fd00:ec2::254", 128, "ipv6"], // AWS over IPv6 +); +const LOOPBACK = list(["127.0.0.0", 8, "ipv4"], ["::1", 128, "ipv6"]); +const UNSPECIFIED = list(["0.0.0.0", 8, "ipv4"], ["::", 128, "ipv6"]); +const LINK_LOCAL = list(["169.254.0.0", 16, "ipv4"], ["fe80::", 10, "ipv6"]); +const MULTICAST = list(["224.0.0.0", 4, "ipv4"], ["240.0.0.0", 4, "ipv4"], ["ff00::", 8, "ipv6"]); +const PRIVATE = list( + ["10.0.0.0", 8, "ipv4"], + ["172.16.0.0", 12, "ipv4"], + ["192.168.0.0", 16, "ipv4"], + ["100.64.0.0", 10, "ipv4"], // CGNAT — where Tailscale addresses live + ["fc00::", 7, "ipv6"], +); + +/** Which kind of address this is. Checked in order, so a metadata address is "metadata" even though it is also link-local or CGNAT. */ +export function classifyAddress(ip: string): AddressClass { + const kind = net.isIP(ip); + if (kind === 0) throw new Error(`Not an IP address: ${ip}`); + const family = kind === 4 ? "ipv4" : "ipv6"; + // net.BlockList treats an IPv4-mapped IPv6 address (::ffff:127.0.0.1) as the IPv4 address it wraps. + if (METADATA.check(ip, family)) return "metadata"; + if (LOOPBACK.check(ip, family)) return "loopback"; + if (UNSPECIFIED.check(ip, family)) return "unspecified"; + if (LINK_LOCAL.check(ip, family)) return "link-local"; + if (MULTICAST.check(ip, family)) return "multicast"; + if (PRIVATE.check(ip, family)) return "private"; + return "public"; +} + +export class BlockedTargetError extends Error { + constructor( + message: string, + public readonly kind: AddressClass | "unresolvable", + ) { + super(message); + } +} + +const WHY: Record, string> = { + loopback: "it's this server itself (loopback)", + unspecified: "it isn't a real destination (0.0.0.0 / ::)", + "link-local": "it's a link-local address, where cloud metadata services live", + multicast: "it's a multicast or reserved address", + metadata: "it's a cloud metadata address", +}; + +/** + * The address to connect to for `host` (an IP or a name), or a BlockedTargetError. When a name resolves to several addresses + * every one of them must be allowed — a name that also points at loopback is refused — and the first is the one to connect to. + */ +export async function resolveTarget(host: string, options: { allowPrivate: boolean }): Promise { + const trimmed = host.trim(); + let addresses: string[]; + if (net.isIP(trimmed)) { + addresses = [trimmed]; + } else { + try { + addresses = (await dns.lookup(trimmed, { all: true })).map((r) => r.address); + } catch { + throw new BlockedTargetError(`Couldn't resolve "${trimmed}".`, "unresolvable"); + } + if (addresses.length === 0) throw new BlockedTargetError(`Couldn't resolve "${trimmed}".`, "unresolvable"); + } + + for (const address of addresses) { + const kind = classifyAddress(address); + if (kind === "public") continue; + if (kind === "private") { + if (options.allowPrivate) continue; + throw new BlockedTargetError(`"${trimmed}" is on a private network, which isn't allowed here.`, kind); + } + throw new BlockedTargetError( + `"${trimmed}"${trimmed === address ? "" : ` (${address})`} can't be used: ${WHY[kind]}.`, + kind, + ); + } + return addresses[0]; +} diff --git a/server/test/hardening.test.ts b/server/test/hardening.test.ts new file mode 100644 index 0000000..22c503f --- /dev/null +++ b/server/test/hardening.test.ts @@ -0,0 +1,512 @@ +/** + * Regression tests for the second security pass: where the server may be pointed, what an agent may send, and how the agent + * scripts handle the token. + * + * - utils/networkGuard.ts: loopback, link-local (cloud metadata) and similar addresses are refused for the certificate check, + * the WHOIS lookup and the port scanner; the connection goes to the address that was checked. + * - the agent endpoint checks the token before reading a body, takes a large report, and trims rather than rejects. + * - the Linux agent keeps the token off curl's command line and out of a fixed /tmp file; its systemd unit is locked down. + * - the Windows installer gives the SYSTEM task's folder explicit permissions. + * + * Run with: npm test --workspace server + */ +import { test, describe, before, after } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, readFileSync, existsSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { spawn, spawnSync } from "node:child_process"; +import http from "node:http"; + +const dir = mkdtempSync(join(tmpdir(), "hm-hardening-test-")); +process.env.DATABASE_PATH = join(dir, "test.sqlite"); +process.env.SESSION_DIR = join(dir, "sessions"); +process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32); +const repoRoot = fileURLToPath(new URL("../../", import.meta.url)); + +const { classifyAddress, resolveTarget, BlockedTargetError } = await import("../src/utils/networkGuard.js"); +const { fetchCertExpiry } = await import("../src/services/tlsCheck.js"); +const { defaultDeps } = await import("../src/services/domainLookup.js"); +const { resolveScanTarget } = await import("../src/services/portScan.js"); +const { runMigrations } = await import("../src/db/migrate.js"); +await runMigrations(); + +const blocked = (kind?: string) => (err: unknown) => err instanceof BlockedTargetError && (kind === undefined || err.kind === kind); + +// ─── Where the server may be pointed ──────────────────────────────────────── + +describe("networkGuard", () => { + test("classifies addresses, including IPv4 wrapped in IPv6", () => { + const expected: Record = { + "127.0.0.1": "loopback", + "127.9.9.9": "loopback", + "::1": "loopback", + "::ffff:127.0.0.1": "loopback", + "0.0.0.0": "unspecified", + "::": "unspecified", + "169.254.169.254": "metadata", + "::ffff:169.254.169.254": "metadata", + "fd00:ec2::254": "metadata", + "100.100.100.200": "metadata", + "169.254.1.1": "link-local", + "fe80::1": "link-local", + "224.0.0.1": "multicast", + "255.255.255.255": "multicast", + "10.1.2.3": "private", + "172.16.5.5": "private", + "192.168.1.10": "private", + "100.64.0.5": "private", + "fd12:3456::1": "private", + "::ffff:10.0.0.1": "private", + "172.32.0.1": "public", + "8.8.8.8": "public", + "2606:4700::1111": "public", + "::ffff:8.8.8.8": "public", + }; + for (const [ip, kind] of Object.entries(expected)) assert.equal(classifyAddress(ip), kind, ip); + }); + + test("refuses what is never allowed, and resolves names before judging them", async () => { + for (const host of ["127.0.0.1", "::1", "::ffff:127.0.0.1", "0.0.0.0", "169.254.169.254", "fe80::1", "fd00:ec2::254", "localhost"]) { + await assert.rejects(() => resolveTarget(host, { allowPrivate: true }), blocked(), host); + } + }); + + test("private ranges: allowed when asked for, refused when not", async () => { + assert.equal(await resolveTarget("192.168.1.10", { allowPrivate: true }), "192.168.1.10"); + assert.equal(await resolveTarget("8.8.8.8", { allowPrivate: false }), "8.8.8.8"); + await assert.rejects(() => resolveTarget("192.168.1.10", { allowPrivate: false }), blocked("private")); + }); + + test("odd spellings of loopback don't get through (they're refused or don't resolve)", async () => { + for (const host of ["2130706433", "0x7f000001", "127.1", "0177.0.0.1"]) { + await assert.rejects(() => resolveTarget(host, { allowPrivate: true }), blocked(), host); + } + }); +}); + +describe("certificate check", () => { + test("won't connect to loopback, link-local or metadata addresses", async () => { + for (const host of ["127.0.0.1", "localhost", "::1", "::ffff:127.0.0.1", "0.0.0.0", "169.254.169.254", "fd00:ec2::254", "100.100.100.200", "2130706433"]) { + await assert.rejects(() => fetchCertExpiry(host, 443, 500), blocked(), host); + } + }); + + test("LAN and public hosts get past the check (and fail only on the connection)", async () => { + // Nothing answers on these, so what comes back is a timeout or an unreachable error — never a refusal by the guard. + for (const host of ["192.0.2.1", "10.255.255.1"]) { + await assert.rejects( + () => fetchCertExpiry(host, 443, 400), + (err: unknown) => !(err instanceof BlockedTargetError), + host, + ); + } + }); +}); + +describe("WHOIS server", () => { + test("must look like a hostname and must be neither this machine, metadata nor private", async () => { + for (const server of ["127.0.0.1", "localhost", "169.254.169.254", "10.0.0.1", "192.168.1.1"]) { + await assert.rejects(() => defaultDeps.whoisQuery(server, "example.se"), blocked(), server); + } + for (const server of ["not a host", "evil.com/x", "a;b", "", "fd00::1", "[::1]"]) { + await assert.rejects(() => defaultDeps.whoisQuery(server, "example.se"), /not a hostname/, JSON.stringify(server)); + } + }); +}); + +describe("port scanner", () => { + test("refuses loopback and the cloud metadata address, still scans the LAN", async () => { + await assert.rejects(() => resolveScanTarget("127.0.0.1")); + await assert.rejects(() => resolveScanTarget("169.254.169.254"), /metadata/); + await assert.rejects(() => resolveScanTarget("8.8.8.8"), /private network/); + assert.equal(await resolveScanTarget("192.168.1.10"), "192.168.1.10"); + assert.equal(await resolveScanTarget("100.64.1.2"), "100.64.1.2"); + }); +}); + +// ─── Routes ───────────────────────────────────────────────────────────────── + +let port = 0; +let server: http.Server; +let operator = ""; + +/** Sends a path exactly as written, with a raw body. Resolves with the status and the reply text. */ +function send(method: string, path: string, opts: { cookie?: string; token?: string; json?: object; raw?: string } = {}): Promise<{ status: number; text: string }> { + return new Promise((resolve, reject) => { + const payload = opts.raw ?? (opts.json ? JSON.stringify(opts.json) : undefined); + const headers: Record = {}; + if (opts.cookie) headers.cookie = opts.cookie; + if (opts.token) headers.authorization = `Bearer ${opts.token}`; + if (payload !== undefined) { + headers["content-type"] = "application/json"; + headers["content-length"] = String(Buffer.byteLength(payload)); + } + const req = http.request({ host: "127.0.0.1", port, method, path, headers }, (res) => { + let text = ""; + res.on("data", (c) => (text += c)); + res.on("end", () => resolve({ status: res.statusCode ?? 0, text })); + }); + // The server may answer (and close) before it has taken the whole body; that's the point of some of these tests. + req.on("error", (err) => (/EPIPE|ECONNRESET/.test(String(err)) ? undefined : reject(err))); + if (payload !== undefined) req.write(payload); + req.end(); + }); +} + +let agentToken = ""; +let agentServerId = 0; + +before(async () => { + const express = (await import("express")).default; + const session = (await import("express-session")).default; + const { db } = await import("../src/db/client.js"); + const { users, servers } = await import("../src/db/schema.js"); + const { generateApiToken } = await import("../src/services/tokens.js"); + const { secretsRouter } = await import("../src/routes/secrets.js"); + const { agentReportRouter } = await import("../src/routes/agentReport.js"); + const { apiErrorHandler } = await import("../src/utils/apiErrorHandler.js"); + + await db.insert(users).values({ oidcSub: "op", email: "op@x", name: "Operator", role: "operator" }); + const { token, prefix, hash } = generateApiToken(); + agentToken = token; + agentServerId = (await db.insert(servers).values({ name: "agent-host", apiTokenHash: hash, apiTokenPrefix: prefix }).returning())[0].id; + + // The same order index.ts uses: the agent endpoint first, then the app-wide JSON parser and sessions, then everything else. + const app = express(); + app.use("/api/agent/report", agentReportRouter); + app.use(express.json()); + app.use(session({ secret: "t", resave: false, saveUninitialized: true })); + app.post("/login", (req, res) => { + req.session.user = { sub: "op" } as never; + res.json({}); + }); + app.use("/api/secrets", secretsRouter); + app.use(apiErrorHandler); + server = app.listen(0); + port = (server.address() as { port: number }).port; + operator = ((await fetch(`http://127.0.0.1:${port}/login`, { method: "POST" })).headers.get("set-cookie") as string).split(";")[0]; +}); + +after(() => { + server?.close(); + try { + rmSync(dir, { recursive: true, force: true }); + } catch { + // Windows keeps the SQLite file locked until the process exits. + } +}); + +describe("secrets: the certificate check can't be aimed at the server itself", () => { + test("a blocked host is refused with a clear reason", async () => { + for (const checkHost of ["127.0.0.1", "169.254.169.254", "localhost"]) { + const res = await send("POST", "/api/secrets", { cookie: operator, json: { name: "probe", type: "ssl_certificate", checkHost, checkPort: 8080 } }); + assert.equal(res.status, 400, `${checkHost}: ${res.text}`); + assert.match(res.text, /can't be used/, checkHost); + } + }); + + test("with a typed-in expiry the secret is saved, and the check records why it wasn't done — it never connects", async () => { + const res = await send("POST", "/api/secrets", { + cookie: operator, + json: { name: "manual", type: "ssl_certificate", checkHost: "127.0.0.1", checkPort: 8080, expiryDate: "2030-01-01" }, + }); + assert.equal(res.status, 201, res.text); + assert.match(JSON.parse(res.text).secret.lastCheckError, /loopback/); + }); +}); + +// ─── The agent endpoint ───────────────────────────────────────────────────── + +describe("agent endpoint", () => { + const report = (extra: object = {}) => ({ hostname: "agent-host", os_type: "linux", tasks: [], ...extra }); + + test("is mounted ahead of the app-wide JSON parser and the session store", () => { + const index = readFileSync(join(repoRoot, "server/src/index.ts"), "utf8"); + const agent = index.indexOf('app.use("/api/agent/report"'); + assert.ok(agent > 0, "agent route not found in index.ts"); + assert.ok(agent < index.indexOf("app.use(express.json())"), "the agent route must come before the 100 KB JSON parser"); + assert.ok(agent < index.indexOf("session({"), "the agent route must come before the session store"); + }); + + test("answers 401 without reading a body when the token is missing or wrong", async () => { + const huge = JSON.stringify(report({ hostname: "x".repeat(3_000_000) })); + assert.equal((await send("POST", "/api/agent/report", { raw: huge })).status, 401); + assert.equal((await send("POST", "/api/agent/report", { token: "hlm_" + "0".repeat(48), raw: huge })).status, 401); + assert.equal((await send("POST", "/api/agent/report", { token: "nonsense", json: report() })).status, 401); + }); + + test("takes an ordinary report", async () => { + const res = await send("POST", "/api/agent/report", { token: agentToken, json: report({ hostname: "web-1" }) }); + assert.equal(res.status, 202, res.text); + }); + + test("takes a big report (well past the 100 KB the rest of the API allows) from a real agent", async () => { + const ports = Array.from({ length: 2500 }, (_, i) => ({ protocol: "tcp", port: 1000 + i, address: "0.0.0.0", process: "some-process-name" })); + const body = JSON.stringify(report({ system: { listening_ports: ports } })); + assert.ok(body.length > 150_000, `the test report should be larger than 100 KB, was ${body.length}`); + const res = await send("POST", "/api/agent/report", { token: agentToken, raw: body }); + assert.equal(res.status, 202, res.text); + const { db } = await import("../src/db/client.js"); + const row = await db.query.servers.findFirst({ where: (s, { eq }) => eq(s.id, agentServerId) }); + assert.equal(JSON.parse(row!.listeningPorts!).length, 2500); + }); + + test("a body over the limit is a 413, not a server error", async () => { + const res = await send("POST", "/api/agent/report", { token: agentToken, raw: JSON.stringify(report({ hostname: "x".repeat(4_500_000) })) }); + assert.equal(res.status, 413, res.text); + assert.match(res.text, /payload_too_large/); + }); + + test("malformed JSON is a 400", async () => { + const res = await send("POST", "/api/agent/report", { token: agentToken, raw: "{not json" }); + assert.equal(res.status, 400); + assert.match(res.text, /invalid_json/); + }); + + test("overlong text is trimmed instead of costing the host its whole report", async () => { + const res = await send("POST", "/api/agent/report", { + token: agentToken, + json: report({ + hostname: "h".repeat(300), + system: { ip_addresses: Array.from({ length: 300 }, (_, i) => `10.0.${Math.floor(i / 250)}.${i % 250}`) }, + tasks: [ + { schedule_type: "cron", name: "n".repeat(600), command: "c".repeat(20_000), schedule_expression: "* * * * *" }, + { schedule_type: "cron", name: "big-metadata", metadata: { blob: "m".repeat(60_000) } }, + { schedule_type: "cron", name: "small-metadata", metadata: { user: "root" } }, + ], + }), + }); + assert.equal(res.status, 202, res.text); + + const { db } = await import("../src/db/client.js"); + const row = await db.query.servers.findFirst({ where: (s, { eq }) => eq(s.id, agentServerId) }); + assert.equal(row!.hostname!.length, 255); + assert.equal(JSON.parse(row!.ipAddresses!).length, 200); + const tasks = await db.query.scheduledTasks.findMany({ where: (t, { eq }) => eq(t.serverId, agentServerId) }); + const long = tasks.find((t) => t.name.startsWith("nnn"))!; + assert.equal(long.name.length, 500); + assert.equal(long.command!.length, 8000); + assert.equal(tasks.find((t) => t.name === "big-metadata")!.rawMetadata, null, "oversize metadata is dropped, the task kept"); + assert.equal(tasks.find((t) => t.name === "small-metadata")!.rawMetadata, JSON.stringify({ user: "root" })); + }); +}); + +// ─── The Linux agent ──────────────────────────────────────────────────────── + +const agentScript = join(repoRoot, "agent/linux/report-tasks.sh"); +const installScript = join(repoRoot, "agent/linux/install.sh"); +const haveBash = spawnSync("bash", ["-c", "command -v curl"]).status === 0; +const posix = (p: string) => p.replace(/\\/g, "/"); + +/** Runs a command without blocking this process (the fake server in these tests lives in it, so a blocking spawn would deadlock). */ +function run(cmd: string, args: string[], env: NodeJS.ProcessEnv): Promise<{ status: number | null; stdout: string; stderr: string }> { + return new Promise((resolve, reject) => { + const child = spawn(cmd, args, { env }); + let stdout = ""; + let stderr = ""; + const timer = setTimeout(() => child.kill(), 30_000); + child.stdout.on("data", (c) => (stdout += c)); + child.stderr.on("data", (c) => (stderr += c)); + child.on("error", reject); + child.on("close", (status) => { + clearTimeout(timer); + resolve({ status, stdout, stderr }); + }); + }); +} + +describe("Linux agent", () => { + test("both scripts are valid bash", { skip: !haveBash }, () => { + for (const script of [agentScript, installScript]) { + const r = spawnSync("bash", ["-n", posix(script)], { encoding: "utf8" }); + assert.equal(r.status, 0, r.stderr); + } + }); + + test("the token never goes on a command line and nothing is written to a fixed /tmp path", () => { + const text = readFileSync(agentScript, "utf8"); + assert.doesNotMatch(text, /-H\s+"Authorization/, "the token must not be passed with -H"); + assert.doesNotMatch(text, /\/tmp\/hlm/, "no fixed file name in /tmp"); + assert.match(text, /mktemp -d/); + assert.match(text, /trap 'rm -rf "\$HLM_TMPDIR"' EXIT/); + assert.match(text, /curl .* -K -/, "curl should read its config (with the token) from stdin"); + }); + + test("the systemd unit is locked down", () => { + const text = readFileSync(installScript, "utf8"); + const unit = text.slice(text.indexOf("[Service]"), text.indexOf("EOF", text.indexOf("[Service]"))); + for (const directive of ["NoNewPrivileges=yes", "PrivateTmp=yes", "ProtectSystem=strict", "ProtectHome=read-only", "ProtectKernelTunables=yes", "ProtectControlGroups=yes", "LockPersonality=yes", "RestrictAddressFamilies="]) { + assert.ok(unit.includes(directive), `missing ${directive}`); + } + // It has to keep seeing every process: that is how it names the program behind a listening port. + assert.doesNotMatch(unit, /ProtectProc|ProcSubset/); + }); + + describe("the upload, run against a fake server", { skip: !haveBash }, () => { + let fake: http.Server; + let fakePort = 0; + let seen: { authorization?: string; contentType?: string; body: string }[] = []; + let work = ""; + + before(async () => { + work = mkdtempSync(join(tmpdir(), "hm-agent-upload-")); + fake = http.createServer((req, res) => { + let body = ""; + req.on("data", (c) => (body += c)); + req.on("end", () => { + seen.push({ authorization: req.headers.authorization, contentType: req.headers["content-type"], body }); + res.writeHead(202, { "content-type": "application/json" }); + res.end(JSON.stringify({ ok: true })); + }); + }); + await new Promise((r) => fake.listen(0, "127.0.0.1", r)); + fakePort = (fake.address() as { port: number }).port; + // A curl that records its own arguments and then runs the real one — to prove what is, and isn't, on the command line. + writeFileSync(join(work, "curl"), '#!/usr/bin/env bash\nprintf \'%s\\n\' "$@" >> "$ARGV_LOG"\nexec "$REAL_CURL" "$@"\n'); + }); + after(() => { + fake?.close(); + try { + rmSync(work, { recursive: true, force: true }); + } catch { + // best effort + } + }); + + /** Runs the script's own post_report function (cut out of the real file) the way the script does. */ + async function upload(token: string, payload: string) { + seen = []; + const argvLog = join(work, "argv.log"); + const tmpRecord = join(work, "tmpdir.txt"); + rmSync(argvLog, { force: true }); + const harness = [ + "set -euo pipefail", + 'REAL_CURL=$(command -v curl); export REAL_CURL ARGV_LOG="$(cygpath -u "$ARGV_LOG_WIN" 2>/dev/null || echo "$ARGV_LOG_WIN")"', + // A "C:/..." directory can't go in PATH on Windows bash (the colon splits it), so convert it the way bash itself would. + 'SHIM_UNIX=$(cygpath -u "$SHIM_DIR" 2>/dev/null || echo "$SHIM_DIR")', + 'chmod +x "$SHIM_UNIX/curl"; PATH="$SHIM_UNIX:$PATH"', + 'source <(sed -n "/^# >>> post_report/,/^# <<< post_report/p" "$AGENT_SCRIPT")', + "CURL_INSECURE_FLAG=()", + 'HLM_TMPDIR=$(mktemp -d); printf "%s" "$HLM_TMPDIR" > "$TMP_RECORD"', + "trap 'rm -rf \"$HLM_TMPDIR\"' EXIT", + "response=$(post_report)", + 'echo "HTTP=$response"', + ].join("\n"); + const r = await run("bash", ["-c", harness], { + ...process.env, + API_URL: `http://127.0.0.1:${fakePort}`, + API_TOKEN: token, + PAYLOAD: payload, + SHIM_DIR: posix(work), + AGENT_SCRIPT: posix(agentScript), + ARGV_LOG_WIN: argvLog, + TMP_RECORD: posix(tmpRecord), + }); + const argv = existsSync(argvLog) ? readFileSync(argvLog, "utf8") : ""; + return { ...r, argv, tmpdir: existsSync(tmpRecord) ? readFileSync(tmpRecord, "utf8") : "" }; + } + + test("an ordinary report arrives with the token as a header, and the token isn't in curl's arguments", async () => { + const r = await upload("hlm_abc123", '{"hostname":"web-1","tasks":[]}'); + assert.equal(r.status, 0, r.stderr); + assert.match(r.stdout, /HTTP=202/); + assert.equal(seen.length, 1); + assert.equal(seen[0].authorization, "Bearer hlm_abc123"); + assert.equal(seen[0].contentType, "application/json"); + assert.equal(seen[0].body, '{"hostname":"web-1","tasks":[]}'); + assert.ok(r.argv.length > 0, "the curl shim recorded nothing, so the test proves nothing"); + assert.doesNotMatch(r.argv, /hlm_abc123/, "the token was on curl's command line"); + assert.doesNotMatch(r.argv, /Authorization/i); + }); + + test("a token with quotes, a backslash and a space arrives intact", async () => { + const token = 'hlm_a"b\\c d'; + const r = await upload(token, "{}"); + assert.equal(r.status, 0, r.stderr); + assert.equal(seen[0].authorization, `Bearer ${token}`); + }); + + test("a large report goes through (it isn't limited by the length of a command line)", async () => { + const payload = JSON.stringify({ tasks: [], padding: "p".repeat(600_000) }); + const r = await upload("hlm_big", payload); + assert.equal(r.status, 0, r.stderr); + assert.equal(seen[0].body.length, payload.length); + assert.doesNotMatch(r.argv, /ppppppppppppppppppppppppp/, "the payload was on curl's command line"); + }); + + test("a token with a line break is refused and nothing is sent", async () => { + const r = await upload("hlm_x\nX-Injected: yes", "{}"); + assert.notEqual(r.status, 0); + assert.match(r.stderr, /line break/); + assert.equal(seen.length, 0); + }); + + test("the private temporary directory is gone afterwards", async () => { + const r = await upload("hlm_clean", "{}"); + assert.equal(r.status, 0, r.stderr); + assert.ok(r.tmpdir.length > 0); + const gone = spawnSync("bash", ["-c", `test ! -e "${r.tmpdir}"`]); + assert.equal(gone.status, 0, `${r.tmpdir} still exists`); + }); + }); +}); + +// ─── The Windows installer ────────────────────────────────────────────────── + +const pwsh = process.platform === "win32" ? spawnSync("pwsh", ["-NoProfile", "-Command", "$PSVersionTable.PSVersion.Major"], { encoding: "utf8" }) : null; +const havePwsh = pwsh?.status === 0; + +describe("Windows installer", { skip: !havePwsh }, () => { + test("the folder the SYSTEM task runs from is writable only by SYSTEM and Administrators", () => { + const work = mkdtempSync(join(tmpdir(), "hm-acl-")); + const target = join(work, "HomelabManager"); + mkdirSync(target); + const script = ` + $ErrorActionPreference = 'Stop' + . '${join(repoRoot, "agent", "windows", "install.ps1").replace(/'/g, "''")}' + $me = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value + Protect-InstallDir '${target.replace(/'/g, "''")}' -ExtraGrants @("*\${me}:(OI)(CI)(F)") # lets this un-elevated test keep access to its own folder + $file = Join-Path '${target.replace(/'/g, "''")}' 'homelab-manager-agent.ps1' + Set-Content -Path $file -Value 'x' + function Describe($p) { + $acl = Get-Acl $p + foreach ($rule in $acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier])) { '{0}|{1}' -f $rule.IdentityReference.Value, $rule.IsInherited } + } + 'DIR'; Describe '${target.replace(/'/g, "''")}' + 'FILE'; Describe $file + 'ME=' + $me + `; + const scriptFile = join(work, "check-acl.ps1"); + writeFileSync(scriptFile, script); + const r = spawnSync("pwsh", ["-NoProfile", "-NonInteractive", "-File", scriptFile], { encoding: "utf8" }); + try { + // No error output and a complete listing; the exit status is left out because PowerShell's -File status isn't reliable across hosts here. + assert.equal(r.stderr.trim(), "", `PowerShell reported an error: +${r.stderr} +${r.stdout}`); + assert.ok(r.stdout.includes("ME="), `the script did not finish: +${r.stdout}`); + const lines = r.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean); + const me = lines.find((l) => l.startsWith("ME="))!.slice(3); + const part = (from: string, to: string | null) => lines.slice(lines.indexOf(from) + 1, to ? lines.indexOf(to) : lines.findIndex((l) => l.startsWith("ME="))).map((l) => l.split("|")); + const dir = part("DIR", "FILE"); + const file = part("FILE", null); + const allowed = new Set(["S-1-5-18", "S-1-5-32-544", me]); + + assert.deepEqual(new Set(dir.map(([sid]) => sid)), allowed, `folder ACL: ${JSON.stringify(dir)}`); + assert.ok(dir.every(([, inherited]) => inherited === "False"), "the folder must not inherit ProgramData's permissions"); + assert.deepEqual(new Set(file.map(([sid]) => sid)), allowed, `file ACL: ${JSON.stringify(file)}`); + for (const everyone of ["S-1-5-32-545" /* Users */, "S-1-5-11" /* Authenticated Users */, "S-1-1-0" /* Everyone */]) { + assert.ok(!dir.some(([sid]) => sid === everyone) && !file.some(([sid]) => sid === everyone), `${everyone} has access`); + } + } finally { + try { + rmSync(work, { recursive: true, force: true }); + } catch { + // best effort + } + } + }); +}); diff --git a/web/src/pages/Privacy.tsx b/web/src/pages/Privacy.tsx index 95ef325..59f1030 100644 --- a/web/src/pages/Privacy.tsx +++ b/web/src/pages/Privacy.tsx @@ -252,7 +252,7 @@ export default function Privacy() {
  • Certificate checks — for {outbound?.tlsCertificateChecks ?? 0} secret{outbound?.tlsCertificateChecks === 1 ? "" : "s"} with - a host to check, the app connects to that host to read its certificate. + a host to check, the app connects to that host to read its certificate — never to this server itself, a loopback or link-local address, or a cloud metadata address.
  • Skatteverket — only when an admin clicks "Import from Skatteverket" under Settings → Names, the app asks