Guards

Composable guard families cover filesystem, shell, network egress, tool access, secrets, patch integrity, prompt safety, threat intel, rate limiting, and agent-surface controls (computer use, input injection, remote desktop, browser automation, code execution). Every guard returns one of Allow, Deny, or PendingApproval. The pipeline is conjunctive: all guards must allow for the request to proceed, and it short-circuits on the first deny.

The Guard Trait

Every guard implements the same trait. The interface is intentionally minimal: a name and an evaluate function.

pub trait Guard: Send + Sync {
    /// Human-readable guard name (e.g., "forbidden-path").
    fn name(&self) -> &str;

    /// Evaluate the guard against a tool call request.
    ///
    /// Returns Ok(Verdict::Allow) to pass, Ok(Verdict::Deny) to block,
    /// or Err on internal failure (which the kernel treats as deny).
    fn evaluate(&self, ctx: &GuardContext) -> Result<Verdict, KernelError>;
}

The Verdict enum has three variants:

pub enum Verdict {
    /// The action is allowed.
    Allow,
    /// The action is denied.
    Deny,
    /// The action is suspended pending a human decision. Emitted only by
    /// the full chio-kernel shell via the approval pipeline.
    PendingApproval,
}

There is no Skip variant. Guards that are disabled or not applicable to the current request type return Allow. If a guard returns Err, the kernel treats it as a deny. Guards never fail open. PendingApproval is emitted only by the approval pipeline in chio-kernel; the stateless guards documented on this page never return it.

Pipeline Evaluation Model

The guard pipeline is conjunctive: every guard must return Allow for the request to proceed. The evaluation order is fixed, running cheapest guards first. The pipeline short-circuits on the first Deny: once any guard denies, remaining guards are not evaluated.

# Stateless guards (cheapest first):
1. forbidden-path      : glob match against path
2. path-allowlist      : allowlist check against path
3. shell-command       : regex + path extraction from command
4. egress-allowlist    : domain allowlist match
5. mcp-tool            : set membership lookup
6. secret-leak         : regex scan of file content
7. patch-integrity     : diff analysis + pattern scan
8. velocity            : token bucket check

# Session-aware guards (observe running session state):
9.  agent-velocity     : cross-capability agent throttle
10. internal-network   : SSRF defense (RFC 1918, metadata, k8s DNS)
11. data-flow          : data provenance and exfiltration tracking

1. Forbidden Paths

Guard name: forbidden-path

Blocks access to sensitive filesystem paths using glob pattern matching. Applies to file access, file write, and patch operations. Non-filesystem actions (shell commands, network egress, MCP tools) return Allow immediately.

Path normalization handles both Unix and Windows paths, and resolves symlinks to prevent traversal bypasses. A symlink pointing outside an allowed directory is still blocked.

Built-in Defaults

The guard ships with a hardcoded set of forbidden patterns covering common secret and credential locations:

# SSH keys
**/.ssh/**
**/id_rsa*
**/id_ed25519*
**/id_ecdsa*

# Cloud credentials
**/.aws/**
**/.kube/**
**/.docker/**

# Environment / config secrets
**/.env
**/.env.*
**/.git-credentials
**/.gitconfig
**/.npmrc

# GPG / password stores
**/.gnupg/**
**/.password-store/**
**/pass/**
**/.1password/**

# System files (Unix)
/etc/shadow
/etc/passwd
/etc/sudoers

# System files (Windows)
**/AppData/Roaming/Microsoft/Credentials/**
**/Windows/System32/config/SAM
**/Windows/System32/config/SECURITY
**/Windows/System32/config/SYSTEM
**/*.reg
# ...and more Windows credential paths

Configuration

You can supply custom patterns and exceptions. Exceptions take priority: if a path matches both a forbidden pattern and an exception, it is allowed.

rules:
  forbidden_paths:
    patterns:
      - "**/.ssh/**"
      - "**/.env"
      - "**/secrets/**"
    exceptions:
      - "**/project/.env"    # Allow this specific .env file

Example Scenarios

2. Path Allowlist

Guard name: path-allowlist

A deny-by-default guard that restricts filesystem access to explicitly allowed paths. While forbidden-path blocks specific dangerous paths, path-allowlist inverts the model: only paths matching the allowlist are permitted. Disabled by default. It must be explicitly enabled and configured.

Maintains separate allowlists for three operation types: file access (reads), file write, and patch. When the patch allowlist is empty, it falls back to the file write allowlist.

Like forbidden-path, this guard resolves symlinks to prevent traversal. A symlink inside an allowed directory that points outside it is denied.

Configuration

