feat: network allowlist policy, sandbox events, namespace/KVM probes, contract 1.19

AGENTS.md

@@ -43,6 +43,15 @@ docs/
 └── adr/                     # immutable architecture decision records
 ```
 
+## Scope: tinybox only sandboxes
+
+tinybox accepts a plan, enforces it, and reports events. It never decides what
+is allowed: approval, audit decisions, redaction and command classification
+belong to `tinysecurity`. A backend that cannot enforce a requested constraint
+refuses with `Unsupported`/`ConstraintNotEnforced` or reports `BestEffort`; it
+never degrades silently. `tinybox_core::shell::{classify, scan, env_guard}` is
+deprecated for that reason and is removed after 0.1.34.
+
 Every crate the spec names now exists. Do not scaffold an empty one; that is a
 placeholder.
 

README.md

@@ -397,3 +397,10 @@ TinyBus itself is not shipped here; the pinned submodule is the build-time SDK.
 ## License
 
 GPL-3.0-only. See [LICENSE](LICENSE).
+
+## Scope
+
+tinybox is sandbox-only. It enforces the confinement a caller asks for (filesystem,
+network, processes, resources), reports observational events, and refuses what it
+cannot enforce. It owns no policy, approval, audit or command-classification logic;
+that is `tinysecurity`. See `docs/specs/contract-1-19.md`.

crates/tinybox-bus/src/event.rs

@@ -0,0 +1,80 @@
+//! Wire vocabulary for network allowlists and sandbox observations.
+//!
+//! These mirror the model types in `tinybox-core` so a module and a host can
+//! exchange them without sharing a dependency. They carry no policy: a sandbox
+//! reports what happened and the caller decides what to do about it.
+
+use serde::{Deserialize, Serialize};
+
+/// Hosts and ports an allowlisted box may reach.
+///
+/// Hostnames are resolved outside the box and pinned; metadata endpoints are
+/// always refused. See `tinybox_core::EgressAllowlist` for the full rules.
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct EgressAllowlist {
+    /// Host names or IP literals.
+    pub hosts: Vec<String>,
+    /// TCP ports.
+    pub ports: Vec<u16>,
+}
+
+/// Which kind of access a sandbox refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DenialKind {
+    /// Filesystem access outside the granted paths.
+    Filesystem,
+    /// A network connection the policy forbids.
+    Network,
+    /// Process creation the sandbox forbids.
+    Subprocess,
+    /// A system call a filter blocked.
+    Syscall,
+}
+
+/// Which resource limit a workload reached.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum LimitKind {
+    /// CPU time or share.
+    Cpu,
+    /// Resident memory.
+    Memory,
+    /// Process or thread count.
+    Pids,
+    /// Writable disk.
+    Disk,
+    /// Wall-clock timeout.
+    Timeout,
+}
+
+/// One observation about a running workload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "event", rename_all = "snake_case")]
+pub enum SandboxEvent {
+    /// The workload started.
+    Started,
+    /// The sandbox refused an access.
+    Denied {
+        /// What was refused.
+        kind: DenialKind,
+        /// The path, address or syscall, when the OS reports it.
+        #[serde(default)]
+        target: Option<String>,
+    },
+    /// The workload reached a resource limit.
+    LimitHit {
+        /// The limit reached.
+        limit: LimitKind,
+    },
+    /// The workload ended.
+    Exited {
+        /// Exit status, or `None` when killed by a signal.
+        #[serde(default)]
+        status: Option<i32>,
+    },
+}
+
+#[cfg(test)]
+#[path = "event_tests.rs"]
+mod tests;

crates/tinybox-bus/src/event_tests.rs

@@ -0,0 +1,46 @@
+use super::*;
+use crate::NetworkPolicy;
+
+#[test]
+fn events_keep_their_wire_labels() -> Result<(), serde_json::Error> {
+    let denied = SandboxEvent::Denied {
+        kind: DenialKind::Network,
+        target: Some("169.254.169.254:80".into()),
+    };
+    assert_eq!(
+        serde_json::to_value(&denied)?,
+        serde_json::json!({"event":"denied","kind":"network","target":"169.254.169.254:80"})
+    );
+    assert_eq!(
+        serde_json::to_value(SandboxEvent::LimitHit {
+            limit: LimitKind::Pids
+        })?,
+        serde_json::json!({"event":"limit_hit","limit":"pids"})
+    );
+    assert_eq!(
+        serde_json::to_value(SandboxEvent::Started)?,
+        serde_json::json!({"event":"started"})
+    );
+    let exited: SandboxEvent = serde_json::from_value(serde_json::json!({"event":"exited"}))?;
+    assert_eq!(exited, SandboxEvent::Exited { status: None });
+    Ok(())
+}
+
+#[test]
+fn an_allowlist_policy_round_trips_and_old_policies_still_parse() -> Result<(), serde_json::Error> {
+    let policy = NetworkPolicy::Allowlist(EgressAllowlist {
+        hosts: vec!["example.com".into()],
+        ports: vec![443],
+    });
+    let value = serde_json::to_value(&policy)?;
+    assert_eq!(
+        value,
+        serde_json::json!({"Allowlist":{"hosts":["example.com"],"ports":[443]}})
+    );
+    assert_eq!(serde_json::from_value::<NetworkPolicy>(value)?, policy);
+    assert_eq!(
+        serde_json::from_value::<NetworkPolicy>(serde_json::json!("Egress"))?,
+        NetworkPolicy::Egress
+    );
+    Ok(())
+}

crates/tinybox-bus/src/lib.rs

@@ -29,6 +29,9 @@ pub use shell_selection::{SelectShellRequest, ShellFlavor, ShellInvocation};
 mod policy;
 pub use policy::{DockerPolicyReport, DockerPolicyRequest};
 
+mod event;
+pub use event::{DenialKind, EgressAllowlist, LimitKind, SandboxEvent};
+
 mod shell;
 pub use shell::{CommandAnalysis, CommandClass, CommandSegment};
 mod files;
@@ -61,7 +64,9 @@ pub use files::{
 /// module for the same verdict the Docker run members enforce without starting
 /// a container, and `hide_window` on [`ShellExecRequest`] (Windows console
 /// suppression for a native shell child; ignored elsewhere).
-pub const CONTRACT_VERSION: (u32, u32) = (1, 18);
+/// 1.19 adds `NetworkPolicy::Allowlist` and the observational
+/// [`SandboxEvent`] vocabulary (`Started`, `Denied`, `LimitHit`, `Exited`).
+pub const CONTRACT_VERSION: (u32, u32) = (1, 19);
 
 /// Whether this host vocabulary can bind to a module's advertised version.
 /// The major must match and the module's minor must include every host member.
@@ -348,13 +353,16 @@ pub struct SshHostConfig {
 }
 
 /// Network access policy applied by a sandbox.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
 pub enum NetworkPolicy {
     /// Disable all network access.
     #[default]
     Denied,
     /// Permit outbound connections without publishing inbound ports.
     Egress,
+    /// Permit outbound connections only to the named hosts and ports. Added in
+    /// contract 1.19; a backend that cannot enforce it refuses the request.
+    Allowlist(EgressAllowlist),
     /// Permit unrestricted network access.
     Open,
 }

crates/tinybox-bus/src/lib_tests.rs

@@ -51,7 +51,7 @@ fn docker_run_vocabulary_is_typed_bounded_and_additive() -> Result<(), serde_jso
     assert_eq!(METHODS[29], "CleanupDocker");
     assert_eq!(METHODS[30], "RunDockerWithoutWorkspace");
     assert_eq!(METHODS[34], "StartNativeShellExec");
-    assert_eq!(CONTRACT_VERSION, (1, 18));
+    assert_eq!(CONTRACT_VERSION, (1, 19));
     assert_eq!(MAX_DOCKER_RUN_TIMEOUT_MS, 86_400_000);
     let serialized = serde_json::to_value(&request)?;
     assert_eq!(serialized["read_only_rootfs"], false);
@@ -129,7 +129,7 @@ fn host_gateway_and_docker_facts_are_additive_and_default_safely() -> Result<(),
 #[test]
 fn version_and_capability_wire_snapshot_preserve_contract_compatibility()
 -> Result<(), serde_json::Error> {
-    assert_eq!(CONTRACT_VERSION, (1, 18));
+    assert_eq!(CONTRACT_VERSION, (1, 19));
     assert!(is_compatible(CONTRACT_VERSION));
     assert!(!is_compatible((1, 8)));
     assert!(!is_compatible((1, 7)));
@@ -147,7 +147,7 @@ fn version_and_capability_wire_snapshot_preserve_contract_compatibility()
         exec_backends: Vec::new(),
         spawn_backends: Vec::new(),
     };
-    let snapshot = serde_json::json!({"contract_version":[1,18],"create_backends":["passthrough"],"exec_backends":[],"spawn_backends":[]});
+    let snapshot = serde_json::json!({"contract_version":[1,19],"create_backends":["passthrough"],"exec_backends":[],"spawn_backends":[]});
     assert_eq!(serde_json::to_value(&capabilities)?, snapshot);
     assert_eq!(
         serde_json::from_value::<ModuleCapabilities>(snapshot)?,
@@ -166,7 +166,7 @@ fn no_workspace_docker_operation_is_present_in_the_contract() {
             .count(),
         1
     );
-    assert_eq!(CONTRACT_VERSION, (1, 18));
+    assert_eq!(CONTRACT_VERSION, (1, 19));
 }
 
 #[test]

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

@@ -84,6 +84,14 @@ pub enum Error {
         limit: &'static str,
     },
 
+    /// A network policy was malformed, such as an empty allowlist or one that
+    /// names a cloud metadata endpoint.
+    #[error("invalid network policy: {reason}")]
+    InvalidNetworkPolicy {
+        /// Stable, non-sensitive reason for rejecting the policy.
+        reason: &'static str,
+    },
+
     /// A box was referenced that the sandbox does not know about.
     #[error("no box with id {id}")]
     UnknownBox {

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

@@ -0,0 +1,109 @@
+//! Purely observational sandbox events.
+//!
+//! A sandbox reports what happened to a workload; it never decides what is
+//! allowed. A caller (the host, and through it an audit log) subscribes with an
+//! [`EventSink`] and records what it is told. Denial attribution is only as
+//! precise as the OS allows, so a [`SandboxEvent::Denied`] carries a
+//! [`DenialKind`] and an optional target, and a backend that cannot attribute
+//! denials emits none and declares that in its capabilities rather than
+//! guessing.
+
+use std::sync::Mutex;
+
+use serde::{Deserialize, Serialize};
+
+/// Which kind of access the sandbox refused.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[non_exhaustive]
+pub enum DenialKind {
+    /// A filesystem read, write or execute outside the granted paths.
+    Filesystem,
+    /// A network connection the policy does not permit.
+    Network,
+    /// A process or thread creation the sandbox forbids.
+    Subprocess,
+    /// A system call a filter blocked.
+    Syscall,
+}
+
+/// Which resource limit a workload reached.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[non_exhaustive]
+pub enum LimitKind {
+    /// CPU time or share.
+    Cpu,
+    /// Resident memory.
+    Memory,
+    /// Process or thread count.
+    Pids,
+    /// Writable disk.
+    Disk,
+    /// Wall-clock timeout.
+    Timeout,
+}
+
+/// One observation about a running workload.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[non_exhaustive]
+pub enum SandboxEvent {
+    /// The workload started inside the sandbox.
+    Started,
+    /// The sandbox refused an access.
+    Denied {
+        /// What was refused.
+        kind: DenialKind,
+        /// The path, address or syscall refused, when the OS reports it.
+        target: Option<String>,
+    },
+    /// The workload reached a resource limit.
+    LimitHit {
+        /// The limit reached.
+        limit: LimitKind,
+    },
+    /// The workload ended.
+    Exited {
+        /// The exit status, or `None` when it was killed by a signal.
+        status: Option<i32>,
+    },
+}
+
+/// Receives events from a sandbox. Implementations must not block.
+pub trait EventSink: Send + Sync {
+    /// Observe one event for the box `box_id`.
+    fn emit(&self, box_id: &str, event: SandboxEvent);
+}
+
+/// An [`EventSink`] that keeps every event in memory, for tests and short runs.
+#[derive(Debug, Default)]
+pub struct CollectingSink {
+    events: Mutex<Vec<(String, SandboxEvent)>>,
+}
+
+impl CollectingSink {
+    /// An empty sink.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Everything received so far, oldest first.
+    #[must_use]
+    pub fn events(&self) -> Vec<(String, SandboxEvent)> {
+        self.events
+            .lock()
+            .map(|events| events.clone())
+            .unwrap_or_default()
+    }
+}
+
+impl EventSink for CollectingSink {
+    fn emit(&self, box_id: &str, event: SandboxEvent) {
+        if let Ok(mut events) = self.events.lock() {
+            events.push((box_id.to_owned(), event));
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "mod_tests.rs"]
+mod tests;

crates/tinybox-core/src/event/mod_tests.rs

@@ -0,0 +1,24 @@
+use super::*;
+
+#[test]
+fn collecting_sink_keeps_events_in_order() {
+    let sink = CollectingSink::new();
+    sink.emit("b1", SandboxEvent::Started);
+    sink.emit(
+        "b1",
+        SandboxEvent::LimitHit {
+            limit: LimitKind::Memory,
+        },
+    );
+    sink.emit("b1", SandboxEvent::Exited { status: Some(137) });
+    let events = sink.events();
+    assert_eq!(events.len(), 3);
+    assert_eq!(events[0].1, SandboxEvent::Started);
+    assert_eq!(
+        events[1].1,
+        SandboxEvent::LimitHit {
+            limit: LimitKind::Memory
+        }
+    );
+    assert_eq!(events[2].1, SandboxEvent::Exited { status: Some(137) });
+}