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:
- macOS —
sandbox-execwith a generated SBPL profile that allows reads, exec and network but denies all writes except under the roots and the OS temp dir. - Linux —
bwrap(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
Functions
Whether an OS sandbox helper is available on this host.
Accepts the same :finder option as wrap/4.
@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.
@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.