kavach

Sandbox execution framework for Rust.

Backend abstraction, strength scoring, policy engine, credential proxy, and lifecycle management — in a single crate. Execute untrusted code across 8 isolation backends with quantitative security guarantees.

Name: Kavach (कवच, Sanskrit) — armor, shield. Protects both what's inside and what's outside. Extracted from SecureYeoman's production sandbox framework.

What it does

kavach is the execution sandbox — it wraps untrusted code in isolation and gives you a number (0–100) that tells you how protected you are. Applications build their agent execution on top of kavach.

Architecture

Consumer (SY, daimon, AgnosAI)
    │
    ▼
Sandbox::create(config) → exec("command") → destroy()
    │
    ├── Policy Engine (seccomp, Landlock, network, resources)
    ├── Strength Scoring (0-100 per backend + modifiers)
    ├── Credential Proxy (secrets injection)
    │
    ▼
Backend Dispatch
    ├── Process (50)      — seccomp + namespaces + cgroups
    ├── OCI (55)          — runc/crun container
    ├── WASM (65)         — wasmtime + WASI
    ├── gVisor (70)       — user-space kernel (runsc)
    ├── SGX (80)          — Intel hardware enclave
    ├── SEV (82)          — AMD encrypted VM
    └── Firecracker (90)  — lightweight microVM

See docs/architecture/overview.md for the full architecture.

Quick start

[dependencies]
kavach = "0.21"

use kavach::{Sandbox, SandboxConfig, Backend, SandboxState};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Build a sandboxed execution environment
    let config = SandboxConfig::builder()
        .backend(Backend::Process)
        .policy_seccomp("basic")
        .network(false)
        .timeout_ms(30_000)
        .agent_id("agent-123")
        .build();

    // Create and start
    let mut sandbox = Sandbox::create(config).await?;
    sandbox.transition(SandboxState::Running)?;

    // Execute
    let result = sandbox.exec("echo hello world").await?;
    println!("exit: {}, stdout: {}", result.exit_code, result.stdout);

    // Cleanup
    sandbox.destroy().await?;
    Ok(())
}

Strength scoring

use kavach::{Backend, SandboxPolicy, scoring};

// Base score per backend
let process_score = scoring::base_score(Backend::Process);    // 50
let gvisor_score = scoring::base_score(Backend::GVisor);      // 70
let firecracker_score = scoring::base_score(Backend::Firecracker); // 90

// Policy modifiers raise the score
let strict = SandboxPolicy::strict();
let score = scoring::score_backend(Backend::Process, &strict);
println!("{}", score); // "63 (standard)" — seccomp + ro rootfs + limits

Credential proxy

use kavach::credential::{CredentialProxy, SecretRef, InjectionMethod};

let mut proxy = CredentialProxy::new();
proxy.register("API_KEY", "sk-secret-12345");

let refs = vec![SecretRef {
    name: "API_KEY".into(),
    inject_via: InjectionMethod::EnvVar { var_name: "OPENAI_API_KEY".into() },
}];

let env_vars = proxy.env_vars(&refs);
// env_vars = [("OPENAI_API_KEY", "sk-secret-12345")]
// The secret never touches the sandbox filesystem

Policy presets

use kavach::SandboxPolicy;

let minimal = SandboxPolicy::minimal();  // No restrictions
let basic = SandboxPolicy::basic();      // Seccomp + no network
let strict = SandboxPolicy::strict();    // Everything locked down

Features

# Just process + WASM sandboxing
kavach = { version = "0.21", features = ["wasm"] }

# Everything
kavach = { version = "0.21", features = ["full"] }

Strength scoring scale

Who uses this

Roadmap

Full details: docs/development/roadmap.md

Building from source

git clone https://github.com/MacCracken/kavach.git
cd kavach

# Build (process backend only — no system deps)
cargo build

# Build with WASM support
cargo build --features wasm

# Run tests
cargo test

# Run all CI checks
make check

Versioning

Pre-1.0 releases use 0.D.M SemVer — e.g. 0.21.3 = March 21st. Post-1.0 follows standard SemVer.

License

AGPL-3.0-only. See LICENSE for details.