sandlock_core/
policy.rs

1use std::collections::HashMap;
2use std::path::PathBuf;
3use std::time::SystemTime;
4
5use serde::{Deserialize, Serialize};
6
7use crate::error::PolicyError;
8
9/// A byte size value.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
11pub struct ByteSize(pub u64);
12
13impl ByteSize {
14    pub fn bytes(n: u64) -> Self {
15        ByteSize(n)
16    }
17
18    pub fn kib(n: u64) -> Self {
19        ByteSize(n * 1024)
20    }
21
22    pub fn mib(n: u64) -> Self {
23        ByteSize(n * 1024 * 1024)
24    }
25
26    pub fn gib(n: u64) -> Self {
27        ByteSize(n * 1024 * 1024 * 1024)
28    }
29
30    pub fn parse(s: &str) -> Result<Self, PolicyError> {
31        let s = s.trim();
32        if s.is_empty() {
33            return Err(PolicyError::Invalid("empty byte size string".into()));
34        }
35
36        // Check for suffix
37        let last = s.chars().last().unwrap();
38        if last.is_ascii_alphabetic() {
39            let (num_str, suffix) = s.split_at(s.len() - 1);
40            let n: u64 = num_str
41                .trim()
42                .parse()
43                .map_err(|_| PolicyError::Invalid(format!("invalid byte size: {}", s)))?;
44            match suffix.to_ascii_uppercase().as_str() {
45                "K" => Ok(ByteSize::kib(n)),
46                "M" => Ok(ByteSize::mib(n)),
47                "G" => Ok(ByteSize::gib(n)),
48                other => Err(PolicyError::Invalid(format!("unknown byte size suffix: {}", other))),
49            }
50        } else {
51            let n: u64 = s
52                .parse()
53                .map_err(|_| PolicyError::Invalid(format!("invalid byte size: {}", s)))?;
54            Ok(ByteSize(n))
55        }
56    }
57}
58
59/// Filesystem isolation mode.
60#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
61pub enum FsIsolation {
62    #[default]
63    None,
64    OverlayFs,
65    BranchFs,
66}
67
68/// Action to take on branch exit.
69#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
70pub enum BranchAction {
71    #[default]
72    Commit,
73    Abort,
74    Keep,
75}
76
77/// Sandbox policy configuration.
78#[derive(Clone, Serialize, Deserialize)]
79pub struct Policy {
80    // Filesystem access
81    pub fs_writable: Vec<PathBuf>,
82    pub fs_readable: Vec<PathBuf>,
83    pub fs_denied: Vec<PathBuf>,
84
85    // Syscall filtering
86    pub deny_syscalls: Option<Vec<String>>,
87    pub allow_syscalls: Option<Vec<String>>,
88
89    // Network
90    pub net_allow_hosts: Vec<String>,
91    pub net_bind: Vec<u16>,
92    pub net_connect: Vec<u16>,
93    pub no_raw_sockets: bool,
94    pub no_udp: bool,
95
96    // Namespace isolation
97    pub isolate_ipc: bool,
98    pub isolate_signals: bool,
99    pub isolate_pids: bool,
100
101    // Resource limits
102    pub max_memory: Option<ByteSize>,
103    pub max_processes: u32,
104    pub max_open_files: Option<u32>,
105    pub max_cpu: Option<u8>,
106
107    // Reproducibility
108    pub random_seed: Option<u64>,
109    pub time_start: Option<SystemTime>,
110    pub no_randomize_memory: bool,
111    pub no_huge_pages: bool,
112    pub deterministic_dirs: bool,
113    pub hostname: Option<String>,
114
115    // Filesystem branch
116    pub fs_isolation: FsIsolation,
117    pub workdir: Option<PathBuf>,
118    pub cwd: Option<PathBuf>,
119    pub fs_storage: Option<PathBuf>,
120    pub max_disk: Option<ByteSize>,
121    pub on_exit: BranchAction,
122    pub on_error: BranchAction,
123
124    // Environment
125    pub chroot: Option<PathBuf>,
126    pub clean_env: bool,
127    pub env: HashMap<String, String>,
128    pub close_fds: bool,
129
130    // Devices
131    pub gpu_devices: Option<Vec<u32>>,
132
133    // CPU
134    pub cpu_cores: Option<Vec<u32>>,
135    pub num_cpus: Option<u32>,
136    pub port_remap: bool,
137
138    // Mode flags
139    pub privileged: bool,
140
141    // Dynamic policy callback
142    #[serde(skip)]
143    pub policy_fn: Option<crate::policy_fn::PolicyCallback>,
144}
145
146impl std::fmt::Debug for Policy {
147    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
148        f.debug_struct("Policy")
149            .field("fs_readable", &self.fs_readable)
150            .field("fs_writable", &self.fs_writable)
151            .field("max_memory", &self.max_memory)
152            .field("max_processes", &self.max_processes)
153            .field("policy_fn", &self.policy_fn.as_ref().map(|_| "<callback>"))
154            .finish_non_exhaustive()
155    }
156}
157
158impl Policy {
159    pub fn builder() -> PolicyBuilder {
160        PolicyBuilder::default()
161    }
162}
163
164/// Fluent builder for `Policy`.
165#[derive(Default)]
166pub struct PolicyBuilder {
167    fs_writable: Vec<PathBuf>,
168    fs_readable: Vec<PathBuf>,
169    fs_denied: Vec<PathBuf>,
170
171    deny_syscalls: Option<Vec<String>>,
172    allow_syscalls: Option<Vec<String>>,
173
174    net_allow_hosts: Vec<String>,
175    net_bind: Vec<u16>,
176    net_connect: Vec<u16>,
177    no_raw_sockets: Option<bool>,
178    no_udp: bool,
179
180    isolate_ipc: bool,
181    isolate_signals: bool,
182    isolate_pids: bool,
183
184    max_memory: Option<ByteSize>,
185    max_processes: Option<u32>,
186    max_open_files: Option<u32>,
187    max_cpu: Option<u8>,
188
189    random_seed: Option<u64>,
190    time_start: Option<SystemTime>,
191    no_randomize_memory: bool,
192    no_huge_pages: bool,
193    deterministic_dirs: bool,
194    hostname: Option<String>,
195
196    fs_isolation: Option<FsIsolation>,
197    workdir: Option<PathBuf>,
198    cwd: Option<PathBuf>,
199    fs_storage: Option<PathBuf>,
200    max_disk: Option<ByteSize>,
201    on_exit: Option<BranchAction>,
202    on_error: Option<BranchAction>,
203
204    chroot: Option<PathBuf>,
205    clean_env: bool,
206    env: HashMap<String, String>,
207    close_fds: Option<bool>,
208
209    gpu_devices: Option<Vec<u32>>,
210
211    cpu_cores: Option<Vec<u32>>,
212    num_cpus: Option<u32>,
213    port_remap: bool,
214
215    privileged: bool,
216    policy_fn: Option<crate::policy_fn::PolicyCallback>,
217}
218
219impl PolicyBuilder {
220    pub fn fs_write(mut self, path: impl Into<PathBuf>) -> Self {
221        self.fs_writable.push(path.into());
222        self
223    }
224
225    pub fn fs_read(mut self, path: impl Into<PathBuf>) -> Self {
226        self.fs_readable.push(path.into());
227        self
228    }
229
230    pub fn fs_deny(mut self, path: impl Into<PathBuf>) -> Self {
231        self.fs_denied.push(path.into());
232        self
233    }
234
235    pub fn deny_syscalls(mut self, calls: Vec<String>) -> Self {
236        self.deny_syscalls = Some(calls);
237        self
238    }
239
240    pub fn allow_syscalls(mut self, calls: Vec<String>) -> Self {
241        self.allow_syscalls = Some(calls);
242        self
243    }
244
245    pub fn net_allow_host(mut self, host: impl Into<String>) -> Self {
246        self.net_allow_hosts.push(host.into());
247        self
248    }
249
250    pub fn net_bind_port(mut self, port: u16) -> Self {
251        self.net_bind.push(port);
252        self
253    }
254
255    pub fn net_connect_port(mut self, port: u16) -> Self {
256        self.net_connect.push(port);
257        self
258    }
259
260    pub fn no_raw_sockets(mut self, v: bool) -> Self {
261        self.no_raw_sockets = Some(v);
262        self
263    }
264
265    pub fn no_udp(mut self, v: bool) -> Self {
266        self.no_udp = v;
267        self
268    }
269
270    pub fn isolate_ipc(mut self, v: bool) -> Self {
271        self.isolate_ipc = v;
272        self
273    }
274
275    pub fn isolate_signals(mut self, v: bool) -> Self {
276        self.isolate_signals = v;
277        self
278    }
279
280    pub fn isolate_pids(mut self, v: bool) -> Self {
281        self.isolate_pids = v;
282        self
283    }
284
285    pub fn max_memory(mut self, size: ByteSize) -> Self {
286        self.max_memory = Some(size);
287        self
288    }
289
290    pub fn max_processes(mut self, n: u32) -> Self {
291        self.max_processes = Some(n);
292        self
293    }
294
295    pub fn max_open_files(mut self, n: u32) -> Self {
296        self.max_open_files = Some(n);
297        self
298    }
299
300    pub fn max_cpu(mut self, pct: u8) -> Self {
301        self.max_cpu = Some(pct);
302        self
303    }
304
305    pub fn random_seed(mut self, seed: u64) -> Self {
306        self.random_seed = Some(seed);
307        self
308    }
309
310    pub fn time_start(mut self, t: SystemTime) -> Self {
311        self.time_start = Some(t);
312        self
313    }
314
315    pub fn no_randomize_memory(mut self, v: bool) -> Self {
316        self.no_randomize_memory = v;
317        self
318    }
319
320    pub fn no_huge_pages(mut self, v: bool) -> Self {
321        self.no_huge_pages = v;
322        self
323    }
324
325    pub fn deterministic_dirs(mut self, v: bool) -> Self {
326        self.deterministic_dirs = v;
327        self
328    }
329
330    pub fn hostname(mut self, name: impl Into<String>) -> Self {
331        self.hostname = Some(name.into());
332        self
333    }
334
335    pub fn fs_isolation(mut self, iso: FsIsolation) -> Self {
336        self.fs_isolation = Some(iso);
337        self
338    }
339
340    pub fn workdir(mut self, path: impl Into<PathBuf>) -> Self {
341        self.workdir = Some(path.into());
342        self
343    }
344
345    pub fn cwd(mut self, path: impl Into<PathBuf>) -> Self {
346        self.cwd = Some(path.into());
347        self
348    }
349
350    pub fn fs_storage(mut self, path: impl Into<PathBuf>) -> Self {
351        self.fs_storage = Some(path.into());
352        self
353    }
354
355    pub fn max_disk(mut self, size: ByteSize) -> Self {
356        self.max_disk = Some(size);
357        self
358    }
359
360    pub fn on_exit(mut self, action: BranchAction) -> Self {
361        self.on_exit = Some(action);
362        self
363    }
364
365    pub fn on_error(mut self, action: BranchAction) -> Self {
366        self.on_error = Some(action);
367        self
368    }
369
370    pub fn chroot(mut self, path: impl Into<PathBuf>) -> Self {
371        self.chroot = Some(path.into());
372        self
373    }
374
375    pub fn clean_env(mut self, v: bool) -> Self {
376        self.clean_env = v;
377        self
378    }
379
380    pub fn env_var(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
381        self.env.insert(key.into(), value.into());
382        self
383    }
384
385    pub fn close_fds(mut self, v: bool) -> Self {
386        self.close_fds = Some(v);
387        self
388    }
389
390    pub fn gpu_devices(mut self, devices: Vec<u32>) -> Self {
391        self.gpu_devices = Some(devices);
392        self
393    }
394
395    pub fn cpu_cores(mut self, cores: Vec<u32>) -> Self {
396        self.cpu_cores = Some(cores);
397        self
398    }
399
400    pub fn num_cpus(mut self, n: u32) -> Self {
401        self.num_cpus = Some(n);
402        self
403    }
404
405    pub fn port_remap(mut self, v: bool) -> Self {
406        self.port_remap = v;
407        self
408    }
409
410    pub fn policy_fn(
411        mut self,
412        f: impl Fn(crate::policy_fn::SyscallEvent, &mut crate::policy_fn::PolicyContext) -> crate::policy_fn::Verdict + Send + Sync + 'static,
413    ) -> Self {
414        self.policy_fn = Some(std::sync::Arc::new(f));
415        self
416    }
417
418    pub fn privileged(mut self, v: bool) -> Self {
419        self.privileged = v;
420        self
421    }
422
423    pub fn build(self) -> Result<Policy, PolicyError> {
424        // Validate: deny_syscalls and allow_syscalls are mutually exclusive
425        if self.deny_syscalls.is_some() && self.allow_syscalls.is_some() {
426            return Err(PolicyError::MutuallyExclusiveSyscalls);
427        }
428
429        // Validate: max_cpu must be 1-100
430        if let Some(cpu) = self.max_cpu {
431            if cpu == 0 || cpu > 100 {
432                return Err(PolicyError::InvalidCpuPercent(cpu));
433            }
434        }
435
436        // Validate: fs_isolation != None requires workdir
437        let fs_isolation = self.fs_isolation.unwrap_or_default();
438        if fs_isolation != FsIsolation::None && self.workdir.is_none() {
439            return Err(PolicyError::FsIsolationRequiresWorkdir);
440        }
441
442        Ok(Policy {
443            fs_writable: self.fs_writable,
444            fs_readable: self.fs_readable,
445            fs_denied: self.fs_denied,
446            deny_syscalls: self.deny_syscalls,
447            allow_syscalls: self.allow_syscalls,
448            net_allow_hosts: self.net_allow_hosts,
449            net_bind: self.net_bind,
450            net_connect: self.net_connect,
451            no_raw_sockets: self.no_raw_sockets.unwrap_or(true),
452            no_udp: self.no_udp,
453            isolate_ipc: self.isolate_ipc,
454            isolate_signals: self.isolate_signals,
455            isolate_pids: self.isolate_pids,
456            max_memory: self.max_memory,
457            max_processes: self.max_processes.unwrap_or(64),
458            max_open_files: self.max_open_files,
459            max_cpu: self.max_cpu,
460            random_seed: self.random_seed,
461            time_start: self.time_start,
462            no_randomize_memory: self.no_randomize_memory,
463            no_huge_pages: self.no_huge_pages,
464            deterministic_dirs: self.deterministic_dirs,
465            hostname: self.hostname,
466            fs_isolation,
467            workdir: self.workdir,
468            cwd: self.cwd,
469            fs_storage: self.fs_storage,
470            max_disk: self.max_disk,
471            on_exit: self.on_exit.unwrap_or_default(),
472            on_error: self.on_error.unwrap_or_default(),
473            chroot: self.chroot,
474            clean_env: self.clean_env,
475            env: self.env,
476            close_fds: self.close_fds.unwrap_or(true),
477            gpu_devices: self.gpu_devices,
478            cpu_cores: self.cpu_cores,
479            num_cpus: self.num_cpus,
480            port_remap: self.port_remap,
481            privileged: self.privileged,
482            policy_fn: self.policy_fn,
483        })
484    }
485}
sandlock_core/policy.rs

sandlock_core/
policy.rs
