feat: add bwrap runtime capability smoke test to hardened preflight

Author: madeinplutofabio

csc_runner/sandbox.py

@@ -2,7 +2,7 @@
 
 Builds a hardened launcher argv using Linux-native tools:
 - bubblewrap (bwrap): mount/pid/network namespace isolation
-- setpriv: --no-new-privs always; privilege drop when configured
+- setpriv: --no-new-privs (always), privilege drop (when configured)
 - prlimit: resource limits (CPU, address space, processes, file size)
 
 No Python preexec_fn. The security boundary is the kernel, not
@@ -49,6 +49,7 @@
 import platform
 import shutil
 import socket
+import subprocess
 from dataclasses import dataclass, field
 
 _GLOB_META = frozenset("*?[")
@@ -300,6 +301,12 @@ def _resolve_writable_roots(write_bind_prefixes: list[str]) -> list[str]:
 
 _REQUIRED_TOOLS: tuple[str, ...] = ("bwrap", "setpriv", "prlimit")
 
+# Candidate probe executables, checked in order against bound paths.
+_PROBE_EXECUTABLES: tuple[tuple[str, str], ...] = (
+    ("/bin", "/bin/true"),
+    ("/usr", "/usr/bin/true"),
+)
+
 
 def verify_platform() -> None:
     """Verify the platform is Linux. Raises SandboxError otherwise."""
@@ -343,21 +350,112 @@ def verify_network_disabled() -> None:
         raise SandboxError(f"network not disabled: found non-loopback interfaces: {', '.join(non_loopback)}")
 
 
