Refuse loopback and metadata targets; check the agent's token before reading its report
Certificate check, WHOIS lookup and port scanner connect to hosts that are typed in or named by a plain-text reply. utils/networkGuard.ts now refuses loopback, link-local (cloud metadata) and similar addresses for all three -- and a WHOIS server on a private network -- and the connection goes to the address that was checked rather than looking the name up again (no DNS rebinding). LAN hosts remain fine for certificate checks and scans. Agent endpoint: the token is checked before the body is read, the route is mounted ahead of the 100 KB JSON parser so a real agent can send a large report (up to 4 MB), and overlong text is trimmed instead of costing the host its whole report. An oversized or malformed body is answered with 413 / 400 instead of a generic 500. Tests (npm test --workspace server): the guard, the secrets route, the agent endpoint, the Linux upload run against a fake server (token never on curl's arguments, private temp dir removed), the systemd unit's directives, and the Windows folder permissions read back by SID. 19 of the 26 new tests fail against the previous code. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
047fcb403e
commit
dbbe4180e0
9 files changed
+710
-40
No files matched your search
+4
-5
@@ -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}`);
|
||||
|
||||
@@ -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 = <T>(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) {
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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<string> {
|
||||
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(
|
||||
|
||||
@@ -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<string> {
|
||||
export async function fetchCertExpiry(host: string, port: number, timeoutMs = 10_000): Promise<string> {
|
||||
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,
|
||||
|
||||
@@ -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" });
|
||||
}
|
||||
@@ -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<Exclude<AddressClass, "public" | "private">, 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<string> {
|
||||
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];
|
||||
}
|
||||
Reference in new issue
Block a user