@push.rocks/smartnftables 4.1.0 → 4.2.0

package/rust/src/forwardhooks.rs

@@ -0,0 +1,176 @@
+//! Read-only view of every packet-filter owner on the IPv4/IPv6 forward hook of
+//! this network namespace. It claims, adopts and changes nothing.
+use crate::wire::{self, Attr, Socket};
+use crate::{decode, encode, Error, Request, Result};
+use serde::Serialize;
+
+#[cfg(test)]
+#[path = "forwardhooks_tests.rs"]
+mod tests;
+
+/// One nf_tables base chain on the forward hook.
+#[derive(Clone, Debug, Serialize, PartialEq, Eq, PartialOrd, Ord)]
+#[serde(rename_all = "camelCase")]
+pub struct Chain {
+    pub family: &'static str,
+    pub table: String,
+    pub table_handle: String,
+    pub chain: String,
+    #[serde(rename = "type")]
+    pub chain_type: String,
+    pub priority: i32,
+    pub policy: &'static str,
+}
+/// Docker's iptables-nft dispatch chains in table `ip filter`.
+#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct Docker {
+    pub docker_user: bool,
+    pub docker_forward: bool,
+}
+/// Registered legacy xtables tables. Their hooks, including FORWARD, are not
+/// nf_tables objects and never appear in `chains`.
+#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct Legacy {
+    pub ipv4: Vec<String>,
+    pub ipv6: Vec<String>,
+}
+#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct Inspection {
+    pub chains: Vec<Chain>,
+    pub docker: Docker,
+    pub legacy_tables: Legacy,
+}
+
+/// The families whose forward hook sees routed IPv4 or IPv6 packets.
+fn family(value: u8) -> Option<&'static str> {
+    match value {
+        1 => Some("inet"),
+        2 => Some("ip"),
+        10 => Some("ip6"),
+        _ => None,
+    }
+}
+const NF_INET_FORWARD: u32 = 2;
+
+/// Classify one consistent table and chain dump.
+pub(crate) fn classify(
+    tables: &[(u8, Vec<Attr>)],
+    chains: &[(u8, Vec<Attr>)],
+) -> Result<(Vec<Chain>, Docker)> {
+    let mut result = Vec::new();
+    let mut docker = Docker {
+        docker_user: false,
+        docker_forward: false,
+    };
+    for (number, attributes) in chains {
+        let table = wire::text(attributes, 1)?;
+        let name = wire::text(attributes, 3)?;
+        if *number == 2 && table == "filter" {
+            match name.as_str() {
+                "DOCKER-USER" => docker.docker_user = true,
+                "DOCKER-FORWARD" => docker.docker_forward = true,
+                _ => {}
+            }
+        }
+        let Some(family) = family(*number) else {
+            continue;
+        };
+        // Only base chains carry a hook.
+        if !attributes.iter().any(|attribute| attribute.id() == 4) {
+            continue;
+        }
+        let hook = wire::attrs(&wire::one(attributes, 4)?.value)?;
+        if wire::number(&hook, 1)? != NF_INET_FORWARD {
+            continue;
+        }
+        let priority = wire::number(&hook, 2)? as i32;
+        let policy = match wire::number(attributes, 5)? {
+            0 => "drop",
+            1 => "accept",
+            _ => return Err(Error::Protocol),
+        };
+        let handle = tables
+            .iter()
+            .filter(|(owner, table_attributes)| {
+                owner == number
+                    && wire::text(table_attributes, 1).ok().as_deref() == Some(table.as_str())
+            })
+            .map(|(_, table_attributes)| wire::handle(table_attributes, 4))
+            .collect::<Result<Vec<_>>>()?;
+        let [handle] = handle.as_slice() else {
+            return Err(Error::Conflict);
+        };
+        result.push(Chain {
+            family,
+            table,
+            table_handle: handle.to_string(),
+            chain: name,
+            chain_type: wire::text(attributes, 7)?,
+            priority,
+            policy,
+        });
+    }
+    result.sort();
+    Ok((result, docker))
+}
+
+/// One registered table name per line; an absent file means none is registered.
+fn legacy(path: &str) -> Result<Vec<String>> {
+    use std::io::Read;
+    let file = match std::fs::File::open(path) {
+        Ok(file) => file,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
+        Err(_) => return Err(Error::Unavailable),
+    };
+    let mut text = String::new();
+    file.take(4097)
+        .read_to_string(&mut text)
+        .map_err(|_| Error::Protocol)?;
+    if text.len() > 4096 {
+        return Err(Error::Protocol);
+    }
+    let mut names = Vec::new();
+    for line in text.lines() {
+        if !crate::policy::identifier(line) {
+            return Err(Error::Protocol);
+        }
+        names.push(line.to_owned());
+    }
+    names.sort();
+    Ok(names)
+}
+
+pub fn inspect() -> Result<Inspection> {
+    let mut socket = Socket::open()?;
+    let generation = socket.generation()?;
+    let tables = socket.dump_all_families(1)?;
+    let chains = socket.dump_all_families(4)?;
+    // Both dumps describe one ruleset generation, or the view is inconclusive.
+    if socket.generation()? != generation {
+        return Err(Error::Conflict);
+    }
+    let (chains, docker) = classify(&tables, &chains)?;
+    Ok(Inspection {
+        chains,
+        docker,
+        legacy_tables: Legacy {
+            ipv4: legacy("/proc/self/net/ip_tables_names")?,
+            ipv6: legacy("/proc/self/net/ip6_tables_names")?,
+        },
+    })
+}
+
+pub fn dispatch(request: Request) -> Result<serde_json::Value> {
+    match request.method.as_str() {
+        "inspectForwardHooks" => {
+            if decode::<serde_json::Value>(request.params)? != serde_json::json!({}) {
+                return Err(Error::Invalid);
+            }
+            encode(inspect()?)
+        }
+        _ => Err(Error::Invalid),
+    }
+}

