Skip to main content

Crate procjail

Crate procjail 

Source
Expand description

§procjail

Process sandbox for running untrusted code in real runtimes.

When security tools need to execute untrusted code (npm packages, pip packages, browser extensions, binaries), they need containment that actually works. This crate provides kernel-level isolation using the best available mechanism on the host.

§Containment Strategies (ordered by preference)

  1. unshare — Linux namespaces (PID, network, mount, user). No root needed.
  2. bubblewrap (bwrap) — Lightweight container (Flatpak uses this). Rootless.
  3. firejail — Feature-rich sandbox. Needs installation.
  4. rlimits — Basic resource limits only. Always available. Least secure.

The sandbox auto-selects the best available strategy, or you can force one.

§Usage

use std::path::Path;
use procjail::{SandboxConfig, SandboxedProcess};

let config = SandboxConfig::builder()
    .runtime("/usr/bin/node")
    .max_memory_mb(256)
    .max_cpu_seconds(30)
    .max_fds(64)
    .allow_localhost(false)
    .env_passthrough(&["HOME", "PATH", "NODE_PATH"])
    .env_strip_secrets(true)
    .build();

let mut proc = SandboxedProcess::spawn(
    Path::new("/path/to/harness.js"),
    Path::new("/path/to/package"),
    &config,
).unwrap();

proc.send(r#"{"method":"eval","args":["1+1"]}"#).unwrap();
if let Some(line) = proc.recv().unwrap() {
    println!("observation: {}", line);
}

§Architecture

Parent (full privileges)
  │
  ├── stdin pipe  → probes flow in
  ├── stdout pipe ← observations flow out
  │
  └── [containment layer]
        ├── PID namespace (process isolation)
        ├── NET namespace (no external network)
        ├── MNT namespace (read-only filesystem)
        ├── USER namespace (unprivileged)
        ├── rlimits (memory, CPU, FDs)
        └── env stripping (no secrets leak)

Structs§

ContainmentLevel
How much containment is available on this host.
ResourceUsage
Usage metrics captured when the sandboxed process exits.
SandboxConfig
Configuration for sandbox behavior.
SandboxConfigBuilder
Builder for SandboxConfig.
SandboxedProcess
A sandboxed child process running untrusted code.

Enums§

EnvMode
Environment inheritance strategy for the sandbox process.
ProcjailError
Public error type for procjail APIs.
Strategy
Which containment mechanism to use.

Traits§

SandboxedIO
Trait for communicating with a sandboxed process.

Functions§

available_strategy
Return the best available containment strategy for the current host.
probe_capabilities
Probe the host and return what containment is available.
quick_spawn
Convenience helper that spawns a sandboxed process with a minimal default config.

Type Aliases§

Result
Result type for procjail public APIs.