Sandbox Runtime

A hardcore Linux sandbox for running untrusted code safely.

Think of it as a bulletproof prison for dangerous programs - they can't escape, can't see your system, and can't use unlimited resources.

What Is This?

A sandbox = isolated environment where code runs trapped in a box.

Real-world example: When you run code on LeetCode or HackerRank, they use sandboxes like this so your code can't:

• Hack their servers
• See other users' solutions
• Mine bitcoin on their machines
• Fork bomb and crash everything

Use Cases

• 🎓 Online Code Judges (LeetCode, HackerRank) - Run student code safely
• 🔧 CI/CD Systems (GitHub Actions) - Execute untrusted build scripts
• 🧩 Plugin Systems - WordPress plugins, browser extensions, game mods
• 🦠 Malware Analysis - Run suspicious files without risk
• ☁️ Cloud Functions (AWS Lambda style) - Multi-tenant code execution

Quick Start - Test It Now

cd tests
./demo.sh

This runs 5 tests showing malicious programs trying to attack and getting blocked.

Manual Testing

cd tests

# Test 1: Fork bomb (tries to crash system by creating infinite processes)
./manual_test ./fork_bomb
# ✓ Should get killed at 10 processes: Exit code 137

# Test 2: Memory hog (tries to eat all RAM)
./manual_test ./memory_hog
# ✓ Should get OOM killed at 100MB: OOM killed: YES

# Test 3: Privilege escalation (tries to hack with ptrace)
./manual_test ./escape_ptrace
# ✓ Should fail: ptrace failed: Operation not permitted

# Test 4: Check root powers
./manual_test ./check_caps
# ✓ Should show no capabilities: (empty set)

What You Get

7 Layers of Isolation:

