Agents → Sandboxing (code execution and shell tools)
What it is
Giving an agent the ability to run code is enormously useful — data analysis, calculations, file transformations, chart generation — and it means an LLM, which can be steered by any document it reads (prompt-injection defence), is now writing programs that execute on your infrastructure.
The threat model is straightforward: the generated code may exfiltrate data (network egress), read secrets (environment, files, metadata endpoints), consume resources (fork bombs, infinite loops, disk fills), escape the container (kernel exploits, mounted sockets), or persist (writing to shared volumes).
The controls, in order of importance:
| Control | What it stops |
|---|---|
| No secrets in the environment | Credential theft — the most common real-world loss |
| Network egress policy (default deny) | Data exfiltration, C2, cloud metadata access (169.254.169.254) |
| Read-only root, writable tmpfs only | Persistence, tampering |
| CPU / memory / PID / disk / time limits | Resource exhaustion |
| Non-root user, dropped capabilities, seccomp, no privileged mode | Container escape |
| Ephemeral, per-run containers | Cross-run and cross-tenant contamination |
| gVisor / Firecracker / Kata for hostile workloads | Kernel-level escape |
How to implement
- Never use
execorsubprocessin your application process. The sandbox is a separate container or microVM, always. - Purpose-built image: minimal base, pinned dependencies, no shells beyond what's needed, non-root user, no cloud SDKs or credential helpers.
- Strip the environment: pass no env vars except what the task needs; no
AWS_*, no API keys, no database URLs. - Default-deny egress with an explicit allow-list if network access is genuinely required; block link-local (metadata) addresses explicitly.
- Resource limits at the container level: CPU quota, memory limit with OOM kill, PID limit, disk quota, and a hard wall-clock timeout enforced outside the container.
- Data in and out through a narrow channel: mount inputs read-only (or copy them in), collect outputs from a designated directory, cap output size.
- Ephemeral by default: fresh container per execution, destroyed after; no shared writable volumes between runs or tenants.
- Log everything: the code executed, exit status, resource usage, files produced, network attempts denied.
Small example
import docker, tempfile, os, json, uuid
client = docker.from_env()
SANDBOX_IMAGE = "acme/agent-sandbox:2024-06-01" # pinned, minimal, non-root, no cloud SDKs
def run_code_sandboxed(code: str, input_files: dict[str, bytes], caller, timeout_s: int = 30,
allow_network: bool = False) -> dict:
run_id = str(uuid.uuid4())
workdir = tempfile.mkdtemp(prefix=f"sbx-{run_id}-")
os.chmod(workdir, 0o755)
for name, data in input_files.items(): # inputs staged read-only
with open(os.path.join(workdir, os.path.basename(name)), "wb") as f:
f.write(data)
with open(os.path.join(workdir, "main.py"), "w") as f:
f.write(code)
container = client.containers.run(
SANDBOX_IMAGE,
command=["python", "/work/main.py"],
detach=True,
# --- filesystem ---
volumes={workdir: {"bind": "/work", "mode": "ro"}}, # inputs + code read-only
tmpfs={"/tmp": "rw,noexec,nosuid,size=64m",
"/out": "rw,noexec,nosuid,size=64m"}, # only writable space
read_only=True, # read-only root filesystem
working_dir="/work",
# --- identity & privileges ---
user="65534:65534", # nobody
cap_drop=["ALL"], security_opt=["no-new-privileges:true", "seccomp=/etc/docker/seccomp-strict.json"],
privileged=False,
# --- resources ---
mem_limit="512m", memswap_limit="512m", nano_cpus=1_000_000_000, # 1 CPU
pids_limit=64, ulimits=[docker.types.Ulimit(name="nofile", soft=256, hard=256)],
# --- network: default deny ---
network_mode="none" if not allow_network else "sandbox-egress-allowlist",
# --- environment: nothing inherited ---
environment={"HOME": "/tmp", "PYTHONDONTWRITEBYTECODE": "1", "TENANT": caller.tenant_id},
labels={"run_id": run_id, "tenant": caller.tenant_id},
)
try:
result = container.wait(timeout=timeout_s)
logs = container.logs(stdout=True, stderr=True)[:20_000].decode("utf-8", "replace")
outputs = collect_outputs(container, "/out", max_bytes=5 * 1024 * 1024)
status = "ok" if result["StatusCode"] == 0 else "error"
except Exception:
container.kill(); status, logs, outputs = "timeout", b"", {}
finally:
stats = container.stats(stream=False)
container.remove(force=True) # ephemeral, always
shutil.rmtree(workdir, ignore_errors=True)
audit_log(action="code_execution", run_id=run_id, tenant=caller.tenant_id,
code_hash=sha256(code), status=status, cpu_ns=stats_cpu(stats), mem_peak=stats_mem(stats))
return {"status": status, "stdout": logs, "files": outputs,
"note": "Output truncated" if len(logs) >= 20_000 else None}
Managed alternatives worth preferring: provider-hosted code execution (Anthropic code execution tool, OpenAI code interpreter), E2B, Modal, Daytona, or Firecracker-based runners — they've already solved the isolation problem.
Pros
- Unlocks genuinely high-value capability: computation, data transformation, plotting, file handling — things LLMs do badly in-context and code does exactly.
- Correct arithmetic and data processing instead of hallucinated numbers (structured + unstructured hybrid).
- Contained blast radius: a malicious or buggy program affects one ephemeral container.
- Resource limits make cost and latency bounded.
Cons
- Container escape is a real class of vulnerability — namespaces and cgroups are not a security boundary against a determined kernel exploit. Hostile workloads need gVisor/Firecracker/microVMs.
- Operational weight: image maintenance, runner fleet, cleanup, monitoring.
- Latency: container start adds 100 ms–2 s; pooling warm sandboxes helps but complicates isolation.
- Legitimate needs pull against the controls: "it needs to pip install", "it needs to call our API" — each exception erodes the boundary.
- Debugging failures inside a locked-down sandbox is harder.
When to use
- Data analysis, computation, format conversion, chart generation, log parsing — any task where writing code is the right answer.
- Whenever the alternative is the LLM doing arithmetic or data manipulation in its head.
When NOT to use
- When a purpose-built tool would do (a
query_warehousetool beats generated SQL in a sandbox for standard analytics). - Without the controls. An
exec()in your application process is not a sandbox; it's a remote code execution vulnerability with an LLM as the attacker's interface. - For tasks needing broad network or credential access — restructure so the agent calls an authorised tool instead of writing code that authenticates.
Production at scale
Prefer a managed sandbox. Provider code-execution tools and specialised runners have solved container escape, pooling, and cleanup. Building your own runner fleet is justified only by residency or cost constraints.
Egress is where data leaves. Default network_mode: none. If network is needed, use a dedicated network with an egress proxy and a domain allow-list, and explicitly block 169.254.169.254 and link-local ranges — cloud metadata endpoints are the classic credential-theft path. Log denied attempts; a spike is a signal worth investigating.
No credentials, ever. If the code needs data, stage it as input files. If it needs to write results, collect them from /out. If it needs an API, the agent should call an authorised tool instead — the sandbox should never hold a token (excessive agency).
Per-tenant isolation: never reuse a container across tenants; label containers with tenant and run ID; ensure no shared writable volumes. Warm pools must be per-tenant or reset completely between uses.
Wall-clock timeout enforced outside the container — a program can ignore signals; the orchestrator must kill and remove it.
Output caps: stdout, stderr, and produced files all capped, with truncation markers (per-source truncation budgets). A program printing 2 GB of logs should not reach your context or your log storage.
Dependency policy: pre-install the allowed libraries in the image; do not allow arbitrary pip install at runtime (that's both an egress hole and a supply-chain risk, model & supply-chain hygiene). Version-pin and rebuild the image on a schedule with vulnerability scanning.
Audit and retention: log the code hash, inputs referenced, resource usage, and outputs produced. In regulated contexts, retain the actual code executed (auditability).
Cost controls: sandbox minutes are compute; cap per run and per tenant, and count them in the run budget (cost & step budgets).
Prod checklist
- Execution in a separate container/microVM; never in the application process
- Minimal pinned image, non-root user,
cap_drop: ALL,no-new-privileges, seccomp profile, read-only root - No secrets or cloud credentials in the environment
- Egress default-deny; allow-list + proxy if needed; link-local/metadata blocked; denials logged
- CPU, memory, PID, file-descriptor, and disk limits; wall-clock timeout enforced externally
- Ephemeral per-execution containers; no cross-tenant reuse or shared writable volumes
- Inputs staged read-only; outputs collected from a designated dir with size caps
- Runtime dependency installation disabled; image scanned and rebuilt on a schedule
- gVisor/Firecracker or a managed sandbox for hostile or multi-tenant workloads
- Full audit: code hash, resource usage, outputs, denied network attempts
Metrics to watch
| Metric | Why |
|---|---|
| Denied egress attempts | Exfiltration attempts or misbehaving code |
| Timeout and OOM rates | Limits calibration |
| Sandbox start latency (p95) | UX |
| Executions per tenant; compute minutes | Cost and abuse |
| Image vulnerability findings | Supply chain |
Related
- Excessive agency — the sandbox holds no credentials
- Prompt injection — the source of hostile code
- Budgets — sandbox minutes count
- Supply-chain hygiene — image and dependency pinning
- Structured hybrid — often a better answer than generated code