vetto

The OS-native, fail-closed sandbox & policy runtime for AI coding agents.

⚡ Quickstart (10 seconds)

1. Install

One-line installation commands:

# Standalone curl (Linux / macOS / WSL2)
curl -fsSL https://raw.githubusercontent.com/shleder/vetto/main/install.sh | sh

# Homebrew (macOS / Linux)
brew install shleder/tap/vetto

# npm global
npm install -g @shledery/vetto

# Cargo (from crates.io)
cargo install vetto

# System-wide installation
curl -fsSL https://raw.githubusercontent.com/shleder/vetto/main/install.sh | sh -s -- --system

# Cargo locked build from crates.io
cargo install vetto --locked

# Docker / Devcontainer (unprivileged user namespaces)
docker run --rm -it --security-opt seccomp=unconfined ghcr.io/shleder/vetto:0.3.5 vetto doctor

Every release binary is attested with SLSA Level 3 Provenance and signed with Minisign (Key ID 75ECEC9B5080C590). Pre-built archives and CycloneDX 1.5 SBOMs are published on GitHub Releases. See Installation Guide for custom paths and platform options.

2. Run

1-command agent activation:

# Enable transparent sandbox shim for your agent:
vetto enable claude     # or codex, cursor, aider, opencode

# Run your agent as usual — vetto enforces boundaries underneath:
claude

Direct execution without shims:

# Execute command under default strict sandbox:
vetto run -- python script.py

# Direct shortcut syntax:
vetto -- npm test

🛡️ What vetto intercepts

When autonomous AI agents run with full execution privileges (e.g. --dangerously-skip-permissions or unattended loops), a single hallucination, compromised dependency hook, or prompt injection can wipe host files or leak sensitive developer keys (~/.ssh, ~/.aws, .env). vetto neutralizes these risks at the OS kernel boundary before untrusted processes execute:

$ claude
> Reading ~/.ssh/id_rsa...
[vetto] BLOCKED: Inode-level secret mask (INV-08). EACCES.
> Opening raw socket to 198.51.100.1...
[vetto] BLOCKED: Network namespace isolated (INV-04). EAFNOSUPPORT.
> Spawning detached daemon via setsid...
[vetto] TERMINATED: Process tree extinction breach (INV-20). Exit 125.

5 Core Security Guarantees

1. Zero Secret Leaks: Credential stores (~/.ssh, ~/.aws, ~/.gnupg) and intra-project secrets (.env*, *.pem, *.key) are physically stripped from environment variables (35+ patterns) and masked at the filesystem layer via mode-000 tmpfs overlays and /dev/null binds.
2. Strict Workspace Isolation: Filesystem writes are locked strictly to the target workspace root and /tmp. Destructive host modifications are blocked fail-closed.
3. Governed Network Relay: Network access is blocked by default (--net off) via network namespaces (CLONE_NEWNET) or routed exclusively through a loopback relay broker enforcing domain allowlists and anti-DNS rebinding defenses.
4. Guaranteed Process Extinction (<500ms): Fail-closed process supervision sweeps all descendant fork trees (cgroup.kill / PID namespaces / Job Objects / kqueue), terminating runaway zombie daemons and orphaned background processes.
5. Zero Daemon Latency (~4ms cold start): Sub-4ms cold start latency, 0 MB idle RAM footprint, and zero background daemons (no root, no dockerd). Boundaries are injected directly between fork() and execve().

💻 Platform Guarantees (3-Tier Honesty)

