Shell & Code Guards

ShellCommandGuard

Source: crates/guards/chio-guards/src/shell_command.rs. Guard name: shell-command. Operates on ToolAction::ShellCommand(commandline). Part of GuardPipeline::default_pipeline() alongside ForbiddenPathGuard, EgressAllowlistGuard, PathAllowlistGuard, McpToolGuard, SecretLeakGuard, and PatchIntegrityGuard.

Struct

pub struct ShellCommandGuard {
    forbidden_regexes: Vec<Regex>,
    forbidden_path: ForbiddenPathGuard,
    enforce_forbidden_paths: bool,
    fail_closed: bool,
}

An operator-supplied pattern that does not compile is a configuration error, and the rule is never silently dropped.

pub enum ShellCommandConfigError {
    #[error("invalid shell-command forbidden pattern {pattern:?}: {source}")]
    InvalidPattern {
        pattern: String,
        source: regex::Error,
    },
}

The public constructors and the match check, with bodies elided. with_patterns is infallible and builds a deny-all guard when a pattern fails to compile, so a direct caller cannot widen access with a typo; try_with_patterns hands the error back (shell_command.rs:55).

impl ShellCommandGuard {
    pub fn new() -> Self;
    pub fn with_patterns(patterns: Vec<String>, enforce_forbidden_paths: bool) -> Self;
    pub fn try_with_patterns(
        patterns: Vec<String>,
        enforce_forbidden_paths: bool,
    ) -> Result<Self, ShellCommandConfigError>;
    pub fn is_forbidden(&self, commandline: &str) -> bool;
}

Default forbidden patterns

From default_forbidden_patterns(). These are case-insensitive regexes.

fn default_forbidden_patterns() -> Vec<String> {
    vec![
        // Explicit destructive operations.
        r"(?i)\brm\s+(-rf?|--recursive)\s+/\s*(?:$|\*)".to_string(),
        // Common "download and execute" patterns.
        r"(?i)\bcurl\s+[^|]*\|\s*(bash|sh|zsh)\b".to_string(),
        r"(?i)\bwget\s+[^|]*\|\s*(bash|sh|zsh)\b".to_string(),
        // Reverse shell indicators.
        r"(?i)\bnc\s+[^\n]*\s+-e\s+".to_string(),
        r"(?i)\bbash\s+-i\s+>&\s+/dev/tcp/".to_string(),
        // Best-effort base64 exfil patterns.
        r"(?i)\bbase64\s+[^|]*\|\s*(curl|wget|nc)\b".to_string(),
    ]
}

Configuration

The HushSpec compiler in crates/guards/chio-policy/src/compiler/rules.rs builds ShellCommandGuard::new() when forbidden_patterns is empty and ShellCommandGuard::with_patterns(...) otherwise, so supplied patterns replace the defaults.

Algorithm

is_forbidden performs four passes on the command line.

