@takodotid/circuit 0.34.3 → 0.35.0

package/src/helpers/filters.ts

@@ -0,0 +1,107 @@
+import { Address } from "../core/address";
+import type { AclRule, FilterRule, Prefix, TcpFlag } from "../schema";
+
+/** What `Filters.antiAmplification` leaves alone. */
+export type AntiAmplificationOptions = {
+    /** Prefixes inside the destinations whose UDP fragments pass: for a host that receives UDP too large for one packet, such as SIP or some VPNs. Every fragment after the first is dropped when absent. */
+    keep_fragments?: readonly Prefix[];
+};
+
+/** Address lists and edge filters: hardware ACL rules and firewall rules for traffic from outside. */
+export class Filters {
+    /** IPv4 sources that never arrive from the internet: loopback, link-local and "this network", after RFC 6890. */
+    static readonly MARTIANS = ["127.0.0.0/8", "169.254.0.0/16", "0.0.0.0/8"] as const satisfies readonly Prefix[];
+
+    /** IPv4 private space, RFC 1918. */
+    static readonly PRIVATE_RANGES = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] as const satisfies readonly Prefix[];
+
+    /** UDP ports of services that answer a small request with a much larger reply, which attackers use to reflect floods at a victim. A reflected flood arrives from these ports. */
+    static readonly AMPLIFIERS = {
+        qotd: 17,
+        chargen: 19,
+        dns: 53,
+        portmap: 111,
+        ntp: 123,
+        netbios: 137,
+        snmp: 161,
+        cldap: 389,
+        slp: 427,
+        rip: 520,
+        "ms-sql": 1434,
+        ssdp: 1900,
+        ard: 3283,
+        "ws-discovery": 3702,
+        mdns: 5353,
+        coap: 5683,
+        ubiquiti: 10001,
+        memcached: 11211,
+        dvr: 37810,
+    } as const satisfies Record<string, number>;
+
+    /** Of the amplifiers, the services hosts do ask across the internet: resolvers, time servers, monitoring. A reply to a real request goes back to the asking port, 1024 or above, or to the service's own port when two servers talk. */
+    private static readonly ASKED: ReadonlySet<number> = new Set([Filters.AMPLIFIERS.dns, Filters.AMPLIFIERS.ntp, Filters.AMPLIFIERS.snmp]);
+
+    /** TCP flag combinations no legitimate packet carries: name, flags set, flags unset. */
+    private static readonly BAD_TCP_FLAGS = [
+        ["FIN+SYN", ["fin", "syn"], []],
+        ["SYN+RST", ["syn", "rst"], []],
+        ["FIN+RST", ["fin", "rst"], []],
+        ["FIN without ACK", ["fin"], ["ack"]],
+        ["FIN+URG", ["fin", "urg"], []],
+        ["Xmas scan", ["fin", "syn", "psh", "urg"], []],
+    ] as const satisfies readonly (readonly [string, readonly TcpFlag[], readonly TcpFlag[]])[];
+
+    /** Hardware ACL rules dropping traffic arriving on a VLAN from sources that cannot be there: your own space, martians, private ranges. One rule per source. */
+    static antiSpoofing<V extends string>(vlan: V, sources: readonly Prefix[]): AclRule<V>[] {
+        return sources.map((src) => ({
+            description: `${vlan}: drop source ${src}`,
+            match: { vlan, src },
+            action: "drop",
+        }));
+    }
+
+    /**
+     * Hardware ACL rules dropping reflected UDP floods toward `destinations`, in the switch chip, without limiting anything else.
+     *
+     * - Replies from an amplifier no host asks across the internet are dropped.
+     * - Replies from DNS, NTP and SNMP are dropped only toward a port below 1024 that is not the service's own. A host that runs its own resolver, time server or monitoring keeps its answers. The service's own port passes first, so every drop takes the one range 0 to 1023: a switch chip has few port-range checkers, and on RouterOS a rule past them is invalid with every rule after it.
+     * - The fragments after the first carry no port, and a switch chip reads them as port 0. They are dropped, but toward `keep_fragments`.
+     */
+    static antiAmplification(destinations: readonly Prefix[], options: AntiAmplificationOptions = {}): AclRule<never>[] {
+        return destinations.flatMap((dst) => [
+            ...(options.keep_fragments ?? [])
+                .filter((prefix) => Address.contains(dst, prefix))
+                .map((prefix): AclRule<never> => ({
+                    description: `UDP fragments to ${prefix} kept`,
+                    match: { protocol: "udp", dst: prefix, src_port: 0 },
+                    action: "accept",
+                })),
+            { description: `UDP fragments to ${dst}`, match: { protocol: "udp", dst, src_port: 0 }, action: "drop" },
+            ...Object.entries(Filters.AMPLIFIERS).flatMap(([name, port]): AclRule<never>[] =>
+                Filters.ASKED.has(port)
+                    ? [
+                          {
+                              description: `UDP to ${dst} from ${name}, between two servers`,
+                              match: { protocol: "udp", dst, src_port: port, dst_port: port },
+                              action: "accept",
+                          },
+                          {
+                              description: `UDP to ${dst} from ${name}, to a port below 1024`,
+                              match: { protocol: "udp", dst, src_port: port, dst_port: { min: 0, max: 1023 } },
+                              action: "drop",
+                          },
+                      ]
+                    : [{ description: `UDP to ${dst} from ${name}`, match: { protocol: "udp", dst, src_port: port }, action: "drop" }]
+            ),
+        ]);
+    }
+
+    /** Firewall rules dropping packets with a TCP flag combination no legitimate packet carries, for a forward chain. */
+    static badTcpFlags(): FilterRule<never, never>[] {
+        return Filters.BAD_TCP_FLAGS.map(([name, set, unset]) => ({
+            description: `Bad flags ${name}`,
+            match: { protocol: "tcp", tcp_flags: { set, unset } },
+            action: "drop",
+        }));
+    }
+}