package/rust/src/forwardhooks_tests.rs

@@ -0,0 +1,136 @@
+use super::*;
+
+fn table(family: u8, name: &str, handle: u64) -> (u8, Vec<Attr>) {
+    (family, vec![Attr::string(1, name), Attr::u64(4, handle)])
+}
+fn base(
+    family: u8,
+    table: &str,
+    name: &str,
+    hook: u32,
+    priority: i32,
+    policy: u32,
+) -> (u8, Vec<Attr>) {
+    let hook = Attr::nested(
+        4,
+        vec![
+            Attr::bytes(1, hook.to_be_bytes().to_vec()),
+            Attr::bytes(2, priority.to_be_bytes().to_vec()),
+        ],
+    );
+    (
+        family,
+        vec![
+            Attr::string(1, table),
+            Attr::string(3, name),
+            hook,
+            Attr::bytes(5, policy.to_be_bytes().to_vec()),
+            Attr::string(7, "filter"),
+        ],
+    )
+}
+fn regular(family: u8, table: &str, name: &str) -> (u8, Vec<Attr>) {
+    (family, vec![Attr::string(1, table), Attr::string(3, name)])
+}
+
+#[test]
+fn forward_hooks_report_every_routed_forward_base_chain_with_its_table() {
+    let tables = [
+        table(1, "snft_host", 7),
+        table(2, "filter", 3),
+        table(10, "filter", 4),
+        table(7, "filter", 5),
+        table(5, "edge", 6),
+        table(1, "other", 8),
+    ];
+    let chains = [
+        base(1, "snft_host", "forward", 2, 0, 1),
+        base(1, "snft_host", "input", 1, 0, 1),
+        base(2, "filter", "FORWARD", 2, 0, 0),
+        regular(2, "filter", "DOCKER-USER"),
+        regular(2, "filter", "DOCKER-FORWARD"),
+        base(10, "filter", "FORWARD", 2, 0, 1),
+        // Bridge and netdev hooks do not see routed packets.
+        base(7, "filter", "FORWARD", 2, -200, 0),
+        base(5, "edge", "ingress", 0, -500, 1),
+        base(1, "other", "early", 2, -150, 0),
+    ];
+    let (chains, docker) = classify(&tables, &chains).unwrap();
+    let summary: Vec<_> = chains
+        .iter()
+        .map(|c| {
+            (
+                c.family,
+                c.table.as_str(),
+                c.table_handle.as_str(),
+                c.chain.as_str(),
+                c.priority,
+                c.policy,
+            )
+        })
+        .collect();
+    assert_eq!(
+        summary,
+        vec![
+            ("inet", "other", "8", "early", -150, "drop"),
+            ("inet", "snft_host", "7", "forward", 0, "accept"),
+            ("ip", "filter", "3", "FORWARD", 0, "drop"),
+            ("ip6", "filter", "4", "FORWARD", 0, "accept"),
+        ]
+    );
+    assert_eq!(
+        docker,
+        Docker {
+            docker_user: true,
+            docker_forward: true
+        }
+    );
+    let json = serde_json::to_value(&chains[0]).unwrap();
+    assert_eq!(
+        json,
+        serde_json::json!({"family":"inet","table":"other","tableHandle":"8","chain":"early",
+        "type":"filter","priority":-150,"policy":"drop"})
+    );
+}
+
+#[test]
+fn forward_hooks_report_absent_docker_chains_and_reject_inconsistent_dumps() {
+    let (chains, docker) = classify(
+        &[],
+        &[
+            regular(10, "filter", "DOCKER-USER"),
+            regular(2, "nat", "DOCKER-FORWARD"),
+        ],
+    )
+    .unwrap();
+    assert!(chains.is_empty());
+    assert_eq!(
+        docker,
+        Docker {
+            docker_user: false,
+            docker_forward: false
+        }
+    );
+    // A base chain whose table the table dump does not hold exactly once.
+    let chain = [base(2, "filter", "FORWARD", 2, 0, 0)];
+    assert_eq!(classify(&[], &chain), Err(Error::Conflict));
+    assert_eq!(
+        classify(&[table(2, "filter", 1), table(2, "filter", 2)], &chain),
+        Err(Error::Conflict)
+    );
+    assert_eq!(
+        classify(
+            &[table(2, "filter", 1)],
+            &[base(2, "filter", "FORWARD", 2, 0, 3)]
+        ),
+        Err(Error::Protocol)
+    );
+}
+
+#[test]
+fn forward_hooks_read_absent_legacy_tables_as_none() {
+    assert_eq!(
+        legacy("/proc/self/net/smartnftables-absent-fixture").unwrap(),
+        Vec::<String>::new()
+    );
+}

