Port presets: name ports automatically, scan many hosts for a preset, apply names in bulk

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-30 22:39:52 +01:00
1 parent 93aaf5476d
commit fca2dc0338
24 files changed
+9764 -40

No files matched your search

+2
View File
@@ -74,6 +74,7 @@ import { wallRouter } from "./routes/wall.js";
import { adguardRouter } from "./routes/adguard.js";
import { grafanaRouter } from "./routes/grafana.js";
import { versionsRouter } from "./routes/versions.js";
import { portPresetsRouter } from "./routes/portPresets.js";
import { costsRouter } from "./routes/costs.js";
import { nextcloudRouter } from "./routes/nextcloud.js";
import { serviceLevelsRouter } from "./routes/serviceLevels.js";
@@ -226,6 +227,7 @@ export function createApp() {
app.use("/api/adguard", adguardRouter);
app.use("/api/grafana", grafanaRouter);
app.use("/api/versions", versionsRouter);
app.use("/api/port-presets", portPresetsRouter);
app.use("/api/costs", costsRouter);
app.use("/api/nextcloud", nextcloudRouter);
app.use("/api/service-levels", serviceLevelsRouter);
+12
View File
@@ -716,6 +716,18 @@ export const portForwards = sqliteTable("port_forwards", {
.default(sql`(current_timestamp)`),
});
// ─── Port presets ───────────────────────────────────────────────────────────
// A named list of ports and what each is — "Remote access": 22 SSH, 3389 RDP — written once and used on every host: to name a port wherever it shows, to scan several hosts for just those
// ports, and to write the names onto what is open. `ports` is JSON: [{ port, protocol, label }]. Some ready-made ones are put there the first time (services/portPresets.ts).
export const portPresets = sqliteTable("port_presets", {
id: integer("id").primaryKey({ autoIncrement: true }),
name: text("name").notNull().unique(),
ports: text("ports").notNull().default("[]"),
createdAt: text("created_at").notNull(), // ISO
updatedAt: text("updated_at").notNull(), // ISO
});
// ─── Domain registrations ───────────────────────────────────────────────────
export const domainOrigins = ["manual", "zone"] as const;
+231
View File
@@ -0,0 +1,231 @@
import { Router } from "express";
import { and, eq, inArray } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { portPresets, servers, serverPorts } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { type AgentPort, groupAgentPorts, parseJson } from "../services/agentPorts.js";
import { getPreset, listPresets, mapLimit, MAX_PRESET_PORTS, scannablePorts, type PresetPort } from "../services/portPresets.js";
import { beginScan, endScan, resolveScanTarget, scanPortList } from "../services/portScan.js";
import { recordPortScan, scanResponded } from "../services/portScanRecord.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const portPresetsRouter = Router();
portPresetsRouter.use(requireAuth);
/** How many hosts a preset is scanned on at the same time: each scan holds hundreds of sockets open at most, but a whole network at once is a burst nobody asked for. */
const HOSTS_AT_ONCE = 3;
const MAX_TARGETS = 100;
const portSchema = z.object({
port: z.number().int().min(1).max(65535),
protocol: z.enum(["tcp", "udp"]).default("tcp"),
label: z.string().trim().min(1).max(60),
});
const presetSchema = z
.object({
name: z.string().trim().min(1).max(60),
ports: z.array(portSchema).min(1).max(MAX_PRESET_PORTS),
})
.refine((d) => new Set(d.ports.map((p) => `${p.protocol}:${p.port}`)).size === d.ports.length, { message: "A port is in the list twice." });
const idOf = (v: string) => (/^\d+$/.test(v) ? Number(v) : NaN);
const invalid = (res: import("express").Response, parsed: { error: z.ZodError }) =>
res.status(400).json({ error: "invalid_body", message: parsed.error.issues[0]?.message ?? "That is not a preset.", details: parsed.error.flatten() });
// Everyone signed in sees the presets: they are what ports are called.
portPresetsRouter.get("/", asyncHandler(async (_req, res) => {
res.json({ presets: await listPresets() });
}));
portPresetsRouter.post("/", requireRole("operator"), asyncHandler(async (req, res) => {
const parsed = presetSchema.safeParse(req.body);
if (!parsed.success) return invalid(res, parsed);
const taken = (await listPresets()).some((p) => p.name.toLowerCase() === parsed.data.name.toLowerCase());
if (taken) return res.status(409).json({ error: "name_taken", message: "There is a preset with that name already." });
const now = new Date().toISOString();
const [row] = await db.insert(portPresets).values({ name: parsed.data.name, ports: JSON.stringify(parsed.data.ports), createdAt: now, updatedAt: now }).returning();
await recordAudit({ actor: req.currentUser!, category: "server", action: "create_port_preset", targetType: "port_preset", targetId: row.id, detail: { name: row.name, ports: parsed.data.ports.length } });
res.status(201).json({ preset: { id: row.id, name: row.name, ports: parsed.data.ports, updatedAt: row.updatedAt } });
}));
portPresetsRouter.put("/:id", requireRole("operator"), asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const parsed = presetSchema.safeParse(req.body);
if (!parsed.success) return invalid(res, parsed);
const before = await getPreset(id);
if (!before) return res.status(404).json({ error: "not_found" });
const taken = (await listPresets()).some((p) => p.id !== id && p.name.toLowerCase() === parsed.data.name.toLowerCase());
if (taken) return res.status(409).json({ error: "name_taken", message: "There is a preset with that name already." });
const now = new Date().toISOString();
await db.update(portPresets).set({ name: parsed.data.name, ports: JSON.stringify(parsed.data.ports), updatedAt: now }).where(eq(portPresets.id, id));
await recordAudit({ actor: req.currentUser!, category: "server", action: "update_port_preset", targetType: "port_preset", targetId: id, detail: { name: parsed.data.name, ports: parsed.data.ports.length } });
res.json({ preset: { id, name: parsed.data.name, ports: parsed.data.ports, updatedAt: now } });
}));
portPresetsRouter.delete("/:id", requireRole("operator"), asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const before = await getPreset(id);
if (!before) return res.status(404).json({ error: "not_found" });
await db.delete(portPresets).where(eq(portPresets.id, id));
await recordAudit({ actor: req.currentUser!, category: "server", action: "delete_port_preset", targetType: "port_preset", targetId: id, detail: { name: before.name } });
res.status(204).end();
}));
// ─── Scanning hosts for a preset ────────────────────────────────────────────
const scanSchema = z.object({
targets: z
.array(z.object({ serverId: z.number().int().positive(), address: z.string().trim().max(255).optional() }))
.min(1)
.max(MAX_TARGETS),
});
export interface PresetHostResult {
serverId: number;
name: string;
/** The address that was scanned; null when none could be found. */
address: string | null;
/** scanned: answered; no_answer: nothing answered (down, or dropping everything — says nothing of its ports); skipped: no address; error: could not be scanned; busy: a scan of it was running. */
state: "scanned" | "no_answer" | "skipped" | "error" | "busy";
message: string | null;
open: number[];
/** Refused: the host answered "nothing here". */
closed: number[];
/** Never answered (a firewall dropping packets). */
filtered: number;
}
/** The address to scan for a server that was not told one: the first address it is known by, else its host name. */
export function addressOf(server: { ipAddresses: string | null; hostname: string | null }): string | null {
const ips = parseJson<unknown>(server.ipAddresses, []);
const first = Array.isArray(ips) ? ips.find((i): i is string => typeof i === "string" && i.trim() !== "") : undefined;
return first?.trim() ?? (server.hostname?.trim() || null);
}
portPresetsRouter.post("/:id/scan", requireRole("operator"), asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const parsed = scanSchema.safeParse(req.body);
if (!parsed.success) return invalid(res, parsed);
const preset = await getPreset(id);
if (!preset) return res.status(404).json({ error: "not_found" });
const ports = scannablePorts(preset);
if (ports.length === 0) return res.status(400).json({ error: "nothing_to_scan", message: "This preset has no TCP ports — a scan only looks at TCP." });
const wanted = new Set(ports);
// A server named twice is scanned once, as the first request for it says.
const targets = parsed.data.targets.filter((t, i, all) => all.findIndex((x) => x.serverId === t.serverId) === i);
const rows = await db.select({ id: servers.id, name: servers.name, ipAddresses: servers.ipAddresses, hostname: servers.hostname }).from(servers).where(inArray(servers.id, targets.map((t) => t.serverId)));
const byId = new Map(rows.map((r) => [r.id, r]));
const results = await mapLimit(targets, HOSTS_AT_ONCE, async (t): Promise<PresetHostResult> => {
const server = byId.get(t.serverId);
const base = { serverId: t.serverId, name: server?.name ?? `#${t.serverId}`, open: [] as number[], closed: [] as number[], filtered: 0 };
if (!server) return { ...base, address: null, state: "error", message: "That server does not exist." };
const given = t.address && t.address !== "" ? t.address : addressOf(server);
if (!given) return { ...base, address: null, state: "skipped", message: "No address is known for it — give one." };
let target: string;
try {
target = await resolveScanTarget(given);
} catch (err) {
return { ...base, address: given, state: "error", message: err instanceof Error ? err.message : String(err) };
}
if (!beginScan(server.id)) return { ...base, address: target, state: "busy", message: "A scan of this server is already running." };
let scan;
try {
scan = await scanPortList(target, ports);
} catch (err) {
return { ...base, address: target, state: "error", message: err instanceof Error ? err.message : String(err) };
} finally {
endScan(server.id);
}
if (!scanResponded(scan)) return { ...base, address: target, state: "no_answer", message: "Nothing answered — it may be down, or dropping everything.", filtered: scan.filtered };
await recordPortScan(server.id, (p) => wanted.has(p), scan, new Date().toISOString());
return { ...base, address: target, state: "scanned", message: null, open: scan.open, closed: scan.refused, filtered: scan.filtered };
});
await recordAudit({
actor: req.currentUser!,
category: "server",
action: "scan_port_preset",
targetType: "port_preset",
targetId: id,
detail: { name: preset.name, servers: results.length, scanned: results.filter((r) => r.state === "scanned").length, open: results.reduce((n, r) => n + r.open.length, 0) },
});
res.json({ preset: { id: preset.id, name: preset.name }, ports, labels: Object.fromEntries(preset.ports.filter((p) => p.protocol === "tcp").map((p) => [p.port, p.label])), results });
}));
// ─── Writing a preset's names onto many hosts ───────────────────────────────
const applySchema = z.object({
serverIds: z.array(z.number().int().positive()).min(1).max(500),
/** Only the ports that are open on the host (a scan found them, or its agent says they are listening) — the default. False notes every port of the preset on every host. */
onlyOpen: z.boolean().default(true),
/** Replace a label somebody wrote with the preset's. Never by default. */
overwrite: z.boolean().default(false),
});
export interface PresetApplyResult {
serverId: number;
name: string;
labelled: { port: number; protocol: "tcp" | "udp"; label: string }[];
skipped: { port: number; protocol: "tcp" | "udp"; reason: "not_open" | "has_label" | "same" }[];
}
portPresetsRouter.post("/:id/apply", requireRole("operator"), asyncHandler(async (req, res) => {
const id = idOf(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const parsed = applySchema.safeParse(req.body);
if (!parsed.success) return invalid(res, parsed);
const preset = await getPreset(id);
if (!preset) return res.status(404).json({ error: "not_found" });
const { onlyOpen, overwrite } = parsed.data;
const ids = [...new Set(parsed.data.serverIds)];
const rows = await db.select({ id: servers.id, name: servers.name, listeningPorts: servers.listeningPorts }).from(servers).where(inArray(servers.id, ids));
const existing = await db.select().from(serverPorts).where(inArray(serverPorts.serverId, rows.map((r) => r.id)));
const now = new Date().toISOString();
const results: PresetApplyResult[] = [];
for (const server of rows) {
const mine = existing.filter((r) => r.serverId === server.id);
const agent = groupAgentPorts(parseJson<AgentPort[] | null>(server.listeningPorts, null) ?? []);
const labelled: PresetApplyResult["labelled"] = [];
const skipped: PresetApplyResult["skipped"] = [];
for (const p of preset.ports as PresetPort[]) {
const row = mine.find((r) => r.port === p.port && r.protocol === p.protocol);
const open = !!row?.open || agent.has(`${p.protocol}:${p.port}`);
if (onlyOpen && !open) {
skipped.push({ port: p.port, protocol: p.protocol, reason: "not_open" });
continue;
}
if (row?.label === p.label) {
skipped.push({ port: p.port, protocol: p.protocol, reason: "same" });
continue;
}
if (row?.label && !overwrite) {
skipped.push({ port: p.port, protocol: p.protocol, reason: "has_label" });
continue;
}
if (row) await db.update(serverPorts).set({ label: p.label, updatedAt: now }).where(and(eq(serverPorts.id, row.id), eq(serverPorts.serverId, server.id)));
else await db.insert(serverPorts).values({ serverId: server.id, port: p.port, protocol: p.protocol, label: p.label, updatedAt: now });
labelled.push({ port: p.port, protocol: p.protocol, label: p.label });
}
results.push({ serverId: server.id, name: server.name, labelled, skipped });
}
await recordAudit({
actor: req.currentUser!,
category: "server",
action: "apply_port_preset",
targetType: "port_preset",
targetId: id,
detail: { name: preset.name, servers: results.length, labelled: results.reduce((n, r) => n + r.labelled.length, 0), onlyOpen, overwrite },
});
res.json({ preset: { id: preset.id, name: preset.name }, results });
}));
+5
View File
@@ -6,6 +6,7 @@ import { servers, portForwards } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { type AgentPort, groupAgentPorts, parseJson, splitPortKey } from "../services/agentPorts.js";
import { listPresets, serviceName, serviceNames } from "../services/portPresets.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const portsRouter = Router();
@@ -23,6 +24,8 @@ export interface AgentPortRow {
addresses: string[];
process: string | null;
localOnly: boolean;
/** What a port preset calls it ("RDP"), when one does. */
service: string | null;
lastSeenAt: string | null;
}
@@ -31,6 +34,7 @@ portsRouter.get("/agent", asyncHandler(async (_req, res) => {
.select({ id: servers.id, name: servers.name, hostname: servers.hostname, listeningPorts: servers.listeningPorts, lastSeenAt: servers.lastSeenAt })
.from(servers);
const names = serviceNames(await listPresets());
const out: AgentPortRow[] = [];
for (const s of rows) {
const raw = parseJson<AgentPort[] | null>(s.listeningPorts, null);
@@ -46,6 +50,7 @@ portsRouter.get("/agent", asyncHandler(async (_req, res) => {
addresses: grouped.addresses,
process: grouped.process,
localOnly: grouped.localOnly,
service: serviceName(names, protocol, port),
lastSeenAt: s.lastSeenAt,
});
}
+9 -27
View File
@@ -1,5 +1,5 @@
import { Router } from "express";
import { and, eq, inArray } from "drizzle-orm";
import { and, eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { servers, serverPorts } from "../db/schema.js";
@@ -7,6 +7,8 @@ import { requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { beginScan, endScan, MAX_SCAN_SPAN, resolveScanTarget, scanPorts, toRanges } from "../services/portScan.js";
import { type AgentPort, groupAgentPorts, parseJson } from "../services/agentPorts.js";
import { listPresets, serviceName, serviceNames } from "../services/portPresets.js";
import { recordPortScan } from "../services/portScanRecord.js";
import { newListeningPorts, parseBaseline, portKey } from "../services/newPorts.js";
import { getSettings } from "../services/settingsStore.js";
import { asyncHandler } from "../utils/asyncHandler.js";
@@ -32,6 +34,8 @@ export interface PortEntry {
protocol: "tcp" | "udp";
label: string | null;
comment: string | null;
/** What a port preset calls this port ("RDP"), when one does; shown where there is no label of its own. */
service: string | null;
/** The last scan from this app connected to it. */
scanOpen: boolean;
lastSeenOpenAt: string | null;
@@ -55,6 +59,7 @@ async function buildPortList(serverId: number) {
const alerting = (await getSettings()).healthChecks.newPortAlerts;
const fresh = new Set(alerting ? newListeningPorts(agentRaw, parseBaseline(server.portBaseline), expected).map((p) => portKey(p.protocol, p.port)) : []);
const names = serviceNames(await listPresets());
const entries = new Map<string, PortEntry>();
for (const row of rows) {
const key = `${row.protocol}:${row.port}`;
@@ -64,6 +69,7 @@ async function buildPortList(serverId: number) {
protocol: row.protocol,
label: row.label,
comment: row.comment,
service: serviceName(names, row.protocol, row.port),
scanOpen: row.open,
lastSeenOpenAt: row.lastSeenOpenAt,
agent: agent.get(key) ?? null,
@@ -80,6 +86,7 @@ async function buildPortList(serverId: number) {
protocol: protocol as "tcp" | "udp",
label: null,
comment: null,
service: serviceName(names, protocol, Number(port)),
scanOpen: false,
lastSeenOpenAt: null,
agent: info,
@@ -160,32 +167,7 @@ serverPortsRouter.post("/scan", requireRole("operator"), asyncHandler(async (req
// which ports are open, so leave what we knew before rather than marking it all closed.
const responded = scan.open.length + scan.refused.length > 0;
if (responded) {
const existing = await db
.select()
.from(serverPorts)
.where(and(eq(serverPorts.serverId, serverId), eq(serverPorts.protocol, "tcp")));
const inRange = existing.filter((r) => r.port >= from && r.port <= to);
const openSet = new Set(scan.open);
const known = new Set(existing.map((r) => r.port));
const newlyFound = scan.open.filter((p) => !known.has(p));
for (let i = 0; i < newlyFound.length; i += 50) {
await db.insert(serverPorts).values(
newlyFound.slice(i, i + 50).map((port) => ({ serverId, port, protocol: "tcp" as const, open: true, lastSeenOpenAt: now })),
);
}
const stillOpen = inRange.filter((r) => openSet.has(r.port)).map((r) => r.id);
if (stillOpen.length > 0) {
await db.update(serverPorts).set({ open: true, lastSeenOpenAt: now }).where(inArray(serverPorts.id, stillOpen));
}
// No longer open: keep it if someone wrote a note about it (it's now "reserved"), otherwise it carries no information.
const gone = inRange.filter((r) => r.open && !openSet.has(r.port));
const keep = gone.filter((r) => r.label || r.comment).map((r) => r.id);
const drop = gone.filter((r) => !(r.label || r.comment)).map((r) => r.id);
if (keep.length > 0) await db.update(serverPorts).set({ open: false }).where(inArray(serverPorts.id, keep));
if (drop.length > 0) await db.delete(serverPorts).where(inArray(serverPorts.id, drop));
}
if (responded) await recordPortScan(serverId, (port) => port >= from && port <= to, scan, now);
const summary: StoredScan = {
at: now,
+3 -1
View File
@@ -13,6 +13,7 @@ import { dependencyCover, HEALTH_STATE_FLAG } from "./dependencies.js";
import { getFailingSources } from "./integrationHealthMonitor.js";
import { hostHealthConditions, parseHostHealth, withoutIgnoredServices, type HostHealth } from "./hostHealth.js";
import { newListeningPorts, newPortMessage, parseBaseline, portKey, type NewPort } from "./newPorts.js";
import { listPresets, serviceName, serviceNames } from "./portPresets.js";
import { parseJson, type AgentPort } from "./agentPorts.js";
import { diskLimit, parseThresholds, type ServerThresholds } from "./serverThresholds.js";
import { computeRuleFindings, findingKey, listRules, type RuleFinding } from "./alertRules.js";
@@ -488,6 +489,7 @@ export async function collectSnapshot(): Promise<{ snapshot: HealthSnapshot; hel
const { healthChecks: checks } = await getSettings();
// The ports somebody has said are expected (a label or a comment on the Ports page); a row that only records an open scan says nothing.
const portNames = serviceNames(await listPresets());
const expectedByServer = new Map<number, Set<string>>();
if (checks.newPortAlerts) {
for (const r of await db.select().from(serverPorts)) {
@@ -504,7 +506,7 @@ export async function collectSnapshot(): Promise<{ snapshot: HealthSnapshot; hel
} catch {
// a malformed report shouldn't stop every other server being checked
}
const newPorts = checks.newPortAlerts ? newListeningPorts(parseJson<AgentPort[] | null>(s.listeningPorts, null), parseBaseline(s.portBaseline), expectedByServer.get(s.id) ?? new Set()) : [];
const newPorts = checks.newPortAlerts ? newListeningPorts(parseJson<AgentPort[] | null>(s.listeningPorts, null), parseBaseline(s.portBaseline), expectedByServer.get(s.id) ?? new Set()).map((p) => ({ ...p, service: serviceName(portNames, "tcp", p.port) })) : [];
snapshot.servers.push({ id: s.id, name: s.name, lastSeenAt: s.lastSeenAt, disks, health: withoutIgnoredServices(parseHostHealth(s.hostHealth), parseThresholds(s.thresholds)?.ignoreServices), thresholds: parseThresholds(s.thresholds), newPorts });
}
+3 -1
View File
@@ -17,6 +17,8 @@ export interface NewPort {
port: number;
/** What is listening, as the agent says; null when it does not. */
process: string | null;
/** What a port preset calls the port ("RDP"), when one does. */
service?: string | null;
}
export const portKey = (protocol: string, port: number) => `${protocol}:${port}`;
@@ -57,4 +59,4 @@ export function newListeningPorts(listening: AgentPort[] | null | undefined, bas
}
export const newPortMessage = (serverName: string, p: NewPort) =>
`${serverName}: a new port is listening — ${p.port}/tcp${p.process ? ` (${p.process})` : ""}. If it should be there, note it on the server's Ports card.`;
`${serverName}: a new port is listening — ${p.port}/tcp${p.service ? ` ${p.service}` : ""}${p.process ? ` (${p.process})` : ""}. If it should be there, note it on the server's Ports card.`;
+106
View File
@@ -0,0 +1,106 @@
/**
* Port presets: a named list of ports and what each is ("Remote access" = 22 SSH, 3389 RDP …), written once and used on every host — to put a name to a port wherever it shows (without a label
* typed for each host), to scan several hosts for just those ports, and to write the names onto the ports that are open on many hosts in one go.
*
* A few ready-made presets are put there the first time they are asked for; they are ordinary presets (change them, delete them) and are not put back once the list has been touched — deleting them all
* leaves none. Scanning is TCP only (as the Ports card's scan is), so a UDP entry in a preset is for naming only.
*/
import { asc, eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { portPresets } from "../db/schema.js";
import { getInternalFlag, setInternalFlag } from "./settingsStore.js";
export interface PresetPort {
port: number;
protocol: "tcp" | "udp";
label: string;
}
export interface PortPreset {
id: number;
name: string;
ports: PresetPort[];
updatedAt: string;
}
export const MAX_PRESET_PORTS = 60;
const SEEDED_FLAG = "portPresetsSeeded";
const tcp = (port: number, label: string): PresetPort => ({ port, protocol: "tcp", label });
/** What is there to begin with. */
export const STARTER_PRESETS: { name: string; ports: PresetPort[] }[] = [
{ name: "Remote access", ports: [tcp(22, "SSH"), tcp(3389, "RDP"), tcp(5900, "VNC"), tcp(5985, "WinRM (HTTP)"), tcp(5986, "WinRM (HTTPS)")] },
{ name: "Databases", ports: [tcp(1433, "SQL Server"), tcp(1521, "Oracle"), tcp(3306, "MySQL / MariaDB"), tcp(5432, "PostgreSQL"), tcp(6379, "Redis"), tcp(11211, "Memcached"), tcp(27017, "MongoDB")] },
{ name: "Web", ports: [tcp(80, "HTTP"), tcp(443, "HTTPS"), tcp(8080, "HTTP (alternate)"), tcp(8443, "HTTPS (alternate)")] },
{ name: "File sharing", ports: [tcp(21, "FTP"), tcp(139, "NetBIOS"), tcp(445, "SMB"), tcp(873, "rsync"), tcp(2049, "NFS")] },
{ name: "Homelab tools", ports: [tcp(3000, "Grafana"), tcp(5000, "Synology DSM"), tcp(5001, "Synology DSM (HTTPS)"), tcp(8006, "Proxmox VE"), tcp(8007, "Proxmox Backup Server"), tcp(9090, "Prometheus")] },
];
function parsePorts(stored: string): PresetPort[] {
try {
const v = JSON.parse(stored);
if (!Array.isArray(v)) return [];
return v
.filter((p): p is PresetPort => p !== null && typeof p === "object" && Number.isInteger(p.port) && (p.protocol === "tcp" || p.protocol === "udp") && typeof p.label === "string")
.map((p) => ({ port: p.port, protocol: p.protocol, label: p.label }));
} catch {
return [];
}
}
const rowToPreset = (r: typeof portPresets.$inferSelect): PortPreset => ({ id: r.id, name: r.name, ports: parsePorts(r.ports), updatedAt: r.updatedAt });
/** Puts the ready-made presets there, once: the first time, and only into an empty list. */
async function ensureStarters(): Promise<void> {
if ((await getInternalFlag(SEEDED_FLAG)) !== null) return;
const existing = await db.select({ id: portPresets.id }).from(portPresets).limit(1);
if (existing.length === 0) {
const now = new Date().toISOString();
for (const p of STARTER_PRESETS) await db.insert(portPresets).values({ name: p.name, ports: JSON.stringify(p.ports), createdAt: now, updatedAt: now });
}
await setInternalFlag(SEEDED_FLAG, new Date().toISOString());
}
/** Every preset, by name. */
export async function listPresets(): Promise<PortPreset[]> {
await ensureStarters();
return (await db.select().from(portPresets).orderBy(asc(portPresets.name))).map(rowToPreset);
}
export async function getPreset(id: number): Promise<PortPreset | null> {
await ensureStarters();
const [row] = await db.select().from(portPresets).where(eq(portPresets.id, id)).limit(1);
return row ? rowToPreset(row) : null;
}
const keyOf = (protocol: string, port: number) => `${protocol}:${port}`;
/**
* Pure: what each port is called, from every preset: "tcp:3389" → "RDP". A port in more than one preset is called what the first of them (by name) calls it, so a port is never
* called two things at once.
*/
export function serviceNames(presets: PortPreset[]): Map<string, string> {
const names = new Map<string, string>();
for (const p of presets) for (const e of p.ports) if (!names.has(keyOf(e.protocol, e.port))) names.set(keyOf(e.protocol, e.port), e.label);
return names;
}
export const serviceName = (names: Map<string, string>, protocol: string, port: number): string | null => names.get(keyOf(protocol, port)) ?? null;
/** Pure: the TCP ports of a preset, in order — what a scan of it looks at. */
export const scannablePorts = (preset: Pick<PortPreset, "ports">): number[] => [...new Set(preset.ports.filter((p) => p.protocol === "tcp").map((p) => p.port))].sort((a, b) => a - b);
/** Runs `run` for each item, at most `limit` at a time, and returns the answers in the order of the items. */
export async function mapLimit<T, R>(items: T[], limit: number, run: (item: T) => Promise<R>): Promise<R[]> {
const out = new Array<R>(items.length);
let next = 0;
async function worker() {
while (next < items.length) {
const i = next++;
out[i] = await run(items[i]);
}
}
await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
return out;
}
+33
View File
@@ -61,6 +61,32 @@ export async function scanPorts(
return { open, refused, filtered };
}
/** TCP connect scan of a list of ports (a preset's), with a bounded number of connections in flight. The answers are as scanPorts gives them. */
export async function scanPortList(host: string, ports: number[], options: { timeoutMs?: number; concurrency?: number } = {}): Promise<ScanResult> {
const timeoutMs = options.timeoutMs ?? 700;
const concurrency = options.concurrency ?? 400;
const list = [...new Set(ports)];
const open: number[] = [];
const refused: number[] = [];
let filtered = 0;
let next = 0;
async function worker() {
while (next < list.length) {
const port = list[next++];
const result = await probe(host, port, timeoutMs);
if (result === "open") open.push(port);
else if (result === "refused") refused.push(port);
else filtered++;
}
}
await Promise.all(Array.from({ length: Math.min(concurrency, list.length) }, worker));
open.sort((a, b) => a - b);
refused.sort((a, b) => a - b);
return { open, refused, filtered };
}
function isPrivateIPv4(ip: string): boolean {
const [a, b] = ip.split(".").map(Number);
return (
@@ -91,6 +117,7 @@ export function isPrivateAddress(ip: string): boolean {
* describe the machine the app itself runs on.
*/
export async function resolveScanTarget(address: string): Promise<string> {
if (resolverOverride) return resolverOverride(address);
const trimmed = address.trim();
if (!trimmed) throw new Error("No address to scan.");
let ips: string[];
@@ -115,6 +142,12 @@ export async function resolveScanTarget(address: string): Promise<string> {
return ip;
}
let resolverOverride: ((address: string) => Promise<string>) | null = null;
/** For tests: what decides which address is scanned, instead of the rule that it must be a private one (a test listens on the loopback address). */
export function setScanTargetResolverForTests(fn: ((address: string) => Promise<string>) | null): void {
resolverOverride = fn;
}
/** Collapses a sorted list of ports into inclusive [start, end] ranges. */
export function toRanges(ports: number[]): [number, number][] {
const ranges: [number, number][] = [];
+33
View File
@@ -0,0 +1,33 @@
/**
* What a scan changes in what is remembered about a server's ports: a port found open that was not known is written down, one that is still open is marked as seen, and one that is no longer open
* is kept if somebody wrote a note about it (it is then "reserved") and dropped if not. Only the ports the scan looked at are touched, whether they are a range or a list. If nothing at all
* answered the host is probably down or dropping everything, which says nothing of its ports, so what was known is left alone.
*/
import { and, eq, inArray } from "drizzle-orm";
import { db } from "../db/client.js";
import { serverPorts } from "../db/schema.js";
import type { ScanResult } from "./portScan.js";
/** Whether anything answered (open, or refusing): the only case in which a scan says anything. */
export const scanResponded = (scan: ScanResult): boolean => scan.open.length + scan.refused.length > 0;
export async function recordPortScan(serverId: number, inScope: (port: number) => boolean, scan: ScanResult, now: string): Promise<void> {
if (!scanResponded(scan)) return;
const existing = await db.select().from(serverPorts).where(and(eq(serverPorts.serverId, serverId), eq(serverPorts.protocol, "tcp")));
const inRange = existing.filter((r) => inScope(r.port));
const openSet = new Set(scan.open);
const known = new Set(existing.map((r) => r.port));
const newlyFound = scan.open.filter((p) => !known.has(p));
for (let i = 0; i < newlyFound.length; i += 50) {
await db.insert(serverPorts).values(newlyFound.slice(i, i + 50).map((port) => ({ serverId, port, protocol: "tcp" as const, open: true, lastSeenOpenAt: now })));
}
const stillOpen = inRange.filter((r) => openSet.has(r.port)).map((r) => r.id);
if (stillOpen.length > 0) await db.update(serverPorts).set({ open: true, lastSeenOpenAt: now }).where(inArray(serverPorts.id, stillOpen));
// No longer open: keep it if someone wrote a note about it (it's now "reserved"), otherwise it carries no information.
const gone = inRange.filter((r) => r.open && !openSet.has(r.port));
const keep = gone.filter((r) => r.label || r.comment).map((r) => r.id);
const drop = gone.filter((r) => !(r.label || r.comment)).map((r) => r.id);
if (keep.length > 0) await db.update(serverPorts).set({ open: false }).where(inArray(serverPorts.id, keep));
if (drop.length > 0) await db.delete(serverPorts).where(inArray(serverPorts.id, drop));
}