Filesystem Guards

Four guards in chio-guards protect the filesystem surface: a forbidden-path denylist, an allowlist counterpart, a secret detector that scans write content, and a patch analyzer that bounds diff size and forbids backdoor patterns. All four operate over a normalized path computed from the request arguments by crate::action::extract_action.

Path Normalization

Every filesystem guard runs the input through three normalizers from crate::path_normalization:

• normalize_path_for_policy :: lexical normalization (strips . and .., collapses separators, handles Windows backslashes).
• normalize_path_for_policy_with_fs :: filesystem-resolved normalization (resolves symlinks via the OS).
• normalize_path_for_policy_lexical_absolute :: absolute lexical normalization without filesystem access.

When the resolved path differs from the lexical path (the symlink-escape case), the guards require the resolved path to match policy. This closes the lexical-bypass hole where a symlink inside an allowed directory points at a denied target.

ForbiddenPathGuard

Blocks file access to sensitive paths via a glob denylist. Source: crates/chio-guards/src/forbidden_path.rs. Guard name: forbidden-path.

Struct

pub struct ForbiddenPathGuard {
    patterns: Vec<glob::Pattern>,
    exceptions: Vec<glob::Pattern>,
}

impl ForbiddenPathGuard {
    pub fn new() -> Self;
    pub fn with_patterns(patterns: Vec<String>, exceptions: Vec<String>) -> Self;
    pub fn is_forbidden(&self, path: &str) -> bool;
}

Default forbidden patterns

Built by default_forbidden_patterns(). These are the actual entries from source, in source order.

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

// AWS credentials
"**/.aws/**"

// Environment files
"**/.env"
"**/.env.*"

// Git credentials
"**/.git-credentials"
"**/.gitconfig"

// GPG keys
"**/.gnupg/**"

// Kubernetes
"**/.kube/**"

// Docker
"**/.docker/**"

// NPM tokens
"**/.npmrc"

// Password stores
"**/.password-store/**"
"**/pass/**"

// 1Password
"**/.1password/**"

// System paths (Unix)
"/etc/shadow"
"/etc/passwd"
"/etc/sudoers"

// Windows credential stores
"**/AppData/Roaming/Microsoft/Credentials/**"
"**/AppData/Local/Microsoft/Credentials/**"
"**/AppData/Roaming/Microsoft/Vault/**"
"**/NTUSER.DAT"
"**/NTUSER.DAT.*"
"**/Windows/System32/config/SAM"
"**/Windows/System32/config/SECURITY"
"**/Windows/System32/config/SYSTEM"
"**/*.reg"
"**/AppData/Roaming/Microsoft/SystemCertificates/**"
"**/WindowsPowerShell/profile.ps1"
"**/PowerShell/profile.ps1"

Windows globs are kept on Unix; they simply never match. There is no platform-conditional compilation on the pattern set.

Configuration

Algorithm

1. Compute the lexical, resolved (FS-aware), and absolute-lexical paths.
2. If the resolved path differs from the lexical target (symlink case), exception matching uses only the resolved path. Otherwise either form can match an exception.
3. For each forbidden pattern, deny if either the resolved or lexical form matches. An exception match short-circuits to allow.

Failure modes & evidence

• Invalid glob in user input :: silently dropped by filter_map(|p| Pattern::new(p).ok()).
• Non-filesystem actions (no FileAccess,FileWrite, or Patch in the action enum): guard returns Verdict::Allow.
• Performance: O(P) glob matches per call, where P is the pattern count. The lexical path computation is allocation-light; the FS-resolved variant performs a single canonicalize syscall on Unix.

guards:
  forbidden_path:
    patterns:
      - "**/.ssh/**"
      - "**/.env"
      - "/etc/shadow"
    exceptions:
      - "**/fixtures/.env.example"

PathAllowlistGuard

The dual of ForbiddenPathGuard: deny-by-default within an explicit allowlist. Source: crates/chio-guards/src/path_allowlist.rs. Guard name: path-allowlist.

Struct

pub struct PathAllowlistConfig {
    pub enabled: bool,
    pub file_access_allow: Vec<String>,
    pub file_write_allow: Vec<String>,
    pub patch_allow: Vec<String>,
}

pub struct PathAllowlistGuard {
    enabled: bool,
    file_access_allow: Vec<glob::Pattern>,
    file_write_allow: Vec<glob::Pattern>,
    patch_allow: Vec<glob::Pattern>,
}

Configuration

Session filesystem roots

When the kernel passes session_filesystem_roots on the GuardContext, the guard also enforces that the path falls within at least one root. This check runs before the enabled flag is consulted, so a session-root violation denies even with the guard disabled. An empty root set means deny (fail-closed).

// Verified from path_allowlist.rs evaluate():
if let Some(session_roots) = ctx.session_filesystem_roots {
    if !self.matches_session_roots(path, session_roots) {
        return Ok(Verdict::Deny);
    }
}

if !self.enabled {
    return Ok(Verdict::Allow);
}

Symlink-escape behavior

