Filesystem Guards

Policy matches the path a request resolves to

A path string can name one file and open another. The path guards compare policy against every form the path takes, and the resolved form wins when the forms disagree.

Three normalizers in crate::path_normalization produce the forms. normalize_path_for_policy is lexical: it strips . and .., collapses separators, and handles Windows backslashes. normalize_path_for_policy_with_fs resolves symlinks through the operating system, and normalize_path_for_policy_lexical_absolute makes the lexical form absolute without touching the filesystem.

When the resolved path differs from the lexical one, as it does through a symlink, the path guards require the resolved path to match policy. For a new file, resolution tries the parent directory; when resolution fails, normalization falls back to the lexical form. Between the check and the file operation the filesystem can change, so the host constrains the operation itself.

Credential paths are refused by default, with exceptions checked first

ForbiddenPathGuard, runtime name forbidden-path, denies access to paths that match a glob denylist. Its defaults cover SSH, AWS, GPG, Kubernetes, Docker, npm, 1Password, and password-store credentials, environment files, Git credentials, /etc/shadow, /etc/passwd, /etc/sudoers, and Windows credential stores, registry hives, and PowerShell profiles: 31 globs in all.

1. Forms. The guard computes the lexical, resolved, and absolute lexical paths.
2. Exceptions. A match against an exception allows the operation. When the resolved path differs from the lexical target, only the resolved path can match an exception; otherwise either form can.
3. Patterns. The guard denies when either the resolved or the lexical form matches a forbidden pattern.

Configure it through a HushSpec policy with the plural forbidden_paths rule name. Operator globs go through with_patterns(patterns, exceptions), which fails closed: an invalid glob returns ForbiddenPathConfigError::InvalidPattern and the guard refuses to construct, so a typo leaves every block in place.

hushspec: "0.1.0"
rules:
  forbidden_paths:
    patterns:
      - "/secrets/**"
      - "**/.ssh/**"
      - "**/.env"
    exceptions:
      - "/workspace/tests/fixtures/.env.example"

An exception is checked before the patterns, so the fixture passes while every other .env is refused. chio policy explain shows both decisions without admitting either call:

chio policy explain policy.yaml --server workspace --tool read_file \
  --params '{"path":"/workspace/tests/fixtures/.env.example"}'
chio policy explain policy.yaml --server workspace --tool read_file \
  --params '{"path":"/workspace/.env"}'

call       workspace.read_file {"path":"/workspace/tests/fixtures/.env.example"}
1 forbidden-path   pass   exception /workspace/tests/fixtures/.env.example
stopped    after guard 1 of 1; decision allow

call       workspace.read_file {"path":"/workspace/.env"}
1 forbidden-path   deny   /workspace/.env matches **/.env
stopped    at guard 1 of 1; decision deny

Evaluation scans the compiled globs against the path bytes, and the filesystem-aware normalizer canonicalizes the target and, when needed, its parent, so filesystem access adds to the cost of each check.

Session roots bound every path, even with the allowlist off

PathAllowlistGuard, runtime name path-allowlist, is the dual of the denylist: inside an explicit allowlist, everything else is denied. It keeps separate lists for reads, writes, and patches, and an empty patch_allow falls back to file_write_allow.

fn evaluate(&self, ctx: &GuardContext) -> Result<GuardDecision, KernelError> {
    if !self.enabled && ctx.session_filesystem_roots.is_none() {
        return Ok(GuardDecision::allow());
    }
    let action = match extract_action_checked(&ctx.request.tool_name, &ctx.request.arguments) {
        Ok(action) => action,
        Err(_) => return Ok(GuardDecision::deny(Vec::new())),
    };
    let Some(path) = action.filesystem_path() else {
        return Ok(GuardDecision::allow());
    };

    if let Some(session_roots) = ctx.session_filesystem_roots {
        if !self.matches_session_roots(path, session_roots) {
            return Ok(GuardDecision::deny(Vec::new()));
        }
    }

    if !self.enabled {
        return Ok(GuardDecision::allow());
    }

    let allowed = match &action {
        ToolAction::FileAccess(path) => self.is_file_access_allowed(path),
        ToolAction::FileWrite(path, _) => self.is_file_write_allowed(path),
        ToolAction::Patch(path, _) => self.is_patch_allowed(path),
        // Fail closed: any path-bearing action this allowlist cannot
        // classify is denied, never silently allowed.
        _ => false,
    };

    if allowed {
        Ok(GuardDecision::allow())
    } else {
        Ok(GuardDecision::deny(Vec::new()))
    }
}

