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

+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));
}