@takodotid/circuit 0.34.2 → 0.35.0

package/src/adapters/registries/index.ts

@@ -1,19 +0,0 @@
-// Registries the framework reads prefix sets from. PeeringDB, which it publishes to, is in ./peeringdb.ts.
-
-import type { Family } from "../../schema";
-import type { Registry } from "../../schema/policy";
-
-/** Prefixes an origin AS announces, from RIPEstat. */
-async function ripeStat(query: string, family: Family): Promise<string[]> {
-    if (!/^AS\d+$/i.test(query)) throw new Error(`ripe-stat takes an AS number, got '${query}'`);
-    const res = await fetch(`https://stat.ripe.net/data/announced-prefixes/data.json?resource=${query.toUpperCase()}`, {
-        signal: AbortSignal.timeout(90_000),
-    });
-    if (!res.ok) throw new Error(`ripe-stat answered ${res.status}`);
-    const data = (await res.json()) as { data: { prefixes: { prefix: string }[] } };
-    return [
-        ...new Set(data.data.prefixes.map((entry) => entry.prefix).filter((entry) => entry.includes(":") === (family === "ipv6"))),
-    ].sort();
-}
-
-export const registries: Record<Registry, (query: string, family: Family) => Promise<string[]>> = { "ripe-stat": ripeStat };

package/src/adapters/registries/librenms.ts

@@ -1,92 +0,0 @@
-// Keeps LibreNMS in step with the config: every device Circuit manages is monitored there, polled with the SNMP credentials its config gives it. A device LibreNMS holds that the config does not is reported, never deleted.
-
-import type { Network } from "../../core/define";
-import { resolve } from "../../core/secrets";
-import type { Device } from "../../schema";
-
-/** What `librenms` would do. */
-export type LibreNmsPlan = {
-    /** Devices to add. */
-    additions: Device[];
-    /** Devices that cannot be added: their config turns SNMP off. */
-    withoutSnmp: Device[];
-    /** Hostnames LibreNMS holds that no device in the config has. */
-    unknown: string[];
-};
-
-/** LibreNMS's names for the algorithms. */
-const AUTH = { sha1: "SHA", sha256: "SHA-256" } as const;
-const PRIVACY = { aes128: "AES", des: "DES" } as const;
-
-function settingsOf(network: Network) {
-    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": resolve(network.librenms.api_token), "Content-Type": "application/json" },
-    };
-}
-
-/** How LibreNMS polls a device: its first SNMP version 3 user, or else its version 2c community. */
-function 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: resolve(user.auth_password),
-            authalgo: AUTH[user.auth],
-            cryptopass: resolve(user.privacy_password),
-            cryptoalgo: PRIVACY[user.privacy],
-        };
-    }
-
-    if (snmp?.community) return { snmpver: "v2c", community: resolve(snmp.community) };
-    return undefined;
-}
-
-/** Compare the config with what LibreNMS monitors. A device is known to LibreNMS by its management address. */
-export async function planLibreNms(network: Network): Promise<LibreNmsPlan> {
-    const { base, headers } = settingsOf(network);
-
-    const response = await fetch(`${base}/devices?type=all`, { headers, signal: AbortSignal.timeout(30_000) });
-    if (!response.ok) throw new Error(`LibreNMS answered ${response.status} to the device list`);
-
-    const monitored = new Set(((await response.json()) as { devices: { hostname: string }[] }).devices.map((device) => device.hostname));
-    // 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(polled.map((device) => device.connection.host));
-    const missing = polled.filter((device) => !monitored.has(device.connection.host!));
-
-    return {
-        additions: missing.filter((device) => device.management?.snmp),
-        withoutSnmp: missing.filter((device) => !device.management?.snmp),
-        unknown: [...monitored].filter((hostname) => !ours.has(hostname)).sort(),
-    };
-}
-
-/** Add each device, named after its `name` and polled with the credentials from its config. */
-export async function sendLibreNms(network: Network, additions: readonly Device[]): Promise<void> {
-    const { base, headers } = settingsOf(network);
-
-    for (const device of additions) {
-        const body = { hostname: device.connection.host, display_template: device.name, ...credentials(device) };
-        const response = await fetch(`${base}/devices`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify(body),
-            signal: AbortSignal.timeout(60_000),
-        });
-        const answer = (await response.json().catch(() => ({}))) as { status?: string; message?: string };
-
-        if (!response.ok || answer.status !== "ok") {
-            throw new Error(`${device.name}: LibreNMS refused it: ${answer.message ?? response.status}`);
-        }
-
-        console.log(`  ${device.name}: ${answer.message}`);
-    }
-}

package/src/adapters/registries/peeringdb.ts