When the kernel passes session_filesystem_roots on the GuardContext, the guard first requires the path to fall within at least one root. That check runs before the enabled flag is read, so a session-root violation denies with the guard disabled, and an empty root set denies everything. A path-bearing action the allowlist cannot classify is denied.

PathAllowlistGuard::new() constructs with enabled = false and empty lists. Supply a configuration through with_config before you rely on the allowlist; until then only the session roots narrow paths. When the resolved path differs from the lexical target, the resolved path must match the allowlist, so a symlink inside an allowed directory cannot open a target outside it.

Writes and patches that carry a credential stop before they land

SecretLeakGuard, runtime name secret-leak, scans the content of FileWrite and Patch actions against 18 built-in detectors and any custom patterns the operator adds.

1. Action. Only FileWrite(path, content) and Patch(path, diff) proceed; other actions are allowed.
2. Skip paths. A path matching a skip glob is allowed without a scan. The defaults exempt test files, so committed example tokens do not block writes.
3. Decode. The content is decoded as UTF-8. Binary content yields no matches and the write is allowed.
4. Scan. Every compiled detector runs over the text with find_iter; any match denies.

A hit is reported as a SecretMatch whose redacted value keeps the first four and last four characters and replaces the middle with *. A match shorter than eight characters becomes all asterisks.

An invalid custom regex fails construction with SecretLeakConfigError::InvalidCustomPattern, and a built-in that fails to compile returns SecretLeakConfigError::InvalidBuiltInPattern. SecretLeakGuard::new() never panics: through build_default_or_fail_closed() it falls back to unavailable_fail_closed(), whose one pattern [\s\S]+ matches all content and blocks every write and patch until the configuration is repaired.

A patch is bounded in size and screened line by line

PatchIntegrityGuard, runtime name patch-integrity, validates unified-diff payloads before they are applied. It reads only Patch actions; file writes belong to SecretLeakGuard.

1. Count. Lines starting with +, excluding +++ headers, are additions; lines starting with -, excluding ---, are deletions.
2. Screen. Every forbidden regex runs over each added line, and each hit appends a ForbiddenMatch.
3. Balance. imbalance_ratio is additions divided by deletions, or f64::INFINITY when deletions are zero and additions are not.
4. Decide. Any forbidden match, or any exceeded threshold, denies the patch.

The defaults cap a patch at 1,000 added and 500 removed lines and screen added lines with nine patterns that disable security checks, run destructive commands, or open shells. The balance check is off until require_balance is set, and then denies above max_imbalance_ratio, 10.0 by default.

An invalid regex passed through with_config fails construction with PatchIntegrityConfigError::InvalidForbiddenPattern.

The four guards run in the library default, interleaved with three others

GuardPipeline::default_pipeline() registers seven guards. The filesystem four sit apart: ShellCommandGuard, EgressAllowlistGuard, and McpToolGuard sit between them.

pub fn default_pipeline() -> Self {
    let mut pipeline = Self::new();
    pipeline.add(Box::new(crate::ForbiddenPathGuard::new()));
    pipeline.add(Box::new(crate::ShellCommandGuard::new()));
    pipeline.add(Box::new(crate::EgressAllowlistGuard::new()));
    pipeline.add(Box::new(crate::PathAllowlistGuard::new()));
    pipeline.add(Box::new(crate::McpToolGuard::new()));
    pipeline.add(Box::new(crate::SecretLeakGuard::new()));
    pipeline.add(Box::new(crate::PatchIntegrityGuard::new()));
    pipeline
}

Path checks come before the content scanner and the patch analyzer, and content size and configured patterns set the cost of the later two. default_runtime_guard_profile() is a separate builder that installs none of these guards. Of the kernel’s three verdicts, Verdict::Allow, Verdict::Deny, and Verdict::PendingApproval, these guards return only the first two, and the verdict itself is bare; its reason lands in the receipt’s evidence.

Read more in Default Pipelines.

Next: compare the other guard families