+def _verify_bwrap_capabilities(config: SandboxConfig) -> None:
+    """Smoke test: verify bwrap can create the namespaces hardened mode needs.
+
+    Runs a representative bwrap probe using the same readonly system
+    paths as the real hardened launcher. Exercises namespace creation
+    (mount, network, pid). If the runtime blocks namespace operations
+    (common on AppArmor-restricted Ubuntu or confined containers), this
+    fails early with an actionable error instead of failing later during
+    contract execution.
+
+    The probe executable is selected from the configured readonly bind
+    paths to avoid false failures when the config does not include /bin
+    but does include /usr.
+
+    Timeout: 5 seconds. This is a preflight check, not a performance test.
+    """
+    # Build probe argv using the same readonly binds as real execution.
+    probe_argv = ["bwrap"]
+
+    bound_paths: set[str] = set()
+    for path in config.readonly_bind_paths:
+        if os.path.exists(path):
+            probe_argv.extend(["--ro-bind", path, path])
+            bound_paths.add(path)
+
+    probe_argv.extend(
+        [
+            "--proc",
+            "/proc",
+            "--dev",
+            "/dev",
+            "--unshare-net",
+            "--unshare-pid",
+            "--new-session",
+            "--die-with-parent",
+            "--",
+        ]
+    )
+
+    # Select probe executable from bound paths.
+    probe_exe = None
+    for parent_path, exe_path in _PROBE_EXECUTABLES:
+        if parent_path in bound_paths and os.path.exists(exe_path):
+            probe_exe = exe_path
+            break
+
+    if probe_exe is None:
+        raise SandboxError(
+            "hardened mode runtime check failed: cannot select a probe "
+            "executable from the configured readonly_bind_paths. "
+            "Ensure at least /bin or /usr is in readonly_bind_paths and "
+            "contains 'true'. "
+            "See docs/deployment-modes.md for runtime prerequisites."
+        )
+
+    probe_argv.append(probe_exe)
+
+    try:
+        result = subprocess.run(
+            probe_argv,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except subprocess.TimeoutExpired:
+        raise SandboxError(
+            "hardened mode runtime check failed: bubblewrap capability "
+            "probe timed out (5s). "
+            "See docs/deployment-modes.md for runtime prerequisites."
+        )
+    except FileNotFoundError:
+        raise SandboxError(
+            "hardened mode runtime check failed: bwrap not found "
+            "during capability probe (passed tool check but not executable). "
+            "See docs/deployment-modes.md for runtime prerequisites."
+        )
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "<no stderr>"
+        raise SandboxError(
+            "hardened mode runtime check failed: bubblewrap could not "
+            "create the required namespace sandbox. "
+            "Common causes: AppArmor-restricted Ubuntu, container runtime "
+            "confinement, disabled user namespaces, restrictive seccomp. "
+            f"bwrap stderr: {stderr}. "
+            "See docs/deployment-modes.md for runtime prerequisites."
+        )
+
+
 def verify_hardened_runtime(config: SandboxConfig) -> None:
     """Run all pre-flight checks for hardened mode.
 
     Checks:
     1. Config values are valid.
     2. Platform is Linux.
     3. Required tools are on PATH (bwrap, setpriv, prlimit).
-    4. Network sanity check (if config.require_network_disabled).
+    4. bwrap can create namespaces in this runtime.
+    5. Network sanity check (if config.require_network_disabled).
 
     Call once at startup before spawning any sandbox subprocess.
     Raises SandboxError on any failure.
     """
     validate_config(config)
     verify_platform()
     verify_tools()
+    _verify_bwrap_capabilities(config)
 
     if config.require_network_disabled:
         verify_network_disabled()

tests/test_sandbox.py

@@ -8,6 +8,7 @@
 
 import os
 import shutil
+import subprocess
 
 import pytest
 
@@ -17,6 +18,7 @@
     _is_under_any,
     _resolve_writable_roots,
     _validate_bind_prefix,
+    _verify_bwrap_capabilities,
     build_hardened_command,
     check_command_allowed,
     default_hardened_config,
@@ -32,6 +34,21 @@ def _config(**overrides) -> SandboxConfig:
     return SandboxConfig(**overrides)
 
 
+def _mock_bwrap_success(*args, **kwargs):
+    """Monkeypatch target for subprocess.run that simulates bwrap success."""
+    return subprocess.CompletedProcess(args=args[0], returncode=0, stdout="", stderr="")
+
+
+def _mock_bwrap_failure(*args, **kwargs):
+    """Monkeypatch target for subprocess.run that simulates bwrap failure."""
+    return subprocess.CompletedProcess(
+        args=args[0],
+        returncode=1,
+        stdout="",
+        stderr="bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted",
+    )
+
+
 # ---------------------------------------------------------------------------
 # Config validation
 # ---------------------------------------------------------------------------
@@ -235,10 +252,108 @@ def _boom():
             verify_network_disabled()
 
 
+# ---------------------------------------------------------------------------
+# bwrap capability smoke test
+# ---------------------------------------------------------------------------
+
+
+class TestVerifyBwrapCapabilities:
+    def test_bwrap_smoke_success(self, monkeypatch):
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _mock_bwrap_success)
+        config = _config()
+        _verify_bwrap_capabilities(config)
+
+    def test_bwrap_smoke_failure_gives_clear_error(self, monkeypatch):
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _mock_bwrap_failure)
+        config = _config()
+        with pytest.raises(SandboxError, match="runtime check failed"):
+            _verify_bwrap_capabilities(config)
+
+    def test_bwrap_smoke_failure_mentions_docs(self, monkeypatch):
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _mock_bwrap_failure)
+        config = _config()
+        with pytest.raises(SandboxError, match="deployment-modes"):
+            _verify_bwrap_capabilities(config)
+
+    def test_bwrap_smoke_failure_includes_stderr(self, monkeypatch):
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _mock_bwrap_failure)
+        config = _config()
+        with pytest.raises(SandboxError, match="RTM_NEWADDR"):
+            _verify_bwrap_capabilities(config)
+
+    def test_bwrap_smoke_empty_stderr_handled(self, monkeypatch):
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
+
+        def _fail_no_stderr(*args, **kwargs):
+            return subprocess.CompletedProcess(args=args[0], returncode=1, stdout="", stderr="")
+
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _fail_no_stderr)
+        config = _config()
+        with pytest.raises(SandboxError, match="<no stderr>"):
+            _verify_bwrap_capabilities(config)
+
+    def test_bwrap_probe_uses_usr_bin_true_when_no_bin(self, monkeypatch):
+        """Config with /usr but not /bin should select /usr/bin/true."""
+
+        def _selective_exists(path):
+            if path in ("/usr", "/usr/bin/true"):
+                return True
+            if path == "/bin":
+                return False
+            return True
+
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", _selective_exists)
+
+        captured_argv = []
+
+        def _capture_run(argv, **kwargs):
+            captured_argv.extend(argv)
+            return subprocess.CompletedProcess(args=argv, returncode=0, stdout="", stderr="")
+
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _capture_run)
+
+        config = _config(readonly_bind_paths=("/usr",))
+        _verify_bwrap_capabilities(config)
+
+        assert "/usr/bin/true" in captured_argv
+        assert "/bin/true" not in captured_argv
+
+    def test_bwrap_probe_no_executable_found(self, monkeypatch):
+        """Config with no usable readonly paths should fail clearly."""
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: False)
+
+        config = _config(readonly_bind_paths=())
+        with pytest.raises(SandboxError, match="cannot select a probe executable"):
+            _verify_bwrap_capabilities(config)
+
+    def test_bwrap_probe_timeout_handled(self, monkeypatch):
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
+
+        def _timeout(*args, **kwargs):
+            raise subprocess.TimeoutExpired(cmd=args[0], timeout=5)
+
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _timeout)
+
+        config = _config()
+        with pytest.raises(SandboxError, match="timed out"):
+            _verify_bwrap_capabilities(config)
+
+
+# ---------------------------------------------------------------------------
+# verify_hardened_runtime (full preflight)
+# ---------------------------------------------------------------------------
+
+
 class TestVerifyHardenedRuntime:
     def test_full_preflight(self, monkeypatch):
         monkeypatch.setattr("csc_runner.sandbox.platform.system", lambda: "Linux")
         monkeypatch.setattr("csc_runner.sandbox.shutil.which", lambda name: f"/usr/bin/{name}")
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _mock_bwrap_success)
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
         monkeypatch.setattr(
             "csc_runner.sandbox.socket.if_nameindex",
             lambda: [(1, "lo")],
@@ -249,6 +364,8 @@ def test_full_preflight(self, monkeypatch):
     def test_network_check_skippable(self, monkeypatch):
         monkeypatch.setattr("csc_runner.sandbox.platform.system", lambda: "Linux")
         monkeypatch.setattr("csc_runner.sandbox.shutil.which", lambda name: f"/usr/bin/{name}")
+        monkeypatch.setattr("csc_runner.sandbox.subprocess.run", _mock_bwrap_success)
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
         config = _config(require_network_disabled=False)
         verify_hardened_runtime(config)
 
@@ -479,7 +596,7 @@ def test_relative_read_prefix_rejected(self, tmp_path):
             self._build(tmp_path, read_bind_prefixes=["relative/path"])
 
     def test_system_paths_readonly(self, tmp_path, monkeypatch):
-        monkeypatch.setattr("os.path.exists", lambda p: True)
+        monkeypatch.setattr("csc_runner.sandbox.os.path.exists", lambda p: True)
         cwd = str(tmp_path / "workspace")
         os.makedirs(cwd, exist_ok=True)
         config = _config(readonly_bind_paths=("/usr", "/lib"))