@takodotid/circuit 0.17.0 → 0.18.0

package/dist/cli/index.js

@@ -1472,10 +1472,11 @@ function command(verb, properties) {
 }
 var yesNo = (on) => on ? "yes" : "no";
 var familySuffix = (family) => family === "ipv4" ? "V4" : "V6";
+var eachPort = (ports) => [ports].flat().map((port) => typeof port === "number" ? String(port) : `${port.min}-${port.max}`);
 function portList(ports) {
   if (ports === undefined)
     return;
-  return [ports].flat().join(",");
+  return eachPort(ports).join(",");
 }
 function duration(seconds) {
   const units = [
@@ -1940,12 +1941,26 @@ var HELPERS = ["ftp", "tftp", "irc", "h323", "sip", "pptp", "rtsp"];
 var CHAINS = ["input", "forward", "output"];
 function renderFirewall(out, ctx) {
   for (const family of ["ipv4", "ipv6"]) {
+    untracked(out, ctx, family);
     filter(out, ctx, family);
     nat(out, ctx, family);
   }
   helpers(out, ctx);
   switchAcls(out, ctx);
 }
+function untracked(out, ctx, family) {
+  const menu = family === "ipv4" ? "/ip firewall raw" : "/ipv6 firewall raw";
+  for (const prefix of ctx.device.firewall?.untracked ?? []) {
+    if (familyOf(prefix) !== family)
+      continue;
+    for (const [direction, property] of [
+      ["to", "dst-address"],
+      ["from", "src-address"]
+    ]) {
+      out.add(menu, command("add", { action: "notrack", chain: "prerouting", comment: `Untracked ${direction} ${prefix}`, [property]: prefix }));
+    }
+  }
+}
 function families(ctx, match) {
   const sets = ctx.device.firewall?.address_sets ?? {};
   const address = match?.src ?? match?.dst;
@@ -2021,7 +2036,7 @@ function helpers(out, ctx) {
   }
 }
 function switchAcls(out, ctx) {
-  const each = (ports) => ports === undefined ? [undefined] : [ports].flat();
+  const each = (ports) => ports === undefined ? [undefined] : eachPort(ports);
   for (const [port, settings] of Object.entries(ctx.ports)) {
     if (!settings.acl)
       continue;

package/dist/presets/index.js

@@ -32,19 +32,26 @@ var AMPLIFIERS = {
   memcached: 11211,
   dvr: 37810
 };
-var antiAmplification = (destinations, trusted = []) => destinations.flatMap((dst) => [
-  ...trusted.map((src) => ({
-    description: `UDP to ${dst} from ${src}`,
-    match: { protocol: "udp", src, dst },
-    action: "accept"
-  })),
-  { description: `UDP fragments to ${dst}`, match: { protocol: "udp", dst, src_port: 0 }, action: "drop" },
-  ...Object.entries(AMPLIFIERS).map(([name, port]) => ({
-    description: `UDP to ${dst} from ${name}`,
-    match: { protocol: "udp", dst, src_port: port },
-    action: "drop"
-  }))
-]);
+var ASKED = new Set([AMPLIFIERS.dns, AMPLIFIERS.ntp, AMPLIFIERS.snmp]);
+function antiAmplification(destinations, options = {}) {
+  const below1024Except = (port) => [
+    { min: 0, max: port - 1 },
+    { min: port + 1, max: 1023 }
+  ];
+  return destinations.flatMap((dst) => [
+    ...(options.keep_fragments ?? []).filter((prefix) => contains(dst, prefix)).map((prefix) => ({
+      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(AMPLIFIERS).map(([name, port]) => ({
+      description: ASKED.has(port) ? `UDP to ${dst} from ${name}, to a port below 1024` : `UDP to ${dst} from ${name}`,
+      match: { protocol: "udp", dst, src_port: port, ...ASKED.has(port) ? { dst_port: below1024Except(port) } : {} },
+      action: "drop"
+    }))
+  ]);
+}
 var BAD_TCP_FLAGS = [
   ["FIN+SYN", ["fin", "syn"], []],
   ["SYN+RST", ["syn", "rst"], []],

package/dist/types/adapters/devices/routeros/render.d.ts

@@ -1,4 +1,4 @@
-import type { Device, Family, Interface, Port } from "../../../schema";
+import type { Device, Family, Interface, Port, Ports } from "../../../schema";
 /** A property value as a command takes it. `undefined` and `false` leave the property out. */
 export type Value = string | number | undefined | false;
 /** Collects commands under their menu. */
@@ -21,8 +21,10 @@ export declare function command(verb: string, properties: Record<string, Value>)
 export declare const yesNo: (on: boolean | undefined) => string;
 /** `V4` or `V6`, the suffix of a chain rendered for one family. */
 export declare const familySuffix: (family: Family) => string;
-/** One port or a list of ports, as `53,123`. */
-export declare function portList(ports: number | readonly number[] | undefined): string | undefined;
+/** Each port or range of ports as the platform writes it: `53`, `0-52`. */
+export declare const eachPort: (ports: Ports) => string[];
+/** One port, a range, or a list of them, as `53,0-52`. */
+export declare function portList(ports: Ports | undefined): string | undefined;
 /** Seconds as the platform writes a duration: `3600` becomes `1h`, `90` becomes `1m30s`. */
 export declare function duration(seconds: number): string;
 /** A rate as the switch chip takes it: `2G` becomes `2.0Gbps`. */

package/dist/types/presets/index.d.ts

@@ -28,10 +28,19 @@ export declare const AMPLIFIERS: {
     readonly memcached: 11211;
     readonly dvr: 37810;
 };
+/** What `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[];
+};
 /**
- * Hardware ACL rules dropping reflected UDP floods toward `destinations`: replies from the ports in `AMPLIFIERS`, and the fragments after the first, which carry no port and which a switch chip reads as port 0. UDP from `trusted` sources, the resolvers and time servers your own hosts ask, is accepted before anything is dropped. Traffic that matches is dropped whole and everything else passes untouched, so nothing legitimate is slowed.
+ * 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 fragments after the first carry no port, and a switch chip reads them as port 0. They are dropped, but toward `keep_fragments`.
  */
-export declare const antiAmplification: (destinations: readonly Prefix[], trusted?: readonly Prefix[]) => AclRule<never>[];
+export declare function antiAmplification(destinations: readonly Prefix[], options?: AntiAmplificationOptions): AclRule<never>[];
 /** Firewall rules dropping packets with a TCP flag combination no legitimate packet carries, for a forward chain. */
 export declare const badTcpFlags: () => FilterRule<never, never>[];
 /** The prefix lengths a BGP import accepts. */

package/dist/types/schema/firewall.d.ts

@@ -3,6 +3,13 @@ import type { Family, IP, Prefix, Rate } from "./common";
 export type Protocol = "tcp" | "udp" | "icmp" | "gre" | "esp" | "ah" | "ospf" | "vrrp";
 /** The state connection tracking assigns a packet. */
 export type ConnectionState = "new" | "established" | "related" | "untracked" | "invalid";
+/** Ports from `min` to `max`, both included. */
+export type PortRange = {
+    min: number;
+    max: number;
+};
+/** A port, a range of ports, or any of several. */
+export type Ports = number | PortRange | readonly (number | PortRange)[];
 /** A TCP header flag. */
 export type TcpFlag = "fin" | "syn" | "rst" | "psh" | "ack" | "urg";
 /** Conditions on a packet. All must hold. A rule with addresses of one family applies to that family only. */
@@ -20,9 +27,9 @@ export type FilterMatch<I extends string, AS extends string> = {
     /** Destination is in this address set. */
     dst_set?: AS;
     /** Source port, or any of several. TCP and UDP only. */
-    src_port?: number | readonly number[];
+    src_port?: Ports;
     /** Destination port, or any of several. TCP and UDP only. */
-    dst_port?: number | readonly number[];
+    dst_port?: Ports;
     /** Arrived on this interface. */
     in_interface?: I;
     /** Leaves through this interface. */
@@ -89,6 +96,8 @@ export type Firewall<I extends string, AS extends string> = {
     };
     /** Helpers that run. None when absent. */
     helpers?: readonly Helper[];
+    /** Traffic to and from these prefixes passes without connection tracking. A flood toward them cannot fill the connection table, and rules see its packets in the state `untracked`. Everything is tracked when absent. */
+    untracked?: readonly Prefix[];
 };
 /** A stateless rule evaluated in hardware where traffic arrives, before routing. */
 export type AclRule<V extends string> = {
@@ -105,9 +114,9 @@ export type AclRule<V extends string> = {
         /** Destination prefix. */
         dst?: Prefix;
         /** Source port, or any of several. */
-        src_port?: number | readonly number[];
+        src_port?: Ports;
         /** Destination port, or any of several. */
-        dst_port?: number | readonly number[];
+        dst_port?: Ports;
         /** Carried in this VLAN. */
         vlan?: V;
     };

package/package.json

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

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

@@ -17,6 +17,7 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - A switch-chip rule's `rate` did not limit traffic the CPU routes. On a CCR2216 on 7.23.5, under a 12 Gbps flood, a rule at `2G` and then at `100M` changed nothing that reached the CPU, while a drop with the same match left 3 Mbps. Drop what you can recognise instead of limiting it.
 - The switch chip reads a UDP fragment after the first as port 0. `src-port=0` drops the rest of a fragmented flood whose first fragments another rule dropped by port; without it they reach the CPU, which holds them waiting for a first fragment that never comes.
 - A switch-chip rule takes one port or a range, `1900-1901`; a list is refused. The render makes one rule for each port in a list.
+- The connection table holds 1,048,576 entries on a CCR2216 with 16 GiB, and a full table refuses every new connection through the router, not only the target's. A SYN flood of 210,000 packets a second filled it in five seconds; a UDP flood from random sources fills it about six times faster, because an unanswered UDP entry lives 30 seconds. Traffic in `untracked` prefixes never enters it.
 - With hardware offload on, routed traffic bypasses the forward chain entirely. `hardware_offload: false` on an interface is what makes the firewall apply to it, at the cost of CPU. The only proof of offload is the `H` flag on a route.
 - `/ip cloud ddns-enabled` cannot be turned off on 7.23.5.
 - `mac-server` and `mac-winbox` work at layer 2 and ignore the IP firewall; they are limited by interface list.

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

@@ -13,6 +13,7 @@ import type {
     NeighborSettings,
     PolicyRule,
     Port,
+    Ports,
     Service,
     Severity,
 } from "../../../schema";
@@ -72,11 +73,15 @@ export const yesNo = (on: boolean | undefined): string => (on ? "yes" : "no");
 /** `V4` or `V6`, the suffix of a chain rendered for one family. */
 export const familySuffix = (family: Family): string => (family === "ipv4" ? "V4" : "V6");
 
-/** One port or a list of ports, as `53,123`. */
-export function portList(ports: number | readonly number[] | undefined): string | undefined {
+/** Each port or range of ports as the platform writes it: `53`, `0-52`. */
+export const eachPort = (ports: Ports): string[] =>
+    [ports].flat().map((port) => (typeof port === "number" ? String(port) : `${port.min}-${port.max}`));
+
+/** One port, a range, or a list of them, as `53,0-52`. */
+export function portList(ports: Ports | undefined): string | undefined {
     if (ports === undefined) return undefined;
 
-    return [ports].flat().join(",");
+    return eachPort(ports).join(",");
 }
 
 /** Seconds as the platform writes a duration: `3600` becomes `1h`, `90` becomes `1m30s`. */
@@ -734,6 +739,7 @@ const CHAINS = ["input", "forward", "output"] as const;
 
 export function renderFirewall(out: Output, ctx: Context): void {
     for (const family of ["ipv4", "ipv6"] as const) {
+        untracked(out, ctx, family);
         filter(out, ctx, family);
         nat(out, ctx, family);
     }
@@ -742,6 +748,25 @@ export function renderFirewall(out: Output, ctx: Context): void {
     switchAcls(out, ctx);
 }
 
+/** Untracked prefixes skip connection tracking in the raw table, both ways, before a connection is ever made. */
+function untracked(out: Output, ctx: Context, family: Family): void {
+    const menu = family === "ipv4" ? "/ip firewall raw" : "/ipv6 firewall raw";
+
+    for (const prefix of ctx.device.firewall?.untracked ?? []) {
+        if (familyOf(prefix) !== family) continue;
+
+        for (const [direction, property] of [
+            ["to", "dst-address"],
+            ["from", "src-address"],
+        ] as const) {
+            out.add(
+                menu,
+                command("add", { action: "notrack", chain: "prerouting", comment: `Untracked ${direction} ${prefix}`, [property]: prefix })
+            );
+        }
+    }
+}
+
 /**
  * The families a rule applies to. An address in the rule decides it; otherwise it applies to both.
  *
@@ -836,10 +861,10 @@ function helpers(out: Output, ctx: Context): void {
 }
 
 /**
- * ACLs run in the switch chip on the port traffic arrives on. The chip matches addresses with a dotted mask on IPv4, drops by forwarding to no port, and limits by rate. A rule takes one port, so a list of ports becomes one rule for each.
+ * ACLs run in the switch chip on the port traffic arrives on. The chip matches addresses with a dotted mask on IPv4, drops by forwarding to no port, and limits by rate. A rule takes one port or range, so a list becomes one rule for each.
  */
 function switchAcls(out: Output, ctx: Context): void {
-    const each = (ports: number | readonly number[] | undefined) => (ports === undefined ? [undefined] : [ports].flat());
+    const each = (ports: Ports | undefined) => (ports === undefined ? [undefined] : eachPort(ports));
 
     for (const [port, settings] of Object.entries(ctx.ports)) {
         if (!settings.acl) continue;

package/src/presets/index.ts

@@ -41,23 +41,44 @@ export const AMPLIFIERS = {
     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. */
+const ASKED: ReadonlySet<number> = new Set([AMPLIFIERS.dns, AMPLIFIERS.ntp, AMPLIFIERS.snmp]);
+
+/** What `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[];
+};
+
 /**
- * Hardware ACL rules dropping reflected UDP floods toward `destinations`: replies from the ports in `AMPLIFIERS`, and the fragments after the first, which carry no port and which a switch chip reads as port 0. UDP from `trusted` sources, the resolvers and time servers your own hosts ask, is accepted before anything is dropped. Traffic that matches is dropped whole and everything else passes untouched, so nothing legitimate is slowed.
+ * 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 fragments after the first carry no port, and a switch chip reads them as port 0. They are dropped, but toward `keep_fragments`.
  */
-export const antiAmplification = (destinations: readonly Prefix[], trusted: readonly Prefix[] = []): AclRule<never>[] =>
-    destinations.flatMap((dst) => [
-        ...trusted.map((src): AclRule<never> => ({
-            description: `UDP to ${dst} from ${src}`,
-            match: { protocol: "udp", src, dst },
-            action: "accept",
-        })),
+export function antiAmplification(destinations: readonly Prefix[], options: AntiAmplificationOptions = {}): AclRule<never>[] {
+    const below1024Except = (port: number) => [
+        { min: 0, max: port - 1 },
+        { min: port + 1, max: 1023 },
+    ];
+
+    return destinations.flatMap((dst) => [
+        ...(options.keep_fragments ?? [])
+            .filter((prefix) => 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(AMPLIFIERS).map(([name, port]): AclRule<never> => ({
-            description: `UDP to ${dst} from ${name}`,
-            match: { protocol: "udp", dst, src_port: port },
+            description: ASKED.has(port) ? `UDP to ${dst} from ${name}, to a port below 1024` : `UDP to ${dst} from ${name}`,
+            match: { protocol: "udp", dst, src_port: port, ...(ASKED.has(port) ? { dst_port: below1024Except(port) } : {}) },
             action: "drop",
         })),
     ]);
+}
 
 /** TCP flag combinations no legitimate packet carries: name, flags set, flags unset. */
 const BAD_TCP_FLAGS = [

package/src/schema/firewall.ts

@@ -6,6 +6,12 @@ export type Protocol = "tcp" | "udp" | "icmp" | "gre" | "esp" | "ah" | "ospf" |
 /** The state connection tracking assigns a packet. */
 export type ConnectionState = "new" | "established" | "related" | "untracked" | "invalid";
 
+/** Ports from `min` to `max`, both included. */
+export type PortRange = { min: number; max: number };
+
+/** A port, a range of ports, or any of several. */
+export type Ports = number | PortRange | readonly (number | PortRange)[];
+
 /** A TCP header flag. */
 export type TcpFlag = "fin" | "syn" | "rst" | "psh" | "ack" | "urg";
 
@@ -24,9 +30,9 @@ export type FilterMatch<I extends string, AS extends string> = {
     /** Destination is in this address set. */
     dst_set?: AS;
     /** Source port, or any of several. TCP and UDP only. */
-    src_port?: number | readonly number[];
+    src_port?: Ports;
     /** Destination port, or any of several. TCP and UDP only. */
-    dst_port?: number | readonly number[];
+    dst_port?: Ports;
     /** Arrived on this interface. */
     in_interface?: I;
     /** Leaves through this interface. */
@@ -98,6 +104,8 @@ export type Firewall<I extends string, AS extends string> = {
     };
     /** Helpers that run. None when absent. */
     helpers?: readonly Helper[];
+    /** Traffic to and from these prefixes passes without connection tracking. A flood toward them cannot fill the connection table, and rules see its packets in the state `untracked`. Everything is tracked when absent. */
+    untracked?: readonly Prefix[];
 };
 
 /** A stateless rule evaluated in hardware where traffic arrives, before routing. */
@@ -115,9 +123,9 @@ export type AclRule<V extends string> = {
         /** Destination prefix. */
         dst?: Prefix;
         /** Source port, or any of several. */
-        src_port?: number | readonly number[];
+        src_port?: Ports;
         /** Destination port, or any of several. */
-        dst_port?: number | readonly number[];
+        dst_port?: Ports;
         /** Carried in this VLAN. */
         vlan?: V;
     };