@@ -1,169 +0,0 @@
-// Keeps a network's exchange presence at PeeringDB in step with the config. Each interface with an `exchange` naming a `peeringdb_ixlan` is one record.
-//
-// Only globally reachable addresses are published: an exchange reached over a tunnel often lands on private or shared space, and publishing it would point others at a dead end. A record the config does not hold is reported, never deleted, and `operational` is never changed, since leaving an exchange is a decision made outside the config.
-
-import { contains, familyOf, host, isGlobal } from "../../core/addr";
-import type { Network } from "../../core/define";
-import { resolve } from "../../core/secrets";
-import type { Device, Interface } from "../../schema";
-
-const API = "https://www.peeringdb.com/api";
-
-/** A network's presence at one exchange LAN, as PeeringDB holds it. */
-type NetIxLan = {
-    id: number;
-    net_id: number;
-    ixlan_id: number;
-    name: string;
-    speed: number;
-    ipaddr4: string | null;
-    ipaddr6: string | null;
-    is_rs_peer: boolean;
-    operational: boolean;
-};
-
-/** One record as the config describes it. */
-type Wanted = {
-    name: string;
-    ixlan_id: number;
-    speed: number;
-    ipaddr4: string | null;
-    ipaddr6: string | null;
-    is_rs_peer: boolean;
-};
-
-/** A change to send. `id` is set when the record exists and is updated in place. */
-export type PeeringDbChange = {
-    summary: string;
-    id?: number;
-    body: Record<string, unknown>;
-};
-
-export type PeeringDbPlan = {
-    changes: PeeringDbChange[];
-    /** Records PeeringDB holds that the config does not. */
-    unknown: string[];
-};
-
-type AnyInterface = Interface<string, string>;
-
-const addressesOf = (iface: AnyInterface) => (iface.addresses ?? []).map((entry) => (typeof entry === "string" ? entry : entry.address));
-
-/** Whether the device peers with a route server on this interface's subnets. */
-function peersWithRouteServer(device: Device, iface: AnyInterface): boolean {
-    const bgp = device.routing?.bgp;
-    const subnets = addressesOf(iface);
-
-    return Object.values(bgp?.neighbors ?? {}).some((neighbor) => {
-        const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-        const role = neighbor.role ?? group?.role;
-        return role === "rs" && subnets.some((subnet) => contains(subnet, neighbor.address));
-    });
-}
-
-/** Every exchange presence the config declares with a PeeringDB exchange LAN. */
-function wanted(network: Network): Wanted[] {
-    const records: Wanted[] = [];
-
-    for (const device of network.devices) {
-        for (const iface of Object.values(device.interfaces ?? {})) {
-            const exchange = iface.exchange;
-            if (!exchange?.peeringdb_ixlan) continue;
-
-            const published = addressesOf(iface).map(host).filter(isGlobal);
-
-            records.push({
-                name: exchange.name,
-                ixlan_id: exchange.peeringdb_ixlan,
-                speed: exchange.speed,
-                ipaddr4: published.find((address) => familyOf(address) === "ipv4") ?? null,
-                ipaddr6: published.find((address) => familyOf(address) === "ipv6") ?? null,
-                is_rs_peer: peersWithRouteServer(device, iface),
-            });
-        }
-    }
-
-    return records;
-}
-
-/** What would change at PeeringDB. Reads the public API; needs no key. */
-export async function planPeeringDb(network: Network): Promise<PeeringDbPlan> {
-    if (!network.asn) throw new Error("the network declares no asn");
-
-    const response = await fetch(`${API}/netixlan?asn=${network.asn}`, {
-        headers: { Accept: "application/json" },
-        signal: AbortSignal.timeout(30_000),
-    });
-    if (!response.ok) throw new Error(`PeeringDB answered ${response.status}`);
-
-    const existing = ((await response.json()) as { data: NetIxLan[] }).data;
-    const desired = wanted(network);
-
-    // The record that owns every presence. Taken from an existing one, since the API has no other lookup by ASN here.
-    const netId = existing[0]?.net_id;
-    const changes: PeeringDbChange[] = [];
-
-    for (const record of desired) {
-        const current = existing.find((candidate) => candidate.ixlan_id === record.ixlan_id);
-
-        const body = {
-            net_id: netId,
-            ixlan_id: record.ixlan_id,
-            asn: network.asn,
-            speed: record.speed,
-            ipaddr4: record.ipaddr4,
-            ipaddr6: record.ipaddr6,
-            is_rs_peer: record.is_rs_peer,
-            operational: current?.operational ?? true,
-        };
-
-        if (!current) {
-            changes.push({ summary: `+ ${record.name}: ${record.ipaddr4}, ${record.ipaddr6}, ${record.speed} Mbit/s`, body });
-            continue;
-        }
-
-        const differs =
-            current.ipaddr4 !== record.ipaddr4 ||
-            current.ipaddr6 !== record.ipaddr6 ||
-            current.speed !== record.speed ||
-            current.is_rs_peer !== record.is_rs_peer;
-
-        if (differs) {
-            const before = `${current.ipaddr4}, ${current.ipaddr6}, ${current.speed} Mbit/s, route server ${current.is_rs_peer}`;
-            const after = `${record.ipaddr4}, ${record.ipaddr6}, ${record.speed} Mbit/s, route server ${record.is_rs_peer}`;
-            changes.push({ summary: `~ ${record.name}: ${before} to ${after}`, id: current.id, body });
-        }
-    }
-
-    const unknown = existing
-        .filter((record) => !desired.some((candidate) => candidate.ixlan_id === record.ixlan_id))
-        .map((record) => record.name);
-
-    if (changes.some((change) => !change.id) && !netId) {
-        throw new Error("PeeringDB holds no presence for this network yet, so its record id is unknown; add the first one by hand");
-    }
-
-    return { changes, unknown };
-}
-
-/** Send the changes, with the network's API key. */
-export async function sendPeeringDb(network: Network, changes: PeeringDbChange[]): Promise<void> {
-    if (!network.peeringdb) throw new Error("the network declares no peeringdb api_key");
-    const apiKey = resolve(network.peeringdb.api_key);
-
-    for (const change of changes) {
-        const response = await fetch(`${API}/netixlan${change.id ? `/${change.id}` : ""}`, {
-            method: change.id ? "PUT" : "POST",
-            headers: { Authorization: `Api-Key ${apiKey}`, "Content-Type": "application/json" },
-            body: JSON.stringify(change.body),
-            signal: AbortSignal.timeout(30_000),
-        });
-
-        if (!response.ok) {
-            const reason = (await response.text()).slice(0, 300);
-            throw new Error(`${change.summary}: PeeringDB answered ${response.status} ${reason}`);
-        }
-
-        console.log(`  sent ${change.summary}`);
-    }
-}

