ExAthena.Sandbox (ExAthena v0.20.0)

Copy Markdown View Source

OS-level command confinement for the Bash tool.

When a run is confined (ExAthena.ToolContext.allowed_roots is set), shell commands are wrapped so they cannot write outside the roots:

  • macOSsandbox-exec with a generated SBPL profile that allows reads, exec and network but denies all writes except under the roots and the OS temp dir.
  • Linuxbwrap (bubblewrap): the whole filesystem mounted read-only, the roots and the temp dir bind-mounted read-write.

Reads and network stay open — that's the FS write boundary, not a full jail (network egress is handled separately by the web tools' SSRF guard). The OS temp dir stays writable so ordinary toolchains (compilers, mktemp) work.

Where no sandbox helper is available the command is returned unwrapped as {:unavailable, argv} and the caller decides the policy. The Bash tool fails closed by default (ExAthena.ToolContext.confine_mode :enforced refuses to run) because we never fake confinement with a command-string scan (trivially bypassed via subshells/eval) — it's real-sandbox-or-refusal, with :best_effort as the explicit degrade-with-warning opt-in.

Summary

Functions

Whether an OS sandbox helper is available on this host.

Name of the sandbox helper this platform needs ("sandbox-exec" on macOS, "bwrap" on other Unixes). Used to build actionable missing-helper errors.

Build the argv to run command confined to roots with working dir cwd.

Types

finder()

@type finder() :: (String.t() -> String.t() | nil)

Functions

available?(opts \\ [])

@spec available?(keyword()) :: boolean()

Whether an OS sandbox helper is available on this host.

Accepts the same :finder option as wrap/4.

required_helper()

@spec required_helper() :: String.t()

Name of the sandbox helper this platform needs ("sandbox-exec" on macOS, "bwrap" on other Unixes). Used to build actionable missing-helper errors.

wrap(command, roots, cwd, opts \\ [])

@spec wrap(String.t(), [Path.t()], Path.t(), keyword()) ::
  {:ok, {String.t(), [String.t()]}} | {:unavailable, {String.t(), [String.t()]}}

Build the argv to run command confined to roots with working dir cwd.

Returns {:ok, {executable, args}} when an OS sandbox is available, or {:unavailable, {executable, args}} (the bare sh -c command) otherwise.

opts:

  • :finder — executable-lookup function (default &System.find_executable/1). A seam so hosts/tests can simulate a machine without the sandbox helper; never model-controlled.