package/src/helpers/index.ts

@@ -0,0 +1,12 @@
+// Building blocks most networks write the same way: address lists, edge filters, a BGP import sanity policy, an exchange's member ports and route servers, checks, and helpers for checks of your own. Each returns plain config to place where it belongs, so nothing here applies itself.
+
+export { Bgp } from "./bgp";
+export type { CommunityScheme, SanityLengths } from "./bgp";
+export { Checks } from "./checks";
+export type { TrustBoundary } from "./checks";
+export { Exchange } from "./exchange";
+export type { ExchangeMember, InternetExchange } from "./exchange";
+export { Filters } from "./filters";
+export { RouteServerConfig } from "./route-server";
+export type { RouteServer } from "./route-server";
+export type { AntiAmplificationOptions } from "./filters";

package/src/helpers/route-server.ts

@@ -0,0 +1,212 @@
+import { Address } from "../core/address";
+import type { Family, IPv4, IPv6, Prefix } from "../schema";
+import type { ExchangeMember } from "./exchange";
+
+/** A route server on an exchange's peering LAN: a server running BIRD 2 or OpenBGPD that passes every member's routes to every other member. */
+export type RouteServer = {
+    /** Its name, such as `rs1`, written at the top of its config. */
+    name: string;
+    /** Its own AS. Members peer with it, but it never adds itself to a path, so members see each other's paths as they were sent. */
+    asn: number;
+    /** Its BGP router ID, an IPv4 address of the server. Its address on the peering LAN is the usual pick. */
+    router_id: IPv4;
+    /** Its IPv4 address on the peering LAN. Every member with an IPv4 address gets an IPv4 session from it. */
+    ipv4?: IPv4;
+    /** Its IPv6 address on the peering LAN. Every member with an IPv6 address gets an IPv6 session from it. */
+    ipv6?: IPv6;
+};
+
+/** A route server's config, written from an exchange's member list. Circuit writes the file; it never logs in to the server. */
+export class RouteServerConfig {
+    /** The shortest and longest prefix a member may send, by family. */
+    static readonly LENGTHS: Readonly<Record<Family, { shortest: number; longest: number }>> = {
+        ipv4: { shortest: 8, longest: 24 },
+        ipv6: { shortest: 12, longest: 48 },
+    };
+
+    /** The rules a route must pass, the same in every config. */
+    private static readonly RULES = [
+        "# 1. the first AS in its path is the member's own,",
+        "# 2. its next hop is the member's own address on the peering LAN,",
+        "# 3. it is not inside the peering LAN,",
+        `# 4. it is /${RouteServerConfig.LENGTHS.ipv4.shortest} to /${RouteServerConfig.LENGTHS.ipv4.longest} long for IPv4, /${RouteServerConfig.LENGTHS.ipv6.shortest} to /${RouteServerConfig.LENGTHS.ipv6.longest} for IPv6.`,
+    ];
+
+    /**
+     * The BIRD 2 config of one route server: one session per member and family, each passing on only the routes the member may send.
+     *
+     * Throws when the server has no address on the peering LAN, has one outside it, or two members would get sessions of one name.
+     */
+    static bird(server: RouteServer, lan: { ipv4?: Prefix; ipv6?: Prefix }, members: readonly ExchangeMember[]): string {
+        const families = RouteServerConfig.families(server, lan);
+        const sessions: string[] = [];
+        const names = new Map<string, string>();
+
+        for (const member of members) {
+            for (const family of families) {
+                const neighbor = member[family];
+                if (!neighbor) continue;
+
+                const name = RouteServerConfig.protocolName(member.name, family);
+                const holder = names.get(name);
+                if (holder) throw new Error(`members ${holder} and ${member.name} would both have session ${name}`);
+                names.set(name, member.name);
+
+                sessions.push(RouteServerConfig.birdSession(name, server, member, family, neighbor, lan[family]!));
+            }
+        }
+
+        const header = [
+            `# ${server.name}, a route server of the exchange, for BIRD 2.`,
+            "# Circuit wrote it from the member list: change the list, not this file.",
+            "",
+            `router id ${server.router_id};`,
+            "",
+            "# Learns the server's interfaces and addresses. It sends no route anywhere.",
+            "protocol device {",
+            "}",
+            "",
+            "# One session per member and family. A route a member sends is kept only when:",
+            ...RouteServerConfig.RULES,
+            "# Every member gets every route the others sent, as they sent it.",
+            "# A route that is not kept stays visible: birdc show route filtered.",
+        ];
+
+        return [...header, ...sessions.flatMap((session) => ["", session])].join("\n") + "\n";
+    }
+
+    /**
+     * The OpenBGPD config (`bgpd.conf`) of one route server: one session per member and family, in one group per family, and filter rules that pass on only the routes each member may send.
+     *
+     * Throws when the server has no address on the peering LAN, or has one outside it.
+     */
+    static openbgpd(server: RouteServer, lan: { ipv4?: Prefix; ipv6?: Prefix }, members: readonly ExchangeMember[]): string {
+        const families = RouteServerConfig.families(server, lan).filter((family) => members.some((member) => member[family]));
+
+        const lines = [
+            `# ${server.name}, a route server of the exchange, for OpenBGPD.`,
+            "# Circuit wrote it from the member list: change the list, not this file.",
+            "",
+            `AS ${server.asn}`,
+            `router-id ${server.router_id}`,
+            "",
+            "# The server passes routes on and carries no traffic, so it keeps them out of its own routing table.",
+            "fib-update no",
+            "",
+            "# Members see each other's paths as they were sent: the server never adds its own AS, and passes MED and communities on untouched.",
+            "transparent-as yes",
+            "",
+            "# A route that is not kept stays visible: bgpctl show rib filtered.",
+            "rde rib Loc-RIB include filtered",
+        ];
+
+        for (const family of families) {
+            lines.push("", ...RouteServerConfig.openbgpdGroup(server, family, members));
+        }
+
+        lines.push("", "# A route a member sends is kept only when:", ...RouteServerConfig.RULES);
+        lines.push("# The last rule a route matches decides, and a route no rule allows is dropped.");
+
+        for (const family of families) {
+            const { shortest, longest } = RouteServerConfig.LENGTHS[family];
+            const any = family === "ipv4" ? "0.0.0.0/0" : "::/0";
+
+            // `prefixlen 8-24` without spaces is a syntax error in bgpd 9.1, though its manual shows it.
+            lines.push(
+                `allow from group "${family} members" peer-as neighbor-as nexthop neighbor prefix ${any} prefixlen ${shortest} - ${longest}`
+            );
+        }
+
+        for (const family of families) {
+            lines.push(`deny from any prefix ${Address.prefixOf(lan[family]!)} or-longer`);
+        }
+
+        lines.push("", "# Every member gets every route the others sent, as they sent it.", "allow to any");
+
+        return lines.join("\n") + "\n";
+    }
+
+    /** The families the server has an address in, each checked to be inside the peering LAN. */
+    private static families(server: RouteServer, lan: { ipv4?: Prefix; ipv6?: Prefix }): Family[] {
+        const families = (["ipv4", "ipv6"] as const).filter((family) => server[family]);
+        if (!families.length) throw new Error(`route server ${server.name} has no address on the peering LAN`);
+
+        for (const family of families) {
+            const prefix = lan[family];
+            const address = server[family]!;
+            if (!prefix || !Address.contains(prefix, address))
+                throw new Error(`${address} of route server ${server.name} is outside the peering LAN`);
+        }
+
+        return families;
+    }
+
+    /** A BIRD symbol: letters, digits and underscores, starting with a letter. */
+    private static protocolName(member: string, family: Family): string {
+        const name = `${member.toLowerCase().replace(/[^a-z0-9_]/g, "_")}_${family}`;
+        return /^[a-z]/.test(name) ? name : `m_${name}`;
+    }
+
+    /** A member's name and AS, safe inside double quotes. */
+    private static description(member: ExchangeMember): string {
+        return `"${member.name.replace(/["\\]/g, "")}, AS${member.asn}"`;
+    }
+
+    private static birdSession(
+        name: string,
+        server: RouteServer,
+        member: ExchangeMember,
+        family: Family,
+        neighbor: string,
+        lan: Prefix
+    ): string {
+        const { shortest, longest } = RouteServerConfig.LENGTHS[family];
+
+        return [
+            `protocol bgp ${name} {`,
+            `    description ${RouteServerConfig.description(member)};`,
+            `    local ${server[family]} as ${server.asn};`,
+            `    neighbor ${neighbor} as ${member.asn};`,
+            "    rs client;",
+            `    ${family} {`,
+            "        import keep filtered on;",
+            "        import filter {",
+            `            if bgp_path.first != ${member.asn} then reject;`,
+            `            if bgp_next_hop != ${neighbor} then reject;`,
+            `            if net ~ [ ${Address.prefixOf(lan)}+ ] then reject;`,
+            `            if net.len < ${shortest} || net.len > ${longest} then reject;`,
+            "            accept;",
+            "        };",
+            "        export all;",
+            "    };",
+            "}",
+        ].join("\n");
+    }
+
+    /** One family's sessions: a group holding every member with an address in that family. */
+    private static openbgpdGroup(server: RouteServer, family: Family, members: readonly ExchangeMember[]): string[] {
+        const lines = [
+            `# One session per member with an ${family === "ipv4" ? "IPv4" : "IPv6"} address.`,
+            `group "${family} members" {`,
+            `    local-address ${server[family]}`,
+            "    # A route whose first AS is not the member's own is dropped by the rules below. The default would close the whole session.",
+            "    enforce neighbor-as no",
+        ];
+
+        for (const member of members) {
+            const neighbor = member[family];
+            if (!neighbor) continue;
+
+            lines.push(
+                `    neighbor ${neighbor} {`,
+                `        remote-as ${member.asn}`,
+                `        descr ${RouteServerConfig.description(member)}`,
+                "    }"
+            );
+        }
+
+        lines.push("}");
+
+        return lines;
+    }
+}

