Bash execution and isolation¶
The bash tool runs a command the model asked for. This page states exactly
what PAR does to contain it, what it does not do, and why the line sits where it
does. It is deliberately explicit: an agent that believes it is confined when it
is not will be trusted with more than it should be.
What a bash call goes through¶
After Runtime.create, Runtime.install_bash_tool registers the handler. Every
call then passes these stages, in order:
| # | Stage | What it does |
|---|---|---|
| 1 | argv only | The tool takes argv : string list. There is no shell string, so no quoting or ; parsing happens before PAR sees the command. |
| 2 | Workspace admission | cwd is validated by Workspace.admit: .., : and sensitive prefixes (/etc, ~/.ssh, …) are rejected; an absolute path is accepted only under a workspace root. |
| 3 | Policy filter | Coder (default), ReadOnly, ReadOnlyNoNet or a custom POLICY decides allow/reject, and can rewrite the command. Coder rejects entries from Bash_blacklist. |
| 4 | Environment scrubbing | Bash_policy.sanitize_env drops *secret* / *key* / *token* / *password* / *credential* names and the AWS_*, AZURE_*, GCP_*, OPENAI_API_KEY, ANTHROPIC_API_KEY, GITHUB_TOKEN families. The filtered set is what the child actually receives. |
| 5 | Timeout | The per-call timeout defaults to 30s and is clamped to 600s. On expiry the child is killed and the tool returns Timeout. |
| 6 | Output handling | stdout/stderr are capped at 50KB and 2000 lines, and ANSI escapes are stripped. |
| 7 | Audit trail | Bash_invoked and Bash_completed events carry the argv, cwd, risk rating, exit code and duration. |
What is not guaranteed¶
- Filesystem confinement.
cwdis where the command starts, not a jail. A command cancd /, or read any path the PAR process can read.Workspaceprotects the file tools, which construct paths throughWorkspace.sandboxed_path; it cannot constrain a process that has already started. - Network isolation.
ReadOnlyNoNetrejects commands it recognises as network clients. That is a classifier, not a firewall: a script can open a socket without runningcurl. - Process-group cleanup. The direct child is killed on timeout. Descendants it started are not reaped.
- CPU and memory limits.
POLICY.max_cpu_secondsandmax_memory_kbare declared and reported, but nothing enforces them today. Treat them as intent, not as a control. - Privilege drop. The child runs with PAR's uid and gid.
Why the gap exists¶
PAR runs on Linux, macOS and Windows, and the mechanisms that close these gaps
are platform-specific: bubblewrap or landlock on Linux, seatbelt (sandbox-exec)
on macOS, job objects on Windows. A library that silently degrades its isolation
per platform is worse than one that states the boundary, because callers cannot
tell which behaviour they got.
There is a second reason: PAR has no pre-exec hook. The reference monad that
would let a child install a landlock ruleset or a new process group between
fork and exec is not part of the process API PAR builds on.
The pluggable design (not implemented)¶
The intended shape is an opt-in wrapper rather than a hidden default:
type sandbox = {
name : string;
(* Wrap the argv about to be spawned. *)
wrap : argv:string list -> cwd:string -> (string list, error_category) result;
(* What this implementation actually provides, so callers can report it. *)
provides : [ `Filesystem | `Network | `Process_group | `Rlimits ] list;
}
val install_bash_tool : ?sandbox:sandbox -> ... -> (unit, error_category) result
Candidate implementations:
| Platform | Mechanism | Provides |
|---|---|---|
| Linux | bwrap --unshare-all --ro-bind / / --bind <cwd> <cwd> -- <argv> |
filesystem, network, process group |
| Linux | landlock ruleset installed before exec |
filesystem (needs a pre-exec hook or a small C stub) |
| macOS | sandbox-exec -p <profile> <argv> |
filesystem, network |
| Windows | job object for CPU/memory limits | rlimits only |
Selection would be explicit and fail closed: requesting a sandbox whose capability probe fails returns an error instead of quietly running unsandboxed.
When this would be built¶
The trigger is a deployment that runs untrusted or multi-tenant commands. Until then, the honest answer for untrusted input is isolation outside PAR — a container, a VM, or a dedicated user — which is a deployment decision, not a library feature.
See also¶
- The SDK pages under
docs/sdk/, starting with Tools for the bash tool's parameters and the safety table - Concurrency model — cancellation and timeouts