@takodotid/circuit 0.4.3 → 0.5.0

package/README.md

@@ -49,7 +49,7 @@ export default defineDevice({
 
 Ports are named `<speed>-<position>`: `10g-1` is the first 10G cage. The model decides which exist; the adapter knows what the platform calls each one. Everything a device can hold is in `src/schema/`, with a comment on every field.
 
-A network is a list of devices in `circuit.config.ts` at the root of the project:
+A network is a list of devices in `circuit.config.ts` at the root of the project, or any file named with `--config <path>`:
 
 ```ts
 import { defineNetwork } from "@takodotid/circuit";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.4.3",
+    "version": "0.5.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",
@@ -39,10 +39,11 @@
     ],
     "type": "module",
     "exports": {
-        ".": "./src/index.ts"
+        ".": "./src/index.ts",
+        "./presets": "./src/presets/index.ts"
     },
     "bin": {
-        "circuit": "./src/cli/index.ts"
+        "circuit": "src/cli/index.ts"
     },
     "files": [
         "src",

package/src/adapters/devices/routeros/plan.ts

@@ -10,6 +10,8 @@ export const INSTALL_CERTIFICATE = "#install-certificate ";
 
 /** Dependency order. A menu not listed sorts after all of these. The longest matching prefix decides. */
 const ORDER = [
+    // Certificates depend on nothing, and services name them.
+    "/certificate",
     "/interface bridge",
     "/interface ethernet",
     "/interface bonding",
@@ -42,7 +44,6 @@ const ORDER = [
     "/ipv6",
     "/routing",
     "/interface ethernet switch",
-    "/certificate",
     "/snmp",
     "/tool",
     "/user",
@@ -257,7 +258,7 @@ function planEntries(menu: string, wanted: Command[], existing: Command[], sendS
 }
 
 /**
- * Certificates are installed from the config when missing or different, after the old one of that name is removed. One the config does not hold is removed in the last phase.
+ * Certificates are installed from the config when missing or different, after the old one of that name is removed. One the device holds under another name, with the same fingerprint and key, is renamed rather than imported a second time. One the config does not hold is removed in the last phase.
  */
 function planCertificates(wanted: Command[], existing: Command[]): MenuPlan {
     const menu = "/certificate";
@@ -265,19 +266,37 @@ function planCertificates(wanted: Command[], existing: Command[]): MenuPlan {
     const install: Step = { title: menu, show: [], send: [] };
     const remove: Step = { title: menu, show: [], send: [] };
     const existingByName = new Map(existing.map((item) => [item.attrs.name, item]));
+    const wantedNames = new Set(wanted.map((item) => item.attrs.name));
+    const renamed = new Set<string>();
 
     for (const entry of wanted) {
         const name = entry.attrs.name!;
         const current = existingByName.get(name);
         if (current && canonical(current) === canonical(entry)) continue;
 
+        const sameCertificate = existing.find(
+            (item) =>
+                !wantedNames.has(item.attrs.name) &&
+                !renamed.has(item.attrs.name!) &&
+                item.attrs.fingerprint === entry.attrs.fingerprint &&
+                item.attrs["private-key"] === entry.attrs["private-key"]
+        );
+
+        if (!current && sameCertificate) {
+            const oldName = sameCertificate.attrs.name!;
+            renamed.add(oldName);
+            install.show.push(`~ rename ${oldName} to ${name}`);
+            install.send.push(`${menu} set [ find name=${quote(oldName)} ] name=${quote(name)}`);
+            continue;
+        }
+
         install.show.push(`${current ? "~" : "+"} install ${name}`);
         if (current) install.send.push(`${menu} remove [ find name=${quote(name)} ]`);
         install.send.push(INSTALL_CERTIFICATE + name);
     }
 
     for (const entry of existing) {
-        if (wanted.some((candidate) => candidate.attrs.name === entry.attrs.name)) continue;
+        if (wantedNames.has(entry.attrs.name) || renamed.has(entry.attrs.name!)) continue;
 
         remove.show.push(`- ${entry.attrs.name}`);
         remove.send.push(`${menu} remove [ find name=${quote(entry.attrs.name!)} ]`);

package/src/adapters/devices/vrp/TRAPS.md

@@ -20,3 +20,4 @@ Behaviour that looks like something else. Each one has been hit on a CE6855 runn
 - `abort` is not a command here. `clear configuration candidate` discards uncommitted changes.
 - sFlow samples per port, `sflow sampling rate N`, N from 4096; the default is 8192 and an explicit 8192 is kept as written. A port names a collector only once the collector exists globally; until then it is refused with "collector does not exist".
 - `vlan batch` holds every VLAN on one line, and undoing a list that names a VLAN with an L3 interface is refused. A change sends only the VLANs added and `undo vlan batch` for the ones removed.
+- A VLAN name is unique across VLANs: a new VLAN cannot take a name another still holds. VLANs no longer used, and their VLAN interfaces, are removed first, in the same candidate.

package/src/adapters/devices/vrp/index.ts

@@ -722,21 +722,52 @@ export async function apply(device: Device, _network: readonly Device[], plan: P
     console.log("  committed, login proved, saved");
 }
 
+/**
+ * What changes, in the order the platform accepts.
+ *
+ * A VLAN list changes by ID. VLANs no longer used go first, with their VLAN interfaces, so their names and numbers are free before a new VLAN takes them: a VLAN name is unique, and a VLAN with an interface cannot be removed. The whole plan is one candidate, so going first leaves nothing half done.
+ */
+function plan(desired: string, current: string): Plan {
+    const groups = compare(desired, current, dialect);
+    vlanListChange(
+        groups,
+        "vlan batch ",
+        batchIds,
+        (ids) => [`vlan batch ${vlanBatch(ids)}`],
+        (ids) => [`vlan batch ${vlanBatch(ids)}`]
+    );
+
+    const top = groups.find((group) => group.path.length === 0);
+    const removedBatch = top?.remove.find((line) => line.startsWith("vlan batch ")) ?? "";
+    const removedIds = removedBatch ? batchIds(removedBatch) : [];
+
+    const firstRemovals = [
+        ...removedIds.map((id) => `interface Vlanif${id}`).filter((line) => top?.remove.includes(line)),
+        ...removedIds.map((id) => `vlan ${id}`).filter((line) => top?.remove.includes(line)),
+        ...(removedBatch ? [removedBatch] : []),
+    ];
+
+    if (top) top.remove = top.remove.filter((line) => !firstRemovals.includes(line));
+
+    const planned = steps(
+        groups.filter((group) => group.add.length || group.remove.length),
+        dialect
+    );
+
+    if (firstRemovals.length) {
+        // `undo vlan batch` removes a VLAN's own settings with it, so only the interfaces and the list are sent.
+        const sent = firstRemovals.filter((line) => !/^vlan \d+$/.test(line)).map(undo);
+        planned.unshift({ title: "VLANs no longer used", show: firstRemovals.map((line) => `- ${line}`), send: sent });
+    }
+
+    return { steps: planned, problems: [] };
+}
+
 export const vrp: DeviceAdapter = {
     extension: ".cfg",
     unsupported,
     render,
     read,
-    plan: (desired, current) => {
-        const groups = compare(desired, current, dialect);
-        vlanListChange(
-            groups,
-            "vlan batch ",
-            batchIds,
-            (ids) => [`vlan batch ${vlanBatch(ids)}`],
-            (ids) => [`vlan batch ${vlanBatch(ids)}`]
-        );
-        return { steps: steps(groups, dialect), problems: [] };
-    },
+    plan,
     apply,
 };

package/src/cli/index.ts

@@ -3,7 +3,7 @@
 
 import { createPrivateKey, createPublicKey } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { 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";
@@ -27,21 +27,33 @@ const HELP = `usage: circuit <command> [device...] [options]
   wireguard <device> <interface> <peer>
                         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`;
+  peeringdb             bring PeeringDB's exchange records in line with the config, with --confirm
 
-const CONFIG_FILE = "circuit.config.ts";
+  --config <path>       the network's config file, circuit.config.ts in the working directory by default`;
 
-const root = process.cwd();
-const configPath = resolve(root, CONFIG_FILE);
+const DEFAULT_CONFIG = "circuit.config.ts";
+
+const [command, ...args] = process.argv.slice(2);
+
+// `--config <path>` and `--config=<path>` both name the config file; neither is a device name.
+const configAt = args.indexOf("--config");
+const configArgument = configAt >= 0 ? args[configAt + 1] : args.find((arg) => arg.startsWith("--config="))?.slice("--config=".length);
+const rest = args.filter((arg, index) => index !== configAt && (configAt < 0 || index !== configAt + 1) && !arg.startsWith("--config="));
+
+const configPath = resolve(process.cwd(), configArgument ?? DEFAULT_CONFIG);
 
 if (!existsSync(configPath)) {
-    console.error(`no ${CONFIG_FILE} in ${root}`);
+    console.error(
+        configArgument ? `no config at ${configPath}` : `no ${DEFAULT_CONFIG} in ${process.cwd()}; name another with --config <path>`
+    );
     process.exit(1);
 }
 
+/** The directory of the config file. The state directory is relative to it. */
+const root = dirname(configPath);
+
 const network = (await import(configPath)).default as Network;
 
-const [command, ...rest] = process.argv.slice(2);
 const flags = rest.filter((arg) => arg.startsWith("--"));
 const names = rest.filter((arg) => !arg.startsWith("--"));
 const confirmed = flags.includes("--confirm");

package/src/presets/index.ts

@@ -0,0 +1,133 @@
+// Building blocks most networks write the same way: address lists, edge filters, a BGP import sanity policy, and checks. Each returns plain config to place where it belongs, so nothing here applies itself.
+
+import { contains } from "../core/addr";
+import type { Check, Finding } from "../core/define";
+import type { AclRule, Device, FilterRule, PolicyRule, Prefix, TcpFlag } from "../schema";
+
+/** IPv4 sources that never arrive from the internet: loopback, link-local and "this network", after RFC 6890. */
+export const 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. */
+export const PRIVATE_RANGES = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] as const satisfies readonly Prefix[];
+
+/** 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. */
+export const antiSpoofing = <V extends string>(vlan: V, sources: readonly Prefix[]): AclRule<V>[] =>
+    sources.map((src) => ({
+        description: `${vlan}: drop source ${src}`,
+        match: { vlan, src },
+        action: "drop",
+    }));
+
+/** TCP flag combinations no legitimate packet carries: name, flags set, flags unset. */
+const 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[]])[];
+
+/** Firewall rules dropping packets with a TCP flag combination no legitimate packet carries, for a forward chain. */
+export const badTcpFlags = (): FilterRule<never, never>[] =>
+    BAD_TCP_FLAGS.map(([name, set, unset]) => ({
+        description: `Bad flags ${name}`,
+        match: { protocol: "tcp", tcp_flags: { set, unset } },
+        action: "drop",
+    }));
+
+/** The prefix lengths a BGP import accepts. */
+export type SanityLengths = {
+    /** Shortest and longest IPv4 prefix accepted. /8 to /24 when absent. */
+    ipv4?: { min: number; max: number };
+    /** Shortest and longest IPv6 prefix accepted. /16 to /48 when absent. */
+    ipv6?: { min: number; max: number };
+};
+
+/** Route policy rules rejecting what no neighbor should send: prefixes too short or too long for the global table, and RPKI invalid. Place it first in an import, or as a policy other imports call. */
+export function bgpSanity(lengths: SanityLengths = {}): PolicyRule<never, never>[] {
+    const ipv4 = lengths.ipv4 ?? { min: 8, max: 24 };
+    const ipv6 = lengths.ipv6 ?? { min: 16, max: 48 };
+
+    return [
+        {
+            description: `IPv4 shorter than /${ipv4.min}`,
+            match: { family: "ipv4", prefix_length: { max: ipv4.min - 1 } },
+            action: "reject",
+        },
+        { description: `IPv4 longer than /${ipv4.max}`, match: { family: "ipv4", prefix_length: { min: ipv4.max + 1 } }, action: "reject" },
+        {
+            description: `IPv6 shorter than /${ipv6.min}`,
+            match: { family: "ipv6", prefix_length: { max: ipv6.min - 1 } },
+            action: "reject",
+        },
+        { description: `IPv6 longer than /${ipv6.max}`, match: { family: "ipv6", prefix_length: { min: ipv6.max + 1 } }, action: "reject" },
+        { description: "RPKI invalid", match: { rpki: "invalid" }, action: "reject" },
+    ];
+}
+
+/** Each BGP neighbor's own policies, or its group's. */
+function neighborPolicies(device: Device) {
+    const bgp = device.routing?.bgp;
+
+    return Object.entries(bgp?.neighbors ?? {}).map(([name, neighbor]) => {
+        const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
+        return { name, address: neighbor.address, import: neighbor.import ?? group?.import, export: neighbor.export ?? group?.export };
+    });
+}
+
+/** The prefixes an export policy accepts by name. */
+export function offered(device: Device, policy: string | undefined): string[] {
+    const rules = policy ? (device.policies?.[policy] ?? []) : [];
+    return rules.filter((rule) => rule.action === "accept" && rule.match?.prefix).map((rule) => rule.match!.prefix!);
+}
+
+/** Every BGP export ends in a reject that matches everything, so nothing leaves by accident. */
+export const exportsEndInReject: Check = (devices) => {
+    const findings: Finding[] = [];
+
+    for (const device of devices) {
+        for (const neighbor of neighborPolicies(device)) {
+            const last = neighbor.export ? device.policies?.[neighbor.export]?.at(-1) : undefined;
+
+            if (neighbor.export && (last?.action !== "reject" || last.match)) {
+                findings.push({
+                    level: "error",
+                    device: device.name,
+                    message: `${neighbor.name}: export ${neighbor.export} does not end in an unconditional reject`,
+                });
+            }
+        }
+    }
+
+    return findings;
+};
+
+/** A GRE or VXLAN tunnel's local address is outside what the neighbors over it are offered, or their replies route back into the tunnel. */
+export const tunnelsOutsideOffered: Check = (devices) => {
+    const findings: Finding[] = [];
+
+    for (const device of devices) {
+        for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
+            if (iface.type !== "gre" && iface.type !== "vxlan") continue;
+
+            const subnets = (iface.addresses ?? []).map((entry) => (typeof entry === "string" ? entry : entry.address));
+
+            for (const neighbor of neighborPolicies(device)) {
+                if (!subnets.some((subnet) => contains(subnet, neighbor.address))) continue;
+
+                for (const prefix of offered(device, neighbor.export)) {
+                    if (contains(prefix, iface.local)) {
+                        findings.push({
+                            level: "error",
+                            device: device.name,
+                            message: `${name} is sourced from ${iface.local}, inside ${prefix}, which ${neighbor.name} is offered`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+
+    return findings;
+};