@push.rocks/smartnftables 4.0.1 → 4.2.0

package/rust/src/owner_exclusiveforwarding_tests.rs

@@ -0,0 +1,200 @@
+//! Exclusive forwarding qualified on a host namespace that forwards IPv4 and
+//! IPv6 between a handoff, an uplink and a LAN link no scope binds.
+use super::egress_traffic_tests::{connect, host_policy, ns_ip, roundtrip, socket};
+use super::host_traffic_tests::{control, ipv6_pair};
+use super::*;
+use crate::egress;
+use std::net::UdpSocket;
+use std::time::Duration;
+
+const SOURCE: &str = "xf_source";
+const HOST: &str = "xf_host";
+const PEER: &str = "xf_peer";
+const LAN: &str = "xf_lan";
+
+/// The fixture host policy at `revision`, with the member and the handoffs
+/// chosen. It reads the bound links, so it runs in the host namespace.
+fn policy(revision: u64, exclusive: bool, handoffs: bool) -> Prepared {
+    let mut policy = host_policy();
+    policy.revision = revision;
+    let egress::Scope::HostTransit(scope) = &mut policy.scope else {
+        panic!()
+    };
+    scope.exclusive_forwarding = exclusive;
+    if !handoffs {
+        scope.handoffs.clear();
+    }
+    let target: Prepared = policy.prepare().unwrap().into();
+    target
+        .validate_interfaces()
+        .expect("exclusive forwarding fixture binding");
+    target
+}
+/// A UDP socket in `ns` on an address built at run time.
+fn bound(ns: &str, address: String) -> UdpSocket {
+    let socket = in_namespace(ns, move || UdpSocket::bind(address).unwrap());
+    socket
+        .set_read_timeout(Some(Duration::from_millis(250)))
+        .unwrap();
+    socket
+}
+/// Every forward this host performs for the LAN link: the host as the LAN's
+/// gateway to the uplink peer, the peer's way back into the LAN, and the same
+/// gateway for IPv6. Fresh ports per call give each probe its own conntrack entry.
+fn lan_probes(port: u16, allowed: bool) {
+    for (from, source, to, destination) in [
+        (
+            LAN,
+            format!("172.16.0.2:{port}"),
+            PEER,
+            format!("192.0.2.3:{port}"),
+        ),
+        (
+            PEER,
+            format!("192.0.2.3:{}", port + 1),
+            LAN,
+            format!("172.16.0.2:{}", port + 1),
+        ),
+        (
+            LAN,
+            format!("[fd00:16::2]:{port}"),
+            PEER,
+            format!("[2001:db8:190::3]:{port}"),
+        ),
+    ] {
+        let target = bound(to, destination.clone());
+        control(&bound(from, source), &destination, &target, allowed);
+    }
+}
+/// Replaces the applied policy with `policy(revision, exclusive, handoffs)`,
+/// bound in the host namespace that holds the links.
+fn reconcile(
+    owner: Owner,
+    previous: Applied,
+    (revision, exclusive, handoffs): (u64, bool, bool),
+) -> (Owner, Applied) {
+    in_namespace(HOST, move || {
+        let mut owner = owner;
+        let applied = owner
+            .reconcile(Transition {
+                previous: Some(previous),
+                target: policy(revision, exclusive, handoffs),
+            })
+            .unwrap();
+        assert!(owner.inspect().enforced);
+        (owner, applied)
+    })
+}
+
+#[test]
+#[ignore = "requires disposable isolated native qualification guest"]
+fn v2_host_exclusive_forwarding_forwards_only_the_scope_and_withdraws_cleanly() {
+    isolated();
+    for name in [SOURCE, HOST, PEER, LAN] {
+        ip(&["netns", "add", name]);
+        ns_ip(name, &["link", "set", "lo", "up"]);
+        in_namespace(name, || {
+            std::fs::write("/proc/sys/net/ipv4/ip_forward", "1").unwrap();
+            std::fs::write("/proc/sys/net/ipv6/conf/all/forwarding", "1").unwrap();
+        });
+    }
+    connect(
+        SOURCE,
+        "source",
+        "10.240.0.2/30",
+        HOST,
+        "router",
+        "10.240.0.1/30",
+    );
+    connect(
+        HOST,
+        "uplink",
+        "192.0.2.2/24",
+        PEER,
+        "underlay",
+        "192.0.2.3/24",
+    );
+    connect(
+        HOST,
+        "lanlink",
+        "172.16.0.1/24",
+        LAN,
+        "lanpeer",
+        "172.16.0.2/24",
+    );
+    ns_ip(SOURCE, &["route", "add", "default", "via", "10.240.0.1"]);
+    ns_ip(PEER, &["route", "add", "default", "via", "192.0.2.2"]);
+    ns_ip(LAN, &["route", "add", "default", "via", "172.16.0.1"]);
+    ipv6_pair(
+        HOST,
+        "uplink",
+        "2001:db8:190::108",
+        PEER,
+        "underlay",
+        "2001:db8:190::3",
+    );
+    ipv6_pair(HOST, "lanlink", "fd00:16::1", LAN, "lanpeer", "fd00:16::2");
+    ns_ip(
+        PEER,
+        &["-6", "route", "add", "default", "via", "2001:db8:190::108"],
+    );
+    ns_ip(LAN, &["-6", "route", "add", "default", "via", "fd00:16::1"]);
+    // The leased egress path: the transit source and a leased port to the
+    // uplink peer's platform endpoint, answered through outer SNAT.
+    let leased = socket(SOURCE, "10.240.0.2:10000");
+    let platform = socket(PEER, "192.0.2.3:5300");
+    let unleased = socket(SOURCE, "10.240.0.2:9999");
+    // Positive controls: without any policy the host forwards for the LAN in
+    // both directions and both families.
+    lan_probes(41000, true);
+    // The scope without the member leaves forwarding outside its handoffs to
+    // other owners, so every later denial is caused by the member.
+    let (owner, applied) = in_namespace(HOST, || {
+        let mut owner = Owner::new(options("host_exclusive")).unwrap();
+        let applied = owner
+            .reconcile(Transition {
+                previous: None,
+                target: policy(1, false, true),
+            })
+            .unwrap();
+        assert!(owner.inspect().enforced);
+        (owner, applied)
+    });
+    lan_probes(41010, true);
+    assert_eq!(roundtrip(&leased, &platform).ip().to_string(), "192.0.2.2");
+    // A LAN flow already established through the host before the member.
+    let established = socket(LAN, "172.16.0.2:41100");
+    let established_target = socket(PEER, "192.0.2.3:41100");
+    assert_eq!(
+        roundtrip(&established, &established_target)
+            .ip()
+            .to_string(),
+        "172.16.0.2"
+    );
+    // Exclusive: only the scope's leased handoff flows still cross the host.
+    let (owner, applied) = reconcile(owner, applied, (2, true, true));
+    lan_probes(41020, false);
+    control(&established, "192.0.2.3:41100", &established_target, false);
+    assert_eq!(roundtrip(&leased, &platform).ip().to_string(), "192.0.2.2");
+    control(&unleased, "192.0.2.3:5300", &platform, false);
+    // Without handoffs the exclusive scope forwards nothing at all.
+    let (owner, applied) = reconcile(owner, applied, (3, true, false));
+    lan_probes(41030, false);
+    control(&leased, "192.0.2.3:5300", &platform, false);
+    // Replacing it with a scope without the member reopens the LAN path.
+    let (owner, applied) = reconcile(owner, applied, (4, false, true));
+    lan_probes(41040, true);
+    assert_eq!(roundtrip(&leased, &platform).ip().to_string(), "192.0.2.2");
+    // Release of an exclusive scope reopens it as well.
+    let (owner, applied) = reconcile(owner, applied, (5, true, true));
+    lan_probes(41050, false);
+    in_namespace(HOST, move || {
+        let mut owner = owner;
+        assert!(owner.inspect().enforced);
+        owner.release(applied).unwrap();
+    });
+    lan_probes(41060, true);
+    let reopened = socket(SOURCE, "10.240.0.2:10001");
+    control(&reopened, "192.0.2.3:5300", &platform, true);
+    println!("V2_HOST_EXCLUSIVE_FORWARDING_PROOF positive_controls=true member_absent_lan_forwarded=true lan_ipv4_denied=true lan_reverse_denied=true lan_ipv6_denied=true established_foreign_flow_stopped=true leased_egress_kept=true unleased_port_denied=true empty_scope_forwards_nothing=true replacement_reopens=true release_reopens=true");
+}