package/rust/src/main.rs

@@ -1,5 +1,6 @@
 mod egress;
 mod docker;
+mod forwardhooks;
 mod managed;
 mod namespace;
 mod owner;
@@ -172,14 +173,12 @@ fn failure(id: &str, error: Error) -> serde_json::Value {
 
 fn main() {
     let arguments = std::env::args().skip(1).collect::<Vec<_>>();
-    let (docker_mode, descriptor) = match arguments.as_slice() {
-        [management] if management == "--management" => (false, None),
-        [management] if management == "--docker-forwarding" => (true, None),
-        [management, option, fd]
-            if (management == "--management" || management == "--docker-forwarding") && option == "--network-namespace-fd" =>
-        {
+    const MODES: [&str; 3] = ["--management", "--docker-forwarding", "--forward-hooks"];
+    let (mode, descriptor) = match arguments.as_slice() {
+        [mode] if MODES.contains(&mode.as_str()) => (mode.clone(), None),
+        [mode, option, fd] if MODES.contains(&mode.as_str()) && option == "--network-namespace-fd" => {
             match fd.parse::<i32>() {
-                Ok(value) => (management == "--docker-forwarding", Some(value)),
+                Ok(value) => (mode.clone(), Some(value)),
                 Err(_) => std::process::exit(2),
             }
         }
@@ -217,7 +216,12 @@ fn main() {
             std::process::exit(2);
         }
         let id = request.id.clone();
-        let response = match if docker_mode { docker::dispatch(&mut docker, request) } else { dispatch(&mut owner, request) } {
+        let result = match mode.as_str() {
+            "--docker-forwarding" => docker::dispatch(&mut docker, request),
+            "--forward-hooks" => forwardhooks::dispatch(request),
+            _ => dispatch(&mut owner, request),
+        };
+        let response = match result {
             Ok(result) => serde_json::json!({"id":id,"success":true,"result":result}),
             Err(error) => failure(&id, error),
         };

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.1.0',
+  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.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 };
+};