When the FS-resolved path differs from the lexical target (a symlink traversal), the guard requires the resolved path to match the allowlist. This prevents a symlink inside an allowed directory from granting access to a target outside it.

SecretLeakGuard

Scans FileWrite and Patch content for credential leaks. Source: crates/chio-guards/src/secret_leak.rs. Guard name: secret-leak.

Struct

pub struct SecretLeakConfig {
    pub enabled: bool,
    pub skip_paths: Vec<String>,
    pub custom_patterns: Vec<CustomSecretPattern>,
}

pub struct CustomSecretPattern {
    pub name: String,
    pub pattern: String,
}

pub struct SecretLeakGuard { /* private */ }

pub struct SecretMatch {
    pub pattern_name: String,
    pub offset: usize,
    pub length: usize,
    pub redacted: String,
}

Default detectors

Names and regex sources verified from default_patterns().

Default skip paths

From SecretLeakConfig::default():

skip_paths: vec![
    "**/test/**",
    "**/tests/**",
    "**/*_test.*",
    "**/*.test.*",
]

Matching paths bypass scanning entirely. The defaults exempt test fixtures so committed example tokens do not block writes.

Configuration

Algorithm

1. Read action. Only FileWrite(path, content) and Patch(path, diff) proceed. Other actions return Verdict::Allow.
2. Skip-path check. If any skip glob matches the path, return Allow.
3. UTF-8 decode the content. Binary content (failed decode) returns empty matches and the call is allowed.
4. Run every compiled detector regex against the text via find_iter. Any match denies.

Failure modes

• Invalid custom_patterns regex :: SecretLeakConfigError::InvalidCustomPattern at with_config. The guard will not construct.
• Built-in regex compile failure :: SecretLeakConfigError::InvalidBuiltInPattern (in practice this should never fire because the patterns are tested).
• SecretLeakGuard::new() panics if the default config fails to compile. This is treated as a source-level invariant.

Redaction format

Detected secrets are reported via SecretMatch.redacted: the first 4 and last 4 characters of the match are kept, the middle is replaced with *. Matches shorter than 8 chars become all asterisks.

PatchIntegrityGuard

Validates unified-diff payloads before they are applied. Source: crates/chio-guards/src/patch_integrity.rs. Guard name: patch-integrity.

Struct

pub struct PatchIntegrityConfig {
    pub enabled: bool,
    pub max_additions: usize,
    pub max_deletions: usize,
    pub forbidden_patterns: Vec<String>,
    pub require_balance: bool,
    pub max_imbalance_ratio: f64,
}

pub struct PatchAnalysis {
    pub additions: usize,
    pub deletions: usize,
    pub imbalance_ratio: f64,
    pub forbidden_matches: Vec<ForbiddenMatch>,
    pub exceeds_max_additions: bool,
    pub exceeds_max_deletions: bool,
    pub exceeds_imbalance: bool,
}

Defaults

Default forbidden patterns

// Disable security features
r"(?i)disable[ _\-]?(security|auth|ssl|tls)"
r"(?i)skip[ _\-]?(verify|validation|check)"

// Dangerous operations
r"(?i)rm\s+-rf\s+/"
r"(?i)chmod\s+777"
r"(?i)eval\s*\("
r"(?i)exec\s*\("

// Backdoor indicators
r"(?i)reverse[_\-]?shell"
r"(?i)bind[_\-]?shell"
r"base64[_\-]?decode.*exec"

Algorithm

1. Iterate diff lines. Lines starting with + (excluding +++ headers) incrementadditions. Lines starting with - (excluding ---) increment deletions.
2. For each added line, run every forbidden regex. Each hit appends a ForbiddenMatch.
3. Compute imbalance_ratio = additions / deletions (or f64::INFINITY when deletions are zero and additions are not).
4. Deny if any forbidden match was found, or any threshold was exceeded.

Failure modes

• Invalid forbidden_patterns regex :: PatchIntegrityConfigError::InvalidForbiddenPattern at construction. PatchIntegrityGuard::new() panics if the default set fails to compile.
• Non-Patch actions return Verdict::Allow. The guard does not look at file writes; that is SecretLeakGuard's job.

Composition in the default pipeline

All four guards land in the default pipeline built by GuardPipeline::default_pipeline(). Cheap glob checks run first; the secret scanner and patch analyzer run later because their cost grows with content size.

use chio_guards::{
    ForbiddenPathGuard, PathAllowlistGuard, SecretLeakGuard, PatchIntegrityGuard,
};

let mut pipeline = chio_guards::GuardPipeline::new();
pipeline.add(Box::new(ForbiddenPathGuard::new()));
pipeline.add(Box::new(PathAllowlistGuard::new()));   // disabled by default
pipeline.add(Box::new(SecretLeakGuard::new()));
pipeline.add(Box::new(PatchIntegrityGuard::new()));

Next Steps

• Network Guards :: SSRF and egress controls.
• Shell & Code Guards :: shell command and code execution checks.
• Default Pipeline :: full registration order.