Security Guide

Zero-Trust Security & Authorization

Kyro implements a zero-trust policy matrix at the native execution boundary. This document covers policy modes, shell lexical analysis, fail-closed container isolation, and atomic approval consumption.

Configurable Policy Modes

Policy Mode	Behavior	Failure Mode
SafeAutoApprove	Permits verified read-only inspection commands (e.g. `git status`). Ambiguous or modifying commands require approval.	Prompts Human Approval
SandboxOnly	Mandatory execution inside an isolated Docker or Podman container with `--network=none`.	Fails Closed (Denies Action)
AskAlways	Generates an approval request for every shell command or modifying operation.	Prompts Human Approval

Fail-Closed Container Sandbox Implementation

A common vulnerability in desktop agent tools is transparently falling back to the host system when a container engine is missing. In Kyro, auth.rs strictly checks daemon availability:

libkyro/src/governance/auth.rs (lines 381-395)

// Fail-closed sandbox policy
if policy.shell_mode == "SandboxOnly" || requested_sandbox {
    let sandbox_status = DockerSandbox::probe();
    if !sandbox_status.available {
        return ShellAnalysis {
            decision: AuthDecision::Deny {
                reason: format!(
                    "Sandbox execution required by policy ({}), but container engine is unavailable: {}",
                    policy.shell_mode, sandbox_status.message
                ),
            },
            argv: None,
            requires_shell: true,
            lexed_words: Vec::new(),
        };
    }
    // Only proceed into isolated container if probe succeeded
}

Approval Proof Binding & TOCTOU Defense

To prevent Time-of-Check to Time-of-Use (TOCTOU) race conditions and argument tampering:

• Every approval proof is bound to the exact approval_id, run_id, and tool name.
• Arguments are compared using canonical JSON equivalence (json_values_canonically_equal).
• Consumption happens in an atomic SQLite transaction via consume_approval_request_bound, transitioning status from approved to consumed.