evalbox_sandbox/
plan.rs

1//! Sandbox execution plan.
2//!
3//! A `Plan` describes everything needed to run a command in the sandbox:
4//! the command, environment, files, mounts, and resource limits.
5//!
6//! ## Example
7//!
8//! ```ignore
9//! use evalbox_sandbox::{Plan, Mount};
10//!
11//! let plan = Plan::new(["python", "main.py"])
12//!     .env("PYTHONPATH", "/work")
13//!     .file("main.py", b"print('hello')")
14//!     .timeout(Duration::from_secs(10))
15//!     .memory(256 * 1024 * 1024);
16//! ```
17//!
18//! ## Advanced Security Configuration
19//!
20//! ```ignore
21//! use evalbox_sandbox::{Plan, Syscalls, Landlock};
22//!
23//! let plan = Plan::new(["python3", "-c", "code"])
24//!     .syscalls(Syscalls::default().allow(libc::SYS_openat))
25//!     .landlock(Landlock::default().allow_read("/etc"))
26//!     .network(false);
27//! ```
28//!
29//! ## Defaults
30//!
31//! | Field | Default |
32//! |-------|---------|
33//! | `timeout` | 30 seconds |
34//! | `memory` | 256 MiB |
35//! | `max_pids` | 64 processes |
36//! | `max_output` | 16 MiB |
37//! | `network` | false (blocked) |
38//! | `cwd` | `/work` |
39
40use std::collections::{HashMap, HashSet};
41use std::path::PathBuf;
42use std::time::Duration;
43
44/// Seccomp user notification mode.
45///
46/// Controls how the supervisor handles intercepted syscalls from the sandboxed child.
47#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
48pub enum NotifyMode {
49    /// No seccomp notify filter installed. Zero overhead. Default.
50    #[default]
51    Disabled,
52    /// Supervisor logs syscalls and returns `SECCOMP_USER_NOTIF_FLAG_CONTINUE`.
53    /// Minimal overhead. For debugging/auditing.
54    Monitor,
55    /// Supervisor intercepts FS syscalls, translates paths via `VirtualFs`,
56    /// opens files at translated paths, injects fd via `SECCOMP_IOCTL_NOTIF_ADDFD`.
57    Virtualize,
58}
59
60/// Mount point configuration.
61///
62/// This is the canonical Mount type used throughout evalbox.
63#[derive(Debug, Clone)]
64pub struct Mount {
65    /// Path on the host filesystem.
66    pub source: PathBuf,
67    /// Path inside the sandbox.
68    pub target: PathBuf,
69    /// If false, mount is read-only (default).
70    pub writable: bool,
71    /// If true, executables can be run from this mount (for Landlock).
72    pub executable: bool,
73}
74
75impl Mount {
76    /// Read-only mount, same path inside/outside sandbox.
77    pub fn ro(path: impl Into<PathBuf>) -> Self {
78        let path = path.into();
79        Self {
80            source: path.clone(),
81            target: path,
82            writable: false,
83            executable: true,
84        }
85    }
86
87    /// Read-only mount without execute permission.
88    pub fn ro_noexec(path: impl Into<PathBuf>) -> Self {
89        let path = path.into();
90        Self {
91            source: path.clone(),
92            target: path,
93            writable: false,
94            executable: false,
95        }
96    }
97
98    /// Read-write mount, same path inside/outside sandbox.
99    pub fn rw(path: impl Into<PathBuf>) -> Self {
100        let path = path.into();
101        Self {
102            source: path.clone(),
103            target: path,
104            writable: true,
105            executable: true,
106        }
107    }
108
109    /// Mount with different host and sandbox paths (read-only by default).
110    pub fn bind(source: impl Into<PathBuf>, target: impl Into<PathBuf>) -> Self {
111        Self {
112            source: source.into(),
113            target: target.into(),
114            writable: false,
115            executable: true,
116        }
117    }
118
119    /// Make mount writable.
120    pub fn writable(mut self) -> Self {
121        self.writable = true;
122        self
123    }
124
125    /// Disable execute permission (for Landlock).
126    pub fn noexec(mut self) -> Self {
127        self.executable = false;
128        self
129    }
130}
131
132/// Syscall filtering configuration.
133///
134/// By default, a strict whitelist of ~40 safe syscalls is allowed.
135/// Use this to customize the allowed syscalls for specific use cases.
136///
137/// ## Example
138///
139/// ```ignore
140/// use evalbox_sandbox::Syscalls;
141///
142/// // Start with default whitelist, add specific syscalls
143/// let syscalls = Syscalls::default()
144///     .allow(libc::SYS_openat)
145///     .allow(libc::SYS_socket);
146///
147/// // Or deny specific syscalls (removes from whitelist)
148/// let syscalls = Syscalls::default()
149///     .deny(libc::SYS_clone);
150/// ```
151#[derive(Debug, Clone, Default)]
152pub struct Syscalls {
153    /// Additional syscalls to allow beyond the default whitelist.
154    pub allowed: HashSet<i64>,
155    /// Syscalls to deny (removes from whitelist).
156    pub denied: HashSet<i64>,
157}
158
159impl Syscalls {
160    /// Create a new Syscalls config (default whitelist).
161    pub fn new() -> Self {
162        Self::default()
163    }
164
165    /// Allow a specific syscall.
166    pub fn allow(mut self, syscall: i64) -> Self {
167        self.allowed.insert(syscall);
168        self.denied.remove(&syscall);
169        self
170    }
171
172    /// Deny a specific syscall (remove from whitelist).
173    pub fn deny(mut self, syscall: i64) -> Self {
174        self.denied.insert(syscall);
175        self.allowed.remove(&syscall);
176        self
177    }
178
179    /// Allow multiple syscalls.
180    pub fn allow_many(mut self, syscalls: impl IntoIterator<Item = i64>) -> Self {
181        for syscall in syscalls {
182            self.allowed.insert(syscall);
183            self.denied.remove(&syscall);
184        }
185        self
186    }
187
188    /// Deny multiple syscalls.
189    pub fn deny_many(mut self, syscalls: impl IntoIterator<Item = i64>) -> Self {
190        for syscall in syscalls {
191            self.denied.insert(syscall);
192            self.allowed.remove(&syscall);
193        }
194        self
195    }
196}
197
198/// Landlock filesystem and network access control configuration.
199///
200/// Landlock is a Linux security module (LSM) that provides fine-grained
201/// filesystem and network access control for unprivileged processes.
202///
203/// ## Example
204///
205/// ```ignore
206/// use evalbox_sandbox::Landlock;
207///
208/// let landlock = Landlock::default()
209///     .allow_read("/etc")
210///     .allow_read_write("/tmp/output")
211///     .allow_execute("/usr/bin");
212/// ```
213#[derive(Debug, Clone, Default)]
214pub struct Landlock {
215    /// Paths with read access.
216    pub read_paths: Vec<PathBuf>,
217    /// Paths with read-write access.
218    pub write_paths: Vec<PathBuf>,
219    /// Paths with execute access.
220    pub execute_paths: Vec<PathBuf>,
221}
222
223impl Landlock {
224    /// Create a new Landlock config.
225    pub fn new() -> Self {
226        Self::default()
227    }
228
229    /// Allow read access to a path.
230    pub fn allow_read(mut self, path: impl Into<PathBuf>) -> Self {
231        self.read_paths.push(path.into());
232        self
233    }
234
235    /// Allow read-write access to a path.
236    pub fn allow_read_write(mut self, path: impl Into<PathBuf>) -> Self {
237        self.write_paths.push(path.into());
238        self
239    }
240
241    /// Allow execute access to a path.
242    pub fn allow_execute(mut self, path: impl Into<PathBuf>) -> Self {
243        self.execute_paths.push(path.into());
244        self
245    }
246}
247
248/// File to write to workspace before execution.
249#[derive(Debug, Clone)]
250pub struct UserFile {
251    pub path: String,
252    pub content: Vec<u8>,
253    pub executable: bool,
254}
255
256impl UserFile {
257    pub fn new(path: impl Into<String>, content: impl Into<Vec<u8>>) -> Self {
258        Self {
259            path: path.into(),
260            content: content.into(),
261            executable: false,
262        }
263    }
264
265    pub fn executable(mut self) -> Self {
266        self.executable = true;
267        self
268    }
269}
270
271/// Complete sandbox execution plan.
272///
273/// This is the low-level API for full control over sandbox execution.
274/// Most users should use the high-level `evalbox` crate instead.
275///
276/// ## Example
277///
278/// ```ignore
279/// use evalbox_sandbox::{Plan, Mount, Executor};
280///
281/// let plan = Plan::new(["python3", "-c", "print('hello')"])
282///     .mount(Mount::ro("/usr/lib"))
283///     .timeout(Duration::from_secs(60))
284///     .memory(256 * 1024 * 1024)
285///     .network(false);
286///
287/// let output = Executor::run(plan)?;
288/// ```
289#[must_use]
290#[derive(Debug, Clone)]
291pub struct Plan {
292    pub cmd: Vec<String>,
293    /// Pre-resolved binary path. If set, sandbox uses this instead of resolving `cmd[0]`.
294    /// This allows evalbox to do binary resolution before calling sandbox.
295    pub binary_path: Option<PathBuf>,
296    pub env: HashMap<String, String>,
297    pub stdin: Option<Vec<u8>>,
298    pub cwd: String,
299    pub mounts: Vec<Mount>,
300    pub user_files: Vec<UserFile>,
301    pub workspace_size: u64,
302    pub timeout: Duration,
303    pub memory_limit: u64,
304    pub max_pids: u32,
305    pub max_output: u64,
306    pub network_blocked: bool,
307    /// Custom syscall filtering configuration.
308    pub syscalls: Option<Syscalls>,
309    /// Custom Landlock configuration.
310    pub landlock: Option<Landlock>,
311    /// Seccomp user notification mode.
312    pub notify_mode: NotifyMode,
313}
314
315impl Default for Plan {
316    fn default() -> Self {
317        Self {
318            cmd: Vec::new(),
319            binary_path: None,
320            env: default_env(),
321            stdin: None,
322            cwd: "/work".into(),
323            mounts: Vec::new(),
324            user_files: Vec::new(),
325            workspace_size: 64 * 1024 * 1024,
326            timeout: Duration::from_secs(30),
327            memory_limit: 256 * 1024 * 1024,
328            max_pids: 64,
329            max_output: 16 * 1024 * 1024,
330            network_blocked: true,
331            syscalls: None,
332            landlock: None,
333            notify_mode: NotifyMode::Disabled,
334        }
335    }
336}
337
338impl Plan {
339    pub fn new(cmd: impl IntoIterator<Item = impl Into<String>>) -> Self {
340        Self {
341            cmd: cmd.into_iter().map(Into::into).collect(),
342            ..Default::default()
343        }
344    }
345
346    pub fn env(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
347        self.env.insert(key.into(), value.into());
348        self
349    }
350
351    pub fn stdin(mut self, data: impl Into<Vec<u8>>) -> Self {
352        self.stdin = Some(data.into());
353        self
354    }
355
356    pub fn cwd(mut self, cwd: impl Into<String>) -> Self {
357        self.cwd = cwd.into();
358        self
359    }
360
361    pub fn mount(mut self, mount: Mount) -> Self {
362        self.mounts.push(mount);
363        self
364    }
365
366    /// Add multiple mounts from an iterator.
367    pub fn mounts(mut self, mounts: impl IntoIterator<Item = Mount>) -> Self {
368        self.mounts.extend(mounts);
369        self
370    }
371
372    /// Set pre-resolved binary path.
373    ///
374    /// When set, the sandbox uses this path directly instead of resolving `cmd[0]`.
375    /// This is used by evalbox to pre-resolve binaries before calling sandbox.
376    pub fn binary_path(mut self, path: impl Into<PathBuf>) -> Self {
377        self.binary_path = Some(path.into());
378        self
379    }
380
381    pub fn file(mut self, path: impl Into<String>, content: impl Into<Vec<u8>>) -> Self {
382        self.user_files.push(UserFile::new(path, content));
383        self
384    }
385
386    /// Add an executable binary to the workspace.
387    pub fn executable(mut self, path: impl Into<String>, content: impl Into<Vec<u8>>) -> Self {
388        self.user_files
389            .push(UserFile::new(path, content).executable());
390        self
391    }
392
393    pub fn timeout(mut self, timeout: Duration) -> Self {
394        self.timeout = timeout;
395        self
396    }
397
398    pub fn memory_limit(mut self, limit: u64) -> Self {
399        self.memory_limit = limit;
400        self
401    }
402
403    pub fn max_pids(mut self, max: u32) -> Self {
404        self.max_pids = max;
405        self
406    }
407
408    pub fn max_output(mut self, max: u64) -> Self {
409        self.max_output = max;
410        self
411    }
412
413    pub fn network_blocked(mut self, blocked: bool) -> Self {
414        self.network_blocked = blocked;
415        self
416    }
417
418    /// Enable or disable network access.
419    ///
420    /// This is the inverse of `network_blocked`: `network(true)` enables network,
421    /// `network(false)` blocks network (default).
422    pub fn network(mut self, enabled: bool) -> Self {
423        self.network_blocked = !enabled;
424        self
425    }
426
427    /// Set memory limit (alias for `memory_limit`).
428    pub fn memory(self, limit: u64) -> Self {
429        self.memory_limit(limit)
430    }
431
432    /// Set custom syscall filtering configuration.
433    pub fn syscalls(mut self, syscalls: Syscalls) -> Self {
434        self.syscalls = Some(syscalls);
435        self
436    }
437
438    /// Set custom Landlock configuration.
439    pub fn landlock(mut self, landlock: Landlock) -> Self {
440        self.landlock = Some(landlock);
441        self
442    }
443
444    /// Set the seccomp user notification mode.
445    ///
446    /// - `Disabled` (default): No notify filter, zero overhead.
447    /// - `Monitor`: Log intercepted syscalls for debugging.
448    /// - `Virtualize`: Full filesystem virtualization via path translation.
449    pub fn notify_mode(mut self, mode: NotifyMode) -> Self {
450        self.notify_mode = mode;
451        self
452    }
453
454    /// Execute this plan (convenience method).
455    ///
456    /// Equivalent to `Executor::run(self)`.
457    pub fn exec(self) -> Result<crate::Output, crate::ExecutorError> {
458        crate::Executor::run(self)
459    }
460}
461
462fn default_env() -> HashMap<String, String> {
463    // Default PATH covers common locations on FHS and NixOS systems.
464    let default_path = if std::path::Path::new("/nix/store").exists() {
465        "/run/current-system/sw/bin:/nix/var/nix/profiles/default/bin:/usr/local/bin:/usr/bin:/bin"
466    } else {
467        "/usr/local/bin:/usr/bin:/bin"
468    };
469
470    HashMap::from([
471        ("PATH".into(), default_path.into()),
472        ("HOME".into(), "/home".into()),
473        ("USER".into(), "sandbox".into()),
474        ("LANG".into(), "C.UTF-8".into()),
475        ("LC_ALL".into(), "C.UTF-8".into()),
476    ])
477}
478
479#[cfg(test)]
480mod tests {
481    use super::*;
482
483    #[test]
484    fn plan_new() {
485        let plan = Plan::new(["echo", "hello"]);
486        assert_eq!(plan.cmd, vec!["echo", "hello"]);
487        assert!(plan.network_blocked);
488    }
489
490    #[test]
491    fn plan_builder() {
492        let plan = Plan::new(["python", "main.py"])
493            .env("PYTHONPATH", "/work")
494            .stdin(b"input".to_vec())
495            .timeout(Duration::from_secs(10))
496            .file("main.py", b"print('hello')");
497
498        assert_eq!(plan.env.get("PYTHONPATH"), Some(&"/work".into()));
499        assert_eq!(plan.stdin, Some(b"input".to_vec()));
500        assert_eq!(plan.timeout, Duration::from_secs(10));
501        assert_eq!(plan.user_files.len(), 1);
502    }
503
504    #[test]
505    fn plan_network_methods() {
506        let plan = Plan::new(["echo"]).network(true);
507        assert!(!plan.network_blocked);
508
509        let plan = Plan::new(["echo"]).network(false);
510        assert!(plan.network_blocked);
511    }
512
513    #[test]
514    fn plan_syscalls_config() {
515        let syscalls = Syscalls::default().allow(1).allow(2).deny(3);
516
517        assert!(syscalls.allowed.contains(&1));
518        assert!(syscalls.allowed.contains(&2));
519        assert!(syscalls.denied.contains(&3));
520    }
521
522    #[test]
523    fn plan_landlock_config() {
524        let landlock = Landlock::new().allow_read("/etc").allow_read_write("/tmp");
525
526        assert_eq!(landlock.read_paths.len(), 1);
527        assert_eq!(landlock.write_paths.len(), 1);
528    }
529}
evalbox_sandbox/plan.rs

evalbox_sandbox/
plan.rs
