Crate proc_jail

Crate proc_jail 

Source
Expand description

§proc_jail

Process execution guard for agentic systems.

proc_jail provides a safe wrapper around process spawning, enforcing deterministic bounds on process execution to prevent command injection, unauthorized binary execution, and resource abuse.

§Quick Start

use proc_jail::{ProcPolicy, ProcRequest, ArgRules, InjectDoubleDash};
use std::time::Duration;

// Define a policy
let policy = ProcPolicy::builder()
    .allow_bin("/usr/bin/grep")
    .arg_rules("/usr/bin/grep", ArgRules::new()
        .allowed_flags(&["-n", "-i", "-l", "-c"])
        .max_flags(4)
        .max_positionals(10)
        .inject_double_dash(InjectDoubleDash::AfterFlags))
    .timeout(Duration::from_secs(30))
    .build()?;

// Create a request
let request = ProcRequest::new(
    "/usr/bin/grep",
    vec!["-n".to_string(), "pattern".to_string(), "file.txt".to_string()],
);

// Validate and execute
let prepared = policy.prepare(request)?;
let output = prepared.spawn().await?;

println!("stdout: {}", output.stdout_string());

§Design Principles

  • No shell interpretation: Commands use argv-style execution, not shell strings
  • Absolute paths only: Avoids PATH hijacking
  • Allowlist-only: No denylists - explicit enumeration of what’s permitted
  • Fail closed: Any error or ambiguity results in denial
  • Type-safe API: Only PreparedCommand can spawn processes

§Platform Support

Unix only (Linux, macOS). Windows is not supported because CreateProcess passes arguments as a string that each program parses differently, making injection prevention impossible to guarantee.

Structs§

ArgRules
Rules for validating arguments to a binary.
Output
Output from a successfully executed command.
PreparedCommand
A validated command ready for execution.
ProcPolicy
Process execution policy.
ProcPolicyBuilder
Builder for ProcPolicy.
ProcRequest
A proposed process execution request.
ResourceLimits
Resource limits applied during process execution.

Enums§

CwdPolicy
Policy for the working directory of spawned processes.
EnvPolicy
Policy for environment variables passed to spawned processes.
ExecError
Execution error during spawn().
InjectDoubleDash
Mode for double-dash injection.
ProcError
Combined error type for the prepare-and-spawn flow.
RiskCategory
Risk category for dangerous binaries.
RiskyBinPolicy
Policy for handling risky binaries.
Violation
Policy violation detected during prepare().

Constants§

ALWAYS_STRIP
Environment variables that are ALWAYS stripped, even with AllowList policy.
RISKY_INTERPRETERS
Script interpreters that can execute arbitrary code.
RISKY_PRIVILEGE
Privilege escalation tools.
RISKY_SHELLS
Shell interpreters that can execute arbitrary commands.
RISKY_SPAWNERS
Process spawners that can execute other binaries.