@takodotid/circuit 0.13.0 → 0.14.0

package/dist/cli/index.js

@@ -3347,6 +3347,67 @@ async function ripeStat(query, family) {
 }
 var registries = { "ripe-stat": ripeStat };
 
+// src/adapters/registries/librenms.ts
+var AUTH = { sha1: "SHA", sha256: "SHA-256" };
+var PRIVACY = { aes128: "AES", des: "DES" };
+function settingsOf2(network2) {
+  if (!network2.librenms)
+    throw new Error("the network has no librenms settings");
+  return {
+    base: `${network2.librenms.url.replace(/\/+$/, "")}/api/v0`,
+    headers: { "X-Auth-Token": resolve(network2.librenms.api_token), "Content-Type": "application/json" }
+  };
+}
+function credentials(device) {
+  const snmp3 = device.management?.snmp;
+  const [name, user] = Object.entries(snmp3?.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 (snmp3?.community)
+    return { snmpver: "v2c", community: resolve(snmp3.community) };
+  return;
+}
+async function planLibreNms(network2) {
+  const { base, headers } = settingsOf2(network2);
+  const response = await fetch(`${base}/devices?type=all`, { headers, signal: AbortSignal.timeout(30000) });
+  if (!response.ok)
+    throw new Error(`LibreNMS answered ${response.status} to the device list`);
+  const monitored = new Set((await response.json()).devices.map((device) => device.hostname));
+  const ours = new Set(network2.devices.map((device) => device.connection.host));
+  const missing = network2.devices.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()
+  };
+}
+async function sendLibreNms(network2, additions) {
+  const { base, headers } = settingsOf2(network2);
+  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(60000)
+    });
+    const answer = await response.json().catch(() => ({}));
+    if (!response.ok || answer.status !== "ok") {
+      throw new Error(`${device.name}: LibreNMS refused it: ${answer.message ?? response.status}`);
+    }
+    console.log(`  ${device.name}: ${answer.message}`);
+  }
+}
+
 // src/adapters/registries/peeringdb.ts
 var API = "https://www.peeringdb.com/api";
 var addressesOf = (iface) => (iface.addresses ?? []).map((entry) => typeof entry === "string" ? entry : entry.address);
@@ -3440,6 +3501,17 @@ async function sendPeeringDb(network2, changes2) {
   }
 }
 
