docketeer-bubblewrap 0.0.7__tar.gz

docketeer_bubblewrap-0.0.7/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.envrc.private
+.claude/settings.local.json
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+workspace/
+.coverage
+.loq_cache

docketeer_bubblewrap-0.0.7/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: docketeer-bubblewrap
+Version: 0.0.7
+Summary: Bubblewrap sandbox executor plugin for Docketeer
+Project-URL: Homepage, https://github.com/chrisguidry/docketeer
+Project-URL: Repository, https://github.com/chrisguidry/docketeer
+Project-URL: Issues, https://github.com/chrisguidry/docketeer/issues
+Author-email: Chris Guidry <guid@omg.lol>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: docketeer
+Description-Content-Type: text/markdown
+
+# docketeer-bubblewrap
+
+Sandboxed command execution for [Docketeer](https://github.com/chrisguidry/docketeer)
+using [bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`).
+
+This plugin provides a `CommandExecutor` implementation that runs external
+programs inside a lightweight Linux sandbox using unprivileged user namespaces.
+Each process gets its own PID, UTS, IPC, and cgroup namespaces, and network
+access is denied by default. The `--die-with-parent` flag ensures sandboxed
+processes are cleaned up if the parent exits.
+
+## Requirements
+
+- Linux with unprivileged user namespaces enabled
+- `bwrap` on `PATH` (install via your distro's `bubblewrap` package)
+
+## How it works
+
+The executor builds a minimal filesystem view inside the sandbox:
+
+- Read-only binds for system directories (`/usr`, `/bin`, `/lib`, `/etc/ssl`, etc.)
+- `/proc`, `/dev`, and a tmpfs `/tmp`
+- User-specified mounts (read-only or writable)
+- Optional network access via `--share-net`

docketeer_bubblewrap-0.0.7/README.md

@@ -0,0 +1,24 @@
+# docketeer-bubblewrap
+
+Sandboxed command execution for [Docketeer](https://github.com/chrisguidry/docketeer)
+using [bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`).
+
+This plugin provides a `CommandExecutor` implementation that runs external
+programs inside a lightweight Linux sandbox using unprivileged user namespaces.
+Each process gets its own PID, UTS, IPC, and cgroup namespaces, and network
+access is denied by default. The `--die-with-parent` flag ensures sandboxed
+processes are cleaned up if the parent exits.
+
+## Requirements
+
+- Linux with unprivileged user namespaces enabled
+- `bwrap` on `PATH` (install via your distro's `bubblewrap` package)
+
+## How it works
+
+The executor builds a minimal filesystem view inside the sandbox:
+
+- Read-only binds for system directories (`/usr`, `/bin`, `/lib`, `/etc/ssl`, etc.)
+- `/proc`, `/dev`, and a tmpfs `/tmp`
+- User-specified mounts (read-only or writable)
+- Optional network access via `--share-net`

docketeer_bubblewrap-0.0.7/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "docketeer-bubblewrap"
+dynamic = ["version"]
+description = "Bubblewrap sandbox executor plugin for Docketeer"
+readme = "README.md"
+authors = [
+    { name = "Chris Guidry", email = "guid@omg.lol" }
+]
+license = "MIT"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Security",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "docketeer",
+]
+
+[project.urls]
+Homepage = "https://github.com/chrisguidry/docketeer"
+Repository = "https://github.com/chrisguidry/docketeer"
+Issues = "https://github.com/chrisguidry/docketeer/issues"
+
+[project.entry-points."docketeer.executor"]
+bubblewrap = "docketeer_bubblewrap"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options.root = ".."
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docketeer_bubblewrap"]
+
+[tool.uv.sources]
+docketeer = { workspace = true }
+
+[tool.docketeer.ci]
+apt-packages = ["bubblewrap"]
+sysctl = ["kernel.apparmor_restrict_unprivileged_userns=0"]
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+addopts = [
+    "--import-mode=importlib",
+    "--cov=docketeer_bubblewrap",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+asyncio_mode = "auto"
+filterwarnings = [
+    "error",
+]

docketeer_bubblewrap-0.0.7/src/docketeer_bubblewrap/__init__.py

@@ -0,0 +1,8 @@
+from docketeer_bubblewrap.executor import BubblewrapExecutor
+
+
+def create_executor() -> BubblewrapExecutor:
+    return BubblewrapExecutor()
+
+
+__all__ = ["BubblewrapExecutor", "create_executor"]

docketeer_bubblewrap-0.0.7/src/docketeer_bubblewrap/executor.py

@@ -0,0 +1,126 @@
+"""Bubblewrap-based sandboxed command executor."""
+
+import asyncio
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from docketeer.executor import CommandExecutor, CompletedProcess, Mount, RunningProcess
+
+SYSTEM_RO_BINDS = [
+    "/usr",
+    "/bin",
+    "/lib",
+    "/lib64",
+    "/etc/ssl",
+    "/etc/resolv.conf",
+    "/etc/hosts",
+    "/etc/alternatives",
+]
+
+
+class _SandboxedProcess(RunningProcess):
+    """RunningProcess that cleans up a temporary directory after the process exits."""
+
+    def __init__(
+        self,
+        process: asyncio.subprocess.Process,
+        tmp_ctx: tempfile.TemporaryDirectory[str] | None,
+    ) -> None:
+        super().__init__(process)
+        self._tmp_ctx = tmp_ctx
+
+    async def wait(self) -> CompletedProcess:
+        result = await super().wait()
+        if self._tmp_ctx:
+            self._tmp_ctx.cleanup()
+        return result
+
+
+class BubblewrapExecutor(CommandExecutor):
+    """Runs commands inside a bubblewrap sandbox."""
+
+    def __init__(self) -> None:
+        if not shutil.which("bwrap"):
+            raise RuntimeError("bwrap not found on PATH")
+
+    async def start(
+        self,
+        command: list[str],
+        *,
+        env: dict[str, str] | None = None,
+        mounts: list[Mount] | None = None,
+        network_access: bool = False,
+        username: str | None = None,
+    ) -> RunningProcess:
+        tmp_ctx: tempfile.TemporaryDirectory[str] | None = None
+        tmp_dir: Path | None = None
+        if username:
+            tmp_ctx = tempfile.TemporaryDirectory()
+            tmp_dir = Path(tmp_ctx.name)
+
+        args = _build_args(
+            mounts=mounts or [],
+            network_access=network_access,
+            username=username,
+            tmp_dir=tmp_dir,
+        )
+        args.extend(command)
+
+        process = await asyncio.create_subprocess_exec(
+            *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env or {},
+        )
+        return _SandboxedProcess(process, tmp_ctx)
+
+
+def _build_args(
+    *,
+    mounts: list[Mount],
+    network_access: bool,
+    username: str | None = None,
+    tmp_dir: Path | None = None,
+) -> list[str]:
+    args = ["bwrap", "--die-with-parent"]
+
+    # Namespace isolation
+    args.extend(["--unshare-pid", "--unshare-uts", "--unshare-ipc", "--unshare-cgroup"])
+    if not network_access:
+        args.append("--unshare-net")
+
+    # Read-only system binds (skip paths that don't exist)
+    for path in SYSTEM_RO_BINDS:
+        if Path(path).exists():
+            args.extend(["--ro-bind", path, path])
+
+    # Virtual filesystems
+    args.extend(["--proc", "/proc"])
+    args.extend(["--dev", "/dev"])
+    args.extend(["--tmpfs", "/tmp"])
+
+    # Identity mapping
+    if username:
+        uid = os.getuid()
+        gid = os.getgid()
+        args.extend(["--uid", str(uid), "--gid", str(gid)])
+
+        stub_dir = tmp_dir if tmp_dir else Path(tempfile.mkdtemp())
+
+        passwd_file = stub_dir / "passwd"
+        passwd_file.write_text(f"{username}:x:{uid}:{gid}::/home/{username}:/bin/sh\n")
+        args.extend(["--ro-bind", str(passwd_file), "/etc/passwd"])
+
+        group_file = stub_dir / "group"
+        group_file.write_text(f"{username}:x:{gid}:\n")
+        args.extend(["--ro-bind", str(group_file), "/etc/group"])
+
+    # User-specified mounts
+    for mount in mounts:
+        flag = "--bind" if mount.writable else "--ro-bind"
+        args.extend([flag, str(mount.source), str(mount.target)])
+
+    return args

docketeer_bubblewrap-0.0.7/tests/test_executor.py

@@ -0,0 +1,260 @@
+"""Tests for the bubblewrap executor."""
+
+import os
+import shutil
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from docketeer.executor import Mount
+from docketeer_bubblewrap import BubblewrapExecutor, create_executor
+from docketeer_bubblewrap.executor import (
+    _build_args,
+    _SandboxedProcess,
+)
+
+has_bwrap = shutil.which("bwrap") is not None
+requires_bwrap = pytest.mark.skipif(not has_bwrap, reason="bwrap not on PATH")
+
+
+# --- Factory ---
+
+
+@requires_bwrap
+def test_create_executor():
+    executor = create_executor()
+    assert isinstance(executor, BubblewrapExecutor)
+
+
+def test_create_executor_bwrap_missing():
+    with patch("shutil.which", return_value=None):
+        with pytest.raises(RuntimeError, match="bwrap not found"):
+            BubblewrapExecutor()
+
+
+# --- _build_args ---
+
+
+def test_build_args_default_flags():
+    args = _build_args(mounts=[], network_access=False)
+    assert args[0] == "bwrap"
+    assert "--die-with-parent" in args
+    assert "--unshare-pid" in args
+    assert "--unshare-uts" in args
+    assert "--unshare-ipc" in args
+    assert "--unshare-cgroup" in args
+    assert "--unshare-net" in args
+    assert "--proc" in args
+    assert "--dev" in args
+    assert "--tmpfs" in args
+
+
+def test_build_args_network_access():
+    args = _build_args(mounts=[], network_access=True)
+    assert "--unshare-net" not in args
+    assert "--unshare-pid" in args
+
+
+def test_build_args_custom_mounts():
+    mounts = [
+        Mount(source=Path("/data"), target=Path("/mnt/data"), writable=True),
+        Mount(source=Path("/config"), target=Path("/mnt/config")),
+    ]
+    args = _build_args(mounts=mounts, network_access=False)
+
+    # Find the writable mount
+    bind_idx = args.index("--bind")
+    assert args[bind_idx + 1] == "/data"
+    assert args[bind_idx + 2] == "/mnt/data"
+
+    # Find the read-only mount (after system binds, so find from the writable mount onward)
+    remaining = args[bind_idx + 3 :]
+    ro_idx = remaining.index("--ro-bind")
+    assert remaining[ro_idx + 1] == "/config"
+    assert remaining[ro_idx + 2] == "/mnt/config"
+
+
+def test_build_args_skips_missing_system_paths():
+    with patch("docketeer_bubblewrap.executor.SYSTEM_RO_BINDS", ["/no/such/path"]):
+        args = _build_args(mounts=[], network_access=False)
+
+    # /no/such/path doesn't exist, so no --ro-bind should appear
+    ro_bind_count = args.count("--ro-bind")
+    assert ro_bind_count == 0
+
+
+def test_build_args_without_username():
+    args = _build_args(mounts=[], network_access=False)
+    assert "--uid" not in args
+    assert "--gid" not in args
+
+
+def test_build_args_with_username():
+    args = _build_args(mounts=[], network_access=False, username="nix")
+    uid = os.getuid()
+    gid = os.getgid()
+
+    uid_idx = args.index("--uid")
+    assert args[uid_idx + 1] == str(uid)
+
+    gid_idx = args.index("--gid")
+    assert args[gid_idx + 1] == str(gid)
+
+
+def test_build_args_with_username_creates_passwd_file(tmp_path: Path):
+    args = _build_args(
+        mounts=[], network_access=False, username="nix", tmp_dir=tmp_path
+    )
+    uid = os.getuid()
+    gid = os.getgid()
+
+    passwd_path = tmp_path / "passwd"
+    assert passwd_path.exists()
+    content = passwd_path.read_text()
+    assert f"nix:x:{uid}:{gid}::" in content
+    assert "/home/nix" in content
+
+    # --ro-bind <source> /etc/passwd
+    passwd_idx = args.index(str(passwd_path))
+    assert args[passwd_idx - 1] == "--ro-bind"
+    assert args[passwd_idx + 1] == "/etc/passwd"
+
+
+def test_build_args_with_username_creates_group_file(tmp_path: Path):
+    args = _build_args(
+        mounts=[], network_access=False, username="nix", tmp_dir=tmp_path
+    )
+    gid = os.getgid()
+
+    group_path = tmp_path / "group"
+    assert group_path.exists()
+    content = group_path.read_text()
+    assert f"nix:x:{gid}:" in content
+
+    # --ro-bind <source> /etc/group
+    group_idx = args.index(str(group_path))
+    assert args[group_idx - 1] == "--ro-bind"
+    assert args[group_idx + 1] == "/etc/group"
+
+
+# --- Integration tests (require bwrap) ---
+
+
+@pytest.fixture()
+def executor() -> BubblewrapExecutor:
+    if not has_bwrap:
+        pytest.skip("bwrap not on PATH")
+    return BubblewrapExecutor()
+
+
+async def test_run_echo(executor: BubblewrapExecutor):
+    rp = await executor.start(["echo", "hello sandbox"])
+    result = await rp.wait()
+    assert result.returncode == 0
+    assert b"hello sandbox" in result.stdout
+
+
+async def test_writable_mount(executor: BubblewrapExecutor, tmp_path: Path):
+    test_file = tmp_path / "output.txt"
+    rp = await executor.start(
+        ["sh", "-c", "echo written > /mnt/work/output.txt"],
+        mounts=[Mount(source=tmp_path, target=Path("/mnt/work"), writable=True)],
+    )
+    result = await rp.wait()
+    assert result.returncode == 0
+    assert test_file.read_text().strip() == "written"
+
+
+async def test_readonly_mount(executor: BubblewrapExecutor, tmp_path: Path):
+    source_file = tmp_path / "input.txt"
+    source_file.write_text("readonly content")
+    rp = await executor.start(
+        ["cat", "/mnt/ro/input.txt"],
+        mounts=[Mount(source=tmp_path, target=Path("/mnt/ro"))],
+    )
+    result = await rp.wait()
+    assert result.returncode == 0
+    assert b"readonly content" in result.stdout
+
+
+async def test_readonly_mount_rejects_writes(
+    executor: BubblewrapExecutor, tmp_path: Path
+):
+    rp = await executor.start(
+        ["sh", "-c", "echo fail > /mnt/ro/nope.txt"],
+        mounts=[Mount(source=tmp_path, target=Path("/mnt/ro"))],
+    )
+    result = await rp.wait()
+    assert result.returncode != 0
+
+
+async def test_terminate(executor: BubblewrapExecutor):
+    rp = await executor.start(["sleep", "60"])
+    rp.terminate()
+    result = await rp.wait()
+    assert result.returncode != 0
+
+
+async def test_env_empty_by_default(executor: BubblewrapExecutor):
+    rp = await executor.start(["env"])
+    result = await rp.wait()
+    assert result.returncode == 0
+    env_vars = dict(
+        line.split("=", 1)
+        for line in result.stdout.decode().strip().splitlines()
+        if "=" in line
+    )
+    # PWD is set by the kernel, not inherited — that's fine
+    env_vars.pop("PWD", None)
+    assert env_vars == {}
+
+
+async def test_env_passed_to_subprocess(executor: BubblewrapExecutor):
+    rp = await executor.start(
+        ["sh", "-c", "echo $MY_VAR"],
+        env={"MY_VAR": "test_value", "PATH": "/usr/bin:/bin"},
+    )
+    result = await rp.wait()
+    assert result.returncode == 0
+    assert b"test_value" in result.stdout
+
+
+async def test_username_stubs_cleaned_up_after_wait(executor: BubblewrapExecutor):
+    rp = await executor.start(["true"], username="nix")
+    assert isinstance(rp, _SandboxedProcess)
+    assert rp._tmp_ctx is not None
+    stub_dir = Path(rp._tmp_ctx.name)
+    assert stub_dir.exists()
+    assert (stub_dir / "passwd").exists()
+    assert (stub_dir / "group").exists()
+
+    await rp.wait()
+    assert not stub_dir.exists()
+
+
+async def test_no_cleanup_without_username(executor: BubblewrapExecutor):
+    rp = await executor.start(["true"])
+    assert isinstance(rp, _SandboxedProcess)
+    assert rp._tmp_ctx is None
+    await rp.wait()
+
+
+async def test_username_sets_identity(executor: BubblewrapExecutor):
+    rp = await executor.start(
+        ["sh", "-c", "whoami && id -gn"],
+        username="nix",
+    )
+    result = await rp.wait()
+    assert result.returncode == 0
+    lines = result.stdout.decode().strip().splitlines()
+    assert lines[0] == "nix"
+    assert lines[1] == "nix"
+
+
+async def test_network_isolated_by_default(executor: BubblewrapExecutor):
+    rp = await executor.start(
+        ["sh", "-c", "cat /proc/net/if_inet6 2>/dev/null || echo no-network"],
+    )
+    result = await rp.wait()
+    assert result.returncode == 0