feat(docker): enforce pinned Linux egress allowlists

crates/tinybox-core/src/lib.rs

@@ -85,7 +85,7 @@ pub use identity::{BoxId, HostRef, ProcessId, SandboxRef, SnapshotId, TemplateNa
 pub use passthrough::PassthroughSandbox;
 pub use runtime::{
     BoxInfo, BoxState, ExecOutput, ExecRequest, ExecutionObserver, Forward, ForwardGuard, Host,
-    OutputStream, Sandbox, WorkspaceFileReader, WorkspaceFileWriter,
+    HostExecutionLocation, OutputStream, Sandbox, WorkspaceFileReader, WorkspaceFileWriter,
 };
 pub use spec::{
     BoxSpec, EgressAllowlist, Lifecycle, NetworkPolicy, Placement, PortMapping, Resources,

crates/tinybox-core/src/runtime/mod.rs

@@ -41,6 +41,21 @@ mod types;
 pub use forward::{Forward, ForwardGuard};
 pub use types::{BoxInfo, BoxState, ExecOutput, ExecRequest};
 
+/// Where a host executes commands relative to the tinybox process.
+///
+/// Security-sensitive controllers use this explicit capability instead of
+/// guessing from a host's registration name. Custom hosts default to
+/// [`Unknown`](Self::Unknown) until they can state their location.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum HostExecutionLocation {
+    /// Commands execute in this process's operating-system environment.
+    Local,
+    /// Commands execute on another machine.
+    Remote,
+    /// The host cannot make a trustworthy locality claim.
+    Unknown,
+}
+
 /// A readable file opened beneath a host- or sandbox-mounted workspace.
 #[async_trait]
 pub trait WorkspaceFileReader: std::fmt::Debug + Send + Sync {
@@ -90,6 +105,15 @@ pub trait Host: std::fmt::Debug + Send + Sync + 'static {
     /// [`HostRef`](crate::identity::HostRef).
     fn name(&self) -> &str;
 
+    /// The machine on which commands run.
+    ///
+    /// This defaults to [`HostExecutionLocation::Unknown`]; a controller that
+    /// requires local machine access must refuse hosts that do not explicitly
+    /// attest to it.
+    fn execution_location(&self) -> HostExecutionLocation {
+        HostExecutionLocation::Unknown
+    }
+
     /// Run a command to completion and collect its output.
     ///
     /// # Errors

crates/tinybox-docker/Cargo.toml

@@ -15,7 +15,11 @@ publish = false
 [dependencies]
 tinybox-core.workspace = true
 async-trait.workspace = true
+# Parse Docker-assigned CIDRs and reject pinned destinations within them.
+ipnet = "2.12"
 serde_json.workspace = true
+# SHA-256 keeps firewall cleanup ownership markers collision-resistant.
+sha2 = "0.10.9"
 # `DockerCli` runs the local `docker` client; one-shot runs need process spawning
 # and a deadline.
 tokio = { workspace = true, features = ["process"] }

crates/tinybox-docker/src/egress.rs

@@ -1,8 +1,7 @@
-//! Planning helpers for future network allowlist enforcement.
+//! Resolve and pin network allowlist destinations for the Docker firewall.
 //!
-//! These types pin resolver answers for a later proxy or firewall to consume.
-//! They do not enforce traffic and do not make `NetworkPolicy::Allowlist`
-//! available in [`DockerSandbox`](crate::DockerSandbox).
+//! The native Linux controller consumes pinned answers for firewall rules and
+//! container `/etc/hosts` entries. Planning alone does not enforce traffic.
 
 use std::{
     collections::{BTreeMap, BTreeSet},
@@ -23,6 +22,9 @@ pub trait EgressResolver: std::fmt::Debug + Send + Sync {
 }
 
 /// A resolved allowlist plan whose destinations no longer depend on DNS.
+///
+/// The native Linux Docker controller uses each target both to install a
+/// destination rule and to create a static hostname mapping for the workload.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PinnedEgressPlan {
     targets: Vec<PinnedEgressTarget>,
@@ -76,16 +78,18 @@ impl PinnedEgressTarget {
 /// is a cloud metadata or loopback address, the whole plan is rejected. Safe
 /// private addresses are retained because this policy does not forbid them.
 ///
-/// This function only prepares data for an enforcing proxy or firewall. It does
-/// not apply network rules and does not enable allowlists in `DockerSandbox`.
+/// This function only prepares pinned data. It does not apply network rules;
+/// the native Linux Docker controller consumes the result during preparation.
 /// The resolver must answer in the environment where the eventual enforcer will
 /// use the plan, which may be remote from the caller for an SSH-backed host.
 ///
 /// # Errors
 ///
 /// Returns [`Error::InvalidNetworkPolicy`] for a malformed allowlist, an empty
-/// DNS answer, or any resolved metadata or loopback address. Resolver errors
-/// are returned as [`Error::Backend`].
+/// DNS answer, or any resolved metadata or loopback address. Returns
+/// [`Error::ConstraintNotEnforced`] when an IPv6 link-local target needs an
+/// interface scope that this backend cannot preserve. Resolver errors are
+/// returned as [`Error::Backend`].
 pub fn plan_egress_allowlist(
     allowlist: &EgressAllowlist,
     resolver: &dyn EgressResolver,
@@ -112,12 +116,23 @@ pub fn plan_egress_allowlist(
                 reason: "allowlist host resolved to no addresses",
             });
         }
+        let addresses = addresses
+            .into_iter()
+            .map(normalize_ip_address)
+            .collect::<BTreeSet<_>>();
         if addresses.iter().any(is_forbidden_address) {
             return Err(Error::InvalidNetworkPolicy {
                 reason: "allowlist host resolves to a metadata or loopback address",
             });
         }
-        addresses_by_host.insert(host, addresses.into_iter().collect());
+        if addresses.iter().any(is_ipv6_link_local) {
+            return Err(Error::ConstraintNotEnforced {
+                sandbox: "docker".to_owned(),
+                constraint: tinybox_core::Constraint::Network,
+                enforcement: tinybox_core::Enforcement::Unsupported,
+            });
+        }
+        addresses_by_host.insert(host, addresses);
     }
 
     let ports: BTreeSet<_> = allowlist.ports.iter().copied().collect();
@@ -141,6 +156,15 @@ fn normalize_host(host: &str) -> String {
     host.trim().trim_matches(['[', ']']).to_ascii_lowercase()
 }
 
+fn normalize_ip_address(address: IpAddr) -> IpAddr {
+    match address {
+        IpAddr::V6(address) => address
+            .to_ipv4_mapped()
+            .map_or(IpAddr::V6(address), IpAddr::V4),
+        IpAddr::V4(address) => IpAddr::V4(address),
+    }
+}
+
 fn is_forbidden_address(address: &IpAddr) -> bool {
     if EgressAllowlist::is_metadata_host(&address.to_string()) {
         return true;
@@ -157,6 +181,13 @@ fn is_forbidden_address(address: &IpAddr) -> bool {
     }
 }
 
+fn is_ipv6_link_local(address: &IpAddr) -> bool {
+    match address {
+        IpAddr::V4(_) => false,
+        IpAddr::V6(address) => address.segments()[0] & 0xffc0 == 0xfe80,
+    }
+}
+
 #[cfg(test)]
 #[path = "egress_tests.rs"]
 mod tests;