• PID namespace - Can't see other processes
• Network namespace - Isolated network (no internet by default)
• Mount namespace - Own filesystem (can't see your files)
• User namespace - Different user ID
• IPC namespace - Can't talk to other programs
• UTS namespace - Different hostname
• Cgroup namespace - Can't see system resources

Resource Limits:

• Max 100MB RAM (configurable) → kills if exceeded
• Max 50% CPU (configurable) → throttles if greedy
• Max 10 processes (configurable) → blocks fork bombs
• Timeout after 10 seconds → kills long-running code

Security:

• Seccomp-BPF - Blocks dangerous syscalls (ptrace, mount, kernel modules)
• Capability dropping - Removes ALL root privileges
• Filesystem isolation - Can't access your files

Architecture

Your Code
    ↓
Sandbox CLI ──→ Supervisor Daemon (root)
                    ↓
                Creates isolated environment:
                  - 7 namespace types
                  - Cgroup limits
                  - Seccomp filter
                  - Drops capabilities
                    ↓
                Sandboxed Executor
                    ↓
                Untrusted Code (TRAPPED)

How It Works

Multi-process architecture:

1. Supervisor Daemon - Privileged process managing sandbox lifecycle
2. Sandbox Manager - Sets up isolation (namespaces, cgroups, mounts)
3. Sandboxed Executor - Runs untrusted code in isolated environment

Isolation layers:

• All 7 namespace types (PID, NET, UTS, IPC, MOUNT, USER, CGROUP)
• Seccomp-BPF syscall filtering (3 policy levels: minimal <10 syscalls, standard ~50, permissive)
• Cgroups v2 resource limits (CPU, memory, PIDs, IO)
• Filesystem isolation with pivot_root + minimal rootfs
• Network isolation (none, loopback-only, bridged with veth)
• Complete capability dropping + bounding set clearing
• Resource limits via rlimits

Communication:

• IPC via Unix domain sockets with binary protocol
• File descriptor passing for stdin/stdout/stderr
• Real-time metrics and audit logging

How The Sandbox Blocks Attacks

Attack	How It's Blocked	Result
Fork bomb (infinite processes)	Cgroup PID limit (max 10)	Killed at process 10
Memory bomb (eat all RAM)	Cgroup memory limit (100MB)	OOM killed
CPU hogging (100% CPU forever)	Cgroup CPU quota (50%)	Throttled to 50%
ptrace (debug parent process)	Seccomp blocks ptrace syscall	Operation not permitted
mount (hack filesystem)	No CAP_SYS_ADMIN capability	Permission denied
Kernel module loading	Seccomp blocks init_module	Bad syscall
Network access	Network namespace (loopback only)	No route to host

Files Explained

Setup

Build

mkdir build && cd build
cmake ..
make -j4

Executables: sandbox_supervisor, sandbox_manager, sandbox_executor, sandbox_cli

Dependencies

# Ubuntu/Debian
sudo apt install libcap-dev libseccomp-dev cmake g++

# Arch
sudo pacman -S libcap libseccomp cmake gcc

Configuration

Create sandbox.conf:

[sandbox]
rootfs_path=/tmp/sandbox_root
work_dir=/sandbox
bind_mounts=/usr/bin:/usr/bin:ro,/lib:/lib:ro,/lib64:/lib64:ro
enable_network=false
seccomp_policy=standard

[resources]
memory_limit=512M
cpu_quota=100000
cpu_period=100000
max_pids=100
max_file_size=100M
max_open_files=1024

[execution]
timeout_seconds=30
capture_output=true

CLI Commands

Start supervisor daemon

sudo ./sandbox_supervisor --config sandbox.conf --socket /var/run/sandbox.sock

Execute command in sandbox

./sandbox_cli start --command "/bin/python3 script.py" --args "arg1 arg2" --config sandbox.conf

Check sandbox status

./sandbox_cli status --sandbox-id <id>

Get resource metrics

./sandbox_cli metrics --sandbox-id <id>

Kill sandbox

./sandbox_cli kill --sandbox-id <id>

Stop supervisor

./sandbox_cli stop

Security Policies

Minimal - Only essential syscalls (<10): read, write, exit, brk, mmap, close

Standard - Common syscalls (~50): + file ops, signals, memory management, basic IO

Permissive - Allow all except dangerous: blocks ptrace, kernel modules, bpf, perf, syslog

Network Modes

• none - No network access
• loopback_only - Only localhost (127.0.0.1)
• bridged - Full network via veth pair to bridge

Resource Limits

• CPU quota/period (microseconds)
• Memory limit (bytes)
• Max PIDs
• Max file size
• Max open files
• Execution timeout

Performance

• Sandbox creation: <10ms
• Syscall filtering overhead: <1%
• Zero-copy IPC with FD passing
• Can run 1000+ sandboxes simultaneously

Example

# Start supervisor
sudo ./sandbox_supervisor --socket /var/run/sandbox.sock &

# Run Python script with 256MB RAM, 50% CPU, 10s timeout
./sandbox_cli start \
  --command "/usr/bin/python3" \
  --args "untrusted.py" \
  --memory 256M \
  --cpu-quota 50000 \
  --timeout 10 \
  --seccomp standard \
  --network none

# Check metrics
./sandbox_cli metrics --sandbox-id sandbox_1234

Technical Details

Multi-process architecture:

1. Supervisor Daemon - Privileged process managing sandbox lifecycle
2. Sandbox Manager - Sets up isolation (namespaces, cgroups, mounts)
3. Sandboxed Executor - Runs untrusted code in isolated environment

Isolation layers:

• All 7 namespace types (PID, NET, UTS, IPC, MOUNT, USER, CGROUP)
• Seccomp-BPF syscall filtering (3 policy levels: minimal <10 syscalls, standard ~50, permissive)
• Cgroups v2 resource limits (CPU, memory, PIDs, IO)
• Filesystem isolation with pivot_root + minimal rootfs
• Network isolation (none, loopback-only, bridged with veth)
• Complete capability dropping + bounding set clearing
• Resource limits via rlimits

Communication:

• IPC via Unix domain sockets with binary protocol
• File descriptor passing for stdin/stdout/stderr
• Real-time metrics and audit logging

---

Need help? Read QUICKSTART.md for detailed explanations for security test results.