package/rust/src/owner_host_traffic_tests.rs

@@ -121,7 +121,7 @@ pub(super) fn control(source: &UdpSocket, destination: &str, target: &UdpSocket,
         assert!(target.recv(&mut [0; 64]).is_err());
     }
 }
-fn ipv6_pair(a: &str, aname: &str, aip: &str, b: &str, bname: &str, bip: &str) {
+pub(super) fn ipv6_pair(a: &str, aname: &str, aip: &str, b: &str, bname: &str, bip: &str) {
     let aname_owned = aname.to_owned();
     let bname_owned = bname.to_owned();
     let amac = in_namespace(a, move || packet_fixture::mac(&aname_owned));

package/rust/src/owner_tests.rs

@@ -21,6 +21,9 @@ mod packet_fixture;
 #[path = "owner_host_traffic_tests.rs"]
 mod host_traffic_tests;
 
+#[path = "owner_exclusiveforwarding_tests.rs"]
+mod exclusiveforwarding_tests;
+
 #[path = "owner_router_traffic_tests.rs"]
 mod router_traffic_tests;
 

package/rust/src/wire.links.rs

@@ -22,6 +22,11 @@ pub struct BoundInterface<'a> {
 }
 
 fn read_link(socket: &mut Socket, index: u32) -> Result<Link> {
+    query_link(socket, index)?.map_err(Error::kernel)
+}
+/// The link at `index`, or the kernel's refusal code, such as `-ENODEV` for an
+/// index no link holds.
+fn query_link(socket: &mut Socket, index: u32) -> Result<std::result::Result<Link, i32>> {
     let sequence = socket.sequence()?;
     let mut request = Vec::new();
     request.extend(32_u32.to_ne_bytes());
@@ -49,17 +54,17 @@ fn read_link(socket: &mut Socket, index: u32) -> Result<Link> {
                         .unwrap(),
                 );
                 if error != 0 {
-                    return Err(Error::kernel(error));
+                    return Ok(Err(error));
                 }
             } else if message.kind == 16 && message.payload.len() >= 16 {
                 if u32::from_ne_bytes(message.payload[4..8].try_into().unwrap()) != index {
                     return Err(Error::Conflict);
                 }
-                return Ok(Link {
+                return Ok(Ok(Link {
                     hardware: u16::from_ne_bytes(message.payload[2..4].try_into().unwrap()),
                     flags: u32::from_ne_bytes(message.payload[8..12].try_into().unwrap()),
                     attributes: attrs(&message.payload[16..])?,
-                });
+                }));
             } else {
                 return Err(Error::Protocol);
             }
@@ -271,9 +276,26 @@ pub fn verify_bound_interfaces<'a>(
 pub fn verify_bound_interfaces_down<'a>(interfaces: impl Iterator<Item = BoundInterface<'a>>) -> Result<()> {
     let mut socket = Socket::open_protocol(libc::NETLINK_ROUTE)?;
     for binding in interfaces {
-        let link = read_link(&mut socket, binding.index)?;
-        matches(&link, &binding)?;
-        if link.flags & libc::IFF_UP as u32 != 0 {return Err(Error::Conflict);}
+        down(&read_link(&mut socket, binding.index)?, &binding)?;
     }
     Ok(())
 }
