@takodotid/circuit 0.15.0 → 0.17.0

package/dist/cli/index.js

@@ -2021,6 +2021,7 @@ function helpers(out, ctx) {
   }
 }
 function switchAcls(out, ctx) {
+  const each = (ports) => ports === undefined ? [undefined] : [ports].flat();
   for (const [port, settings] of Object.entries(ctx.ports)) {
     if (!settings.acl)
       continue;
@@ -2028,20 +2029,24 @@ function switchAcls(out, ctx) {
       const match = rule.match ?? {};
       const ipv6 = match.family === "ipv6" || [match.src, match.dst].some((address2) => address2 && familyOf(address2) === "ipv6");
       const address = (prefix) => prefix && !ipv6 ? dottedMask(prefix) : prefix;
-      out.add("/interface ethernet switch rule", command("add", {
-        comment: rule.description,
-        [ipv6 ? "dst-address6" : "dst-address"]: address(match.dst),
-        "dst-port": portList(match.dst_port),
-        "mac-protocol": ipv6 ? "ipv6" : "ip",
-        "new-dst-ports": rule.action === "drop" ? "" : undefined,
-        ports: ctx.name(port),
-        protocol: match.protocol,
-        rate: rule.rate && bitrate(rule.rate),
-        [ipv6 ? "src-address6" : "src-address"]: address(match.src),
-        "src-port": portList(match.src_port),
-        switch: "switch1",
-        "vlan-id": match.vlan && ctx.vlanId(match.vlan)
-      }));
+      for (const srcPort of each(match.src_port)) {
+        for (const dstPort of each(match.dst_port)) {
+          out.add("/interface ethernet switch rule", command("add", {
+            comment: rule.description,
+            [ipv6 ? "dst-address6" : "dst-address"]: address(match.dst),
+            "dst-port": dstPort,
+            "mac-protocol": ipv6 ? "ipv6" : "ip",
+            "new-dst-ports": rule.action === "drop" ? "" : undefined,
+            ports: ctx.name(port),
+            protocol: match.protocol,
+            rate: rule.rate && bitrate(rule.rate),
+            [ipv6 ? "src-address6" : "src-address"]: address(match.src),
+            "src-port": srcPort,
+            switch: "switch1",
+            "vlan-id": match.vlan && ctx.vlanId(match.vlan)
+          }));
+        }
+      }
     }
   }
 }

package/dist/presets/index.js

@@ -11,6 +11,40 @@ var antiSpoofing = (vlan, sources) => sources.map((src) => ({
   match: { vlan, src },
   action: "drop"
 }));
