Sandbox

The Sandbox primitive defines the execution environment in which tools run. It controls isolation level, resource limits, network access, filesystem scope, and secret injection.

URI pattern: claw://local/sandbox/{name}

---

Schema

claw: "0.3.0"
kind: Sandbox
metadata:
  name: "standard-sandbox"
  version: "1.0.0"
spec:
  level: "container"              # "none" | "process" | "wasm" | "container" | "vm"
  runtime: "docker"               # "docker" | "apple-container" | "wasmtime"
                                  # | "firecracker" | "gvisor" | "native"

  capabilities:
    network:
      mode: "allowlist"           # "deny" | "allowlist" | "allow-all"
      allowed_hosts:
        - "api.example.com"
        - "*.googleapis.com"
      ssrf_protection:
        enabled: true
        block_private_ips: true
        dns_pinning: true

    filesystem:
      mode: "scoped"              # "deny" | "read-only" | "scoped" | "full"
      mount_paths:
        - path: "/workspace"
          permissions: "rw"
        - path: "/config"
          permissions: "ro"
        - path: "/tmp"
          permissions: "rw"
      denied_paths:
        - "/etc/shadow"
        - "/root/.ssh"

    secrets:
      injection: "host-boundary"  # "host-boundary" | "environment" | "file-mount"
      encryption: "aes-256-gcm"
      leak_detection:
        enabled: true
        patterns: 22

    shell:
      mode: "restricted"          # "deny" | "restricted" | "full"
      blocked_commands:
        - "rm -rf /"
        - "curl * | bash"
        - "chmod 777"
      blocked_patterns:
        - ".*password.*=.*"
        - "\\|\\s*bash"
        - "eval\\s+"

  resource_limits:
    memory_mb: 512
    cpu_shares: 256
    max_processes: 50
    max_open_files: 1024
    timeout_ms: 300000
    max_output_bytes: 10485760    # 10 MB

---

Key Fields

Field	Required	Description
level	Yes	Isolation level: none, process, wasm, container, or vm.
runtime	No	Runtime implementation (level-dependent). Inferred from level if omitted.
capabilities.network	No	Network access controls with SSRF protection.
capabilities.filesystem	No	Filesystem access controls with mount paths and deny lists.
capabilities.secrets	No	Secret injection method and leak detection.
capabilities.shell	No	Shell command restrictions and blocked patterns.
resource_limits	No	Resource caps (memory, CPU, processes, files, timeout, output size).

---

Isolation Levels

Level	Mechanism	Overhead	Security
none	No isolation. Tool runs in agent process.	Zero	Minimal
process	Separate OS process with limited permissions.	Low	Moderate
wasm	WebAssembly sandbox with capability grants.	Low	High
container	Docker/Apple Container with filesystem isolation.	Medium	High
vm	Full virtual machine isolation.	High	Maximum

---

Network Security

The ssrf_protection block defends against Server-Side Request Forgery:

• block_private_ips — Blocks requests to private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• dns_pinning — Resolves DNS and checks the resulting IP against blocked ranges, preventing DNS rebinding attacks

---

Shell Pattern Matching

Values in blocked_patterns are matched as regular expressions against the full command string. This enables blocking categories of dangerous commands rather than just specific strings.

---

Validation Rules

• The level field is REQUIRED.
• If runtime is omitted, the runtime SHOULD infer an appropriate implementation from the level (e.g., container implies docker).
• Resource limits, when specified, MUST be enforced by the runtime.
• Blocked patterns MUST be valid regular expressions.

---

Design Rationale

The Sandbox primitive unifies five isolation levels (none, process, WASM, container, VM) with declarative resource limits, network controls, SSRF protection, and host-boundary secret injection. By making execution constraints declarative, CKP enables security posture to be audited, versioned, and shared across teams and implementations.