package/src/adapters/registries/prometheus.ts

@@ -1,71 +0,0 @@
-// Prometheus targets for snmp_exporter, in its file-based discovery format, and the `auths` section of its config: one auth per device, named after it, so each device is asked with its own credentials.
-//
-// The auths hold no secret. A password is written as `${NAME}`, the name of its secret, and snmp_exporter reads it from its environment when started with `--config.expand-environment-variables`.
-
-import type { Network } from "../../core/define";
-import type { Device, Secret } from "../../schema";
-
-export type PrometheusTarget = { targets: string[]; labels: Record<string, string> };
-
-/** snmp_exporter's names for the algorithms. */
-const AUTH = { sha1: "SHA", sha256: "SHA256" } as const;
-const PRIVACY = { aes128: "AES", des: "DES" } as const;
-
-/** The targets, and the devices left out because their config turns SNMP off. */
-export function prometheusTargets(network: Network): { targets: PrometheusTarget[]; withoutSnmp: Device[] } {
-    return {
-        targets: network.devices
-            .filter((device) => device.management?.snmp && device.connection.host)
-            .map((device) => ({
-                targets: [device.connection.host!],
-                // `__param_auth` picks the device's own auth in snmp_exporter.
-                labels: { device: device.name, platform: device.platform, model: device.model, __param_auth: device.name },
-            })),
-        withoutSnmp: network.devices.filter((device) => !device.management?.snmp),
-    };
-}
-
-/** A password as snmp_exporter reads it from its environment, or a note when the secret is a file, which it cannot read. */
-function fromEnvironment(secret: Secret, notes: string[], where: string): string {
-    if ("secret" in secret) return `\${${secret.secret}}`;
-
-    notes.push(`${where} is read from a file; write its value in place of FILL_IN`);
-    return "FILL_IN";
-}
-
-/** The `auths` section, as YAML, and what the operator must still fill in by hand. */
-export function snmpExporterAuths(network: Network): { yaml: string; notes: string[] } {
-    const notes: string[] = [];
-    const lines = [
-        "# Written by `circuit prometheus --auths`. Load it beside snmp.yml, with --config.expand-environment-variables.",
-        "auths:",
-    ];
-
-    for (const device of network.devices) {
-        const snmp = device.management?.snmp;
-        if (!snmp) continue;
-
-        const [name, user] = Object.entries(snmp.users ?? {})[0] ?? [];
-        lines.push(`  ${device.name}:`);
-
-        if (name && user) {
-            lines.push(
-                "    version: 3",
-                `    username: ${name}`,
-                "    security_level: authPriv",
-                `    password: ${fromEnvironment(user.auth_password, notes, `${device.name}'s SNMP password`)}`,
-                `    auth_protocol: ${AUTH[user.auth]}`,
-                `    priv_protocol: ${PRIVACY[user.privacy]}`,
-                `    priv_password: ${fromEnvironment(user.privacy_password, notes, `${device.name}'s SNMP privacy password`)}`
-            );
-        } else {
-            // snmp_exporter reads no community from the environment, and Circuit never writes a secret's value.
-            lines.push("    version: 2", "    community: FILL_IN");
-            notes.push(
-                `${device.name} has only an SNMP version 2c community, which snmp_exporter cannot read from its environment; write it in place of FILL_IN, or give the device a version 3 user`
-            );
-        }
-    }
-
-    return { yaml: lines.join("\n") + "\n", notes };
-}