+// src/adapters/registries/prometheus.ts
+function prometheusTargets(network2) {
+  return {
+    targets: network2.devices.filter((device) => device.management?.snmp).map((device) => ({
+      targets: [device.connection.host],
+      labels: { device: device.name, platform: device.platform, model: device.model }
+    })),
+    withoutSnmp: network2.devices.filter((device) => !device.management?.snmp)
+  };
+}
+
 // src/core/validate.ts
 import { X509Certificate as X509Certificate2 } from "node:crypto";
 function validate(network2) {
@@ -3796,6 +3868,8 @@ var HELP = `usage: circuit <command> [device...] [options]
                         a client config for one peer, its private key left for the peer to fill
   communities           the network's BGP communities, one per line, for a looking glass or bgp.tools
   peeringdb             bring PeeringDB's exchange records in line with the config, with --confirm
+  librenms              add every device LibreNMS does not monitor yet, with --confirm
+  prometheus            every device with SNMP, as Prometheus targets for snmp_exporter
   secrets               every secret the config uses, and whether each can be read
 
   --config <path>       the network's config file, circuit.config.ts in the working directory by default`;
@@ -4030,6 +4104,31 @@ Nothing sent. Re-run with --confirm.`);
   }
   await sendPeeringDb(network2, plan4.changes);
 }
+async function librenmsCommand() {
+  const plan4 = await planLibreNms(network2);
+  for (const hostname of plan4.unknown)
+    console.log(`  LibreNMS monitors ${hostname}, which the config does not. Remove it by hand if it is gone.`);
+  for (const device of plan4.withoutSnmp)
+    console.log(`  ${device.name} has no SNMP in its config, so LibreNMS cannot poll it. Add management.snmp first.`);
+  for (const device of plan4.additions)
+    console.log(`  add ${device.name}, ${device.connection.host}`);
+  if (!plan4.additions.length) {
+    console.log("LibreNMS monitors every device it can.");
+    return;
+  }
+  if (!confirmed) {
+    console.log(`
+Nothing sent. Re-run with --confirm.`);
+    return;
+  }
+  await sendLibreNms(network2, plan4.additions);
+}
+function prometheusCommand() {
+  const { targets, withoutSnmp } = prometheusTargets(network2);
+  for (const device of withoutSnmp)
+    console.error(`${device.name} has no SNMP in its config; left out`);
+  console.log(JSON.stringify(targets, null, 4));
+}
 function secretsIn(value2, found = new Set) {
   if (isSecret(value2))
     found.add(referenceOf(value2));
@@ -4042,7 +4141,7 @@ function secretsIn(value2, found = new Set) {
   return found;
 }
 function secretsCommand() {
-  const references = [...secretsIn([network2.devices, network2.peeringdb])].sort();
+  const references = [...secretsIn([network2.devices, network2.peeringdb, network2.librenms])].sort();
   let missing = 0;
   for (const reference of references) {
     const name = reference.replace(/^file:/, "");
@@ -4068,6 +4167,8 @@ var commands = {
   wireguard: wireguardCommand,
   communities: communitiesCommand,
   peeringdb: peeringdbCommand,
+  librenms: librenmsCommand,
+  prometheus: prometheusCommand,
   secrets: secretsCommand
 };
 var run = commands[command2];

package/dist/types/adapters/registries/librenms.d.ts

@@ -0,0 +1,15 @@
+import type { Network } from "../../core/define";
+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[];
+};
+/** Compare the config with what LibreNMS monitors. A device is known to LibreNMS by its management address. */
+export declare function planLibreNms(network: Network): Promise<LibreNmsPlan>;
+/** Add each device, named after its `name` and polled with the credentials from its config. */
+export declare function sendLibreNms(network: Network, additions: readonly Device[]): Promise<void>;

package/dist/types/adapters/registries/prometheus.d.ts

@@ -0,0 +1,11 @@
+import type { Network } from "../../core/define";
+import type { Device } from "../../schema";
+export type PrometheusTarget = {
+    targets: string[];
+    labels: Record<string, string>;
+};
+/** The targets, and the devices left out because their config turns SNMP off. */
+export declare function prometheusTargets(network: Network): {
+    targets: PrometheusTarget[];
+    withoutSnmp: Device[];
+};

package/dist/types/core/define.d.ts

@@ -45,6 +45,13 @@ export type Network = {
         /** An API key with write access to the network's record. */
         api_key: Secret;
     };
+    /** Keeps LibreNMS monitoring every device: `circuit librenms`. */
+    librenms?: {
+        /** Where LibreNMS is, such as `https://librenms.example.com`. */
+        url: string;
+        /** An API token that can add devices. */
+        api_token: Secret;
+    };
 };
 /** Declare the network, in `circuit.config.ts`. */
 export declare const defineNetwork: (network: Network) => Network;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.13.0",
+    "version": "0.14.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/adapters/registries/librenms.ts

@@ -0,0 +1,90 @@
+// 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));
+    const ours = new Set(network.devices.map((device) => device.connection.host));
+    const missing = network.devices.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/prometheus.ts