1. Tokenize with shlex_split_best_effort: single and double quotes, backslash escapes, and the shell separators ;, |, ||, &, &&, newline, and carriage return.
2. Recursive rm of root. Walk the token segments split on shell separators. Inside each segment, skip wrappers (sudo, env, command, builtin) and locate the first executable token. If it is rm with both a recursive flag (-r, -R, -rf, --recursive) and a root target (/ or /*), deny. The env -S and env --split-string forms are re-tokenized so a payload smuggled through that wrapper is still inspected. When the first executable is a shell interpreter (sh, bash, zsh, dash, ksh) carrying a -c <script> argument, shell_command_string pulls out the inner script, shlex_split_best_effort re-tokenizes it, and the check recurses into it up to MAX_SHELL_COMMAND_NESTING (4) levels, so bash -c "rm -rf /" behind a wrapper is still reached.
3. Regex pass over a normalization of the command line in which the literal '|' sequence becomes a bare |, which catches quoted-pipe obfuscation.
4. Forbidden-path extraction (when enforce_forbidden_paths is on). Split tokens on shell separators and pull out of each segment: redirection targets (>, >>, <, 2>, and the rest); inline-redirection prefixes glued to a path (2>/path); flag values of the form --output=/path; bare path-shaped tokens (starting with /, ~, ./, or ../, containing /.ssh/, /.aws/, or /.gnupg/, literally .env or .env.*, or shaped like a Windows drive path); best-effort Windows drive paths (C:\\Windows\\System32\\config\\SAM); and scripts handed to a shell interpreter with -c (sh -c "cat ~/.ssh/id_rsa"), re-tokenized with their own path candidates extracted, to the same MAX_SHELL_COMMAND_NESTING depth. Each candidate runs through ForbiddenPathGuard::is_forbidden; a hit denies.

Failure modes

• The evaluate signature is Result<GuardDecision, KernelError>. Non-shell actions return GuardDecision::allow(); a malformed action (a type mismatch during extraction) denies.
• A malformed regex in operator-supplied patterns fails closed. with_patterns delegates to try_with_patterns; if one pattern fails to compile, the whole guard falls back to a deny-all configuration (forbidden_regexes empty, fail_closed: true) and is_forbidden returns true for every command line. The other patterns stop matching along with the bad one. Use try_with_patterns to return the failure as ShellCommandConfigError::InvalidPattern and reject the config at load time.
• The shlex parser is best-effort, with no variable expansion, command substitution, or process substitution. Shell tricks that rely on runtime expansion may pass it.

CodeExecutionGuard

Source: crates/guards/chio-guards/src/code_execution.rs. Guard name: code-execution. Operates on ToolAction::CodeExecution { language, code }, derived from tools like python, eval, run_code, and jupyter.

Struct

pub struct CodeExecutionConfig {
    /// Enable/disable the guard entirely.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Allowed interpreter languages.  Empty means "any language".
    #[serde(default)]
    pub language_allowlist: Vec<String>,
    /// Dangerous module names (used as word-boundary literal matches
    /// against the code body).  Defaults to
    /// [`default_dangerous_modules`].
    #[serde(default = "default_dangerous_modules")]
    pub module_denylist: Vec<String>,
    /// When `false`, deny code-execution calls that request network
    /// access (either via argument flag or a detectable network import).
    #[serde(default = "default_true")]
    pub network_access: bool,
    /// Maximum execution time in milliseconds.  When set, any call with
    /// an `execution_time_ms` / `timeout_ms` argument above this value
    /// is denied.  `None` disables the check.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_execution_time_ms: Option<u64>,
    /// Maximum bytes of code to scan for module / network detection.
    /// Longer code bodies are denied outright (fail-closed) so a
    /// padding-based bypass cannot push a forbidden import past the
    /// scan boundary.
    #[serde(default = "default_max_scan_bytes")]
    pub max_scan_bytes: usize,
}

The guard keeps the compiled form: the allowlist as a set, the denylist as name and regex pairs.

pub struct CodeExecutionGuard {
    enabled: bool,
    language_allowlist: HashSet<String>,
    module_patterns: Vec<(String, Regex)>,
    network_access: bool,
    max_execution_time_ms: Option<u64>,
    max_scan_bytes: usize,
}

Defaults

The network_access and language_allowlist defaults above are the CodeExecutionConfig::default() values used by CodeExecutionGuard::new(). Their serde attributes differ: #[serde(default = "default_true")] on network_access and a bare #[serde(default)] on language_allowlist, so a policy-driven config that omits those keys deserializes to network_access: true and language_allowlist: [].

Default dangerous modules

From default_dangerous_modules(). Python-focused, case-sensitive literal matches with word boundaries.

pub fn default_dangerous_modules() -> Vec<String> {
    vec![
        "os".to_string(),
        "subprocess".to_string(),
        "socket".to_string(),
        "sys".to_string(),
        "ctypes".to_string(),
        "shutil".to_string(),
        "pickle".to_string(),
        "marshal".to_string(),
        "importlib".to_string(),
    ]
}

Network-module signal list

Used by the network gate when an explicit flag is absent. From default_network_modules():

&[
    "socket",
    "requests",
    "urllib",
    "urllib2",
    "urllib3",
    "http",
    "httpx",
    "aiohttp",
    "websockets",
    "ftplib",
    "smtplib",
    "telnetlib",
]

A bare fetch( call also fires the network signal, so JavaScript code paths cover the browser API.

Detection method

Each denylist entry becomes a word-boundary regex through module_regex_source, which matches:

(?m)(?:^|[^A-Za-z0-9_])(?:
    import\s+<m>(?:\s|$|\.|,)|
    from\s+<m>(?:\s|\.)|
    require\s*\(\s*['"]<m>['"]\s*\)|
    <m>\s*\.
)

That covers Python (import x, from x import, x.attr), Node (require('x')), and attribute-style usage. The dotted-name escape preserves literal matches.

Execution-time arguments

When max_execution_time_ms is set, the guard reads the requested ceiling from the arguments, trying these keys in order:

fn read_execution_time_ms(arguments: &serde_json::Value) -> Option<u64> {
    for key in [
        "execution_time_ms",
        "executionTimeMs",
        "timeout_ms",
        "timeoutMs",
        "max_execution_time_ms",
        "maxExecutionTimeMs",
    ] {
        if let Some(v) = arguments.get(key).and_then(|v| v.as_u64()) {
            return Some(v);
        }
    }
    None
}

Network flag keys

When network_access is false, the guard reads:

fn requested_network_access(arguments: &serde_json::Value) -> Option<bool> {
    for key in [
        "network_access",
        "networkAccess",
        "allow_network",
        "allowNetwork",
    ] {
        if let Some(v) = arguments.get(key).and_then(|v| v.as_bool()) {
            return Some(v);
        }
    }
    None
}

If any flag is true, deny. If all flags are absent, fall back to the network-module regex over the code body.

Algorithm

1. Skip if enabled = false.
2. Pull (language, code) from the action. Non-CodeExecution actions allow.
3. Lowercase the language. If the allowlist is non-empty and the language is outside it (or is unknown), deny.
4. If the code body is longer than max_scan_bytes, deny outright (fail-closed).
5. Run each compiled module-denylist regex on the code body; the first hit denies.
6. Network gate. If network_access is false and either the explicit flag or the network-module regex fires, deny.
7. Execution-time check. If a requested time exceeds the ceiling, deny.

Failure modes

• An invalid module-denylist regex returns CodeExecutionError::InvalidPattern at construction.
• If the default config fails to compile (its inputs are literal identifiers), the guard falls back to empty_failclosed: empty allowlist, empty patterns, network_access: false, max_execution_time_ms: Some(0). This fallback admits some calls. The empty allowlist skips the language check (the guard runs it only if !language_allowlist.is_empty()); the empty pattern set matches no module; the network gate fires only on an explicit network flag or a network-module hit; and the zero-ms ceiling fires only if let Some(requested) = read_execution_time_ms(...), when the caller supplies an execution-time argument. A benign code-execution call with no network flag, no network import, and no execution-time key is allowed under this fallback.
• If the network-module alternation fails to compile, the compiler logs and falls back to a regex that matches no input. The guard keeps running without the implicit network-import signal.

PatchIntegrityGuard

PatchIntegrityGuard operates on ToolAction::Patch(path, diff) from patch-applying tools. It bounds added and deleted line counts and denies a patch whose added lines match a forbidden pattern (disabled security checks, rm -rf /, reverse shells, and similar). It ships in default_pipeline(). Its configuration, defaults, forbidden-pattern list, algorithm, and failure modes are on Filesystem Guards.