rules:
  path_allowlist:
    enabled: true
    file_access_allow:
      - "/workspace/project/**"
      - "/tmp/cache/**"
    file_write_allow:
      - "/workspace/project/src/**"
    patch_allow: []  # Falls back to file_write_allow when empty

Example Scenarios

3. Shell Command

Guard name: shell-command

Blocks dangerous shell command patterns before execution. Uses regex matching on command lines and also extracts file paths from shell commands to run them through the forbidden-path guard. Non-shell-command tool calls return Allow immediately.

Built-in Patterns

The guard ships with regex patterns targeting the most dangerous command categories:

The guard also performs best-effort shlex splitting to extract file path candidates from commands, then checks them against the forbidden-path guard. This catches commands like cat ~/.ssh/id_rsa or echo hi > ~/.ssh/id_rsa. Redirection targets, flag arguments with =, and Windows drive-rooted paths are all extracted.

Configuration

rules:
  shell_command:
    patterns:
      - '(?i)\brm\s+(-rf?|--recursive)\s+/\s*(?:$|\*)'
      - '(?i)\bcurl\s+[^|]*\|\s*(bash|sh|zsh)\b'
    enforce_forbidden_paths: true  # Also check extracted paths

Example Scenarios

4. Egress Allowlist

Guard name: egress-allowlist

Controls outbound network access by domain using an allow/block list model. Fail-closed by default: any domain not in the allow list is denied. The block list takes precedence over the allow list, enabling surgical overrides. Non-network-egress tool calls return Allow immediately.

Built-in Defaults

The default allow list includes well-known AI API endpoints and package registries:

# AI/ML APIs
*.openai.com
*.anthropic.com
api.github.com

# Package registries
*.npmjs.org
registry.npmjs.org
pypi.org
files.pythonhosted.org
crates.io
static.crates.io

Configuration

rules:
  egress:
    allow:
      - "*.mycompany.com"
      - "api.stripe.com"
    block:
      - "blocked.mycompany.com"  # Block takes precedence

Example Scenarios

5. Tool Access

Guard name: mcp-tool

Restricts which MCP tools an agent may invoke, using allow/block lists with a configurable default action. Also enforces a maximum serialized argument size to prevent abuse via oversized payloads. Enabled by default.

Built-in Defaults

The default configuration blocks dangerous tools while allowing everything else:

# Default blocked tools:
shell_exec
run_command
raw_file_write
raw_file_delete

# Default action: allow (anything not explicitly blocked)
# Default max argument size: 1 MB

Evaluation Order

The guard evaluates in this order:

1. Argument size check: if serialized arguments exceed max_args_size, deny immediately.
2. Block list: if the tool name is in the block list, deny. Block always takes precedence.
3. Allow list: if an allow list is configured (non-empty), only tools in it may proceed. Everything else is denied.
4. Default action: if neither list matches, fall back to the configured default (allow or block).

Configuration

rules:
  tool_access:
    enabled: true
    allow:
      - read_file
      - list_directory
      - search_files
    block:
      - shell_exec
      - raw_file_delete
    default: block           # Deny any tool not in allow list
    max_args_size: 524288    # 512 KB

Example Scenarios

6. Secret Leak

Guard name: secret-leak

Detects potential secret exposure in file writes and patches. Uses regex patterns to identify API keys, tokens, passwords, and private keys in content before it is written to disk. Enabled by default. Non-write operations return Allow immediately.

Detected Secret Types

The guard ships with 18 built-in patterns covering the most common secret formats:

Configuration

The guard can be disabled and supports path-based skip patterns for test fixtures that intentionally contain example secrets:

rules:
  secret_leak:
    enabled: true
    skip_paths:
      - "**/test/**"
      - "**/tests/**"
      - "**/*_test.*"
      - "**/*.test.*"

When a secret is detected, the guard redacts it in evidence using a masking function that preserves the first and last 4 characters: AKIA************MPLE.

Example Scenarios

7. Patch Integrity

Guard name: patch-integrity

Validates the safety of applied patches and diffs. Checks for maximum addition/deletion thresholds, forbidden code patterns in added lines, and optional addition/deletion imbalance. Enabled by default. Non-patch operations return Allow immediately.

Safety Checks

The guard runs four independent checks. The patch is denied if any check fails:

1. Max additions: blocks patches with more than 1,000 added lines (default).
2. Max deletions: blocks patches with more than 500 deleted lines (default).
3. Forbidden patterns: scans added lines for dangerous code patterns.
4. Imbalance ratio: optionally checks the ratio of additions to deletions (disabled by default).

Forbidden Patterns in Patches

# Security disablement
disable_security, disable_auth, skip_verify, skip_validation

# Dangerous operations
rm -rf /, chmod 777, eval(), exec()

# Backdoor indicators
reverse_shell, bind_shell, base64_decode...exec

Configuration