vetto formally separates operating system platforms into 3 distinct tiers to reflect actual kernel guarantees (Issue #26):

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                vetto Supervisor Engine                                 │
│          (Fail-Closed Lifecycle · Env Sanitizer · Secret Masker · Audit Log)           │
└──────────────────┬────────────────────────────┬────────────────────────────┬───────────┘
                   │                            │                            │
                   ▼                            ▼                            ▼
┌─────────────────────────────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────────┐
│       Linux Backend (Tier 1)        │ │    macOS Backend (Tier 2)    │ │   Windows Backend (Tier 3)   │
│ ─────────────────────────────────── │ │ ──────────────────────────── │ │ ──────────────────────────── │
│ • Landlock LSM (ABI v1–v6) Inodes   │ │ • Apple Seatbelt C API (SBPL)│ │ • AppContainer & LPAC Tokens │
│ • Rootless Namespaces (bwrap/clone) │ │ • Shape D AST Engine         │ │ • Job Object Kill-On-Close   │
│ • Seccomp-BPF Syscall Filter        │ │ • dyld Tracking (Issue #62)  │ │ • Deny-Path Overlap Analysis │
│ • PID Namespace / Deathsig init     │ │ • kqueue Watchdog & pgroup   │ │ • Opt-in WFP Admin Gate (#63)│
│ • cgroups v2 & rlimits Ceilings     │ │ • Best-effort rlimits        │ │ • WSL2 Production Pathway    │
└─────────────────────────────────────┘ └──────────────────────────────┘ └──────────────────────────────┘

Linux Backend (Tier 1 — Production)

• Rootless Namespaces & Bubblewrap (bwrap): Isolates Mount (CLONE_NEWNS), Network (CLONE_NEWNET), PID (CLONE_NEWPID), and IPC (CLONE_NEWIPC) namespaces entirely in unprivileged user space.
• Landlock LSM: Kernel-level VFS inode access control (ABI v1–v6) restricting filesystem reads and writes.
• Seccomp-BPF: Enforces fine-grained system call interception before execve (UnixOnly and AgentMin), terminating debugger attachment (ptrace), eBPF injections (bpf), userfaultfd exploits, and raw socket allocations.
• cgroups v2 & rlimits: Immutable resource ceilings on CPU time (RLIMIT_CPU), virtual memory address space (RLIMIT_AS), process limits (RLIMIT_NPROC), and file size (RLIMIT_FSIZE).

macOS Backend (Tier 2 — Experimental)

• Native Seatbelt: Dynamic Scheme SBPL (Sandbox Profile Language) compilation loaded via Apple's private C API (libsandbox.1.dylib), bypassing brittle CLI wrappers.
• Filesystem Confinement: Strict write isolation locked to the workspace root and /tmp. Known secret paths (~/.ssh, ~/.aws, .env) are masked via tail denials (deny_resolved). Broad reads remain permitted due to Apple's dyld shared cache constraints (Issue #62).
• Process Lifecycle Supervision: Watchdog supervisor thread monitoring parent death via kqueue and executing clean process-group (pgroup) SIGKILL sweeps on termination.

Windows Backend (Tier 3 — Experimental)

• AppContainer & LPAC: Process sandboxing via Less Privileged AppContainer tokens (S-1-15-2-2) stripping implicit capabilities and enforcing default-deny filesystem boundaries.
• Deny-Path Overlap Analysis: Granular verification of display-only deny paths against granted roots; fails closed on unsubtractable subpath collisions (Issue #63).
• Job Objects: Enforces JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE ensuring 100% process tree extinction upon session exit.
• WSL2 Production Pathway: For production-grade Landlock LSM and namespace isolation on Windows, executing through WSL2 (wsl -- vetto ...) is recommended.

🤖 Supported AI Agents (Roster)

vetto includes 20 native agent presets with automatic credential isolation, configuration path allowlisting, and zero-config network profiles (see Agent Compatibility Registry):

Model Context Protocol (MCP) Support

Isolate third-party MCP servers connected to Claude Desktop or Codex Desktop (see MCP Integration Guide and Tutorial):

vetto mcp wrap --allow ./data --allow-read /usr/share --net off -- <mcp-server-binary> [args...]

🔒 Policy Management & Security Audit (Policy UX)

vetto compiles declarative security policies into deterministic, BLAKE3-sealed cryptographic contracts before execution:

# Explain resolved policy and sealed BLAKE3 contract:
vetto policy explain --limits pids=50,mem=1G

# Preflight configuration linter:
vetto policy lint --strict

# Check configuration and verify policies without spawning:
vetto check

# Run throwaway leak-detection battery on current policy:
vetto verify

# Inspect blocked filesystem attempts, syscalls, and network egress from past runs:
vetto audit --latest

# Print post-session security recap:
vetto audit --latest --recap

# Dynamic runtime grants (no manual TOML editing):
vetto allow ./target                    # Grant read+write to a folder
vetto allow --read-only /usr/share/doc  # Grant read-only access
vetto allow --net api.github.com        # Allow egress to domain
vetto deny ~/.aws/credentials           # Mask sensitive file

📚 Architecture Invariants & Specifications

Deep architectural specifications, threat models, and verification suites:

• 🏛️ Architecture Blueprint — Tri-plane compiler, execution FSM, kernel invariants, and process extinction theorems.
• 🛡️ Threat Model & Boundary Guarantees — Inode-level masking, network brokers, and attack vector mitigations.
• 🧪 Verify-NG Test Harness — 6-tier hermetic trap suites and kernel boundary regression testing.
• 🔏 SLSA Level 3 Provenance & Attestation — Cryptographic supply-chain attestations, Minisign signatures, and CycloneDX SBOMs.
• ⚠️ Exit Codes Specification — Fail-closed exit contract (125), child process exit propagation, and signal handling.
• ⚙️ Profile Inheritance & Presets — Hierarchical security profile syntax and preset configuration.
• 🌐 Platform Backends & Parity Matrix — Technical deep dive into Linux, macOS, and Windows isolation mechanisms.

Built-in Security Profiles

⚖️ Comparison: vetto vs. Alternatives

See In-Depth Sandbox Comparison for full benchmark metrics, microVM trade-offs, and platform breakdown.

Contributing

We welcome contributions from security researchers, systems engineers, and AI developers!

1. Fork the repository and create your branch from main.
2. Follow strict code hygiene: adhere to formatting, clippy lints, and existing error-handling idioms.
3. Ensure every capability claim is backed by real kernel tests:
   • No mock tests for kernel boundaries: all boundary checks must assert real kernel enforcement.
   • No silent downgrades: any failure to establish isolation must fail closed with exit code 125.
4. Open a Pull Request with a clear description of changes and test evidence.

For security vulnerabilities, please refer to SECURITY.md and report responsibly via GitHub Security Advisories.

License

vetto is distributed under the dual Apache-2.0 / MIT license.

See LICENSE and THIRD_PARTY_NOTICES.md for full terms.