fix(core): reject loopback hosts in network allowlists

.gitignore

@@ -9,6 +9,7 @@
 *.profraw
 *.profdata
 lcov.info
+rustc-ice-*.txt
 
 # Local secrets — never commit; copy .env.example to .env
 .env

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

@@ -201,6 +201,16 @@ pub enum Error {
         message: String,
     },
 
+    /// A Docker egress controller could not undo resources created for an
+    /// allowlist network, so the sandbox must retain the box record for retry.
+    #[error("{sandbox} could not roll back egress network setup: {message}")]
+    EgressRollbackFailed {
+        /// The sandbox whose egress resources could not be removed.
+        sandbox: String,
+        /// The setup and cleanup failures that require a later retry.
+        message: String,
+    },
+
     /// Reading or writing the box store failed, or its contents were not
     /// valid.
     #[error("box store {operation} failed: {message}")]

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-core/src/spec/mod_tests.rs

@@ -228,8 +228,15 @@ fn allowlist_validation_rejects_malformed_and_metadata_hosts() {
     );
     for host in [
         "169.254.169.254",
+        "0251.0376.0251.0376",
+        "0xa9fea9fe",
+        "0xa9feaa02",
+        "0x646464c8",
         "[fd00:ec2::254]",
         "Metadata.Google.Internal",
+        "metadata.google.internal.",
+        "Metadata.Google.Internal.",
+        "metadata.",
     ] {
         assert!(
             EgressAllowlist::new([host], [80]).validate().is_err(),
@@ -238,6 +245,49 @@ fn allowlist_validation_rejects_malformed_and_metadata_hosts() {
     }
 }
 
+#[test]
+fn allowlist_validation_rejects_loopback_targets() {
+    use super::EgressAllowlist;
+
+    for host in [
+        "127.0.0.1",
+        "[::1]",
+        "[::ffff:127.0.0.1]",
+        "localhost",
+        "LOCALHOST.",
+        "service.localhost",
+    ] {
+        assert!(
+            EgressAllowlist::new([host], [80]).validate().is_err(),
+            "{host} must be refused"
+        );
+    }
+}
+
+#[test]
+fn allowlist_validation_rejects_legacy_numeric_loopback_targets() {
+    use super::EgressAllowlist;
+
+    for host in ["127.1", "2130706433", "0x7f000001", "0177.0.0.1"] {
+        assert!(
+            EgressAllowlist::new([host], [80]).validate().is_err(),
+            "{host} must be refused"
+        );
+    }
+}
+
+#[test]
+fn allowlist_validation_rejects_scoped_ipv6_loopback_targets() {
+    use super::EgressAllowlist;
+
+    for host in ["::1%1", "[::1%1]"] {
+        assert!(
+            EgressAllowlist::new([host], [80]).validate().is_err(),
+            "{host} must be refused"
+        );
+    }
+}
+
 #[test]
 fn allowlist_policy_allows_egress_but_open_is_highest_risk() {
     use super::EgressAllowlist;

crates/tinybox-core/src/spec/types.rs

@@ -1,5 +1,6 @@
 //! The parts a [`BoxSpec`](crate::spec::BoxSpec) is assembled from.
 
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
 use std::path::PathBuf;
 use std::time::Duration;
 
@@ -252,8 +253,16 @@ pub enum NetworkPolicy {
 /// `Unsupported`, never `Enforced`.
 ///
 /// The cloud metadata endpoints in [`EgressAllowlist::is_metadata_host`] are
-/// refused at validation time and must also be blocked by the backend even
-/// when a hostname resolves to one of them.
+/// refused at validation time, including legacy numeric IPv4 spellings such as
+/// `0251.0376.0251.0376` and `0xa9fea9fe` for `169.254.169.254`. They must also
+/// be blocked by the backend even when a hostname resolves to one of them.
+///
+/// Explicit loopback addresses and aliases are also invalid. This includes
+/// IPv4/IPv6 loopback literals, IPv4-mapped loopback literals, scoped IPv6
+/// literals such as `::1%1`, `localhost` names, and legacy numeric IPv4
+/// spellings accepted by common resolvers (for example `127.1`, `2130706433`,
+/// `0x7f000001`, and `0177.0.0.1`). These are checked as explicit allowlist
+/// entries; enforcing backends must also reject resolved loopback addresses.
 #[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
 pub struct EgressAllowlist {
     /// Host names or IP literals the box may connect to.
@@ -276,10 +285,15 @@ impl EgressAllowlist {
     }
 
     /// Whether `host` names a cloud instance-metadata endpoint, which no
-    /// policy may ever allow.
+    /// policy may ever allow. Matching ignores DNS case and terminal root dots,
+    /// and recognizes legacy numeric IPv4 spellings of metadata addresses.
     #[must_use]
     pub fn is_metadata_host(host: &str) -> bool {
-        let host = host.trim().trim_matches(['[', ']']).to_ascii_lowercase();
+        let host = host
+            .trim()
+            .trim_end_matches('.')
+            .trim_matches(['[', ']'])
+            .to_ascii_lowercase();
         matches!(
             host.as_str(),
             "169.254.169.254"
@@ -289,9 +303,109 @@ impl EgressAllowlist {
                 | "metadata.google.internal"
                 | "metadata"
         ) || host.starts_with("::ffff:169.254.169.254")
+            || Self::parse_legacy_ipv4(&host).is_some_and(|address| {
+                address == Ipv4Addr::new(169, 254, 169, 254)
+                    || address == Ipv4Addr::new(169, 254, 170, 2)
+                    || address == Ipv4Addr::new(100, 100, 100, 200)
+            })
+    }
+
+    /// Whether an allowlist entry explicitly names a loopback address or alias.
+    fn is_loopback_host(host: &str) -> bool {
+        let host = host
+            .trim()
+            .trim_matches(['[', ']'])
+            .trim_end_matches('.')
+            .to_ascii_lowercase();
+        if host == "localhost" || host.ends_with(".localhost") {
+            return true;
+        }
+
+        match host.parse::<IpAddr>() {
+            Ok(IpAddr::V4(address)) => address.is_loopback(),
+            Ok(IpAddr::V6(address)) => Self::is_loopback_ipv6(address),
+            Err(_) => {
+                Self::parse_scoped_ipv6(&host).is_some_and(Self::is_loopback_ipv6)
+                    || Self::parse_legacy_ipv4(&host).is_some_and(|address| address.is_loopback())
+            }
+        }
     }
 
-    /// Check the list is non-empty, well formed and names no metadata endpoint.
+    fn is_loopback_ipv6(address: Ipv6Addr) -> bool {
+        address.is_loopback()
+            || address
+                .to_ipv4_mapped()
+                .is_some_and(|mapped| mapped.is_loopback())
+    }
+
+    /// Parse an IPv6 address with a non-empty zone identifier, if present.
+    fn parse_scoped_ipv6(host: &str) -> Option<Ipv6Addr> {
+        let (address, scope_id) = host.split_once('%')?;
+        if scope_id.is_empty() || scope_id.contains('%') {
+            return None;
+        }
+        address.parse().ok()
+    }
+
+    /// Parse the legacy numeric IPv4 formats accepted by common resolvers.
+    ///
+    /// These formats are still relevant to validation because a backend may
+    /// resolve the input through a system resolver that treats them as IP
+    /// addresses rather than DNS names.
+    fn parse_legacy_ipv4(host: &str) -> Option<Ipv4Addr> {
+        let components: Vec<_> = host.split('.').collect();
+        if !(1..=4).contains(&components.len()) || components.iter().any(|part| part.is_empty()) {
+            return None;
+        }
+
+        let numbers: Vec<u32> = components
+            .iter()
+            .map(|part| {
+                let number = if let Some(hex) =
+                    part.strip_prefix("0x").or_else(|| part.strip_prefix("0X"))
+                {
+                    u64::from_str_radix(hex, 16).ok()
+                } else if part.len() > 1 && part.starts_with('0') {
+                    u64::from_str_radix(&part[1..], 8).ok()
+                } else {
+                    part.parse().ok()
+                }?;
+                u32::try_from(number).ok()
+            })
+            .collect::<Option<_>>()?;
+
+        if numbers[..numbers.len() - 1]
+            .iter()
+            .any(|number| *number > u8::MAX.into())
+        {
+            return None;
+        }
+        let last = *numbers.last()?;
+        let last_max = match numbers.len() {
+            1 => u32::MAX,
+            2 => 0x00ff_ffff,
+            3 => 0x0000_ffff,
+            4 => u8::MAX.into(),
+            _ => return None,
+        };
+        if last > last_max {
+            return None;
+        }
+
+        let address = match numbers.as_slice() {
+            [whole] => *whole,
+            [first, last] => (*first << 24) | *last,
+            [first, second, last] => (*first << 24) | (*second << 16) | *last,
+            [first, second, third, last] => {
+                (*first << 24) | (*second << 16) | (*third << 8) | *last
+            }
+            _ => return None,
+        };
+        Some(Ipv4Addr::from(address))
+    }
+
+    /// Check the list is non-empty, well formed, and names no metadata or
+    /// explicit loopback endpoint.
     ///
     /// # Errors
     ///
@@ -323,6 +437,11 @@ impl EgressAllowlist {
                     reason: "allowlist names a cloud metadata endpoint",
                 });
             }
+            if Self::is_loopback_host(trimmed) {
+                return Err(Error::InvalidNetworkPolicy {
+                    reason: "allowlist names a loopback endpoint",
+                });
+            }
         }
         Ok(())
     }

crates/tinybox-docker/Cargo.toml

@@ -15,7 +15,13 @@ 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
+# Keep workload Docker client credentials out of host CLI environment and argv.
+tempfile = "3"
+# 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"] }
@@ -25,7 +31,6 @@ uuid = { version = "1", features = ["v4"] }
 tokio.workspace = true
 # The live suite drives a real daemon through the real local host.
 tinybox-host.workspace = true
-tempfile = "3"
 
 [lints]
 workspace = true