+var AMPLIFIERS = {
+  qotd: 17,
+  chargen: 19,
+  dns: 53,
+  portmap: 111,
+  ntp: 123,
+  netbios: 137,
+  snmp: 161,
+  cldap: 389,
+  slp: 427,
+  rip: 520,
+  "ms-sql": 1434,
+  ssdp: 1900,
+  ard: 3283,
+  "ws-discovery": 3702,
+  mdns: 5353,
+  coap: 5683,
+  ubiquiti: 10001,
+  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 BAD_TCP_FLAGS = [
   ["FIN+SYN", ["fin", "syn"], []],
   ["SYN+RST", ["syn", "rst"], []],
@@ -160,22 +194,15 @@ function communityScheme(scheme) {
   const community = (fn, parameter) => `${asn}:${fn}:${parameter}`;
   const ours = { standard: [`${asn}:*`], large: [`${asn}:*:*`] };
   const information = [scheme.learned_from?.function, scheme.learned_at?.function, scheme.learned_from_as].filter((fn) => fn !== undefined);
-  const requests = [
-    { functions: [scheme.do_not_announce?.function], trusted: scheme.do_not_announce?.trusted },
-    { functions: PREPENDS.map(([name]) => scheme.prepend?.[name]), trusted: scheme.prepend?.trusted },
-    { functions: [scheme.blackhole?.function], trusted: scheme.blackhole?.trusted }
-  ].map(({ functions, trusted }) => ({ functions: functions.filter((fn) => fn !== undefined), trusted: trusted ?? [] }));
   const tag = (neighborClass, neighborAs, options = {}) => {
-    const { site } = options;
-    const untrusted = requests.filter((request) => !request.trusted.includes(neighborClass)).flatMap((request) => request.functions);
-    const trustedForAny = requests.some((request) => request.functions.length && request.trusted.includes(neighborClass));
+    const { site, trusted = false } = options;
     if (scheme.learned_at && site === undefined)
       throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
     return {
       description: `Learned from AS${neighborAs}`,
       set: {
         remove_communities: ours.standard,
-        remove_large_communities: trustedForAny ? [...information, ...untrusted].map((fn) => community(fn, "*")) : ours.large,
+        remove_large_communities: trusted ? information.map((fn) => community(fn, "*")) : ours.large,
         add_large_communities: [
           ...scheme.learned_from ? [community(scheme.learned_from.function, scheme.learned_from.classes[neighborClass])] : [],
           ...scheme.learned_at ? [community(scheme.learned_at.function, site)] : [],
@@ -184,67 +211,69 @@ function communityScheme(scheme) {
       }
     };
   };
-  const blackhole = (neighborClass, prefixSet) => {
-    if (scheme.blackhole === undefined)
+  const blackhole = (prefixSets) => {
+    const fn = scheme.blackhole?.function;
+    if (fn === undefined)
       throw new Error("communityScheme: blackhole needs a function number in the scheme");
-    if (!scheme.blackhole.trusted.includes(neighborClass))
-      throw new Error(`communityScheme: ${neighborClass} is not trusted to ask for a blackhole`);
-    return {
+    return prefixSets.map((prefixSet) => ({
       description: "Blackhole, asked by the neighbor",
-      match: { large_community: community(scheme.blackhole.function, 0), prefix_set: prefixSet },
+      match: { large_community: community(fn, 0), prefix_set: prefixSet },
       set: { blackhole: true },
       action: "accept"
-    };
+    }));
   };
-  const actions = (neighborAs, options = {}) => [
-    ...scheme.blackhole !== undefined && !options.blackhole ? [
-      {
-        description: "Blackholed here, never announced",
-        match: { large_community: community(scheme.blackhole.function, 0) },
-        action: "reject"
-      }
-    ] : [],
-    ...scheme.do_not_announce !== undefined ? [
-      {
-        description: "Asked not to be announced anywhere",
-        match: { large_community: community(scheme.do_not_announce.function, 0) },
-        action: "reject"
-      },
-      {
-        description: `Asked not to be announced to AS${neighborAs}`,
-        match: { large_community: community(scheme.do_not_announce.function, neighborAs) },
-        action: "reject"
-      }
-    ] : [],
-    ...scheme.blackhole !== undefined && options.blackhole ? [
-      {
-        description: `Blackhole passed on to AS${neighborAs}`,
-        match: { large_community: community(scheme.blackhole.function, 0) },
-        set: {
-          remove_communities: ours.standard,
-          remove_large_communities: ours.large,
-          add_communities: [options.blackhole]
+  const actions = (neighborAs) => {
+    const passOn = scheme.blackhole?.upstreams?.[neighborAs];
+    return [
+      ...scheme.blackhole !== undefined && !passOn ? [
+        {
+          description: "Blackholed here, never announced",
+          match: { large_community: community(scheme.blackhole.function, 0) },
+          action: "reject"
+        }
+      ] : [],
+      ...scheme.do_not_announce !== undefined ? [
+        {
+          description: "Asked not to be announced anywhere",
+          match: { large_community: community(scheme.do_not_announce, 0) },
+          action: "reject"
         },
-        action: "accept"
-      }
-    ] : [],
-    ...PREPENDS.flatMap(([name, times]) => {
-      const fn = scheme.prepend?.[name];
-      if (fn === undefined)
-        return [];
-      return [
         {
-          description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
-          match: { large_community: community(fn, neighborAs) },
-          set: { prepend: times }
+          description: `Asked not to be announced to AS${neighborAs}`,
+          match: { large_community: community(scheme.do_not_announce, neighborAs) },
+          action: "reject"
         }
-      ];
-    }),
-    {
-      description: "Our communities stay inside our network",
-      set: { remove_communities: ours.standard, remove_large_communities: ours.large }
-    }
-  ];
+      ] : [],
+      ...scheme.blackhole !== undefined && passOn ? [
+        {
+          description: `Blackhole passed on to AS${neighborAs}`,
+          match: { large_community: community(scheme.blackhole.function, 0) },
+          set: {
+            remove_communities: ours.standard,
+            remove_large_communities: ours.large,
+            add_communities: [passOn]
+          },
+          action: "accept"
+        }
+      ] : [],
+      ...PREPENDS.flatMap(([name, times]) => {
+        const fn = scheme.prepend?.[name];
+        if (fn === undefined)
+          return [];
+        return [
+          {
+            description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
+            match: { large_community: community(fn, neighborAs) },
+            set: { prepend: times }
+          }
+        ];
+      }),
+      {
+        description: "Our communities stay inside our network",
+        set: { remove_communities: ours.standard, remove_large_communities: ours.large }
+      }
+    ];
+  };
   const catalogue = [
     ...Object.entries(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
       community: community(scheme.learned_from.function, value),
@@ -259,14 +288,19 @@ function communityScheme(scheme) {
     ] : [],
     ...scheme.learned_from_as !== undefined ? [{ community: community(scheme.learned_from_as, "nnn"), description: "Learned from AS$0" }] : [],
     ...scheme.do_not_announce !== undefined ? [
-      { community: community(scheme.do_not_announce.function, 0), description: "Do not announce to anyone" },
-      { community: community(scheme.do_not_announce.function, "nnn"), description: "Do not announce to AS$0" }
+      { community: community(scheme.do_not_announce, 0), description: "Do not announce to anyone" },
+      { community: community(scheme.do_not_announce, "nnn"), description: "Do not announce to AS$0" }
     ] : [],
     ...PREPENDS.flatMap(([name]) => {
       const fn = scheme.prepend?.[name];
       return fn === undefined ? [] : [{ community: community(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
     }),
-    ...scheme.blackhole !== undefined ? [{ community: community(scheme.blackhole.function, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }] : []
+    ...scheme.blackhole !== undefined ? [
+      {
+        community: community(scheme.blackhole.function, 0),
+        description: Object.keys(scheme.blackhole.upstreams ?? {}).length ? `Blackhole: dropped in AS${asn} and by its upstreams that take it` : `Blackhole: dropped in AS${asn}, not announced further`
+      }
+    ] : []
   ];
   return { community, tag, actions, blackhole, catalogue };
 }
@@ -337,6 +371,8 @@ export {
   bgpSanity,
   badTcpFlags,
   antiSpoofing,
+  antiAmplification,
   PRIVATE_RANGES,
-  MARTIANS
+  MARTIANS,
+  AMPLIFIERS
 };

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

@@ -6,6 +6,32 @@ export declare const MARTIANS: readonly ["127.0.0.0/8", "169.254.0.0/16", "0.0.0
 export declare const PRIVATE_RANGES: readonly ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"];
 /** 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 declare const antiSpoofing: <V extends string>(vlan: V, sources: readonly Prefix[]) => AclRule<V>[];
+/** UDP ports of services that answer a small request with a much larger reply, which attackers use to reflect floods at a victim. A reflected flood arrives from these ports. */
+export declare const AMPLIFIERS: {
+    readonly qotd: 17;
+    readonly chargen: 19;
+    readonly dns: 53;
+    readonly portmap: 111;
+    readonly ntp: 123;
+    readonly netbios: 137;
+    readonly snmp: 161;
+    readonly cldap: 389;
+    readonly slp: 427;
+    readonly rip: 520;
+    readonly "ms-sql": 1434;
+    readonly ssdp: 1900;
+    readonly ard: 3283;
+    readonly "ws-discovery": 3702;
+    readonly mdns: 5353;
+    readonly coap: 5683;
+    readonly ubiquiti: 10001;
+    readonly memcached: 11211;
+    readonly dvr: 37810;
+};
+/**
+ * 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.
+ */
+export declare const antiAmplification: (destinations: readonly Prefix[], trusted?: readonly Prefix[]) => 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. */
@@ -72,42 +98,39 @@ export type CommunityScheme<Class extends string = string> = {
     /** Set on import: the AS a route was learned from, `asn:function:asn`. */
     learned_from_as?: number;
     /** A neighbor asks: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
-    do_not_announce?: Request<Class> & {
-        function: number;
-    };
+    do_not_announce?: number;
     /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
-    prepend?: Request<Class> & {
+    prepend?: {
         once?: number;
         twice?: number;
         three_times?: number;
     };
-    /** A neighbor asks: drop traffic to the route in your network, before it reaches them, `asn:function:0`. */
-    blackhole?: Request<Class> & {
+    /**
+     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it, and so does every upstream in `upstreams`.
+     *
+     * `upstreams` maps an upstream's AS to its own blackhole community, as its NOC gives it. The route is passed to that upstream with it, so the traffic stops before it reaches your links. An upstream not listed never receives the route.
+     */
+    blackhole?: {
         function: number;
+        upstreams?: Readonly<Record<number, string>>;
     };
 };
-/** Something a neighbor can ask you for, and who may. */
-type Request<Class extends string> = {
-    /** The classes allowed to ask for it, from `learned_from.classes`. From anyone else, the request is removed when the route comes in. */
-    trusted: readonly NoInfer<Class>[];
-};
 /**
  * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
  *
- * - `tag(neighborClass, neighborAs, { site })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A neighbor keeps the requests its class is trusted with. `site` is needed when the scheme has `learned_at`.
+ * - `tag(neighborClass, neighborAs, { site, trusted })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A `trusted` neighbor keeps its requests: do not announce, prepend, blackhole. `site` is needed when the scheme has `learned_at`.
  * - `actions(neighborAs, { blackhole })`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept. A blackholed route goes no further, unless `blackhole` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too.
- * - `blackhole(neighborClass, prefixSet)`: a rule for the import policy of a neighbor trusted with blackholes, before anything that rejects long prefixes. It takes a route the neighbor asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
+ * - `blackhole(prefixSets)`: rules for the import policy of a neighbor you trust with blackholes, before anything that rejects long prefixes. They take a route the neighbor asked to blackhole, but only inside `prefixSets`, its own space, and drop traffic to it here. One rule per set, so one call covers both families.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
 export declare function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>): {
     community: (fn: number, parameter: number | string) => string;
     tag: (neighborClass: Class, neighborAs: number, options?: {
         site?: number;
+        trusted?: boolean;
     }) => PolicyRule<never, never>;
-    actions: (neighborAs: number, options?: {
-        blackhole?: string;
-    }) => PolicyRule<never, never>[];
-    blackhole: <S extends string>(neighborClass: Class, prefixSet: S) => PolicyRule<never, S>;
+    actions: (neighborAs: number) => PolicyRule<never, never>[];
+    blackhole: <S extends string>(prefixSets: readonly S[]) => PolicyRule<never, S>[];
     catalogue: Community[];
 };
 /** A member of an internet exchange: a network with a port on the fabric and an address on the peering LAN. */
@@ -145,4 +168,3 @@ export declare function internetExchange<const V extends string>(exchange: Inter
     ports: (device: string) => Record<string, Port<V, string, string, string>>;
     check: Check;
 };
-export {};

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

@@ -113,6 +113,6 @@ export type AclRule<V extends string> = {
     };
     /** What happens to a matching packet. */
     action: "accept" | "drop";
-    /** Accepted traffic above this rate is dropped. */
+    /** Accepted traffic above this rate is dropped. On RouterOS it did not limit traffic the CPU routes; see its TRAPS.md. */
     rate?: Rate;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.15.0",
+    "version": "0.17.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

@@ -14,6 +14,9 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - `tcp-md5-key` set from the CLI has been seen discarded without an error, and a mismatch logs nothing. Confirm with `/tool sniffer quick port=179`.
 - Incoming GRE is subject to the input chain. Accept it before testing the tunnel.
 - Switch-chip rules have no address lists and no connection state. A drop is an empty `new-dst-ports`.
+- 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.
 - 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

@@ -836,9 +836,11 @@ 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.
+ * 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.
  */
 function switchAcls(out: Output, ctx: Context): void {
+    const each = (ports: number | readonly number[] | undefined) => (ports === undefined ? [undefined] : [ports].flat());
+
     for (const [port, settings] of Object.entries(ctx.ports)) {
         if (!settings.acl) continue;
 
@@ -847,23 +849,27 @@ function switchAcls(out: Output, ctx: Context): void {
             const ipv6 = match.family === "ipv6" || [match.src, match.dst].some((address) => address && familyOf(address) === "ipv6");
             const address = (prefix: string | undefined) => (prefix && !ipv6 ? dottedMask(prefix) : prefix);
 
-            out.add(
-                "/interface ethernet switch rule",
-                command("add", {
-                    comment: rule.description,
-                    [ipv6 ? "dst-address6" : "dst-address"]: address(match.dst),
-                    "dst-port": portList(match.dst_port),
-                    "mac-protocol": ipv6 ? "ipv6" : "ip",
-                    "new-dst-ports": rule.action === "drop" ? "" : undefined,
-                    ports: ctx.name(port),
-                    protocol: match.protocol,
-                    rate: rule.rate && bitrate(rule.rate),
-                    [ipv6 ? "src-address6" : "src-address"]: address(match.src),
-                    "src-port": portList(match.src_port),
-                    switch: "switch1",
-                    "vlan-id": match.vlan && ctx.vlanId(match.vlan),
-                })
-            );
+            for (const srcPort of each(match.src_port)) {
+                for (const dstPort of each(match.dst_port)) {
+                    out.add(
+                        "/interface ethernet switch rule",
+                        command("add", {
+                            comment: rule.description,
+                            [ipv6 ? "dst-address6" : "dst-address"]: address(match.dst),
+                            "dst-port": dstPort,
+                            "mac-protocol": ipv6 ? "ipv6" : "ip",
+                            "new-dst-ports": rule.action === "drop" ? "" : undefined,
+                            ports: ctx.name(port),
+                            protocol: match.protocol,
+                            rate: rule.rate && bitrate(rule.rate),
+                            [ipv6 ? "src-address6" : "src-address"]: address(match.src),
+                            "src-port": srcPort,
+                            switch: "switch1",
+                            "vlan-id": match.vlan && ctx.vlanId(match.vlan),
+                        })
+                    );
+                }
+            }
         }
     }
 }

package/src/presets/index.ts

@@ -18,6 +18,47 @@ export const antiSpoofing = <V extends string>(vlan: V, sources: readonly Prefix
         action: "drop",
     }));
 
+/** UDP ports of services that answer a small request with a much larger reply, which attackers use to reflect floods at a victim. A reflected flood arrives from these ports. */
+export const AMPLIFIERS = {
+    qotd: 17,
+    chargen: 19,
+    dns: 53,
+    portmap: 111,
+    ntp: 123,
+    netbios: 137,
+    snmp: 161,
+    cldap: 389,
+    slp: 427,
+    rip: 520,
+    "ms-sql": 1434,
+    ssdp: 1900,
+    ard: 3283,
+    "ws-discovery": 3702,
+    mdns: 5353,
+    coap: 5683,
+    ubiquiti: 10001,
+    memcached: 11211,
+    dvr: 37810,
+} as const satisfies Record<string, number>;
+
+/**
+ * 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.
+ */
+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",
+        })),
+        { 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 },
+            action: "drop",
+        })),
+    ]);
+
 /** TCP flag combinations no legitimate packet carries: name, flags set, flags unset. */
 const BAD_TCP_FLAGS = [
     ["FIN+SYN", ["fin", "syn"], []],
@@ -231,17 +272,15 @@ export type CommunityScheme<Class extends string = string> = {
     /** Set on import: the AS a route was learned from, `asn:function:asn`. */
     learned_from_as?: number;
     /** A neighbor asks: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
-    do_not_announce?: Request<Class> & { function: number };
+    do_not_announce?: number;
     /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
-    prepend?: Request<Class> & { once?: number; twice?: number; three_times?: number };
-    /** A neighbor asks: drop traffic to the route in your network, before it reaches them, `asn:function:0`. */
-    blackhole?: Request<Class> & { function: number };
-};
-
-/** Something a neighbor can ask you for, and who may. */
-type Request<Class extends string> = {
-    /** The classes allowed to ask for it, from `learned_from.classes`. From anyone else, the request is removed when the route comes in. */
-    trusted: readonly NoInfer<Class>[];
+    prepend?: { once?: number; twice?: number; three_times?: number };
+    /**
+     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it, and so does every upstream in `upstreams`.
+     *
+     * `upstreams` maps an upstream's AS to its own blackhole community, as its NOC gives it. The route is passed to that upstream with it, so the traffic stops before it reaches your links. An upstream not listed never receives the route.
+     */
+    blackhole?: { function: number; upstreams?: Readonly<Record<number, string>> };
 };
 
 const PREPENDS = [
@@ -255,9 +294,9 @@ const article = (word: string) => (/^[aeiou]/i.test(word) ? `an ${word}` : `a ${
 /**
  * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
  *
- * - `tag(neighborClass, neighborAs, { site })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A neighbor keeps the requests its class is trusted with. `site` is needed when the scheme has `learned_at`.
+ * - `tag(neighborClass, neighborAs, { site, trusted })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A `trusted` neighbor keeps its requests: do not announce, prepend, blackhole. `site` is needed when the scheme has `learned_at`.
  * - `actions(neighborAs, { blackhole })`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept. A blackholed route goes no further, unless `blackhole` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too.
- * - `blackhole(neighborClass, prefixSet)`: a rule for the import policy of a neighbor trusted with blackholes, before anything that rejects long prefixes. It takes a route the neighbor asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
+ * - `blackhole(prefixSets)`: rules for the import policy of a neighbor you trust with blackholes, before anything that rejects long prefixes. They take a route the neighbor asked to blackhole, but only inside `prefixSets`, its own space, and drop traffic to it here. One rule per set, so one call covers both families.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
 export function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>) {
@@ -269,17 +308,12 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         (fn): fn is number => fn !== undefined
     );
 
-    // Each request's function numbers, and who may make it.
-    const requests = [
-        { functions: [scheme.do_not_announce?.function], trusted: scheme.do_not_announce?.trusted },
-        { functions: PREPENDS.map(([name]) => scheme.prepend?.[name]), trusted: scheme.prepend?.trusted },
-        { functions: [scheme.blackhole?.function], trusted: scheme.blackhole?.trusted },
-    ].map(({ functions, trusted }) => ({ functions: functions.filter((fn): fn is number => fn !== undefined), trusted: trusted ?? [] }));
-
-    const tag = (neighborClass: Class, neighborAs: number, options: { site?: number } = {}): PolicyRule<never, never> => {
-        const { site } = options;
-        const untrusted = requests.filter((request) => !request.trusted.includes(neighborClass)).flatMap((request) => request.functions);
-        const trustedForAny = requests.some((request) => request.functions.length && request.trusted.includes(neighborClass));
+    const tag = (
+        neighborClass: Class,
+        neighborAs: number,
+        options: { site?: number; trusted?: boolean } = {}
+    ): PolicyRule<never, never> => {
+        const { site, trusted = false } = options;
         if (scheme.learned_at && site === undefined)
             throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
 
@@ -287,8 +321,8 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             description: `Learned from AS${neighborAs}`,
             set: {
                 remove_communities: ours.standard,
-                // A neighbor trusted with nothing loses every community of ours it set. One trusted with some requests keeps those, and loses the rest.
-                remove_large_communities: trustedForAny ? [...information, ...untrusted].map((fn) => community(fn, "*")) : ours.large,
+                // A trusted neighbor keeps its requests and loses only the "where it came from" tags, which are ours to set. Anyone else loses every community of ours.
+                remove_large_communities: trusted ? information.map((fn) => community(fn, "*")) : ours.large,
                 add_large_communities: [
                     ...(scheme.learned_from ? [community(scheme.learned_from.function, scheme.learned_from.classes[neighborClass])] : []),
                     ...(scheme.learned_at ? [community(scheme.learned_at.function, site!)] : []),
@@ -298,74 +332,78 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         };
     };
 
-    const blackhole = <S extends string>(neighborClass: Class, prefixSet: S): PolicyRule<never, S> => {
-        if (scheme.blackhole === undefined) throw new Error("communityScheme: blackhole needs a function number in the scheme");
-        if (!scheme.blackhole.trusted.includes(neighborClass))
-            throw new Error(`communityScheme: ${neighborClass} is not trusted to ask for a blackhole`);
+    const blackhole = <S extends string>(prefixSets: readonly S[]): PolicyRule<never, S>[] => {
+        const fn = scheme.blackhole?.function;
+        if (fn === undefined) throw new Error("communityScheme: blackhole needs a function number in the scheme");
 
-        return {
+        return prefixSets.map((prefixSet) => ({
             description: "Blackhole, asked by the neighbor",
-            match: { large_community: community(scheme.blackhole.function, 0), prefix_set: prefixSet },
+            match: { large_community: community(fn, 0), prefix_set: prefixSet },
             set: { blackhole: true },
             action: "accept",
-        };
+        }));
     };
 
-    const actions = (neighborAs: number, options: { blackhole?: string } = {}): PolicyRule<never, never>[] => [
-        ...(scheme.blackhole !== undefined && !options.blackhole
-            ? [
-                  {
-                      description: "Blackholed here, never announced",
-                      match: { large_community: community(scheme.blackhole.function, 0) },
-                      action: "reject" as const,
-                  },
-              ]
-            : []),
-        ...(scheme.do_not_announce !== undefined
-            ? [
-                  {
-                      description: "Asked not to be announced anywhere",
-                      match: { large_community: community(scheme.do_not_announce.function, 0) },
-                      action: "reject" as const,
-                  },
-                  {
-                      description: `Asked not to be announced to AS${neighborAs}`,
-                      match: { large_community: community(scheme.do_not_announce.function, neighborAs) },
-                      action: "reject" as const,
-                  },
-              ]
-            : []),
-        ...(scheme.blackhole !== undefined && options.blackhole
-            ? [
-                  {
-                      description: `Blackhole passed on to AS${neighborAs}`,
-                      match: { large_community: community(scheme.blackhole.function, 0) },
-                      set: {
-                          remove_communities: ours.standard,
-                          remove_large_communities: ours.large,
-                          add_communities: [options.blackhole],
+    const actions = (neighborAs: number): PolicyRule<never, never>[] => {
+        // The upstream's own blackhole community, when it takes blackholes from us.
+        const passOn = scheme.blackhole?.upstreams?.[neighborAs];
+
+        return [
+            ...(scheme.blackhole !== undefined && !passOn
+                ? [
+                      {
+                          description: "Blackholed here, never announced",
+                          match: { large_community: community(scheme.blackhole.function, 0) },
+                          action: "reject" as const,
                       },
-                      action: "accept" as const,
-                  },
-              ]
-            : []),
-        ...PREPENDS.flatMap(([name, times]) => {
-            const fn = scheme.prepend?.[name];
-            if (fn === undefined) return [];
-
-            return [
-                {
-                    description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
-                    match: { large_community: community(fn, neighborAs) },
-                    set: { prepend: times },
-                },
-            ];
-        }),
-        {
-            description: "Our communities stay inside our network",
-            set: { remove_communities: ours.standard, remove_large_communities: ours.large },
-        },
-    ];
+                  ]
+                : []),
+            ...(scheme.do_not_announce !== undefined
+                ? [
+                      {
+                          description: "Asked not to be announced anywhere",
+                          match: { large_community: community(scheme.do_not_announce, 0) },
+                          action: "reject" as const,
+                      },
+                      {
+                          description: `Asked not to be announced to AS${neighborAs}`,
+                          match: { large_community: community(scheme.do_not_announce, neighborAs) },
+                          action: "reject" as const,
+                      },
+                  ]
+                : []),
+            ...(scheme.blackhole !== undefined && passOn
+                ? [
+                      {
+                          description: `Blackhole passed on to AS${neighborAs}`,
+                          match: { large_community: community(scheme.blackhole.function, 0) },
+                          set: {
+                              remove_communities: ours.standard,
+                              remove_large_communities: ours.large,
+                              add_communities: [passOn],
+                          },
+                          action: "accept" as const,
+                      },
+                  ]
+                : []),
+            ...PREPENDS.flatMap(([name, times]) => {
+                const fn = scheme.prepend?.[name];
+                if (fn === undefined) return [];
+
+                return [
+                    {
+                        description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
+                        match: { large_community: community(fn, neighborAs) },
+                        set: { prepend: times },
+                    },
+                ];
+            }),
+            {
+                description: "Our communities stay inside our network",
+                set: { remove_communities: ours.standard, remove_large_communities: ours.large },
+            },
+        ];
+    };
 
     const catalogue: Community[] = [
         ...Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
@@ -386,8 +424,8 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             : []),
         ...(scheme.do_not_announce !== undefined
             ? [
-                  { community: community(scheme.do_not_announce.function, 0), description: "Do not announce to anyone" },
-                  { community: community(scheme.do_not_announce.function, "nnn"), description: "Do not announce to AS$0" },
+                  { community: community(scheme.do_not_announce, 0), description: "Do not announce to anyone" },
+                  { community: community(scheme.do_not_announce, "nnn"), description: "Do not announce to AS$0" },
               ]
             : []),
         ...PREPENDS.flatMap(([name]) => {
@@ -395,7 +433,14 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             return fn === undefined ? [] : [{ community: community(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
         }),
         ...(scheme.blackhole !== undefined
-            ? [{ community: community(scheme.blackhole.function, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }]
+            ? [
+                  {
+                      community: community(scheme.blackhole.function, 0),
+                      description: Object.keys(scheme.blackhole.upstreams ?? {}).length
+                          ? `Blackhole: dropped in AS${asn} and by its upstreams that take it`
+                          : `Blackhole: dropped in AS${asn}, not announced further`,
+                  },
+              ]
             : []),
     ];
 

package/src/schema/firewall.ts

@@ -123,6 +123,6 @@ export type AclRule<V extends string> = {
     };
     /** What happens to a matching packet. */
     action: "accept" | "drop";
-    /** Accepted traffic above this rate is dropped. */
+    /** Accepted traffic above this rate is dropped. On RouterOS it did not limit traffic the CPU routes; see its TRAPS.md. */
     rate?: Rate;
 };