procjail 0.2.0

Process sandbox for running untrusted code — Linux namespaces, seccomp, firejail, bubblewrap, rlimits
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

//! # 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
//!
//! ```rust,no_run
//! 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
//!
//! ```text
//! 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)
//! ```

// Note: unsafe code is used in process.rs for libc calls
#![warn(missing_docs)]

mod config;
mod detect;
mod error;
mod process;
mod strategy;

#[cfg(test)]
mod adversarial_tests;

pub use config::{EnvMode, SandboxConfig, SandboxConfigBuilder};
pub use detect::{available_strategy, probe_capabilities, ContainmentLevel};
pub use error::{ProcjailError, Result};
pub use process::{ResourceUsage, SandboxedProcess};
pub use strategy::Strategy;

/// Trait for communicating with a sandboxed process.
pub trait SandboxedIO {
    /// Send a line to the process.
    fn send(&mut self, line: &str) -> Result<()>;
    /// Receive a line from the process. None = EOF.
    fn recv(&mut self) -> Result<Option<String>>;
    /// Kill the process.
    fn kill(&mut self);
    /// Check if alive.
    fn is_alive(&mut self) -> bool;
}

/// Convenience helper that spawns a sandboxed process with a minimal default config.
///
/// Example:
/// ```rust,no_run
/// use std::path::Path;
/// use procjail::quick_spawn;
///
/// let _child = quick_spawn(
///     "node",
///     Path::new("/abs/path/to/harness.js"),
///     Path::new("/abs/path/to/workdir"),
/// )?;
/// # Ok::<(), procjail::ProcjailError>(())
/// ```
pub fn quick_spawn(
    runtime: &str,
    harness: impl AsRef<std::path::Path>,
    work_dir: impl AsRef<std::path::Path>,
) -> Result<process::SandboxedProcess> {
    let config = config::SandboxConfig::builder()
        .runtime(runtime)
        .timeout_seconds(30)
        .build();
    process::SandboxedProcess::spawn(harness.as_ref(), work_dir.as_ref(), &config)
}