Skip to content
Python

Seatbelt provider: the tool runner inside the macOS sandbox

Devika Verma58385ef02bfb
diff --git a/coworker/config.py b/coworker/config.py
index ae740ff4..b8a6c702 100644
--- a/coworker/config.py
+++ b/coworker/config.py
@@ -113,8 +113,9 @@ class Config:
# off entirely; dev/BYO deployments point elsewhere.
cloud_machines_base: str = "https://machines.openworker.com"
# Where agents' commands and file tools run: "direct" (in this process, unconfined),
- # "openshell" (one OpenShell sandbox per agent; sessions are refused when OpenShell is
- # not usable). Unset = the default rule in coworker/sandbox/selection.py. Machine-level
+ # "seatbelt" (macOS: a process on this Mac under the system sandbox), "openshell" (one
+ # OpenShell sandbox per agent). Sessions are refused when the chosen sandbox is not
+ # usable. Unset = the default rule in coworker/sandbox/selection.py. Machine-level
# only: a repository's own config must never be able to switch the sandbox off.
# Environment override: OPENWORKER_SANDBOX_PROVIDER.
sandbox_provider: Optional[str] = None
diff --git a/coworker/sandbox/client.py b/coworker/sandbox/client.py
index 019a5b43..ebebc6b1 100644
--- a/coworker/sandbox/client.py
+++ b/coworker/sandbox/client.py
@@ -86,6 +86,17 @@ class RunnerClient:
self._send(transport, frame)
return hello
+ def detach(self) -> None:
+ """The provider is about to replace the runner on purpose (a sandbox restart). Drop
+ this connection without the automatic reconnect, which would chase a runner that is
+ going away. `connect()` follows."""
+ with self._connect_lock:
+ with self._state_lock:
+ self._generation += 1 # the old read loop sees a newer generation and stops
+ transport, self._transport = self._transport, None
+ if transport is not None:
+ transport.close()
+
def _reconnect(self, generation: int) -> None:
with self._connect_lock:
if self._closed or generation != self._generation:
diff --git a/coworker/sandbox/executor.py b/coworker/sandbox/executor.py
index 20bdb0ca..df7ae097 100644
--- a/coworker/sandbox/executor.py
+++ b/coworker/sandbox/executor.py
@@ -29,8 +29,12 @@ class RunnerExecutor(Executor):
shell: str = "main",
default_timeout: float = _DEFAULT_TIMEOUT,
on_output: Optional[Callable[[str], None]] = None,
+ before_call: Optional[Callable[[], Optional[str]]] = None,
) -> None:
self._client = client
+ # Called before every command. The workspace uses it to restart the sandbox when the
+ # session's folders changed; what it returns is told to the agent with the result.
+ self._before_call = before_call
self.shell = shell
self.cwd = str(cwd) # the last folder the runner reported; a reopened shell starts here
self.default_timeout = default_timeout
@@ -49,6 +53,7 @@ class RunnerExecutor(Executor):
def run(self, command: str, timeout: Optional[float] = None) -> dict[str, Any]:
timeout = timeout or self.default_timeout
+ notice = self._before_call() if self._before_call is not None else None
def live(method: str, params: dict[str, Any]) -> None:
if method == "shell.output" and self._on_output is not None:
@@ -65,7 +70,10 @@ class RunnerExecutor(Executor):
return self._failed(command, exc.message)
if isinstance(result.get("cwd"), str) and result["cwd"]:
self.cwd = result["cwd"]
- return {key: result[key] for key in _RESULT_KEYS if key in result}
+ answer = {key: result[key] for key in _RESULT_KEYS if key in result}
+ if notice:
+ answer["sandbox_notice"] = notice
+ return answer
def run_background(self, command: str) -> dict[str, Any]:
return self._simple("task.start", {"command": command, "cwd": self.cwd})
diff --git a/coworker/sandbox/providers/openshell.py b/coworker/sandbox/providers/openshell.py
index f3a352f0..7829372d 100644
--- a/coworker/sandbox/providers/openshell.py
+++ b/coworker/sandbox/providers/openshell.py
@@ -186,11 +186,23 @@ class OpenShellProvider:
if "entries" not in info:
raise RuntimeError(f"the folder {root['path']} is not reachable inside the sandbox")
- def destroy(self) -> None:
+ def regrant(self, roots: Sequence[dict[str, Any]]) -> None:
+ """The session's folders changed. Mounts and the file policy are fixed when a sandbox
+ is created, so this one is deleted and a new one is created with the new folders."""
+ self._delete()
+ self.roots = [{"path": str(Path(r["path"]).expanduser().resolve()), "writable": bool(r.get("writable"))} for r in roots]
+ self.sandbox_name = f"ow-{uuid.uuid4().hex[:12]}"
+ self.sandbox_id = None
+ self.create()
+
+ def _delete(self) -> None:
try:
_cli("sandbox", "delete", self.sandbox_name, timeout=90, check=False)
except (subprocess.TimeoutExpired, OpenShellUnavailable):
pass
+
+ def destroy(self) -> None:
+ self._delete()
shutil.rmtree(self._tmp, ignore_errors=True)
diff --git a/coworker/sandbox/providers/seatbelt.py b/coworker/sandbox/providers/seatbelt.py
new file mode 100644
index 00000000..f3b9657b
--- /dev/null
+++ b/coworker/sandbox/providers/seatbelt.py
@@ -0,0 +1,222 @@
+"""`seatbelt`: the tool runner as a process on this Mac, confined by the macOS sandbox.
+
+The same runner and the same protocol as every other provider. What differs is the wall:
+the daemon is started through `sandbox-exec` with a profile rendered from the session's
+folders (seatbelt_profile.py), and every command it starts inherits that profile. The
+kernel enforces it; a process cannot take it off.
+
+- Files: the session's folders, one temporary folder, the system, a list of developer
+ toolchains. Nothing else under the home folder.
+- Network: only the server's allow-list proxy (netproxy.py).
+- Environment: the server's own variables are not passed on when their name says they hold
+ a secret, so a model key in the server's environment never reaches a command.
+
+The attach relay runs OUTSIDE the sandbox: it is our code, it only moves bytes between the
+server and the daemon's Unix socket, and nothing the agent says is executed by it.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Optional, Sequence
+
+from .. import netproxy, network_profiles
+from ..bundle import build_runner_zipapp
+from ..transport import PipeTransport, Transport
+from . import seatbelt_profile
+
+SANDBOX_EXEC = "/usr/bin/sandbox-exec"
+_SECRET_NAME = re.compile(r"KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|COOKIE|SESSION", re.IGNORECASE)
+_OWN_PREFIXES = ("COWORKER_", "OPENWORKER_")
+# Caches that tools keep under the home folder, moved into the sandbox's temporary folder.
+_CACHE_VARIABLES = {
+ "npm_config_cache": "npm",
+ "PIP_CACHE_DIR": "pip",
+ "UV_CACHE_DIR": "uv",
+ "XDG_CACHE_HOME": "xdg",
+ "GOCACHE": "go-build",
+ "YARN_CACHE_FOLDER": "yarn",
+ "PYTHONPYCACHEPREFIX": "pycache",
+}
+
+
+class SeatbeltUnavailable(RuntimeError):
+ """The macOS sandbox cannot be used here. The message says why."""
+
+
+def preflight() -> None:
+ if sys.platform != "darwin":
+ raise SeatbeltUnavailable("The Seatbelt sandbox exists only on macOS.")
+ if not os.access(SANDBOX_EXEC, os.X_OK):
+ raise SeatbeltUnavailable(f"{SANDBOX_EXEC} is missing on this Mac.")
+ if getattr(sys, "frozen", False):
+ raise SeatbeltUnavailable("The Seatbelt sandbox is not available in the packaged desktop app yet.")
+ probe = subprocess.run(
+ [SANDBOX_EXEC, "-p", "(version 1)(allow default)", "/usr/bin/true"],
+ stdin=subprocess.DEVNULL,
+ capture_output=True,
+ text=True,
+ timeout=15,
+ )
+ if probe.returncode != 0:
+ # The usual cause: this process is itself inside a sandbox, and macOS does not nest them.
+ raise SeatbeltUnavailable(f"sandbox-exec could not apply a profile: {probe.stderr.strip() or probe.returncode}")
+
+
+def clean_environment(base: Optional[dict[str, str]] = None) -> dict[str, str]:
+ """The server's environment without anything whose name says it is a secret, and without
+ OpenWorker's own variables (one of them is the server's API token)."""
+ source = os.environ if base is None else base
+ return {k: v for k, v in source.items() if not k.startswith(_OWN_PREFIXES) and not _SECRET_NAME.search(k)}
+
+
+def _python_read_paths() -> list[str]:
+ """What the Python that runs the runner needs to read: itself and its standard library.
+ In a virtual environment the real interpreter lives elsewhere (`base_prefix`)."""
+ paths = {sys.prefix, sys.base_prefix, os.path.dirname(os.path.realpath(sys.executable))}
+ return sorted(p for p in paths if p)
+
+
+class SeatbeltProvider:
+ name = "seatbelt"
+
+ def __init__(
+ self,
+ *,
+ roots: Sequence[dict[str, Any]],
+ cwd: str | Path,
+ profile: str = network_profiles.DEFAULT_PROFILE,
+ network: bool = True,
+ runner_path: Optional[Path] = None,
+ relay_silence_seconds: Optional[float] = None,
+ ) -> None:
+ self.roots = [{"path": seatbelt_profile.real(r["path"]), "writable": bool(r.get("writable"))} for r in roots]
+ self.cwd = seatbelt_profile.real(cwd)
+ self.profile = network_profiles.check(profile)
+ self.network = network
+ self._runner = Path(runner_path) if runner_path is not None else build_runner_zipapp()
+ self._relay_silence = relay_silence_seconds
+ self.sandbox = f"sb-{uuid.uuid4().hex[:12]}"
+ # Short, because a Unix socket path is limited to about 100 bytes; resolved, because
+ # Seatbelt matches real paths and `/tmp` is a link on macOS.
+ self._dir = seatbelt_profile.real(tempfile.mkdtemp(prefix="owr-", dir="/tmp"))
+ self.socket_path = os.path.join(self._dir, "r.sock")
+ self._daemon: Optional[subprocess.Popen] = None
+ self._proxy: Optional[netproxy.AllowListProxy] = None
+
+ def describe(self) -> dict[str, Any]:
+ network = f"only the hosts of the '{self.profile}' profile, through the allow-list proxy" if self.network else "none"
+ return {
+ "provider": self.name,
+ "sandbox": self.sandbox,
+ "enforcement": "full",
+ "reason": f"macOS sandbox: files limited to the session's folders; network: {network}",
+ }
+
+ def profile_text(self) -> str:
+ from ... import toolchain
+
+ return seatbelt_profile.render(
+ self.roots,
+ runtime_dir=self._dir,
+ read_only=[str(self._runner), *_python_read_paths(), str(toolchain.bin_dir())],
+ proxy_port=self._proxy.port if self._proxy is not None else None,
+ )
+
+ def _environment(self) -> dict[str, str]:
+ env = clean_environment()
+ tmp = os.path.join(self._dir, "tmp")
+ env["TMPDIR"] = tmp + "/"
+ for variable, folder in _CACHE_VARIABLES.items():
+ env[variable] = os.path.join(tmp, "cache", folder)
+ if self._proxy is not None:
+ env.update(netproxy.environment(self._proxy))
+ return env
+
+ def create(self) -> None:
+ preflight()
+ os.makedirs(os.path.join(self._dir, "tmp", "cache"), exist_ok=True)
+ self._proxy = netproxy.shared(self.profile) if self.network else None
+ log = open(os.path.join(self._dir, "daemon.log"), "wb")
+ self._daemon = subprocess.Popen(
+ [
+ SANDBOX_EXEC, "-p", self.profile_text(),
+ sys.executable, "-S", str(self._runner),
+ "serve", "--socket", self.socket_path, "--cwd", self.cwd, "--exit-with-parent",
+ ], # fmt: skip
+ stdin=subprocess.DEVNULL,
+ stdout=subprocess.DEVNULL,
+ stderr=log, # a file, not a pipe: nobody reads a pipe while the daemon lives
+ env=self._environment(),
+ cwd="/",
+ start_new_session=True,
+ )
+ log.close()
+ deadline = time.monotonic() + 15
+ while not os.path.exists(self.socket_path):
+ if self._daemon.poll() is not None:
+ said = Path(self._dir, "daemon.log").read_text(errors="replace").strip()
+ raise SeatbeltUnavailable(f"the sandboxed tool runner exited at once (code {self._daemon.returncode}). {said[-400:]}")
+ if time.monotonic() > deadline:
+ raise SeatbeltUnavailable("the sandboxed tool runner did not come up in 15 seconds")
+ time.sleep(0.02)
+
+ def open_runner(self) -> Transport:
+ argv = [sys.executable, "-S", str(self._runner), "attach", "--socket", self.socket_path]
+ if self._relay_silence is not None:
+ argv += ["--silence-seconds", str(self._relay_silence)]
+ return PipeTransport(
+ subprocess.Popen(argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, bufsize=0)
+ )
+
+ def verify(self, client: Any) -> None:
+ """Every folder is reachable inside, and the wall is really up: the home folder,
+ which no session is given as a whole, must NOT be listable."""
+ from ..runner.protocol import RunnerError
+
+ for root in self.roots:
+ client.call("fs.list", {"path": root["path"], "limit": 1}, timeout=15)
+ home = seatbelt_profile.real("~")
+ if any(home == r["path"] or home.startswith(r["path"] + os.sep) for r in self.roots):
+ return # the user granted the home folder itself; nothing to prove
+ try:
+ client.call("fs.list", {"path": home, "limit": 1}, timeout=15)
+ except RunnerError:
+ return
+ raise SeatbeltUnavailable("the sandbox did not take effect: the home folder can be listed from inside")
+
+ def regrant(self, roots: Sequence[dict[str, Any]]) -> None:
+ """The session's folders changed. A profile is fixed when a process starts, so the
+ daemon is started again with a new one; the client sees a runner restart."""
+ self.roots = [{"path": seatbelt_profile.real(r["path"]), "writable": bool(r.get("writable"))} for r in roots]
+ self._stop_daemon()
+ self.create()
+
+ def restart_daemon(self) -> None:
+ """Tests only: what a sandbox restart looks like from the client's side."""
+ self._stop_daemon()
+ self.create()
+
+ def _stop_daemon(self) -> None:
+ if self._daemon is not None and self._daemon.poll() is None:
+ self._daemon.terminate()
+ try:
+ self._daemon.wait(timeout=5)
+ except subprocess.TimeoutExpired:
+ self._daemon.kill()
+ try:
+ os.unlink(self.socket_path)
+ except OSError:
+ pass
+
+ def destroy(self) -> None:
+ self._stop_daemon()
+ shutil.rmtree(self._dir, ignore_errors=True)
diff --git a/coworker/sandbox/providers/seatbelt_profile.py b/coworker/sandbox/providers/seatbelt_profile.py
new file mode 100644
index 00000000..8f945e06
--- /dev/null
+++ b/coworker/sandbox/providers/seatbelt_profile.py
@@ -0,0 +1,156 @@
+"""Render a macOS Seatbelt profile from OUR words: the session's folders and a proxy port.
+
+The profile starts from "deny everything" and allows:
+- reading the system (programs, libraries, settings), never the user's home as a whole;
+- reading and writing the session's folders (a read-only folder: reading only) and one
+ temporary folder that belongs to this sandbox;
+- reading a fixed list of developer toolchains under the home folder, so `node`, `cargo`
+ and friends still run, and the user's git settings (git refuses to run without them);
+- the network only through one local port, where the server's allow-list proxy listens.
+ Without a port there is no network at all.
+
+Everything else under the home folder (`~/.ssh`, `~/.aws`, documents, other projects,
+OpenWorker's own state with its keys) cannot be read, listed or written.
+
+Seatbelt matches real paths, so every path is resolved first (`/tmp` is `/private/tmp`).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Optional, Sequence
+
+# Programs, libraries and settings. No entry here is under a home folder.
+_SYSTEM_READ = [
+ "/usr",
+ "/bin",
+ "/sbin",
+ "/System",
+ "/Library",
+ "/opt",
+ "/Applications",
+ "/private/etc",
+ "/private/var/db/timezone",
+ "/private/var/db/xcode_select_link",
+ "/private/var/select",
+ "/dev",
+]
+# Folders that must be walkable for path lookups to work, without listing what is in them.
+_LITERAL_READ = ["/", "/private", "/private/tmp", "/private/var", "/private/var/folders", "/Users", "/Volumes"]
+
+# Developer toolchains under the home folder: readable, never writable.
+TOOLCHAINS = [
+ ".nvm",
+ ".volta",
+ ".bun",
+ ".deno",
+ ".pyenv",
+ ".rbenv",
+ ".asdf",
+ ".sdkman",
+ ".cargo",
+ ".rustup",
+ ".local/bin",
+ ".local/share/uv",
+ ".local/share/mise",
+ ".local/pipx",
+ "go",
+]
+# The user's git settings. Files, not folders of secrets: credentials live in the keychain.
+GIT_SETTINGS = [".gitconfig", ".gitignore", ".gitignore_global", ".config/git"]
+
+# System services a command-line program needs. Not the keychain, not the pasteboard.
+_MACH_SERVICES = [
+ "com.apple.system.opendirectoryd.libinfo",
+ "com.apple.system.opendirectoryd.membership",
+ "com.apple.system.logger",
+ "com.apple.system.notification_center",
+ "com.apple.logd",
+ "com.apple.diagnosticd",
+ "com.apple.trustd",
+ "com.apple.trustd.agent",
+ "com.apple.bsd.dirhelper",
+ "com.apple.CoreServices.coreservicesd",
+ "com.apple.lsd.mapdb",
+ "com.apple.cfprefsd.daemon",
+ "com.apple.cfprefsd.agent",
+ "com.apple.SecurityServer",
+ "com.apple.ocspd",
+]
+
+
+_XCRUN_CACHE = r"/private/var/folders/[^/]+/[^/]+/[TC]/xcrun_db"
+
+
+def real(path: str | os.PathLike[str]) -> str:
+ return os.path.realpath(os.path.expanduser(str(path)))
+
+
+def _quote(path: str) -> str:
+ return '"' + path.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _subpaths(paths: Sequence[str]) -> str:
+ return " ".join(f"(subpath {_quote(p)})" for p in paths)
+
+
+def _literals(paths: Sequence[str]) -> str:
+ return " ".join(f"(literal {_quote(p)})" for p in paths)
+
+
+def home_read_only(home: Optional[str] = None) -> list[str]:
+ """The toolchain folders and git settings that exist under this home folder."""
+ base = Path(real(home or "~"))
+ return [real(base / name) for name in (*TOOLCHAINS, *GIT_SETTINGS) if (base / name).exists()]
+
+
+def render(
+ roots: Sequence[dict[str, Any]],
+ *,
+ runtime_dir: str,
+ read_only: Sequence[str] = (),
+ proxy_port: Optional[int] = None,
+ home: Optional[str] = None,
+) -> str:
+ """`roots`: [{"path": absolute path, "writable": bool}]. `runtime_dir`: this sandbox's
+ own folder (socket and temporary files). `read_only`: more paths to read, e.g. the
+ runner file and the Python that runs it."""
+ writable = [real(r["path"]) for r in roots if r.get("writable")]
+ readable = [real(r["path"]) for r in roots if not r.get("writable")]
+ readable += [real(p) for p in read_only] + home_read_only(home)
+ runtime = real(runtime_dir)
+ lines = [
+ "(version 1)",
+ "(deny default)",
+ "; processes: start programs, and signal only processes inside this sandbox",
+ "(allow process-fork)",
+ "(allow process-exec)",
+ "(allow signal (target same-sandbox))",
+ "(allow process-info* (target same-sandbox))",
+ "(allow sysctl-read)",
+ "(allow ipc-posix-shm-read-data)",
+ f"(allow mach-lookup {' '.join(f'(global-name {_quote(s)})' for s in _MACH_SERVICES)})",
+ "; files: names and sizes anywhere (path lookups need it), contents only where listed",
+ "(allow file-read-metadata)",
+ f"(allow file-read* {_subpaths(_SYSTEM_READ)} {_literals(_LITERAL_READ)})",
+ f"(allow file-write-data {_literals(['/dev/null', '/dev/zero', '/dev/tty', '/dev/dtracehelper'])})",
+ "(allow file-ioctl (literal \"/dev/tty\") (literal \"/dev/dtracehelper\"))",
+ f"(allow file-read* file-write* {_subpaths([runtime, *writable])})",
+ "; Apple's command-line shims (/usr/bin/git, /usr/bin/python3) keep a small lookup cache in",
+ "; the per-user temporary folder and ignore TMPDIR; without it every call takes a second",
+ f"(allow file-read* file-write* (regex #\"^{_XCRUN_CACHE}\"))",
+ ]
+ if readable:
+ lines.append(f"(allow file-read* {_subpaths(readable)})")
+ lines += [
+ "; the runner's own socket lives in the sandbox's folder",
+ f"(allow network-bind network-inbound network-outbound (local unix-socket (subpath {_quote(runtime)})))",
+ f"(allow network-bind network-inbound network-outbound (remote unix-socket (subpath {_quote(runtime)})))",
+ ]
+ if proxy_port:
+ lines += [
+ "; the network: only the allow-list proxy on this machine",
+ f'(allow network-outbound (remote tcp "localhost:{int(proxy_port)}"))',
+ ]
+ return "\n".join(lines) + "\n"
diff --git a/coworker/sandbox/proxy.py b/coworker/sandbox/proxy.py
index a8c27b0d..8d7250e8 100644
--- a/coworker/sandbox/proxy.py
+++ b/coworker/sandbox/proxy.py
@@ -37,6 +37,9 @@ def proxy_tool(tool: Callable[..., Any], workspace: Any, *, root: str, roots: Op
@functools.wraps(tool)
def call(*args: Any, **kwargs: Any) -> Any:
bound = signature.bind(*args, **kwargs)
+ sync = getattr(workspace, "sync_roots", None)
+ if sync is not None:
+ sync() # a folder granted since the sandbox started: restart it with the new walls
# The session's roots list is live (folders are granted while a session runs), so
# it is read on every call, as the in-process tools do.
live = [{"path": str(r.path), "writable": bool(r.writable)} for r in (roots or [])]
diff --git a/coworker/sandbox/runner/daemon.py b/coworker/sandbox/runner/daemon.py
index d161a3bc..ef81a016 100644
--- a/coworker/sandbox/runner/daemon.py
+++ b/coworker/sandbox/runner/daemon.py
@@ -23,6 +23,7 @@ from __future__ import annotations
import collections
import os
import platform
+import shutil
import socket
import subprocess
import sys
@@ -381,8 +382,14 @@ class Daemon:
os.unlink(self.socket_path)
except OSError:
pass
+ folder = os.path.dirname(self.socket_path)
try:
- os.rmdir(os.path.dirname(self.socket_path)) # only if the socket had its own folder
+ if os.path.basename(folder).startswith("owr-"):
+ # A folder a provider made for this one runner (socket, temporary files, log).
+ # Nobody else cleans it up when the server was killed.
+ shutil.rmtree(folder, ignore_errors=True)
+ else:
+ os.rmdir(folder) # only if the socket had its own folder
except OSError:
pass
diff --git a/coworker/sandbox/runner/executor.py b/coworker/sandbox/runner/executor.py
index 05dca357..b6a296ad 100644
--- a/coworker/sandbox/runner/executor.py
+++ b/coworker/sandbox/runner/executor.py
@@ -73,6 +73,20 @@ class Executor(ABC):
pass
+def _child_pids_darwin(parent: int) -> list[int]:
+ if sys.platform != "darwin":
+ return []
+ try:
+ import ctypes
+
+ lib = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
+ buf = (ctypes.c_int * 256)()
+ count = lib.proc_listchildpids(parent, buf, ctypes.sizeof(buf))
+ return [int(pid) for pid in buf[: max(count, 0)] if pid > 0]
+ except (OSError, AttributeError):
+ return []
+
+
class _BackgroundTask:
"""One detached background command: its own process (not the persistent shell), a
reader thread draining output into a buffer, and an incremental-read cursor."""
@@ -405,7 +419,12 @@ class LocalExecutor(Executor):
capture_output=True,
text=True,
)
- for pid in found.stdout.split():
+ pids = found.stdout.split()
+ if found.returncode not in (0, 1):
+ # pgrep itself failed. Inside the macOS sandbox it cannot reach the service
+ # it lists processes with; the system library can still list OUR children.
+ pids = [str(pid) for pid in _child_pids_darwin(self._proc.pid)]
+ for pid in pids:
try:
os.kill(int(pid), signal.SIGINT)
except (ProcessLookupError, ValueError, OSError):
diff --git a/coworker/sandbox/selection.py b/coworker/sandbox/selection.py
index 4ba07dfc..309fcd4c 100644
--- a/coworker/sandbox/selection.py
+++ b/coworker/sandbox/selection.py
@@ -16,10 +16,10 @@ import time
from dataclasses import dataclass
from typing import Optional
-from .workspace import DIRECT, OPENSHELL, PROVIDER_ENV, RUNNER_LOCAL
+from .workspace import DIRECT, OPENSHELL, PROVIDER_ENV, RUNNER_LOCAL, SEATBELT
HEADLESS_ENV = "OPENWORKER_HEADLESS" # set by `openworker up` / `join` for their process
-KNOWN = (DIRECT, OPENSHELL, RUNNER_LOCAL)
+KNOWN = (DIRECT, SEATBELT, OPENSHELL, RUNNER_LOCAL)
_PROBE_SECONDS = 30.0
_probe_lock = threading.Lock()
@@ -57,7 +57,8 @@ def openshell_problem(*, fresh: bool = False) -> Optional[str]:
def select(configured: Optional[str] = None, *, headless: Optional[bool] = None) -> Selection:
- """Raises `OpenShellUnavailable` when OpenShell was chosen explicitly and is not usable."""
+ """Raises `OpenShellUnavailable` or `SeatbeltUnavailable` when that sandbox was chosen
+ explicitly and is not usable: a silent fallback would hide the loss of protection."""
chosen = (os.environ.get(PROVIDER_ENV) or configured or "").strip().lower()
if chosen:
if chosen not in KNOWN:
@@ -70,6 +71,15 @@ def select(configured: Optional[str] = None, *, headless: Optional[bool] = None)
raise OpenShellUnavailable(
f"This machine is set to run agents in OpenShell sandboxes, and OpenShell cannot be used right now, so no session will start. {problem}"
)
+ if chosen == SEATBELT:
+ from .providers import seatbelt
+
+ try:
+ seatbelt.preflight()
+ except seatbelt.SeatbeltUnavailable as exc:
+ raise seatbelt.SeatbeltUnavailable(
+ f"This machine is set to run agents in the macOS sandbox (Seatbelt), and it cannot be used right now, so no session will start. {exc}"
+ ) from None
return Selection(chosen, explicit=True)
if headless if headless is not None else is_headless():
problem = openshell_problem()
diff --git a/coworker/sandbox/setup_cmd.py b/coworker/sandbox/setup_cmd.py
index 58d21a34..a721198d 100644
--- a/coworker/sandbox/setup_cmd.py
+++ b/coworker/sandbox/setup_cmd.py
@@ -63,7 +63,22 @@ def checks() -> list[tuple[str, bool, str]]:
return out
+def seatbelt_check() -> tuple[str, bool, str]:
+ from .providers import seatbelt
+
+ try:
+ seatbelt.preflight()
+ return ("the macOS sandbox (Seatbelt) can be used", True, "")
+ except seatbelt.SeatbeltUnavailable as exc:
+ return ("the macOS sandbox (Seatbelt) can be used", False, str(exc))
+
+
def status(print_fn: Callable[[str], None] = print) -> int:
+ if sys.platform == "darwin":
+ what, ok, detail = seatbelt_check()
+ print_fn(f" [{'ok' if ok else '--'}] {what}" + (f" ({detail})" if detail else ""))
+ print_fn(" to use it: set `sandbox_provider = \"seatbelt\"` in " + str(app_config.global_config_path()))
+ print_fn("\nOpenShell on this machine:")
rows = checks()
for what, ok, detail in rows:
print_fn(f" [{'ok' if ok else '--'}] {what}" + (f" ({detail})" if detail and not ok else ""))
diff --git a/coworker/sandbox/workspace.py b/coworker/sandbox/workspace.py
index 9f5db3e8..d3db7571 100644
--- a/coworker/sandbox/workspace.py
+++ b/coworker/sandbox/workspace.py
@@ -23,6 +23,12 @@ PROVIDER_ENV = "OPENWORKER_SANDBOX_PROVIDER"
DIRECT = "direct"
RUNNER_LOCAL = "runner-local"
OPENSHELL = "openshell"
+SEATBELT = "seatbelt"
+
+RESTART_NOTICE = (
+ "The sandbox was restarted because the session's folders changed. The shell started again: "
+ "variables and background tasks from before are gone, files are untouched."
+)
class Workspace(ABC):
@@ -62,6 +68,7 @@ class RunnerWorkspace(Workspace):
registry: Any = None,
session_id: str = "",
agent: str = "",
+ live_roots: Optional[list] = None,
) -> None:
from .client import RunnerClient
from .executor import RunnerExecutor
@@ -69,6 +76,10 @@ class RunnerWorkspace(Workspace):
self.provider = provider
self.registry = registry
self._registered: Optional[str] = None
+ self._session_id, self._agent = session_id, agent
+ # The session's own RootDir list. It changes while the session runs (a folder is
+ # granted or taken away); a sandbox's walls are fixed when it starts.
+ self._live_roots = live_roots
if registry is not None:
registry.reap() # sandboxes left behind by a server that is gone
registry.check_room()
@@ -82,19 +93,48 @@ class RunnerWorkspace(Workspace):
except Exception:
provider.destroy()
raise
- self._executor = RunnerExecutor(self.client, cwd=str(Path(cwd).expanduser().resolve()), shell=shell)
- if registry is not None:
- info = provider.describe()
- self._registered = str(info.get("sandbox") or f"{info['provider']}-{id(self):x}")
- registry.record(
- self._registered,
- provider=info["provider"],
- session_id=session_id,
- agent=agent,
- roots=getattr(provider, "roots", None),
- profile=getattr(provider, "profile", ""),
- enforcement=info.get("enforcement", ""),
- )
+ self._executor = RunnerExecutor(
+ self.client, cwd=str(Path(cwd).expanduser().resolve()), shell=shell, before_call=self.sync_roots
+ )
+ self._record()
+
+ def _record(self) -> None:
+ """Enter this sandbox in the registry; after a restart that replaced it, under its
+ new name."""
+ if self.registry is None:
+ return
+ info = self.provider.describe()
+ name = str(info.get("sandbox") or f"{info['provider']}-{id(self):x}")
+ if self._registered and self._registered != name:
+ self.registry.close(self._registered)
+ self._registered = name
+ self.registry.record(
+ name,
+ provider=info["provider"],
+ session_id=self._session_id,
+ agent=self._agent,
+ roots=getattr(self.provider, "roots", None),
+ profile=getattr(self.provider, "profile", ""),
+ enforcement=info.get("enforcement", ""),
+ )
+
+ def sync_roots(self) -> Optional[str]:
+ """Restart the sandbox when the session's folders are no longer the ones it was
+ started with (design ruling 15). Returns what to tell the agent, or None."""
+ regrant = getattr(self.provider, "regrant", None)
+ if regrant is None or self._live_roots is None:
+ return None
+ wanted = [{"path": str(r.path), "writable": bool(r.writable)} for r in self._live_roots]
+ if not wanted or _same_roots(wanted, getattr(self.provider, "roots", [])):
+ return None
+ self.client.detach()
+ regrant(wanted)
+ self.client.connect() # a new runner: the client notes the restart
+ verify = getattr(self.provider, "verify", None)
+ if verify is not None:
+ verify(self.client)
+ self._record()
+ return RESTART_NOTICE
@property
def executor(self) -> Executor:
@@ -113,6 +153,13 @@ class RunnerWorkspace(Workspace):
self.registry.close(self._registered)
+def _same_roots(a: list, b: list) -> bool:
+ def key(roots: list) -> set:
+ return {(os.path.realpath(str(r["path"])), bool(r.get("writable"))) for r in roots}
+
+ return key(a) == key(b)
+
+
def provider_name(explicit: Optional[str] = None) -> str:
return (explicit or os.environ.get(PROVIDER_ENV) or DIRECT).strip().lower()
@@ -136,11 +183,22 @@ def open_workspace(
from .providers.runner_local import RunnerLocalProvider
return RunnerWorkspace(RunnerLocalProvider(cwd=cwd), cwd=cwd)
+ listed = [{"path": str(r.path), "writable": bool(r.writable)} for r in (roots or [])]
+ listed = listed or [{"path": str(cwd), "writable": True}]
+ if name == SEATBELT:
+ from .providers.seatbelt import SeatbeltProvider
+ from .registry import SandboxRegistry
+
+ return RunnerWorkspace(
+ SeatbeltProvider(roots=listed, cwd=str(cwd)),
+ cwd=cwd,
+ registry=SandboxRegistry(),
+ session_id=session_id,
+ agent=agent,
+ live_roots=roots,
+ )
if name == OPENSHELL:
from .providers.openshell import OpenShellProvider
-
- listed = [{"path": str(r.path), "writable": bool(r.writable)} for r in (roots or [])]
- listed = listed or [{"path": str(cwd), "writable": True}]
from .registry import SandboxRegistry
label = "-".join(part for part in (session_id[:24], agent[:24]) if part)
@@ -150,5 +208,6 @@ def open_workspace(
registry=SandboxRegistry(),
session_id=session_id,
agent=agent,
+ live_roots=roots,
)
- raise ValueError(f"unknown sandbox provider: {name!r} (known: {DIRECT}, {OPENSHELL}, {RUNNER_LOCAL})")
+ raise ValueError(f"unknown sandbox provider: {name!r} (known: {DIRECT}, {SEATBELT}, {OPENSHELL}, {RUNNER_LOCAL})")
diff --git a/tests/test_sandbox_seatbelt.py b/tests/test_sandbox_seatbelt.py
new file mode 100644
index 00000000..e93f87cb
--- /dev/null
+++ b/tests/test_sandbox_seatbelt.py
@@ -0,0 +1,280 @@
+"""The Seatbelt provider: the tool runner inside the macOS sandbox.
+
+The first half runs anywhere: the profile text, the allow-list proxy, the environment that
+is passed on. The second half runs only on a Mac where `sandbox-exec` works, and checks the
+wall itself with real commands.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import sys
+import threading
+from pathlib import Path
+
+import pytest
+
+from coworker.agents.base import AgentContext # noqa: E402 (before catalog: import order)
+from coworker import catalog # noqa: E402, I001
+from coworker.roots import RootDir
+from coworker.sandbox import netproxy, network_profiles
+from coworker.sandbox.providers import seatbelt, seatbelt_profile
+from coworker.sandbox.selection import select
+
+
+# -- the profile ----------------------------------------------------------------------
+def test_profile_lists_the_folders_and_nothing_else_under_home(tmp_path):
+ home = tmp_path / "home"
+ (home / ".nvm").mkdir(parents=True)
+ (home / ".ssh").mkdir()
+ (home / ".gitconfig").write_text("[user]\n")
+ project, reference = tmp_path / "project", tmp_path / "reference"
+ project.mkdir()
+ reference.mkdir()
+ text = seatbelt_profile.render(
+ [{"path": str(project), "writable": True}, {"path": str(reference), "writable": False}],
+ runtime_dir=str(tmp_path / "run"),
+ home=str(home),
+ )
+ assert text.startswith("(version 1)\n(deny default)\n")
+ real = os.path.realpath
+ write_rule = next(line for line in text.splitlines() if line.startswith("(allow file-read* file-write* (subpath"))
+ assert real(project) in write_rule and real(tmp_path / "run") in write_rule
+ assert real(reference) not in write_rule # a read-only folder is never writable
+ read_rule = next(line for line in text.splitlines() if line.startswith("(allow file-read* (subpath") and real(reference) in line)
+ assert real(home / ".nvm") in read_rule and real(home / ".gitconfig") in read_rule
+ assert ".ssh" not in text
+ assert "remote tcp" not in text # no proxy port given: no network at all
+
+
+def test_profile_allows_only_the_proxy_port_and_quotes_paths(tmp_path):
+ odd = tmp_path / 'has "quotes" and spaces'
+ odd.mkdir()
+ text = seatbelt_profile.render([{"path": str(odd), "writable": True}], runtime_dir=str(tmp_path), proxy_port=45678, home=str(tmp_path))
+ assert '(allow network-outbound (remote tcp "localhost:45678"))' in text
+ assert text.count("remote tcp") == 1
+ assert 'has \\"quotes\\" and spaces' in text
+
+
+def test_secrets_in_the_servers_environment_are_not_passed_on():
+ env = seatbelt.clean_environment(
+ {
+ "PATH": "/usr/bin",
+ "LANG": "en_US.UTF-8",
+ "NVM_DIR": "/Users/sam/.nvm",
+ "ANTHROPIC_API_KEY": "x",
+ "GITHUB_TOKEN": "x",
+ "AWS_SECRET_ACCESS_KEY": "x",
+ "AWS_SESSION_TOKEN": "x",
+ "COWORKER_API_TOKEN": "x",
+ "OPENWORKER_HEADLESS": "1",
+ "SSH_AUTH_SOCK": "/tmp/agent",
+ "DB_PASSWORD": "x",
+ }
+ )
+ assert env == {"PATH": "/usr/bin", "LANG": "en_US.UTF-8", "NVM_DIR": "/Users/sam/.nvm"}
+
+
+# -- the allow-list proxy -------------------------------------------------------------
+def _ask(proxy: netproxy.AllowListProxy, request: bytes) -> bytes:
+ with socket.create_connection(("127.0.0.1", proxy.port), timeout=5) as s:
+ s.sendall(request)
+ s.settimeout(5)
+ chunks = []
+ while True:
+ try:
+ data = s.recv(4096)
+ except socket.timeout:
+ break
+ if not data:
+ break
+ chunks.append(data)
+ if b"pong" in data:
+ break
+ return b"".join(chunks)
+
+
+def test_proxy_refuses_hosts_that_are_not_listed_and_says_why():
+ proxy = netproxy.AllowListProxy("strict")
+ try:
+ answer = _ask(proxy, b"CONNECT example.com:443 HTTP/1.1\r\nHost: example.com:443\r\n\r\n")
+ assert answer.startswith(b"HTTP/1.1 403 ")
+ assert b"example.com:443 is not on this sandbox's allow list" in answer
+ assert list(proxy.denied) == ["example.com:443"]
+ # a listed host on another port, and plain HTTP, are refused too
+ assert _ask(proxy, b"CONNECT github.com:22 HTTP/1.1\r\n\r\n").startswith(b"HTTP/1.1 403 ")
+ assert _ask(proxy, b"GET http://github.com/ HTTP/1.1\r\nHost: github.com\r\n\r\n").startswith(b"HTTP/1.1 403 ")
+ finally:
+ proxy.close()
+
+
+def test_proxy_tunnels_a_listed_host(monkeypatch):
+ upstream = socket.socket()
+ upstream.bind(("127.0.0.1", 0))
+ upstream.listen(1)
+
+ def serve() -> None:
+ conn, _ = upstream.accept()
+ with conn:
+ if conn.recv(16) == b"ping":
+ conn.sendall(b"pong")
+
+ threading.Thread(target=serve, daemon=True).start()
+ wanted: list[tuple[str, int]] = []
+ real_connect = socket.create_connection
+
+ def fake_connect(address, *args, **kwargs):
+ if address[0] == "github.com":
+ wanted.append(address)
+ return real_connect(upstream.getsockname(), *args, **kwargs)
+ return real_connect(address, *args, **kwargs)
+
+ monkeypatch.setattr(netproxy.socket, "create_connection", fake_connect)
+ proxy = netproxy.AllowListProxy("strict")
+ try:
+ with real_connect(("127.0.0.1", proxy.port), timeout=5) as s:
+ s.sendall(b"CONNECT github.com:443 HTTP/1.1\r\nHost: github.com:443\r\n\r\n")
+ s.settimeout(5)
+ assert s.recv(4096).startswith(b"HTTP/1.1 200 ")
+ s.sendall(b"ping")
+ assert s.recv(16) == b"pong"
+ assert wanted == [("github.com", 443)]
+ finally:
+ proxy.close()
+ upstream.close()
+
+
+def test_every_profile_has_hosts_and_an_unknown_one_is_refused():
+ assert "github.com" in network_profiles.hosts("strict")
+ assert set(network_profiles.hosts("strict")) < set(network_profiles.hosts("standard"))
+ with pytest.raises(ValueError):
+ netproxy.AllowListProxy("wide-open")
+
+
+# -- selection ------------------------------------------------------------------------
+def test_an_explicit_seatbelt_setting_refuses_when_it_cannot_be_used(monkeypatch):
+ def broken() -> None:
+ raise seatbelt.SeatbeltUnavailable("The Seatbelt sandbox exists only on macOS.")
+
+ monkeypatch.delenv("OPENWORKER_SANDBOX_PROVIDER", raising=False)
+ monkeypatch.setattr(seatbelt, "preflight", broken)
+ with pytest.raises(seatbelt.SeatbeltUnavailable, match="no session will start"):
+ select("seatbelt")
+ monkeypatch.setattr(seatbelt, "preflight", lambda: None)
+ assert select("seatbelt") == type(select("direct"))("seatbelt", explicit=True)
+
+
+# -- the wall itself (macOS only) -----------------------------------------------------
+def _usable() -> bool:
+ if sys.platform != "darwin":
+ return False
+ try:
+ seatbelt.preflight()
+ return True
+ except seatbelt.SeatbeltUnavailable:
+ return False
+
+
+live = pytest.mark.skipif(not _usable(), reason="needs a Mac where sandbox-exec can apply a profile")
+
+
+def sandbox(tmp_path, monkeypatch):
+ """(workspace, project folder, read-only folder, a folder that was NOT granted)."""
+ from coworker.sandbox.bundle import build_runner_zipapp
+ from coworker.sandbox.workspace import RunnerWorkspace
+
+ monkeypatch.setenv("ANTHROPIC_API_KEY", "not-a-real-key")
+ project, reference, private = tmp_path / "project", tmp_path / "reference", tmp_path / "private"
+ for folder in (project, reference, private):
+ folder.mkdir()
+ (reference / "ref.txt").write_text("reference\n")
+ (private / "secret.txt").write_text("classified-content\n")
+ roots = [RootDir(path=project, writable=True), RootDir(path=reference, writable=False)]
+ provider = seatbelt.SeatbeltProvider(
+ roots=[{"path": str(r.path), "writable": r.writable} for r in roots],
+ cwd=project,
+ runner_path=build_runner_zipapp(tmp_path / "dist"),
+ )
+ ws = RunnerWorkspace(provider, cwd=project, live_roots=roots)
+ ws.executor.default_timeout = 20
+ yield ws, project, reference, private, roots
+ ws.close()
+
+
+@live
+def test_files_outside_the_sessions_folders_cannot_be_read_or_written(sandbox):
+ ws, project, reference, private, _ = sandbox
+ run = ws.executor.run
+ assert ws.describe()["enforcement"] == "full"
+ assert run("echo made > made.txt && cat made.txt")["output"].strip() == "made"
+ assert (project / "made.txt").read_text() == "made\n"
+ assert "reference" in run(f"cat {reference}/ref.txt")["output"]
+ assert run(f"echo no > {reference}/new.txt")["exit_code"] != 0
+ assert not (reference / "new.txt").exists()
+ assert "classified-content" not in run(f"cat {private}/secret.txt 2>&1")["output"]
+ assert run(f"echo no > {private}/new.txt")["exit_code"] != 0
+ home = Path.home()
+ assert "not permitted" in run(f"ls {home} 2>&1")["output"]
+ assert run(f"echo no > {home}/openworker-seatbelt-test.txt")["exit_code"] != 0
+ assert not (home / "openworker-seatbelt-test.txt").exists()
+ assert run("touch /usr/local/bin/openworker-seatbelt-test")["exit_code"] != 0
+
+
+@live
+def test_the_servers_secrets_do_not_reach_a_command(sandbox):
+ ws, *_ = sandbox
+ out = ws.executor.run("env")["output"]
+ assert "not-a-real-key" not in out and "ANTHROPIC_API_KEY" not in out
+ assert "COWORKER_" not in out
+
+
+@live
+def test_the_network_is_only_the_proxy(sandbox):
+ """No internet needed: a listener on this machine stands in for 'somewhere else'."""
+ ws, *_ = sandbox
+ elsewhere = socket.socket()
+ elsewhere.bind(("127.0.0.1", 0))
+ elsewhere.listen(1)
+ try:
+ port = elsewhere.getsockname()[1]
+ direct = ws.executor.run(f"curl -sS -m 5 --noproxy '*' http://127.0.0.1:{port}/ 2>&1")
+ assert direct["exit_code"] != 0 # the kernel refuses the connection
+ refused = ws.executor.run("curl -sS -m 5 https://example.com 2>&1")
+ assert "403" in refused["output"]
+ finally:
+ elsewhere.close()
+
+
+@live
+def test_our_own_tools_run_behind_the_wall(sandbox):
+ ws, project, reference, private, roots = sandbox
+ ctx = AgentContext(workspace=project, executor=ws.executor, roots=roots, sandbox=ws)
+ tools = {t.__name__: t for t in catalog.expand(["code_files", "search"], ctx)}
+ tools["write_file"]("notes.md", "one\ntwo\n")
+ assert (project / "notes.md").read_text() == "one\ntwo\n"
+ assert "two" in tools["read_file"]("notes.md")["content"]
+ assert "reference" in tools["read_file"](str(reference / "ref.txt"))["content"]
+ with pytest.raises(PermissionError):
+ tools["write_file"](str(reference / "new.txt"), "no")
+
+
+@live
+def test_granting_a_folder_restarts_the_sandbox_and_says_so(sandbox):
+ from coworker.sandbox.workspace import RESTART_NOTICE
+
+ ws, project, reference, private, roots = sandbox
+ run = ws.executor.run
+ run("export KEEP=yes")
+ assert "classified-content" not in run(f"cat {private}/secret.txt 2>&1")["output"]
+ before = ws.client.restarts
+ roots.append(RootDir(path=private, writable=True))
+ granted = run(f"cat {private}/secret.txt; echo KEEP=$KEEP")
+ assert "classified-content" in granted["output"]
+ assert granted["sandbox_notice"] == RESTART_NOTICE
+ assert "KEEP=yes" not in granted["output"] # a new shell, as the notice says
+ assert ws.client.restarts == before + 1
+ assert "sandbox_notice" not in run("true") # said once
+ roots.pop() # taken away again: the wall goes back up
+ assert "classified-content" not in run(f"cat {private}/secret.txt 2>&1")["output"]
diff --git a/tests/test_shell.py b/tests/test_shell.py
index 6b71f385..6bb1bf2b 100644
--- a/tests/test_shell.py
+++ b/tests/test_shell.py
@@ -35,6 +35,8 @@ PRINT_1000 = (
# the same contract served by a tool runner in another process (the sandbox path). The two
# must not drift apart. The runner needs Unix sockets, so it is skipped on Windows.
_EXECUTORS = ["direct"] if _WIN else ["direct", "runner"]
+if sys.platform == "darwin":
+ _EXECUTORS.append("seatbelt") # the same runner, inside the macOS sandbox
@pytest.fixture(params=_EXECUTORS)
@@ -47,7 +49,19 @@ def executor(request, tmp_path):
from coworker.sandbox.providers.runner_local import RunnerLocalProvider
from coworker.sandbox.workspace import RunnerWorkspace
- ws = RunnerWorkspace(RunnerLocalProvider(cwd=tmp_path, runner_path=_runner_zipapp(tmp_path)), cwd=tmp_path)
+ if request.param == "seatbelt":
+ from coworker.sandbox.providers import seatbelt
+
+ try:
+ seatbelt.preflight()
+ except seatbelt.SeatbeltUnavailable as exc:
+ pytest.skip(str(exc))
+ provider = seatbelt.SeatbeltProvider(
+ roots=[{"path": str(tmp_path), "writable": True}], cwd=tmp_path, runner_path=_runner_zipapp(tmp_path), network=False
+ )
+ else:
+ provider = RunnerLocalProvider(cwd=tmp_path, runner_path=_runner_zipapp(tmp_path))
+ ws = RunnerWorkspace(provider, cwd=tmp_path)
ws.executor.default_timeout = 10
yield ws.executor
ws.close()