Files

T

ducoterra b273bfef09 name the sandbox's working directory, and drive phases through it

Two features, one shared reason: what the sandbox calls things decides
what a run tells you afterwards.

The cwd is now mounted at the path it has on the host and that is the
working directory, so pwd, an error the agent quotes, a commit message and
the window title a harness derives from the cwd all name this project
instead of reading the same as every sandbox in the session. The mount is
unchanged: same directory, same rw, same :z, still the only writable one.

Only the destination changed, and a destination is where a bind mount can
do damage -- it hides whatever the image already had there. So
mirror_block_of() refuses the paths the image or the sandbox owns (/usr,
/etc, /var, /opt, /bin, /sbin, /lib*, /boot, /proc, /sys, /dev, /root,
/run, /tmp, /home, /home/sandbox*) and / itself, while /home/<user>/...
mirrors: the one standard hierarchy where work lives, and the one whose
per-user tree never meets the container's /home/sandbox volume or the
read-only .agents share inside it.

/tmp is what set the shape, and it was measured rather than assumed: with
--tmpfs /tmp and -v /tmp/x:/tmp/x in one run podman puts the tmpfs on top,
so pwd prints the right path, writes succeed, and the project is not there.
A failure that quiet earns a refusal plus a line of output instead:
workdir_note in --print-policy, a comment in --dry-run, one log line on a
real run. --workdir DIR still chooses the mount point; onto a refused path
it is honoured (it was asked for) and warned about. /project, the one
directory baked into the image, is every fallback, so a workdir always
exists -- --no-cwd included.

ai-sandbox-autophase runs a .agents/phases/ pipeline with the split the
sandbox forces: every executor agent and the .agents/validate.sh gate
inside, the commits and the pushes outside. The gate is in the writable
mount, so running it on the host is running agent-editable bash on the
host; the git remote is deliberately unreachable in there, because an agent
that can push can ship what you are about to review. It runs your launcher,
not a copy of it -- the definition is read out of your rc files and never
called, which is what lets --status and --dry-run promise no token fetch,
no build, no container. Host git runs with an empty hooks path and no ext::
transport, and delivery is refused if a sandboxed unit rewrote .git/config
or planted a hook. Needs --no-interactive to go with --no-tty: an
unattended run must not leave stdin open on your keyboard, and the two are
now separate choices on both sides.

Tests and tooling, most of it forced by what the two changes exposed:
mirror_block_of is extracted from the script and asked about /usr and
/home/sandbox, which a test cannot create (the 06_entrypoint.sh pattern),
and both real branches are driven from a scratch dir under $HOME, since
$TMPDIR is always the fallback -- which is why the whole suite had only
ever seen /project. e2e/12 holds a real container to the same promise,
including that /project, /home/sandbox and a home-volume marker survive a
mirrored run. The "nothing was started" checks now compare the set of
container ids before and after instead of counting every sandbox on the
machine, so a session you have open is not a test failure; the pty cases
fall back to python3 where util-linux's script is not installed.
shellcheck covers both programs, the completion file and the fixtures, so
the completion builds are word-by-word now, and a colon in the project path
is refused with the reason instead of podman's "invalid option type".

558 unit assertions, 719 with e2e; lint and bash -n clean.

LLM-Generated: true

2026-10-28 10:06:31 -04:00

8.9 KiB

Raw Blame History

Threat model

Read this before relying on ai-sandbox. It is a seatbelt, not a jail: it raises the cost of an agent's mistakes and of a moderately compromised prompt context, on a machine you still log into as yourself.

Who we assume is hostile

The modelled adversary is the agent you are running: an LLM harness with your write access to one directory, capable of running arbitrary shell commands, and vulnerable to prompt injection from the files it reads, the web pages it fetches, and the package changelogs it installs. We assume it will try to escape when a prompt injection tells it to.

We do not model a kernel-level adversary, a hostile container image from a registry you don't control, or someone with access to your host user account.

What stops working (defence in depth, most to least load-bearing)

Attack	Stopped by	Evidence
Editing / deleting anything outside the project directory	`$PWD` is the only writable mount; the rest of the host is not in the mount namespace	`tests/e2e/12_sandbox.sh`
Rewriting your skills, prompts or global `AGENTS.md`	`~/.agents` is mounted, but read-only, and there is no flag to change that	`tests/e2e/12_sandbox.sh`
Reading `~/.ssh`, `~/.aws`, `~/.config/gcloud`, browser profiles	same as above; those paths do not exist in the container	`tests/e2e/12_sandbox.sh`
Exfiltrating your environment (API keys for other services)	nothing is passed through unless named with `--env`	`tests/unit/04_env.sh`, `tests/e2e/12_sandbox.sh`
Passing secrets through the process list to other users	values travel in a `0600` file, never in argv	`tests/e2e/12_sandbox.sh`
Egress to an arbitrary host (curl, python, a raw socket, a bespoke exfil tool)	netfilter `policy drop` inside the container's namespace	`tests/e2e/11_net.sh`
Egress through the proxy to a non-allowlisted domain, including HTTPS	squid's `http_access deny all` after the allowlist	`tests/e2e/11_net.sh`
Deleting or weakening the egress ruleset	the command runs with no capabilities; `CAP_NET_ADMIN` was dropped across `exec`	`tests/e2e/11_net.sh`
`unshare -n` to get a fresh namespace with its own routes	requires `CAP_SYS_ADMIN`, which the command does not have	`tests/e2e/11_net.sh`
Privilege escalation via a setuid binary in the image	`--security-opt no-new-privileges` + `--cap-drop=ALL`	container config, asserted in `tests/e2e/10_image.sh`
Reaching other host services on loopback	only the gate's port is routable through the mapped loopback address	`tests/e2e/11_net.sh`
Fork bombs, memory bombs, runaway builds	`--pids-limit`, `--memory`, `--cpus`, `--tmpfs` sizes	`tests/e2e/10_image.sh`
Writing to the host's package manager, `/etc`, global npm/pip	read-only-ish image, `HOME` inside the container, optional `--read-only`	`tests/e2e/12_sandbox.sh`
Credential persistence you did not ask for	`--ephemeral-home`; the default home volume is named and inspectable	`tests/e2e/12_sandbox.sh`
Silent wide-open starts	an empty allowlist in `allow` mode is a hard error	`tests/unit/01_args.sh`
An agent shipping work you have not looked at (`git push`)	the git remote is not in the allowlist, so nothing in the container can reach it; `ai-sandbox-autophase` commits and pushes on the host, outside the sandbox, between unit runs	`tests/unit/10_autophase.sh`
The gate becoming the escape (`validate.sh` is inside the writable mount)	the pass/fail gate runs in the sandbox as the same unprivileged user, not on the host	`tests/unit/10_autophase.sh`