@@ -0,0 +1,19 @@
+// Prometheus targets for snmp_exporter, in its file-based discovery format: one entry per device that answers SNMP, labelled with what the config knows about it.
+
+import type { Network } from "../../core/define";
+import type { Device } from "../../schema";
+
+export type PrometheusTarget = { targets: string[]; labels: Record<string, string> };
+
+/** 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)
+            .map((device) => ({
+                targets: [device.connection.host],
+                labels: { device: device.name, platform: device.platform, model: device.model },
+            })),
+        withoutSnmp: network.devices.filter((device) => !device.management?.snmp),
+    };
+}

package/src/cli/index.ts

@@ -7,7 +7,9 @@ import { basename, dirname, join, resolve } from "node:path";
 import { adapters } from "../adapters/devices";
 import type { ApplyOptions, DeviceAdapter, Plan } from "../adapters/devices/types";
 import { registries } from "../adapters/registries";
+import { planLibreNms, sendLibreNms } from "../adapters/registries/librenms";
 import { planPeeringDb, sendPeeringDb } from "../adapters/registries/peeringdb";
+import { prometheusTargets } from "../adapters/registries/prometheus";
 import { network as prefixOf } from "../core/addr";
 import type { Network } from "../core/define";
 import { isSecret, referenceOf, resolve as reveal, sourceOf, useRoot } from "../core/secrets";
@@ -29,6 +31,8 @@ const HELP = `usage: circuit <command> [device...] [options]
                         a client config for one peer, its private key left for the peer to fill
   communities           the network's BGP communities, one per line, for a looking glass or bgp.tools
   peeringdb             bring PeeringDB's exchange records in line with the config, with --confirm
+  librenms              add every device LibreNMS does not monitor yet, with --confirm
+  prometheus            every device with SNMP, as Prometheus targets for snmp_exporter
   secrets               every secret the config uses, and whether each can be read
 
   --config <path>       the network's config file, circuit.config.ts in the working directory by default`;
@@ -325,6 +329,34 @@ async function peeringdbCommand(): Promise<void> {
     await sendPeeringDb(network, plan.changes);
 }
 
+async function librenmsCommand(): Promise<void> {
+    const plan = await planLibreNms(network);
+
+    for (const hostname of plan.unknown)
+        console.log(`  LibreNMS monitors ${hostname}, which the config does not. Remove it by hand if it is gone.`);
+    for (const device of plan.withoutSnmp)
+        console.log(`  ${device.name} has no SNMP in its config, so LibreNMS cannot poll it. Add management.snmp first.`);
+    for (const device of plan.additions) console.log(`  add ${device.name}, ${device.connection.host}`);
+
+    if (!plan.additions.length) {
+        console.log("LibreNMS monitors every device it can.");
+        return;
+    }
+
+    if (!confirmed) {
+        console.log("\nNothing sent. Re-run with --confirm.");
+        return;
+    }
+
+    await sendLibreNms(network, plan.additions);
+}
+
+function prometheusCommand(): void {
+    const { targets, withoutSnmp } = prometheusTargets(network);
+    for (const device of withoutSnmp) console.error(`${device.name} has no SNMP in its config; left out`);
+    console.log(JSON.stringify(targets, null, 4));
+}
+
 /** Every secret reference in a value, however deep. */
 function secretsIn(value: unknown, found = new Set<string>()): Set<string> {
     if (isSecret(value)) found.add(referenceOf(value));
@@ -335,7 +367,7 @@ function secretsIn(value: unknown, found = new Set<string>()): Set<string> {
 }
 
 function secretsCommand(): void {
-    const references = [...secretsIn([network.devices, network.peeringdb])].sort();
+    const references = [...secretsIn([network.devices, network.peeringdb, network.librenms])].sort();
     let missing = 0;
 
     for (const reference of references) {
@@ -365,6 +397,8 @@ const commands: Record<string, () => void | Promise<void>> = {
     wireguard: wireguardCommand,
     communities: communitiesCommand,
     peeringdb: peeringdbCommand,
+    librenms: librenmsCommand,
+    prometheus: prometheusCommand,
     secrets: secretsCommand,
 };
 

package/src/core/define.ts

@@ -86,6 +86,13 @@ export type Network = {
         /** An API key with write access to the network's record. */
         api_key: Secret;
     };
+    /** Keeps LibreNMS monitoring every device: `circuit librenms`. */
+    librenms?: {
+        /** Where LibreNMS is, such as `https://librenms.example.com`. */
+        url: string;
+        /** An API token that can add devices. */
+        api_token: Secret;
+    };
 };
 
 /** Declare the network, in `circuit.config.ts`. */