+/// Cleanup fence: a bound link whose index no link holds any more carries no
+/// packets and counts as down. A link at that index must still be the exact
+/// bound link, and down.
+pub fn verify_bound_interfaces_down_or_absent<'a>(interfaces: impl Iterator<Item = BoundInterface<'a>>) -> Result<()> {
+    let mut socket = Socket::open_protocol(libc::NETLINK_ROUTE)?;
+    for binding in interfaces {
+        match query_link(&mut socket, binding.index)? {
+            Ok(link) => down(&link, &binding)?,
+            Err(code) if code == -libc::ENODEV => {}
+            Err(code) => return Err(Error::kernel(code)),
+        }
+    }
+    Ok(())
+}
+fn down(link: &Link, binding: &BoundInterface<'_>) -> Result<()> {
+    matches(link, binding)?;
+    if link.flags & libc::IFF_UP as u32 != 0 {return Err(Error::Conflict);}
+    Ok(())
+}

package/rust/src/wire.rs

@@ -139,7 +139,10 @@ pub struct Socket {
 
 #[path = "wire.links.rs"]
 mod links;
-pub use links::{verify_bound_interfaces, verify_bound_interfaces_down, verify_interfaces, BoundInterface};
+pub use links::{
+    verify_bound_interfaces, verify_bound_interfaces_down, verify_bound_interfaces_down_or_absent,
+    verify_interfaces, BoundInterface,
+};
 impl Socket {
     pub fn open() -> Result<Self> {
         Self::open_protocol(libc::NETLINK_NETFILTER)
@@ -311,6 +314,23 @@ impl Socket {
         self.query_family(operation, input, dump, 2)
     }
     fn query_family(&mut self, operation: u16, input: Vec<Attr>, dump: bool, family: u8) -> Result<Vec<Vec<Attr>>> {
+        Ok(self
+            .query_families(operation, input, dump, family)?
+            .into_iter()
+            .map(|(_, attributes)| attributes)
+            .collect())
+    }
+    /// Dump every object of one kind across all families, each with its family.
+    pub fn dump_all_families(&mut self, operation: u16) -> Result<Vec<(u8, Vec<Attr>)>> {
+        self.query_families(operation, vec![], true, 0)
+    }
+    fn query_families(
+        &mut self,
+        operation: u16,
+        input: Vec<Attr>,
+        dump: bool,
+        family: u8,
+    ) -> Result<Vec<(u8, Vec<Attr>)>> {
         let (sequence, bytes) =
             self.message_family(0x0a00 | operation, 1 | if dump { 0x300 } else { 0 }, &input, family)?;
         self.send(&bytes)?;
@@ -350,7 +370,7 @@ impl Socket {
                         return Err(Error::Protocol);
                     }
                     if family == 2 && message.payload[0] != family {return Err(Error::Protocol);}
-                    result.push(attrs(&message.payload[4..])?);
+                    result.push((message.payload[0], attrs(&message.payload[4..])?));
                     if !dump {
                         return Ok(result);
                     }

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartnftables',
-  version: '4.0.1',
+  version: '4.2.0',
   description: 'A TypeScript module for managing nftables rules including NAT, firewall, and rate limiting with a high-level API.'
 }

package/ts/classes.manageddockerforwarding.ts

@@ -65,7 +65,8 @@ export class ManagedDockerForwarding {
     return this.#invoke('releaseDockerForwarding', expected);
   }
 
-  /** Join operations and exact contributed-rule deletion, then native termination. Keep affected handoff links down through cleanup. */
+  /** Join operations and exact contributed-rule deletion, then native termination. Keep affected handoff links down
+   * through cleanup; a handoff link that no longer exists counts as down. */
   public close(): Promise<void> {
     if (this.#close) return this.#close;
     if (this.#state === 'stopped') return Promise.resolve();

package/ts/forwardhooks.ts

@@ -0,0 +1,39 @@
+import * as plugins from './plugins.js';
+import { snapshot, managedIpcBytes, ManagedNftablesError, nativeError } from './classes.managednftables.js';
+import type { IForwardHookInspection, IForwardHookInspectionOptions, TForwardHookCommands } from './managed.forwardhooks.types.js';
+
+/** Reads every packet-filter owner on the IPv4/IPv6 forward hook of one network
+ * namespace: nf_tables forward base chains of the `ip`, `ip6` and `inet`
+ * families, Docker's DOCKER-USER/DOCKER-FORWARD chains and registered legacy
+ * xtables tables. One native process takes one generation-consistent read and
+ * exits; it claims, adopts and changes nothing. The result is a point-in-time
+ * view: another owner can appear after it. */
+export async function inspectForwardHooks(options: IForwardHookInspectionOptions = {}): Promise<IForwardHookInspection> {
+  const captured = snapshot(options);
+  if (Object.keys(captured).some((key) => !['binaryPath', 'networkNamespaceFd'].includes(key))
+    || captured.binaryPath !== undefined && (typeof captured.binaryPath !== 'string'
+      || !plugins.path.isAbsolute(captured.binaryPath) || captured.binaryPath.includes('\0'))
+    || captured.networkNamespaceFd !== undefined && (!Number.isInteger(captured.networkNamespaceFd)
+      || captured.networkNamespaceFd < 0 || captured.networkNamespaceFd > 0x7fff_ffff)) {
+    throw new ManagedNftablesError('INVALID');
+  }
+  if (process.platform !== 'linux' || !['x64', 'arm64'].includes(process.arch)) throw new ManagedNftablesError('UNSUPPORTED_PLATFORM');
+  const root = plugins.url.fileURLToPath(new URL('../', import.meta.url));
+  const bridge = new plugins.smartrust.RustBridge<TForwardHookCommands>({
+    binaryName: 'smartnftables', binaryPath: captured.binaryPath
+      ?? plugins.path.join(root, 'dist_rust', `smartnftables_linux_${process.arch === 'x64' ? 'amd64' : 'arm64'}_musl`),
+    localPaths: [], searchSystemPath: false,
+    cliArgs: ['--forward-hooks', ...(captured.networkNamespaceFd === undefined ? [] : ['--network-namespace-fd', '3'])],
+    inheritedFileDescriptors: captured.networkNamespaceFd === undefined ? undefined : [captured.networkNamespaceFd],
+    readyTimeoutMs: 3000, requestTimeoutMs: 30_000, maxPayloadSize: managedIpcBytes,
+    maxPendingRequestsByMethod: { inspectForwardHooks: 1 },
+  });
+  try {
+    if (!await bridge.spawn()) throw new ManagedNftablesError('UNAVAILABLE');
+    return snapshot(await bridge.sendCommand('inspectForwardHooks', {}));
+  } catch (error) {
+    throw error instanceof ManagedNftablesError ? error : nativeError(error);
+  } finally {
+    await bridge.terminate({ gracePeriodMs: 1000 });
+  }
+}

package/ts/index.ts

@@ -64,3 +64,5 @@ export type {
 } from './nft.types.js';
 export * from './managed.docker.types.js';
 export * from './classes.manageddockerforwarding.js';
+export type * from './managed.forwardhooks.types.js';
+export { inspectForwardHooks } from './forwardhooks.js';

package/ts/managed.docker.types.ts

@@ -25,7 +25,8 @@ export interface IAppliedManagedDockerForwardingPolicy {
   receipt: { identity: IManagedDockerForwardingIdentity; backend: string; revision: number; digest: string };
   prepared: IPreparedManagedDockerForwardingPolicy;
 }
-/** Persist before mutation. Keep both generations' exact handoff links down until reconciliation is confirmed. */
+/** Persist before mutation. A handoff link both generations bind exactly may stay up: one atomic transaction swaps
+ * the contribution. Keep every link the transition adds or drops down until reconciliation is confirmed. */
 export interface IManagedDockerForwardingTransition {
   previous: IAppliedManagedDockerForwardingPolicy | null;
   target: IPreparedManagedDockerForwardingPolicy;

package/ts/managed.egress.types.ts

@@ -193,6 +193,11 @@ export interface IManagedNftHostTransitScopeV2 {
    * leased source address and a source port of the allocation's range for the endpoint's protocol; its
    * ESTABLISHED replies return. Absent and empty are the same canonical policy, digest and compiled graph. */
   localPlatformEndpoints?: string[];
+  /** Optional: this table is the host's only forwarding owner. Every forwarded packet the scope does not
+   * admit (its leased, published and symmetric handoff flows) drops, IPv4 and IPv6, on every pair of
+   * interfaces, including forwarding that another table would accept. With no `handoffs` the host forwards
+   * nothing. It sets no sysctl. Absent and `false` are the same canonical policy, digest and compiled graph. */
+  exclusiveForwarding?: boolean;
 }
 
 /** One loopback TCP service that only one local user may dial. Every packet the host sends to the

package/ts/managed.forwardhooks.types.ts

@@ -0,0 +1,26 @@
+import type { IManagedNftOptions } from './managed.types.js';
+
+export interface IForwardHookInspectionOptions extends Pick<IManagedNftOptions, 'binaryPath' | 'networkNamespaceFd'> {}
+/** One nf_tables base chain on the forward hook of the `ip`, `ip6` or `inet` family. */
+export interface IForwardHookChain {
+  family: 'ip' | 'ip6' | 'inet';
+  table: string;
+  /** Kernel table handle, as a managed receipt's `tableHandle`. */
+  tableHandle: string;
+  chain: string;
+  type: string;
+  priority: number;
+  policy: 'accept' | 'drop';
+}
+/** One consistent read of every packet-filter owner on the routed forward path of a network namespace. */
+export interface IForwardHookInspection {
+  /** Every forward base chain, sorted by family, table and chain; managed tables included. */
+  chains: IForwardHookChain[];
+  /** Docker's iptables-nft dispatch chains in table `ip filter`. */
+  docker: { dockerUser: boolean; dockerForward: boolean };
+  /** Registered legacy xtables tables, whose hooks are not nf_tables chains. */
+  legacyTables: { ipv4: string[]; ipv6: string[] };
+}
+export type TForwardHookCommands = {
+  inspectForwardHooks: { params: Record<string, never>; result: IForwardHookInspection };
+};