diff --git a/DATABASE.md b/DATABASE.md index 34af91b..32d7a38 100644 --- a/DATABASE.md +++ b/DATABASE.md @@ -413,7 +413,7 @@ records them; it can't check or change them. #### `port_presets` -A named list of ports ("Remote access": SSH, RDP, VNC). A port in any preset is named wherever it is shown, can be scanned for on many servers at once, and can have its name written onto the servers where it is open (`server_ports.label`). The ready-made ones are written once, into an empty table (flag `_internal:portPresetsSeeded` in `settings`), and are ordinary rows after that. +A named list of ports ("Remote access": SSH, RDP, VNC). A port in any preset is named wherever it is shown, can be scanned for on many servers at once, and can have its name written onto the servers where it is open (`server_ports.label`). The ready-made ones are written once, into an empty table (flag `_internal:portPresetsSeeded` in `settings`), and are ordinary rows after that. The operating-system ones (*Windows client*, *Windows server*, *Debian / Ubuntu*) came later, with their own flag (`_internal:portPresetsOsSeeded`): once, into a table already in use they are added unless a preset of that name exists, and an emptied table stays empty. | Column | Type | Notes | |---|---|---| diff --git a/README.md b/README.md index cd9aa32..9c5d0a6 100644 --- a/README.md +++ b/README.md @@ -1101,7 +1101,7 @@ install one-liner on a host to pick that up. **Ports named by their containers.** When a server's Docker host is in Dockhand (the Docker integration), the ports its running containers publish are named after the container — 8096 → *jellyfin* — on the server's Ports card, in the agent table on the Network → Ports page (hover for the image) and in the new-port alert ("a new port is listening — 8096/tcp jellyfin (container)"). It is automatic: nothing to set up beyond the Docker host in Dockhand having the same name as the server (the short name, the hostname or an address — the match Uptime Kuma targets use), and it is only a name beside the port. A label you wrote wins; a container's name wins over a port preset's; it is never written onto the port notes, so a published port is still a new port to be noted, and a container that starts publishing something is still news — now with its name. It is read on the health pass from the container list Dockhand already gives (every 15 minutes, and at start-up, whether or not the container alerts are on); a Docker host Dockhand can't reach keeps its names, and names not refreshed for a day are dropped. Containers on the host network publish nothing Docker lists, so their ports aren't named. -**Port presets** (Network → Ports → the *Presets* tab). A preset is a named list of ports written once — *Remote access* (SSH, RDP, VNC, WinRM), *Databases* (MySQL, PostgreSQL, Redis, MongoDB …), *Web*, *File sharing*, *Homelab tools* come ready-made, and are ordinary presets you can change or delete. Add your own by typing one port to a line (`3389 RDP`, `53/udp DNS`). A preset does three things: it **names ports** — a port in any preset shows its name (3389 → RDP) on every server's Ports card, in the agent table and in the new-port alert ("a new port is listening — 3389/tcp RDP"), without a label typed for each host, and a name you write yourself always wins; it **checks hosts** — pick any number of servers and see in one table which of the preset's TCP ports are open on each, from a scan from the app (private addresses only, at the server's first known address; what it finds is remembered like any scan); and it **names the open ports on all of them** in one go, keeping names somebody already wrote unless you say to replace them. Note that a port with a name counts as noted, so writing names also quiets the new-port alert for those ports. A scan only looks at TCP; a UDP port in a preset is only given its name. Operators change presets; everyone sees them. +**Port presets** (Network → Ports → the *Presets* tab). A preset is a named list of ports written once — *Remote access* (SSH, RDP, VNC, WinRM), *Databases* (MySQL, PostgreSQL, Redis, MongoDB …), *Web*, *File sharing*, *Homelab tools*, and what a machine has open out of the box — *Windows client*, *Windows server* (with the Active Directory ports) and *Debian / Ubuntu* — come ready-made, and are ordinary presets you can change or delete. The operating-system ones are added once to an install that already had presets (a preset of the same name is left alone, a deleted one is not put back). Add your own by typing one port to a line (`3389 RDP`, `53/udp DNS`). A preset does three things: it **names ports** — a port in any preset shows its name (3389 → RDP) on every server's Ports card, in the agent table and in the new-port alert ("a new port is listening — 3389/tcp RDP"), without a label typed for each host, and a name you write yourself always wins; it **checks hosts** — pick any number of servers and see in one table which of the preset's TCP ports are open on each, from a scan from the app (private addresses only, at the server's first known address; what it finds is remembered like any scan); and it **names the open ports on all of them** in one go, keeping names somebody already wrote unless you say to replace them. Note that a port with a name counts as noted, so writing names also quiets the new-port alert for those ports. A scan only looks at TCP; a UDP port in a preset is only given its name. Operators change presets; everyone sees them. **Network → Ports** is the cross-server counterpart: one page listing every port every agent currently reports as listening, across all servers at once diff --git a/server/src/services/portPresets.ts b/server/src/services/portPresets.ts index 294c195..a408022 100644 --- a/server/src/services/portPresets.ts +++ b/server/src/services/portPresets.ts @@ -25,8 +25,12 @@ export interface PortPreset { export const MAX_PRESET_PORTS = 60; const SEEDED_FLAG = "portPresetsSeeded"; +const OS_SEEDED_FLAG = "portPresetsOsSeeded"; const tcp = (port: number, label: string): PresetPort => ({ port, protocol: "tcp", label }); +const udp = (port: number, label: string): PresetPort => ({ port, protocol: "udp", label }); +/** A run of ports with one name: the dynamic RPC ports Windows listens on, 49664–49670. */ +const run = (from: number, to: number, label: string): PresetPort[] => Array.from({ length: to - from + 1 }, (_, i) => tcp(from + i, label)); /** What is there to begin with. */ export const STARTER_PRESETS: { name: string; ports: PresetPort[] }[] = [ @@ -37,6 +41,38 @@ export const STARTER_PRESETS: { name: string; ports: PresetPort[] }[] = [ { 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")] }, ]; +/** + * What a machine has open out of the box, by operating system. These came later than the five above, so they are put there once more (see ensureStarters), into a list that is already in use. + * A port that other presets name too is called the same thing here, so it is never called two names; the ones named only here are what is new. + */ +export const OS_PRESETS: { name: string; ports: PresetPort[] }[] = [ + { + name: "Windows client", + ports: [ + tcp(135, "RPC endpoint mapper"), tcp(139, "NetBIOS"), tcp(445, "SMB"), tcp(2869, "UPnP device host"), tcp(3389, "RDP"), tcp(5040, "Device association (CDPSvc)"), tcp(5357, "Web Services for Devices"), + tcp(5985, "WinRM (HTTP)"), tcp(5986, "WinRM (HTTPS)"), tcp(7680, "Delivery Optimization"), ...run(49664, 49670, "RPC (dynamic)"), + udp(137, "NetBIOS name"), udp(138, "NetBIOS datagram"), udp(1900, "SSDP (UPnP discovery)"), udp(3702, "WS-Discovery"), udp(5353, "mDNS"), udp(5355, "LLMNR"), + ], + }, + { + name: "Windows server", + ports: [ + tcp(53, "DNS"), tcp(80, "HTTP"), tcp(88, "Kerberos"), tcp(135, "RPC endpoint mapper"), tcp(139, "NetBIOS"), tcp(389, "LDAP"), tcp(443, "HTTPS"), tcp(445, "SMB"), tcp(464, "Kerberos password change"), + tcp(593, "RPC over HTTP"), tcp(636, "LDAPS"), tcp(1688, "KMS activation"), tcp(2179, "Hyper-V VM console"), tcp(3268, "Global Catalog"), tcp(3269, "Global Catalog (SSL)"), tcp(3389, "RDP"), + tcp(5722, "DFS Replication"), tcp(5985, "WinRM (HTTP)"), tcp(5986, "WinRM (HTTPS)"), tcp(8530, "WSUS"), tcp(8531, "WSUS (HTTPS)"), tcp(9389, "AD Web Services"), tcp(47001, "WinRM (HTTP.sys)"), + ...run(49664, 49670, "RPC (dynamic)"), + udp(53, "DNS"), udp(67, "DHCP server"), udp(88, "Kerberos"), udp(123, "NTP"), udp(137, "NetBIOS name"), udp(138, "NetBIOS datagram"), udp(389, "LDAP"), udp(464, "Kerberos password change"), udp(5355, "LLMNR"), + ], + }, + { + name: "Debian / Ubuntu", + ports: [ + tcp(22, "SSH"), tcp(25, "SMTP"), tcp(53, "DNS"), tcp(111, "rpcbind"), tcp(631, "CUPS (printing)"), tcp(5355, "LLMNR"), + udp(53, "DNS"), udp(68, "DHCP client"), udp(111, "rpcbind"), udp(123, "NTP"), udp(161, "SNMP"), udp(323, "NTP (chrony)"), udp(5353, "mDNS"), udp(5355, "LLMNR"), udp(41641, "Tailscale"), + ], + }, +]; + function parsePorts(stored: string): PresetPort[] { try { const v = JSON.parse(stored); @@ -51,15 +87,26 @@ function parsePorts(stored: string): PresetPort[] { 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. */ +/** + * Puts the ready-made presets there, once: the first time, and only into an empty list. The operating-system ones are put there once as well, and in a list that is already in use + * only the ones whose name is not taken (whatever its case) — an empty list stays empty, since somebody cleared it — so a preset deleted afterwards is not put back. + */ async function ensureStarters(): Promise { - 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 }); + const first = (await getInternalFlag(SEEDED_FLAG)) === null; + const osDone = (await getInternalFlag(OS_SEEDED_FLAG)) !== null; + if (!first && osDone) return; + const now = new Date().toISOString(); + const add = (p: { name: string; ports: PresetPort[] }) => db.insert(portPresets).values({ name: p.name, ports: JSON.stringify(p.ports), createdAt: now, updatedAt: now }); + const existing = await db.select({ name: portPresets.name }).from(portPresets); + if (first) { + if (existing.length === 0) for (const p of [...STARTER_PRESETS, ...OS_PRESETS]) await add(p); + await setInternalFlag(SEEDED_FLAG, now); + await setInternalFlag(OS_SEEDED_FLAG, now); + return; } - await setInternalFlag(SEEDED_FLAG, new Date().toISOString()); + const taken = new Set(existing.map((e) => e.name.toLowerCase())); + if (existing.length > 0) for (const p of OS_PRESETS) if (!taken.has(p.name.toLowerCase())) await add(p); + await setInternalFlag(OS_SEEDED_FLAG, now); } /** Every preset, by name. */ diff --git a/server/test/portPresets.test.ts b/server/test/portPresets.test.ts index a52f9a1..712d419 100644 --- a/server/test/portPresets.test.ts +++ b/server/test/portPresets.test.ts @@ -150,12 +150,28 @@ describe("the routes", () => { test("the ready-made presets are there the first time, for everyone", async () => { const list = (await json<{ presets: Preset[] }>(await call("viewer", "GET", "/port-presets"))).presets; - assert.deepEqual(list.map((p) => p.name), ["Databases", "File sharing", "Homelab tools", "Remote access", "Web"]); + assert.deepEqual(list.map((p) => p.name), ["Databases", "Debian / Ubuntu", "File sharing", "Homelab tools", "Remote access", "Web", "Windows client", "Windows server"]); const remote = list.find((p) => p.name === "Remote access")!; assert.deepEqual(remote.ports.map((p) => [p.port, p.label]), [[22, "SSH"], [3389, "RDP"], [5900, "VNC"], [5985, "WinRM (HTTP)"], [5986, "WinRM (HTTPS)"]]); assert.ok(list.find((p) => p.name === "Databases")!.ports.some((p) => p.port === 5432 && p.label === "PostgreSQL")); }); + test("the operating-system presets name what a Windows client, a Windows server and a Debian or Ubuntu machine have open, and no port is called two things", async () => { + const list = (await json<{ presets: Preset[] }>(await call("viewer", "GET", "/port-presets"))).presets; + const has = (name: string, protocol: string, port: number, label: string) => list.find((p) => p.name === name)!.ports.some((p) => p.protocol === protocol && p.port === port && p.label === label); + assert.ok(has("Windows client", "tcp", 445, "SMB") && has("Windows client", "tcp", 49664, "RPC (dynamic)") && has("Windows client", "udp", 5353, "mDNS")); + assert.ok(has("Windows server", "tcp", 389, "LDAP") && has("Windows server", "tcp", 9389, "AD Web Services") && has("Windows server", "udp", 67, "DHCP server")); + assert.ok(has("Debian / Ubuntu", "tcp", 22, "SSH") && has("Debian / Ubuntu", "udp", 41641, "Tailscale")); + for (const p of list) assert.ok(p.ports.length <= pp.MAX_PRESET_PORTS, p.name); + // Whichever preset names a port first (by name) is the one heard, so every preset that names the same port must say the same thing. + const said = new Map(); + for (const p of list) for (const e of p.ports) { + const key = `${e.protocol}:${e.port}`; + assert.equal(said.get(key) ?? e.label, e.label, `${key} is called two things (${p.name})`); + said.set(key, e.label); + } + }); + test("an operator writes, changes and removes one; a viewer cannot; the name is unique whatever its case; what is not a preset is refused", async () => { const mine = { name: "Media", ports: [{ port: 8096, protocol: "tcp", label: "Jellyfin" }, { port: 8989, label: "Sonarr" }] }; assert.equal((await call("viewer", "POST", "/port-presets", mine)).status, 403); @@ -322,3 +338,30 @@ describe("the routes", () => { }); }); }); + +describe("the operating-system presets on a list that is already in use", () => { + const names = async () => (await pp.listPresets()).map((p) => p.name).sort(); + + test("they are added once, beside what is there: a preset of the same name is left as it is, a deleted one is not put back, and an emptied list stays empty", async () => { + const { settings } = await import("../src/db/schema.js"); + const forgetOsFlag = () => db.delete(settings).where(eq(settings.key, "_internal:portPresetsOsSeeded")); + // The list as an install from before them has it: five presets (one changed) and a flag for those five only. + await db.delete(portPresets); + const now = new Date().toISOString(); + await db.insert(portPresets).values([ + { name: "Remote access", ports: JSON.stringify([{ port: 22, protocol: "tcp", label: "SSH" }]), createdAt: now, updatedAt: now }, + { name: "windows CLIENT", ports: JSON.stringify([{ port: 1, protocol: "tcp", label: "Mine" }]), createdAt: now, updatedAt: now }, + ]); + await forgetOsFlag(); + assert.deepEqual(await names(), ["Debian / Ubuntu", "Remote access", "Windows server", "windows CLIENT"], "the missing ones came, the one with the same name (any case) did not"); + assert.deepEqual((await pp.listPresets()).find((p) => p.name === "windows CLIENT")!.ports.map((p) => p.label), ["Mine"]); + + for (const p of (await pp.listPresets()).filter((x) => x.name === "Debian / Ubuntu")) await db.delete(portPresets).where(eq(portPresets.id, p.id)); + assert.deepEqual(await names(), ["Remote access", "Windows server", "windows CLIENT"], "deleted, and not put back"); + + await db.delete(portPresets); + await forgetOsFlag(); + assert.deepEqual(await names(), [], "somebody emptied the list, so it stays empty"); + assert.deepEqual(await names(), [], "and the next look is the same"); + }); +});