package/src/cli/graph.ts

@@ -1,89 +0,0 @@
-// What `circuit graph` prints: the graph of the network with what `validate` found and how each device compares with its last snapshot, as Mermaid, DOT or JSON.
-
-import { type Annotated, deviceId, type GraphNode } from "../core/graph";
-
-/** `error` when validate found an error on the device, `warning` for a warning or a difference from its snapshot. */
-export function markOf(graph: Annotated, node: GraphNode): "error" | "warning" | undefined {
-    if (node.kind !== "device") return undefined;
-
-    const findings = graph.findings.filter((finding) => finding.device && deviceId(finding.device) === node.id);
-    if (findings.some((finding) => finding.level === "error")) return "error";
-
-    const drift = graph.drift[node.label]?.status;
-    if (findings.length || drift === "differs" || drift === "cannot plan") return "warning";
-
-    return undefined;
-}
-
-/** Mermaid, which GitHub draws wherever Markdown is shown. */
-export function mermaid(graph: Annotated): string {
-    const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]));
-    // Lines of text, each escaped, as one quoted label.
-    const text = (...lines: string[]) =>
-        `"${lines.map((line) => line.replace(/"/g, "#quot;").replace(/</g, "#lt;").replace(/>/g, "#gt;")).join("<br/>")}"`;
-
-    const shapes: Record<GraphNode["kind"], (label: string) => string> = {
-        device: (label) => `[${label}]`,
-        segment: (label) => `([${label}])`,
-        outside: (label) => `{{${label}}}`,
-    };
-
-    const lines = ["graph LR"];
-
-    for (const node of graph.nodes) {
-        const label = node.kind === "device" ? text(node.label, node.detail[0] ?? "") : text(node.label);
-        lines.push(`    ${ids.get(node.id)}${shapes[node.kind](label)}`);
-    }
-
-    for (const edge of graph.edges) {
-        const arrow = edge.oneSided ? "-.-" : "---";
-        lines.push(`    ${ids.get(edge.from)} ${arrow}|${text(edge.label)}| ${ids.get(edge.to)}`);
-    }
-
-    lines.push(
-        "    classDef error stroke:#d1242f,stroke-width:3px",
-        "    classDef warning stroke:#bf8700,stroke-width:3px",
-        "    classDef outside stroke-dasharray:4 3"
-    );
-
-    for (const node of graph.nodes) {
-        const mark = markOf(graph, node) ?? (node.kind === "outside" ? "outside" : undefined);
-        if (mark) lines.push(`    class ${ids.get(node.id)} ${mark}`);
-    }
-
-    return lines.join("\n") + "\n";
-}
-
-/** DOT, which Graphviz turns into an image: `circuit graph --format=dot | dot -Tsvg > network.svg`. */
-export function dot(graph: Annotated): string {
-    const text = (value: string) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-    const colors = { error: "#d1242f", warning: "#bf8700" };
-
-    const shapes: Record<GraphNode["kind"], string> = {
-        device: "shape=box, style=rounded",
-        segment: "shape=ellipse",
-        outside: "shape=box, style=dashed",
-    };
-
-    const lines = [
-        "graph network {",
-        "    rankdir=LR;",
-        '    node [fontname="Helvetica"];',
-        '    edge [fontname="Helvetica", fontsize=10];',
-    ];
-
-    for (const node of graph.nodes) {
-        const label = node.kind === "device" ? `${node.label}\n${node.detail[0] ?? ""}` : node.label;
-        const mark = markOf(graph, node);
-        const color = mark ? `, color=${text(colors[mark])}, penwidth=2` : "";
-        lines.push(`    ${text(node.id)} [label=${text(label)}, ${shapes[node.kind]}${color}];`);
-    }
-
-    for (const edge of graph.edges) {
-        const style = edge.oneSided ? ", style=dashed" : "";
-        lines.push(`    ${text(edge.from)} -- ${text(edge.to)} [label=${text(edge.label)}${style}];`);
-    }
-
-    lines.push("}");
-    return lines.join("\n") + "\n";
-}