What does not stop it

Be honest about these, and design your work accordingly.

Anything you allowlist is reachable, in both directions. Allow api.github.com and a prompt-injected agent can push your code to a repository it controls, using the token you deliberately handed it. The allowlist limits where, not what. Prefer least-privilege, read-only, short-lived tokens.
The project directory is genuinely writable. A bad rm -rf, a force push, a corrupted lockfile all still happen — just confined to that directory. Keep the tree committed (ai-sandbox doctor warns you when it is dirty).
Kernel and runtime escapes. A container is not a VM. A container escape vulnerability in runc/crun or the kernel gets an attacker to your user account. For genuinely untrusted code, use a VM or a disposable machine.
--net full and the escape hatches do what they say. --allow-unenforced, --insecure-keep-root, --mount, AISB_EXTRA_ARGS, --net full all weaken the posture. They are named to be uncomfortable on purpose; nothing uses them implicitly.
Side channels. Timing, resource consumption, and "the agent typed X into a form on a site you allowed" are out of scope.
A cached home volume can hold credentials. If a harness logs in inside the sandbox, the token lives in the aisb-home volume, and any later sandbox run using that volume can read it. --ephemeral-home per run, or a dedicated AISB_HOME_VOLUME per trust level.
DNS is closed in gate mode, open in --no-gate mode. With --no-gate, name lookups leave the container; that is a modest data channel and a fingerprint of what you are doing. Egress to non-allowlisted IPs stays blocked either way.
The gate sees everything that flows through it — including any credentials in proxied requests. That is the point of an egress proxy; the squid config logs to its own container log, and gate logs shows them. Do not put secrets in URLs.
Supply chain inside the allowlist. registry.npmjs.org allowlisted means any package, including a typosquatted one, can be fetched. Allowlisting a domain is not a security review of what you install from it.
Rootless podman still means shared kernel and shared UID namespace. Files the container writes are owned by you. There is no uid boundary between "agent's file" and "your file" beyond ownership metadata and your own discipline.
Your ~/.agents is readable inside the sandbox. This is a deliberate exception to "only your project directory is mounted", because a harness without your skills is a harness you re-brief every run: ~/.agents arrives read-only at /home/sandbox/.agents (--no-agents for a run without it, --agents-dir for a curated set). Read-only means the agent cannot write a SKILL.md that you will follow tomorrow on the host — that is the part that matters, and it holds even under --insecure-keep-root. It does not mean the contents are secret: the whole tree, including its .git history and any token someone pasted into a skill, is readable by whatever you run in there. Treat a shared skill directory as published to the agent, lint it for secrets (skill-lint), and keep credentials in the environment you pass explicitly rather than in a file that is mounted everywhere.
The pi bridge reads a file that may hold a live key. It rewrites apiKey to an environment reference and never copies auth.json, but the endpoint in your models.json becomes an endpoint the sandbox can be pointed at, and the token it uses is your real one. So the bridged config is a convenience, not a narrower credential: prefer a per-sandbox token from your gateway if it can mint one, and note that a bridged run whose token variable is unset or empty is refused rather than started. Sandboxed edits to ~/.pi/agent persist in the home volume and win over later host changes (see the README), which is convenience with a consequence: a hostile run could rewrite the sandboxed pi config for later runs of that volume — point baseUrl at a host it controls, swap a model, change the provider. Merging settings.json per key limits this (a run can only pin the keys it actually writes, and everything else keeps following your host config), and defaultThinkingLevel is re-forced every run so a run cannot quietly lower the reasoning of the next. It is not eliminated: --ephemeral-home removes it, and inspect shows what is bridged.
A push on the host still pushes what the agent wrote. ai-sandbox-autophase keeps the remote away from the sandbox, but somebody has to deliver the work, and that somebody is the harness running as you. It commits only the phase's own changes and only after .agents/validate.sh passes — so read that gate as part of your trust base. It lives in the writable mount, which is exactly why the gate runs in the sandbox by default; --validate-in host hands that judgement to you and warns on every run.

Residual risk rating

Accidental destruction and ambient credential leakage: largely eliminated. Deliberate data exfiltration over an allowlisted path: mitigated, not prevented. Container escape to the host: out of scope, accept it or use a VM.

8.9 KiB Raw Blame History