Sandbox & Security

Anvil can verify generated code in a sandbox environment before saving it, protecting against malicious or dangerous code.

Verified Mode

Enable sandbox verification:

from anvil import Anvil

anvil = Anvil(verified_mode=True)

# Generated code is now verified before saving
tool = anvil.use_tool(name="risky_tool", intent="Do something risky")

When verified mode is enabled:

1. Code is generated as usual
2. Static analysis checks for dangerous patterns
3. Code is executed in a sandbox
4. Only if verification passes is the code saved

Sandbox Drivers

Anvil supports two sandbox drivers:

Docker Sandbox (Recommended)

Full isolation using Docker containers:

# Automatically used if Docker is available
anvil = Anvil(verified_mode=True)

# Check sandbox status
status = anvil.get_sandbox_status()
print(status["active_driver"])  # "docker" or "local"

Requires Docker to be installed and running.

Local Sandbox (Fallback)

Restricted execution environment without Docker:

• Uses static analysis to block dangerous code
• Less secure than Docker
• Always available

Security Policies

Customize what generated code can do:

from anvil import Anvil
from anvil.sandbox import SecurityPolicy

policy = SecurityPolicy(
    # Network access
    allow_network=True,
    allowed_hosts=["api.example.com", "*.github.com"],

    # Filesystem access
    allow_filesystem_read=True,
    allow_filesystem_write=False,
    allowed_paths=["/tmp", "./data"],

    # System access
    allow_subprocess=False,
    allow_env_access=True,

    # Resource limits
    max_memory_mb=256,
    max_cpu_seconds=30.0,
    max_output_size_kb=1024,
)

anvil = Anvil(
    verified_mode=True,
    security_policy=policy,
)

Policy Options

Option	Default	Description
allow_network	False	Allow network requests
allowed_hosts	None	Whitelist of allowed hosts
allow_filesystem_read	True	Allow reading files
allow_filesystem_write	False	Allow writing files
allowed_paths	None	Whitelist of filesystem paths
allow_subprocess	False	Allow subprocess execution
allow_env_access	True	Allow reading environment variables
max_memory_mb	256	Maximum memory usage
max_cpu_seconds	30.0	Maximum CPU time
max_output_size_kb	1024	Maximum output size

Blocked Patterns

Static analysis blocks dangerous code patterns:

Blocked Imports

# These imports are blocked by default:
import subprocess      # System command execution
import multiprocessing # Process spawning
import ctypes          # Low-level memory access
import socket          # Raw network access
import paramiko        # SSH access
import fabric          # Remote execution
import shutil          # File operations (if filesystem write disabled)

Blocked Functions

# These functions are blocked:
eval("...")           # Dynamic code execution
exec("...")           # Dynamic code execution
compile("...")        # Code compilation
__import__("...")     # Dynamic imports
getattr(obj, "...")   # Reflection
setattr(obj, "...")   # Reflection
delattr(obj, "...")   # Reflection
globals()             # Global namespace access
locals()              # Local namespace access

Dangerous OS Calls

# These os module calls are blocked:
os.system("...")      # Shell execution
os.popen("...")       # Process creation
os.spawn*()           # Process spawning
os.exec*()            # Process replacement

Manual Verification

Verify a tool’s code manually:

anvil verify my_tool

Output:

🔍 Verifying: my_tool

  Sandbox: docker

✓ Code passed verification!
  Duration: 45.2ms

Or via API:

result = anvil.sandbox.verify_code("""
import requests

def run(url):
    return requests.get(url).json()
""")

if result.success:
    print("Code is safe")
else:
    print(f"Violations: {result.security_violations}")

Verification Results

The SandboxResult object contains:

result = anvil.sandbox.verify_code(code)

print(result.success)              # True/False
print(result.output)               # Execution output
print(result.error)                # Error message if failed
print(result.duration_ms)          # Execution time
print(result.security_violations)  # List of violations

Docker Configuration

When using Docker sandbox:

# Docker sandbox configuration is automatic
# It uses the python:3.11-slim image

# Check if Docker is available
from anvil.sandbox import DockerSandbox
docker = DockerSandbox()
print(docker.is_available())  # True/False

Sandbox Status

Check the current sandbox configuration:

status = anvil.get_sandbox_status()
print(status)
# {
#     "enabled": True,
#     "active_driver": "docker",
#     "docker_available": True,
#     "policy": {...}
# }

When to Use Verified Mode

Enable for:

• Production environments
• Multi-tenant systems
• Untrusted intents or documentation URLs
• Compliance requirements

Skip for:

• Development/testing
• Trusted internal tools
• Performance-critical applications (adds latency)

Security Considerations

1. Defense in Depth

Sandbox verification is one layer. Also use:

• API key rotation
• Network segmentation
• Least-privilege access

2. Review Generated Code

Even with verification, review critical tools:

code = anvil.get_tool_code("critical_tool")
print(code)  # Manual review

3. Eject Verified Tools

For production, eject and lock down critical tools:

# Generate and verify
tool = anvil.use_tool(name="production_tool", intent="...")

# Review the code
print(anvil.get_tool_code("production_tool"))

# Eject to prevent changes
# Edit ANVIL-MANAGED: false in the file

Next Steps

• Logging & Observability
• Multi-Provider Support
• CLI Reference