kavach

Sandbox execution framework for Rust.

10 isolation backends, strength scoring (0-100), 3-scanner pipeline, credential proxy, runtime guards, threat classification, audit chain — in a single crate.

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 wraps untrusted code in isolation and gives you a number (0-100) that tells you how protected you are.

Architecture

Consumer (SY, stiva, kiran, AgnosAI, hoosh)
    |
    v
Sandbox::create(config) -> exec("command") -> destroy()
    |
    |-- Scanning Pipeline (secrets + code + data)
    |-- Threat Classifier (intent score, kill-chain, escalation)
    |-- Runtime Guards (fork bomb, path blocklist, command blocklist)
    |-- Credential Proxy (env/file/stdin + HTTP proxy)
    |-- Strength Scoring (0-100 per backend + policy modifiers)
    |
    v
Backend Dispatch (or CompositeBackend for layered isolation)
    |-- Process (50)      -- seccomp + namespaces + landlock + cgroups
    |-- OCI (55)          -- runc/crun container
    |-- WASM (65)         -- wasmtime + WASI + fuel metering
    |-- gVisor (70)       -- user-space kernel (runsc)
    |-- SGX (80)          -- Intel hardware enclave (Gramine)
    |-- SEV (82)          -- AMD encrypted VM (QEMU + SNP)
    |-- TDX (85)          -- Intel Trust Domain Extensions
    |-- SyAgnos (80-88)   -- Hardened AGNOS OS (3 tiers)
    |-- Firecracker (90)  -- lightweight microVM + jailer
    '-- Noop (0)          -- testing only

Quick start

[dependencies]
kavach = "1.0"

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

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = SandboxConfig::builder()
        .backend(Backend::Process)
        .policy_seccomp("basic")
        .network(false)
        .timeout_ms(30_000)
        .build();

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

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

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

Auto-select the strongest backend

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

let policy = SandboxPolicy::strict();
let best = Backend::resolve_best(&policy);
// Returns Firecracker if available, else gVisor, else Process, etc.

let config = SandboxConfig::builder()
    .backend(best)
    .policy(policy)
    .build();

Composite isolation (defense-in-depth)

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

let config = SandboxConfig::builder()
    .backend(Backend::GVisor)          // outer: gVisor container
    .inner_backend(Backend::Process)   // inner: seccomp + landlock
    .policy(SandboxPolicy::strict())
    .build();
// Score: gVisor(70) + Process policy merged + composite bonus = ~80

Sandbox pooling (fast startup)

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

let config = SandboxConfig::builder().backend(Backend::Noop).build();
let mut pool = SandboxPool::new(config, 10).await?; // Pre-warm 10

let mut sandbox = pool.claim().await?;               // Instant
sandbox.transition(SandboxState::Running)?;
let result = sandbox.exec("echo fast").await?;

pool.replenish().await?;                              // Refill pool

HTTP credential proxy

use kavach::credential::http_proxy::{HttpProxyConfig, CredentialRule, start_proxy};

let mut config = HttpProxyConfig::default();
config.credential_rules.insert(
    "api.openai.com".into(),
    CredentialRule {
        header_name: "Authorization".into(),
        header_value: "Bearer sk-...".into(),
    },
);
config.enforce_allowlist = true;
config.allowed_hosts = vec!["api.openai.com".into()];

let handle = start_proxy(config).await?;
// Set http_proxy=http://127.0.0.1:{handle.port()} on sandboxed process
// Credentials injected automatically, never exposed to sandbox

Strength scoring

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

let score = scoring::score_backend(Backend::Process, &SandboxPolicy::strict());
println!("{}", score); // "68 (standard)"

let score = scoring::score_backend(Backend::Firecracker, &SandboxPolicy::strict());
println!("{}", score); // "100 (fortress)"

Features

kavach = { version = "1.0", features = ["wasm"] }        # Process + WASM
kavach = { version = "1.0", features = ["full"] }         # All backends
kavach = { version = "1.0", features = ["attestation"] }  # + EAR tokens

Scanning pipeline

The externalization gate runs three scanners on every sandbox output:

Plus: threat classification (intent score 0.0-1.0, kill-chain stages), repeat offender tracking, quarantine storage, HMAC-SHA256 audit chain.

Strength scoring scale

Consumers

Building from source

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

cargo build                          # Process backend only
cargo build --features full          # All backends
cargo test --all-features            # 561 tests
make check                           # fmt + clippy + test + audit
make semver                          # cargo-semver-checks
./scripts/bench-history.sh           # Benchmark with CSV history

License

AGPL-3.0-only. See LICENSE for details.