rules:
  patch_integrity:
    enabled: true
    max_additions: 1000
    max_deletions: 500
    forbidden_patterns:
      - '(?i)disable[ _\-]?(security|auth|ssl|tls)'
      - '(?i)eval\s*\('
      - '(?i)reverse[_\-]?shell'
    require_balance: false
    max_imbalance_ratio: 10.0

Example Scenarios

8. Velocity

Guard name: velocity

Rate-limits agent invocations using synchronous token buckets. Each (capability_id, grant_index) pair gets an independent bucket, so two grants in the same token are throttled separately. The internal bucket balance and refill are integer milli-tokens; capacity is derived once per bucket via round(max_invocations * burst_factor) where burst_factor is an f64 (default 1.0), with a floor of 1. Both invocation count limits and monetary spend limits are supported.

Token Bucket Model

Each (capability_id, grant_index) pair gets its own independent token bucket. Tokens refill continuously at a rate derived from the configured window. The burst factor controls how many tokens can accumulate above the steady-state rate.

# Example: max 10 invocations per 60s window, burst_factor 1.5
#
# Capacity: round(10 * 1.5) = 15 tokens (burst ceiling, floored at 1)
# Refill rate: 10 tokens per 60 seconds (continuous)
#
# An agent can burst up to 15 calls instantly, then must
# wait for tokens to refill at ~1 token per 6 seconds.
#
# With the default burst_factor of 1.0, capacity equals
# round(max_invocations * 1.0) = max_invocations (no burst).

Configuration

rules:
  velocity:
    max_invocations_per_window: 100
    max_spend_per_window: 1000    # In currency minor units
    window_secs: 60
    burst_factor: 1.5

Spend velocity uses the max_cost_per_invocation from the matched grant to determine how many spend units each call consumes. If the grant lacks cost metadata and spend limiting is configured, the guard fails closed with an internal error.

Example Scenarios

9. Agent Velocity (session-aware)

Guard name: agent-velocity

Session-aware companion to velocity. While velocity is bound to a specific (capability_id, grant_index) pair, agent-velocity observes the live session state and throttles an agent that is hot-cycling across many capabilities. This is the guard that catches a runaway agent loop that would otherwise stay under each individual grant's ceiling.

10. Internal Network (session-aware)

Guard name: internal-network

SSRF defense. Blocks outbound connections targeting internal or sensitive network endpoints regardless of any egress allowlist match. The guard denies:

• RFC 1918 private address ranges
• Cloud metadata endpoints (e.g., the 169.254.169.254 class)
• Kubernetes service DNS (*.svc.cluster.local and related)
• DNS rebinding patterns
• Obfuscated IP encodings (decimal, octal, hex, zero-padded, mixed notations)

An egress allowlist tells the kernel what an agent is allowed to reach; this guard tells the kernel what no allowlist should ever cover, no matter how it was spelled.

11. Data Flow (session-aware)

Guard name: data-flow

Tracks data provenance across a session so a secret read from one source cannot be silently written to an unrelated sink. Combined with secret-leak and egress-allowlist, this guard closes the gap where each individual operation looks benign but the cross-step composition is exfiltration.

Guard Evidence in Receipts

Every receipt includes a evidence array recording what each guard reported. The GuardEvidence struct contains:

pub struct GuardEvidence {
    /// Name of the guard (e.g. "forbidden-path").
    pub guard_name: String,
    /// Whether the guard passed (true) or denied (false).
    pub verdict: bool,
    /// Optional details about the guard's decision.
    pub details: Option<String>,
}

When the pipeline short-circuits, only guards that were actually evaluated appear in the evidence array. Unevaluated guards are omitted, so the evidence array may have fewer entries than the total number of enabled guards.

{
  "evidence": [
    {
      "guard_name": "forbidden-path",
      "verdict": false,
      "details": "path /home/user/.ssh/id_rsa matches pattern **/.ssh/**"
    }
  ]
}

Writing Custom Guards

Custom guards implement the Guard trait. The kernel passes a GuardContext containing the full request, the resolved scope, agent and server identifiers, optional session filesystem roots, and the matched grant index:

use chio_kernel::{Guard, GuardContext, KernelError, Verdict};

pub struct BusinessHoursGuard {
    start_hour: u32,
    end_hour: u32,
}

impl Guard for BusinessHoursGuard {
    fn name(&self) -> &str {
        "business-hours"
    }

    fn evaluate(&self, _ctx: &GuardContext) -> Result<Verdict, KernelError> {
        let hour = chrono::Local::now().hour();
        if hour >= self.start_hour && hour < self.end_hour {
            Ok(Verdict::Allow)
        } else {
            Ok(Verdict::Deny)
        }
    }
}

Summary Table