Sandboxed Tool Executor

An isolated, secure code execution runtime and REST API designed to safely run untrusted, LLM-generated code. It enforces multi-layered host isolation using Linux cgroups v2, network air-gapping, read-only root filesystems, and watchdog deadline terminations.

---

Threat Model & Security Boundaries

Attack Vector	Security Mechanism	Enforcement Layer
Out-of-Memory DOS	cgroups v2 Memory Ceiling	Enforces mem_limit with swap disabled (memswap_limit = mem_limit). Kernel terminates breach via SIGKILL (exit code 137).
CPU Starvation	CFS Bandwidth Quota	Bounds CPU compute via nano_cpus scheduling quotas.
Fork Bombs	Kernel PID Limits	Constrains active process tree to pids_limit=32.
Data Exfiltration	Network Air-Gapping	Dedicated Network Namespace with network_mode="none".
Filesystem Tampering	Read-Only Root & Scratch tmpfs	Mounts container root as read_only=True with an unprivileged /workspace tmpfs (noexec,nosuid).
Privilege Escalation	Capability Dropping & Non-Root UID	Strips all Linux capabilities (cap_drop=["ALL"]) and drops process privileges to UID 1000.
Process Hangs	Watchdog Deadline Reaper	Supervisor enforces wall-clock timeouts, killing stalled processes.

---

Architecture

Client / Autonomous Agent (FastAPI / HTTP)
                    │
            (ExecutionRequest)
                    ▼
          [ Sandbox Supervisor ]
                    │
    ┌───────────────┴───────────────┐
    ▼                               ▼
[ Resource Constraints (cgroups) ] [ Namespace Isolation ]
  • memory.max (e.g., 64MB)          • CLONE_NEWNET (network: none)
  • cpu.max (e.g., 0.5 CPU)          • Read-Only RootFS
  • pids.max (32 processes)          • cap_drop: ALL (UID 1000)
                    │
                    ▼
      [ Isolated Alpine Runner Container ]

---

Quickstart

1. Build the Unprivileged Runner Image

docker build -t sandbox-runner:latest -f Dockerfile.runner .

2. Install Host Dependencies

pip install -r requirements.txt

3. Run the Security & Isolation Test Suite

pytest -v tests/

4. Start the HTTP API Server

uvicorn executor.server:app --host 0.0.0.0 --port 8000 --reload

---

API Reference

POST /execute

Executes arbitrary Python code inside an isolated container with hard resource constraints.

Request Body

{
  "code": "import platform; print(platform.python_version())",
  "timeout_seconds": 3,
  "memory_limit_mb": 64,
  "cpu_limit": 0.5,
  "allow_network": false
}

Response (200 OK)

{
  "status": "success",
  "stdout": "3.11.16\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time_ms": 384.21,
  "memory_used_mb": null
}

Status Codes

• success: Script finished cleanly with exit code 0.
• timeout: Process exceeded timeout_seconds and was killed (exit_code: 124).
• memory_exceeded: Script exceeded memory ceiling and was killed by Linux OOM killer (exit_code: 137).
• error: Script encountered runtime exceptions or non-zero exit codes.

---

Agent Integration Example

To run the built-in LLM tool-calling simulation:

python -m examples.agent_tool_example

---