@takodotid/circuit 0.4.7 → 0.6.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.7",
+    "version": "0.6.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",
@@ -39,7 +39,8 @@
     ],
     "type": "module",
     "exports": {
-        ".": "./src/index.ts"
+        ".": "./src/index.ts",
+        "./presets": "./src/presets/index.ts"
     },
     "bin": {
         "circuit": "src/cli/index.ts"

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/core/merge.ts

@@ -0,0 +1,19 @@
+// Combining records from several sources, such as a device's own interfaces and those a module derives for it.
+
+type Merged<T extends readonly object[]> = T extends readonly [infer Head, ...infer Tail extends readonly object[]]
+    ? Head & Merged<Tail>
+    : unknown;
+
+/** Combine records into one. Unlike spreading them, a name two of them hold is an error rather than one silently replacing the other. */
+export function merge<const T extends readonly Record<string, unknown>[]>(...records: T): Merged<T> {
+    const result: Record<string, unknown> = {};
+
+    for (const record of records) {
+        for (const [key, value] of Object.entries(record)) {
+            if (key in result) throw new Error(`merge: ${key} is declared twice`);
+            result[key] = value;
+        }
+    }
+
+    return result as Merged<T>;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export { defineDevice, defineNetwork, secret, secretFile } from "./core/define";
+export { merge } from "./core/merge";
 export type { Check, Community, Finding, Network } from "./core/define";
 export type * from "./schema";
 

package/src/presets/index.ts

@@ -0,0 +1,211 @@
+// Building blocks most networks write the same way: address lists, edge filters, a BGP import sanity policy, checks, and helpers for checks of your own. 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. */
+export 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;
+};
+
+/** The VLANs a port carries, untagged or tagged. */
+export const vlansOf = (port: { access_vlan?: string; trunk_vlans?: readonly string[] }): string[] =>
+    [port.access_vlan, ...(port.trunk_vlans ?? [])].filter((vlan): vlan is string => vlan !== undefined);
+
+/** Where traffic from outside, before anything filters it, may go. */
+export type TrustBoundary = {
+    /** VLANs carrying traffic straight from outside: transits, exchanges, an ISP handoff. */
+    untrusted: readonly string[];
+    /** VLANs that must not meet them on a port: customers, servers, management. */
+    trusted: readonly string[];
+    /** The devices that filter: the only ones that may give an untrusted VLAN an address, and the only ones a port carrying both may face. */
+    routers: readonly string[];
+};
+
+/** A check: untrusted traffic reaches trusted VLANs only through a router. A port carrying both faces a router or is on one, and only a router gives an untrusted VLAN an address. */
+export const trustBoundary =
+    (boundary: TrustBoundary): Check =>
+    (devices) => {
+        const untrusted = new Set(boundary.untrusted);
+        const trusted = new Set(boundary.trusted);
+        const routers = new Set(boundary.routers);
+        const findings: Finding[] = [];
+
+        for (const device of devices) {
+            const isRouter = routers.has(device.name);
+            const ports = Object.entries(device.ports ?? {}).flatMap(([name, port]) => (port ? [{ name, port }] : []));
+
+            // What carries VLANs: a port on its own, or a LAG, which faces whatever its members link to.
+            const carriers = [
+                ...ports
+                    .filter(({ port }) => !port.lag)
+                    .map(({ name, port }) => ({
+                        what: `port ${name}`,
+                        carried: vlansOf(port),
+                        faces: port.link ? [port.link.device] : [],
+                    })),
+                ...Object.entries(device.interfaces ?? {}).flatMap(([name, iface]) =>
+                    iface.type === "lag"
+                        ? [
+                              {
+                                  what: `LAG ${name}`,
+                                  carried: vlansOf(iface),
+                                  faces: ports.filter(({ port }) => port.lag === name && port.link).map(({ port }) => port.link!.device),
+                              },
+                          ]
+                        : []
+                ),
+            ];
+
+            for (const { what, carried, faces } of carriers) {
+                const mixes = carried.some((vlan) => untrusted.has(vlan)) && carried.some((vlan) => trusted.has(vlan));
+                const facesRouter = isRouter || faces.some((name) => routers.has(name));
+
+                if (mixes && !facesRouter) {
+                    findings.push({
+                        level: "error",
+                        device: device.name,
+                        message: `${what} carries an untrusted VLAN beside a trusted one and does not face a router`,
+                    });
+                }
+            }
+
+            if (isRouter) continue;
+
+            for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
+                if (iface.type === "vlan" && untrusted.has(iface.vlan)) {
+                    findings.push({
+                        level: "error",
+                        device: device.name,
+                        message: `interface ${name} puts an address on untrusted VLAN ${iface.vlan}; only a router may`,
+                    });
+                }
+            }
+        }
+
+        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;
+};