package/src/index.ts

@@ -1,7 +1,10 @@
 export { defineDevice, defineNetwork, secret, secretFile } from "./core/define";
-export { merge } from "./core/merge";
-export type { Check, Community, Finding, Network } from "./core/define";
+export { Utils } from "./core/utils";
+export type { Check, Community, Finding, NetBoxDevice, Network } from "./core/define";
 export type * from "./schema";
 
 /** Address helpers, for checks of your own. */
-export { contains, familyOf, host, isAddress, isCidr, isGlobal, network as prefixOf } from "./core/addr";
+export { Address } from "./core/address";
+
+/** Secrets, for tools of your own: a secret's value, text with every secret hidden, and how Circuit logs in to a device. */
+export { Secrets } from "./core/secrets";

package/src/integrations/librenms.ts

@@ -0,0 +1,291 @@
+// Keeps LibreNMS in step with the config: every device Circuit manages is monitored there, under its name, polled with the SNMP credentials its config gives it, at the location it reports, and in a group for its site. A device LibreNMS holds that the config does not is reported, never deleted, and so is a group.
+//
+// Written against LibreNMS's API v0 as LibreNMS 26.10 serves it: a device's name is its `display_template`, which LibreNMS 26.5 and later take.
+
+import type { Network } from "../core/define";
+import { Secrets } from "../core/secrets";
+import type { Device } from "../schema";
+
+/** A device as LibreNMS lists it, with the fields Circuit compares. */
+type Monitored = {
+    device_id: number | string;
+    hostname: string;
+    display?: string | null;
+    location?: string | null;
+    [field: string]: unknown;
+};
+
+/** A device LibreNMS monitors whose settings differ from its config. */
+export type LibreNmsChange = {
+    device: Device;
+    /** LibreNMS's id for it. */
+    id: number;
+    /** What differs, in words: `name`, `SNMP credentials` or `location`. Never a secret's value. */
+    what: string[];
+    /** What is sent: LibreNMS's field names and their values. */
+    fields: Record<string, string>;
+};
+
+/** A device group for one site, to make or whose devices change. */
+export type LibreNmsGroup = {
+    /** The site's name, which is the group's. */
+    name: string;
+    /** LibreNMS has no group of this name yet. */
+    create: boolean;
+    /** Devices at the site that are not in the group. */
+    add: Device[];
+    /** Devices in the group that the config puts at another site. */
+    remove: Device[];
+};
+
+/** What `librenms` would do. */
+export type LibreNmsPlan = {
+    /** Devices to add. */
+    additions: Device[];
+    /** Devices to change. */
+    changes: LibreNmsChange[];
+    /** Site groups to make or change. Empty when the network has no `site`. */
+    groups: LibreNmsGroup[];
+    /** Devices that cannot be added: their config turns SNMP off. */
+    withoutSnmp: Device[];
+    /** Hostnames LibreNMS holds that no device in the config has. */
+    unknown: string[];
+    /** Site groups LibreNMS holds as dynamic groups, which Circuit cannot fill, so leaves alone. */
+    dynamicGroups: string[];
+    /** LibreNMS's id for each device it monitors, by hostname. */
+    ids: ReadonlyMap<string, number>;
+};
+
+export class LibreNms {
+    /** LibreNMS's names for the algorithms. */
+    private static readonly AUTH = { sha1: "SHA", sha256: "SHA-256" } as const;
+    private static readonly PRIVACY = { aes128: "AES", des: "DES" } as const;
+
+    /** Compare the config with what LibreNMS monitors. A device is known to LibreNMS by its management address. */
+    static async plan(network: Network): Promise<LibreNmsPlan> {
+        const settings = LibreNms.settingsOf(network);
+
+        const listed = await LibreNms.call<{ devices: Monitored[] }>(settings, "GET", "devices?type=all");
+        const monitored = new Map(listed.devices.map((device) => [device.hostname, device]));
+        const ids = new Map(listed.devices.map((device) => [device.hostname, Number(device.device_id)]));
+
+        // A device reached only through its console has no address to poll.
+        const polled = network.devices.filter((device) => device.connection.host);
+        const ours = new Set<string | undefined>(polled.map((device) => device.connection.host));
+        const missing = polled.filter((device) => !monitored.has(device.connection.host!));
+        const additions = missing.filter((device) => device.management?.snmp);
+
+        const changes = polled.flatMap((device) => {
+            const current = monitored.get(device.connection.host!);
+            return current ? LibreNms.changeOf(device, current) : [];
+        });
+
+        const atSites = polled.filter((device) => monitored.has(device.connection.host!) || additions.includes(device));
+        const { groups, dynamicGroups } = await LibreNms.groupsOf(network, settings, atSites, ids);
+
+        return {
+            additions,
+            changes,
+            groups,
+            withoutSnmp: missing.filter((device) => !device.management?.snmp),
+            unknown: [...monitored.keys()].filter((hostname) => !ours.has(hostname)).sort(),
+            dynamicGroups,
+            ids,
+        };
+    }
+
+    /** How many changes a plan holds. */
+    static count(plan: LibreNmsPlan): number {
+        return plan.additions.length + plan.changes.length + plan.groups.length;
+    }
+
+    /** Add each device, change each that differs, then make and fill the site groups. */
+    static async send(network: Network, plan: LibreNmsPlan): Promise<void> {
+        const settings = LibreNms.settingsOf(network);
+        const ids = new Map(plan.ids);
+
+        for (const device of plan.additions) {
+            const location = device.management?.snmp?.location;
+            const body = {
+                hostname: device.connection.host,
+                display_template: device.name,
+                ...LibreNms.credentials(device),
+                ...(location ? { location } : {}),
+            };
+            const answer = await LibreNms.call<{ message?: string; devices?: Monitored[] }>(settings, "POST", "devices", body);
+
+            const added = answer.devices?.[0];
+            if (added) ids.set(device.connection.host!, Number(added.device_id));
+
+            console.log(`  ${device.name}: ${answer.message}`);
+        }
+
+        for (const change of plan.changes) {
+            const fields = Object.keys(change.fields);
+            await LibreNms.call(settings, "PATCH", `devices/${change.id}`, {
+                field: fields,
+                data: fields.map((field) => change.fields[field]),
+            });
+
+            console.log(`  ${change.device.name}: changed its ${change.what.join(", ")}`);
+        }
+
+        // A device LibreNMS did not give an id for is left for the next run.
+        const idsOf = (devices: readonly Device[]) => devices.flatMap((device) => ids.get(device.connection.host!) ?? []);
+
+        for (const group of plan.groups) {
+            const path = `devicegroups/${encodeURIComponent(group.name)}`;
+
+            if (group.create) {
+                await LibreNms.call(settings, "POST", "devicegroups", {
+                    name: group.name,
+                    desc: `The devices at ${group.name}, kept by Circuit`,
+                    type: "static",
+                    devices: idsOf(group.add),
+                });
+                console.log(`  made the group ${group.name}`);
+                continue;
+            }
+
+            if (group.add.length) await LibreNms.call(settings, "POST", `${path}/devices`, { devices: idsOf(group.add) });
+            if (group.remove.length) await LibreNms.call(settings, "DELETE", `${path}/devices`, { devices: idsOf(group.remove) });
+
+            console.log(`  changed the group ${group.name}`);
+        }
+    }
+
+    /** What differs between a device's config and LibreNMS's record of it: its name, SNMP credentials and location. */
+    private static changeOf(device: Device, current: Monitored): LibreNmsChange[] {
+        const what: string[] = [];
+        let fields: Record<string, string> = {};
+
+        if (current.display !== device.name) {
+            what.push("name");
+            fields.display_template = device.name;
+        }
+
+        const credentials = LibreNms.credentials(device);
+        if (credentials && Object.entries(credentials).some(([field, value]) => String(current[field] ?? "") !== value)) {
+            what.push("SNMP credentials");
+            fields = { ...fields, ...credentials };
+        }
+
+        // LibreNMS reads the location from the device too; setting it now shows it before the next poll.
+        const location = device.management?.snmp?.location;
+        if (location && current.location !== location) {
+            what.push("location");
+            fields.location = location;
+        }
+
+        return what.length ? [{ device, id: Number(current.device_id), what, fields }] : [];
+    }
+
+    /** A static group for each site, with the devices at it. Only groups named after a site are read or changed. */
+    private static async groupsOf(
+        network: Network,
+        settings: LibreNmsSettings,
+        devices: readonly Device[],
+        ids: ReadonlyMap<string, number>
+    ): Promise<{ groups: LibreNmsGroup[]; dynamicGroups: string[] }> {
+        const siteOf = network.site;
+        if (!siteOf) return { groups: [], dynamicGroups: [] };
+
+        const existing =
+            (await LibreNms.call<{ groups?: { name: string; type: string }[] }>(settings, "GET", "devicegroups", undefined, true)).groups ??
+            [];
+        const sites = [...new Set(devices.map(siteOf))].sort();
+
+        const groups: LibreNmsGroup[] = [];
+        const dynamicGroups: string[] = [];
+
+        for (const site of sites) {
+            const atSite = devices.filter((device) => siteOf(device) === site);
+            const found = existing.find((group) => group.name === site);
+
+            if (!found) {
+                groups.push({ name: site, create: true, add: atSite, remove: [] });
+                continue;
+            }
+
+            if (found.type !== "static") {
+                dynamicGroups.push(site);
+                continue;
+            }
+
+            const listed = await LibreNms.call<{ devices?: { device_id: number | string }[] }>(
+                settings,
+                "GET",
+                `devicegroups/${encodeURIComponent(site)}`,
+                undefined,
+                true
+            );
+            const members = new Set((listed.devices ?? []).map((member) => Number(member.device_id)));
+            const isMember = (device: Device) => members.has(ids.get(device.connection.host!) ?? -1);
+
+            const add = atSite.filter((device) => !isMember(device));
+            const remove = devices.filter((device) => siteOf(device) !== site && isMember(device));
+            if (add.length || remove.length) groups.push({ name: site, create: false, add, remove });
+        }
+
+        return { groups, dynamicGroups };
+    }
+
+    private static settingsOf(network: Network): LibreNmsSettings {
+        if (!network.librenms) throw new Error("the network has no librenms settings");
+
+        return {
+            base: `${network.librenms.url.replace(/\/+$/, "")}/api/v0`,
+            // The header every version of API v0 accepts.
+            headers: { "X-Auth-Token": Secrets.reveal(network.librenms.api_token), "Content-Type": "application/json" },
+        };
+    }
+
+    /** One request. LibreNMS answers a list with nothing in it with 404, so `emptyOn404` reads that as an empty answer. */
+    private static async call<T>(
+        settings: LibreNmsSettings,
+        method: "GET" | "POST" | "PATCH" | "DELETE",
+        path: string,
+        body?: unknown,
+        emptyOn404 = false
+    ): Promise<T> {
+        const response = await fetch(`${settings.base}/${path}`, {
+            method,
+            headers: settings.headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(60_000),
+        });
+
+        if (response.status === 404 && emptyOn404) return {} as T;
+
+        const answer = (await response.json().catch(() => ({}))) as T & { status?: string; message?: string };
+        if (!response.ok || answer.status === "error") {
+            throw new Error(`LibreNMS refused ${method} ${path}: ${answer.message ?? response.status}`);
+        }
+
+        return answer;
+    }
+
+    /** How LibreNMS polls a device: its first SNMP version 3 user, or else its version 2c community. */
+    private static credentials(device: Device): Record<string, string> | undefined {
+        const snmp = device.management?.snmp;
+        const [name, user] = Object.entries(snmp?.users ?? {})[0] ?? [];
+
+        if (name && user) {
+            return {
+                snmpver: "v3",
+                authlevel: "authPriv",
+                authname: name,
+                authpass: Secrets.reveal(user.auth_password),
+                authalgo: LibreNms.AUTH[user.auth],
+                cryptopass: Secrets.reveal(user.privacy_password),
+                cryptoalgo: LibreNms.PRIVACY[user.privacy],
+            };
+        }
+
+        if (snmp?.community) return { snmpver: "v2c", community: Secrets.reveal(snmp.community) };
+        return undefined;
+    }
+}
+
+/** Where LibreNMS's API is, and the headers every request sends. */
+type LibreNmsSettings = { base: string; headers: Record<string, string> };