secure_exec_kernel/
permissions.rs

1use crate::vfs::{
2    validate_path, VfsError, VfsResult, VirtualDirEntry, VirtualFileSystem, VirtualStat,
3    VirtualUtimeSpec,
4};
5use std::collections::{BTreeMap, HashMap};
6use std::error::Error;
7use std::fmt;
8use std::path::Path;
9use std::sync::Arc;
10
11pub type FsPermissionCheck = Arc<dyn Fn(&FsAccessRequest) -> PermissionDecision + Send + Sync>;
12pub type NetworkPermissionCheck =
13    Arc<dyn Fn(&NetworkAccessRequest) -> PermissionDecision + Send + Sync>;
14pub type CommandPermissionCheck =
15    Arc<dyn Fn(&CommandAccessRequest) -> PermissionDecision + Send + Sync>;
16pub type EnvironmentPermissionCheck =
17    Arc<dyn Fn(&EnvAccessRequest) -> PermissionDecision + Send + Sync>;
18
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub struct PermissionDecision {
21    pub allow: bool,
22    pub reason: Option<String>,
23}
24
25impl PermissionDecision {
26    pub fn allow() -> Self {
27        Self {
28            allow: true,
29            reason: None,
30        }
31    }
32
33    pub fn deny(reason: impl Into<String>) -> Self {
34        Self {
35            allow: false,
36            reason: Some(reason.into()),
37        }
38    }
39}
40
41#[derive(Debug, Clone, PartialEq, Eq)]
42pub struct PermissionError {
43    code: &'static str,
44    message: String,
45}
46
47impl PermissionError {
48    pub fn code(&self) -> &'static str {
49        self.code
50    }
51
52    fn access_denied(subject: impl Into<String>, reason: Option<&str>) -> Self {
53        let subject = subject.into();
54        let message = match reason {
55            Some(reason) => format!("permission denied, {subject}: {reason}"),
56            None => format!("permission denied, {subject}"),
57        };
58
59        Self {
60            code: "EACCES",
61            message,
62        }
63    }
64}
65
66impl fmt::Display for PermissionError {
67    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
68        write!(f, "{}: {}", self.code, self.message)
69    }
70}
71
72impl Error for PermissionError {}
73
74#[derive(Debug, Clone, Copy, PartialEq, Eq)]
75pub enum FsOperation {
76    Read,
77    Write,
78    Mkdir,
79    CreateDir,
80    ReadDir,
81    Stat,
82    Remove,
83    Rename,
84    Exists,
85    Symlink,
86    ReadLink,
87    Link,
88    Chmod,
89    Chown,
90    Utimes,
91    Truncate,
92    MountSensitive,
93}
94
95impl FsOperation {
96    fn as_str(self) -> &'static str {
97        match self {
98            Self::Read => "read",
99            Self::Write => "write",
100            Self::Mkdir => "mkdir",
101            Self::CreateDir => "createDir",
102            Self::ReadDir => "readdir",
103            Self::Stat => "stat",
104            Self::Remove => "rm",
105            Self::Rename => "rename",
106            Self::Exists => "exists",
107            Self::Symlink => "symlink",
108            Self::ReadLink => "readlink",
109            Self::Link => "link",
110            Self::Chmod => "chmod",
111            Self::Chown => "chown",
112            Self::Utimes => "utimes",
113            Self::Truncate => "truncate",
114            Self::MountSensitive => "mount",
115        }
116    }
117}
118
119#[derive(Debug, Clone, PartialEq, Eq)]
120pub struct FsAccessRequest {
121    pub vm_id: String,
122    pub op: FsOperation,
123    pub path: String,
124}
125
126#[derive(Debug, Clone, Copy, PartialEq, Eq)]
127pub enum NetworkOperation {
128    Fetch,
129    Http,
130    Dns,
131    Listen,
132}
133
134#[derive(Debug, Clone, PartialEq, Eq)]
135pub struct NetworkAccessRequest {
136    pub vm_id: String,
137    pub op: NetworkOperation,
138    pub resource: String,
139}
140
141#[derive(Debug, Clone, PartialEq, Eq)]
142pub struct CommandAccessRequest {
143    pub vm_id: String,
144    pub command: String,
145    pub args: Vec<String>,
146    pub cwd: Option<String>,
147    pub env: BTreeMap<String, String>,
148}
149
150#[derive(Debug, Clone, Copy, PartialEq, Eq)]
151pub enum EnvironmentOperation {
152    Read,
153    Write,
154}
155
156#[derive(Debug, Clone, PartialEq, Eq)]
157pub struct EnvAccessRequest {
158    pub vm_id: String,
159    pub op: EnvironmentOperation,
160    pub key: String,
161    pub value: Option<String>,
162}
163
164#[derive(Clone, Default)]
165pub struct Permissions {
166    pub filesystem: Option<FsPermissionCheck>,
167    pub network: Option<NetworkPermissionCheck>,
168    pub child_process: Option<CommandPermissionCheck>,
169    pub environment: Option<EnvironmentPermissionCheck>,
170}
171
172impl Permissions {
173    pub fn allow_all() -> Self {
174        Self {
175            filesystem: Some(Arc::new(|_: &FsAccessRequest| PermissionDecision::allow())),
176            network: Some(Arc::new(|_: &NetworkAccessRequest| {
177                PermissionDecision::allow()
178            })),
179            child_process: Some(Arc::new(|_: &CommandAccessRequest| {
180                PermissionDecision::allow()
181            })),
182            environment: Some(Arc::new(|_: &EnvAccessRequest| PermissionDecision::allow())),
183        }
184    }
185}
186
187pub fn permission_glob_matches(pattern: &str, value: &str) -> bool {
188    fn matches(
189        pattern: &[u8],
190        value: &[u8],
191        pattern_index: usize,
192        value_index: usize,
193        memo: &mut HashMap<(usize, usize), bool>,
194    ) -> bool {
195        if let Some(result) = memo.get(&(pattern_index, value_index)) {
196            return *result;
197        }
198
199        let result = if pattern_index == pattern.len() {
200            value_index == value.len()
201        } else {
202            match pattern[pattern_index] {
203                b'?' => {
204                    value_index < value.len()
205                        && value[value_index] != b'/'
206                        && matches(pattern, value, pattern_index + 1, value_index + 1, memo)
207                }
208                b'*' => {
209                    let mut next_pattern_index = pattern_index;
210                    while next_pattern_index < pattern.len() && pattern[next_pattern_index] == b'*'
211                    {
212                        next_pattern_index += 1;
213                    }
214
215                    if matches(pattern, value, next_pattern_index, value_index, memo) {
216                        true
217                    } else {
218                        let crosses_separators = next_pattern_index - pattern_index > 1;
219                        let mut next_value_index = value_index;
220                        while next_value_index < value.len()
221                            && (crosses_separators || value[next_value_index] != b'/')
222                        {
223                            next_value_index += 1;
224                            if matches(pattern, value, next_pattern_index, next_value_index, memo) {
225                                return true;
226                            }
227                        }
228                        false
229                    }
230                }
231                expected => {
232                    value_index < value.len()
233                        && expected == value[value_index]
234                        && matches(pattern, value, pattern_index + 1, value_index + 1, memo)
235                }
236            }
237        };
238
239        memo.insert((pattern_index, value_index), result);
240        result
241    }
242
243    matches(
244        pattern.as_bytes(),
245        value.as_bytes(),
246        0,
247        0,
248        &mut HashMap::new(),
249    )
250}
251
252pub fn filter_env(
253    vm_id: &str,
254    env: &BTreeMap<String, String>,
255    permissions: &Permissions,
256) -> BTreeMap<String, String> {
257    let Some(check) = permissions.environment.as_ref() else {
258        return BTreeMap::new();
259    };
260
261    env.iter()
262        .filter_map(|(key, value)| {
263            let request = EnvAccessRequest {
264                vm_id: vm_id.to_owned(),
265                op: EnvironmentOperation::Read,
266                key: key.clone(),
267                value: Some(value.clone()),
268            };
269            let decision = check(&request);
270            decision.allow.then(|| (key.clone(), value.clone()))
271        })
272        .collect()
273}
274
275pub fn check_command_execution(
276    vm_id: &str,
277    permissions: &Permissions,
278    command: &str,
279    args: &[String],
280    cwd: Option<&str>,
281    env: &BTreeMap<String, String>,
282) -> Result<(), PermissionError> {
283    let Some(check) = permissions.child_process.as_ref() else {
284        return Err(PermissionError::access_denied(
285            format!("spawn '{command}'"),
286            None,
287        ));
288    };
289
290    let request = CommandAccessRequest {
291        vm_id: vm_id.to_owned(),
292        command: command.to_owned(),
293        args: args.to_vec(),
294        cwd: cwd.map(ToOwned::to_owned),
295        env: env.clone(),
296    };
297    let decision = check(&request);
298    if decision.allow {
299        Ok(())
300    } else {
301        Err(PermissionError::access_denied(
302            format!("spawn '{command}'"),
303            decision.reason.as_deref(),
304        ))
305    }
306}
307
308pub fn check_network_access(
309    vm_id: &str,
310    permissions: &Permissions,
311    op: NetworkOperation,
312    resource: &str,
313) -> Result<(), PermissionError> {
314    let Some(check) = permissions.network.as_ref() else {
315        return Err(PermissionError::access_denied(resource, None));
316    };
317
318    let request = NetworkAccessRequest {
319        vm_id: vm_id.to_owned(),
320        op,
321        resource: resource.to_owned(),
322    };
323    let decision = check(&request);
324    if decision.allow {
325        Ok(())
326    } else {
327        Err(PermissionError::access_denied(
328            resource,
329            decision.reason.as_deref(),
330        ))
331    }
332}
333
334#[derive(Clone)]
335pub struct PermissionedFileSystem<F> {
336    inner: F,
337    vm_id: String,
338    permissions: Permissions,
339}
340
341impl<F> PermissionedFileSystem<F> {
342    pub fn new(inner: F, vm_id: impl Into<String>, permissions: Permissions) -> Self {
343        Self {
344            inner,
345            vm_id: vm_id.into(),
346            permissions,
347        }
348    }
349
350    pub fn into_inner(self) -> F {
351        self.inner
352    }
353
354    pub fn inner(&self) -> &F {
355        &self.inner
356    }
357
358    pub fn inner_mut(&mut self) -> &mut F {
359        &mut self.inner
360    }
361
362    fn check(&self, op: FsOperation, path: &str) -> VfsResult<()> {
363        validate_path(path)?;
364        // Standard emulated character devices (/dev/null, /dev/zero, /dev/urandom,
365        // /dev/std{in,out,err}) are world-accessible on Linux and have no host
366        // backing; the device layer enforces their fixed semantics. Exempt them from
367        // the VM file-permission policy so guest fs ops on them (readFileSync /
368        // existsSync / redirects) behave like native Linux regardless of policy.
369        if crate::device_layer::is_standard_device_path(path) {
370            return Ok(());
371        }
372        let Some(check) = self.permissions.filesystem.as_ref() else {
373            return Err(VfsError::access_denied(op.as_str(), path, None));
374        };
375
376        let request = FsAccessRequest {
377            vm_id: self.vm_id.clone(),
378            op,
379            path: path.to_owned(),
380        };
381        let decision = check(&request);
382        if decision.allow {
383            Ok(())
384        } else {
385            Err(VfsError::access_denied(
386                op.as_str(),
387                path,
388                decision.reason.as_deref(),
389            ))
390        }
391    }
392}
393
394impl<F: VirtualFileSystem> PermissionedFileSystem<F> {
395    fn resolved_existing_path(&self, path: &str) -> VfsResult<String> {
396        self.inner.realpath(path)
397    }
398
399    fn resolved_destination_path(&self, path: &str) -> VfsResult<String> {
400        let normalized = crate::vfs::normalize_path(path);
401        if normalized == "/" {
402            return Ok(normalized);
403        }
404
405        let parent = Path::new(&normalized)
406            .parent()
407            .unwrap_or_else(|| Path::new("/"))
408            .to_string_lossy()
409            .into_owned();
410        let basename = Path::new(&normalized)
411            .file_name()
412            .map(|value| value.to_string_lossy().into_owned())
413            .unwrap_or_default();
414
415        let mut candidate = parent;
416        let mut unresolved_segments = Vec::new();
417
418        let resolved_parent = loop {
419            match self.inner.realpath(&candidate) {
420                Ok(resolved) => break resolved,
421                Err(error) if matches!(error.code(), "ENOENT" | "ENOTDIR") => {
422                    if candidate == "/" {
423                        break String::from("/");
424                    }
425                    let candidate_path = Path::new(&candidate);
426                    if let Some(segment) = candidate_path.file_name() {
427                        unresolved_segments.push(segment.to_string_lossy().into_owned());
428                    }
429                    candidate = candidate_path
430                        .parent()
431                        .unwrap_or_else(|| Path::new("/"))
432                        .to_string_lossy()
433                        .into_owned();
434                }
435                Err(error) => return Err(error),
436            }
437        };
438
439        let mut resolved = resolved_parent;
440        for segment in unresolved_segments.iter().rev() {
441            if resolved == "/" {
442                resolved = format!("/{segment}");
443            } else {
444                resolved = format!("{resolved}/{segment}");
445            }
446        }
447
448        if resolved == "/" {
449            Ok(format!("/{basename}"))
450        } else {
451            Ok(format!("{resolved}/{basename}"))
452        }
453    }
454
455    fn permission_subject(&self, op: FsOperation, path: &str) -> VfsResult<String> {
456        validate_path(path)?;
457        match op {
458            FsOperation::Read
459            | FsOperation::ReadDir
460            | FsOperation::Stat
461            | FsOperation::ReadLink
462            | FsOperation::Chmod
463            | FsOperation::Chown
464            | FsOperation::Utimes
465            | FsOperation::Truncate => self.resolved_existing_path(path),
466            FsOperation::Exists | FsOperation::Write => self
467                .resolved_existing_path(path)
468                .or_else(|_| self.resolved_destination_path(path)),
469            FsOperation::Mkdir
470            | FsOperation::CreateDir
471            | FsOperation::Rename
472            | FsOperation::Symlink
473            | FsOperation::Link
474            | FsOperation::MountSensitive
475            | FsOperation::Remove => self.resolved_destination_path(path),
476        }
477    }
478
479    fn check_subject(&self, op: FsOperation, path: &str) -> VfsResult<()> {
480        let subject = self.permission_subject(op, path)?;
481        self.check(op, &subject)
482    }
483
484    fn check_existing_subject(&self, op: FsOperation, path: &str) -> VfsResult<()> {
485        validate_path(path)?;
486        let subject = self.resolved_existing_path(path)?;
487        self.check(op, &subject)
488    }
489
490    fn check_destination_subject(&self, op: FsOperation, path: &str) -> VfsResult<()> {
491        validate_path(path)?;
492        let subject = self.resolved_destination_path(path)?;
493        self.check(op, &subject)
494    }
495
496    pub fn check_path(&self, op: FsOperation, path: &str) -> VfsResult<()> {
497        self.check_subject(op, path)
498    }
499
500    pub fn check_virtual_path(&self, op: FsOperation, path: &str) -> VfsResult<()> {
501        self.check(op, path)
502    }
503
504    pub fn exists(&self, path: &str) -> VfsResult<bool> {
505        if let Err(error) = self.check_subject(FsOperation::Exists, path) {
506            if matches!(error.code(), "EACCES" | "ENOENT" | "ENOTDIR" | "ELOOP") {
507                return Ok(false);
508            }
509            return Err(error);
510        }
511        Ok(self.inner.exists(path))
512    }
513}
514
515impl<F: VirtualFileSystem> VirtualFileSystem for PermissionedFileSystem<F> {
516    fn read_file(&mut self, path: &str) -> VfsResult<Vec<u8>> {
517        self.check_subject(FsOperation::Read, path)?;
518        self.inner.read_file(path)
519    }
520
521    fn read_dir(&mut self, path: &str) -> VfsResult<Vec<String>> {
522        self.check_subject(FsOperation::ReadDir, path)?;
523        self.inner.read_dir(path)
524    }
525
526    fn read_dir_limited(&mut self, path: &str, max_entries: usize) -> VfsResult<Vec<String>> {
527        self.check_subject(FsOperation::ReadDir, path)?;
528        self.inner.read_dir_limited(path, max_entries)
529    }
530
531    fn read_dir_with_types(&mut self, path: &str) -> VfsResult<Vec<VirtualDirEntry>> {
532        self.check_subject(FsOperation::ReadDir, path)?;
533        self.inner.read_dir_with_types(path)
534    }
535
536    fn write_file(&mut self, path: &str, content: impl Into<Vec<u8>>) -> VfsResult<()> {
537        self.check_subject(FsOperation::Write, path)?;
538        self.inner.write_file(path, content)
539    }
540
541    fn create_file_exclusive(&mut self, path: &str, content: impl Into<Vec<u8>>) -> VfsResult<()> {
542        self.check_subject(FsOperation::Write, path)?;
543        self.inner.create_file_exclusive(path, content)
544    }
545
546    fn append_file(&mut self, path: &str, content: impl Into<Vec<u8>>) -> VfsResult<u64> {
547        self.check_subject(FsOperation::Write, path)?;
548        self.inner.append_file(path, content)
549    }
550
551    fn create_dir(&mut self, path: &str) -> VfsResult<()> {
552        self.check_subject(FsOperation::CreateDir, path)?;
553        self.inner.create_dir(path)
554    }
555
556    fn mkdir(&mut self, path: &str, recursive: bool) -> VfsResult<()> {
557        self.check_subject(FsOperation::Mkdir, path)?;
558        self.inner.mkdir(path, recursive)
559    }
560
561    fn exists(&self, path: &str) -> bool {
562        PermissionedFileSystem::exists(self, path).unwrap_or(false)
563    }
564
565    fn stat(&mut self, path: &str) -> VfsResult<VirtualStat> {
566        self.check_subject(FsOperation::Stat, path)?;
567        self.inner.stat(path)
568    }
569
570    fn remove_file(&mut self, path: &str) -> VfsResult<()> {
571        self.check_subject(FsOperation::Remove, path)?;
572        self.inner.remove_file(path)
573    }
574
575    fn remove_dir(&mut self, path: &str) -> VfsResult<()> {
576        self.check_subject(FsOperation::Remove, path)?;
577        self.inner.remove_dir(path)
578    }
579
580    fn rename(&mut self, old_path: &str, new_path: &str) -> VfsResult<()> {
581        self.check_subject(FsOperation::Rename, old_path)?;
582        self.check_subject(FsOperation::Rename, new_path)?;
583        self.inner.rename(old_path, new_path)
584    }
585
586    fn realpath(&self, path: &str) -> VfsResult<String> {
587        self.check_subject(FsOperation::Read, path)?;
588        self.inner.realpath(path)
589    }
590
591    fn symlink(&mut self, target: &str, link_path: &str) -> VfsResult<()> {
592        self.check_subject(FsOperation::Symlink, link_path)?;
593        self.inner.symlink(target, link_path)
594    }
595
596    fn read_link(&self, path: &str) -> VfsResult<String> {
597        // Authorize the parent-symlink-resolved path (without following the
598        // final component, matching `lstat`/`readlink` semantics). A lexical
599        // check would let a symlink whose parent resolves into a denied prefix
600        // disclose link targets of permission-denied paths.
601        validate_path(path)?;
602        let subject = self.resolved_destination_path(path)?;
603        self.check(FsOperation::ReadLink, &subject)?;
604        self.inner.read_link(path)
605    }
606
607    fn lstat(&self, path: &str) -> VfsResult<VirtualStat> {
608        // Authorize the parent-symlink-resolved path (see `read_link`); a
609        // lexical check would leak metadata (size/mode/mtime/inode) of files
610        // under a permission-denied prefix reached via a symlinked parent.
611        validate_path(path)?;
612        let subject = self.resolved_destination_path(path)?;
613        self.check(FsOperation::Stat, &subject)?;
614        self.inner.lstat(path)
615    }
616
617    fn link(&mut self, old_path: &str, new_path: &str) -> VfsResult<()> {
618        self.check_existing_subject(FsOperation::Link, old_path)?;
619        self.check_destination_subject(FsOperation::Link, new_path)?;
620        self.inner.link(old_path, new_path)
621    }
622
623    fn chmod(&mut self, path: &str, mode: u32) -> VfsResult<()> {
624        self.check_subject(FsOperation::Chmod, path)?;
625        self.inner.chmod(path, mode)
626    }
627
628    fn chown(&mut self, path: &str, uid: u32, gid: u32) -> VfsResult<()> {
629        self.check_subject(FsOperation::Chown, path)?;
630        self.inner.chown(path, uid, gid)
631    }
632
633    fn utimes(&mut self, path: &str, atime_ms: u64, mtime_ms: u64) -> VfsResult<()> {
634        self.check_subject(FsOperation::Utimes, path)?;
635        self.inner.utimes(path, atime_ms, mtime_ms)
636    }
637
638    fn utimes_spec(
639        &mut self,
640        path: &str,
641        atime: VirtualUtimeSpec,
642        mtime: VirtualUtimeSpec,
643        follow_symlinks: bool,
644    ) -> VfsResult<()> {
645        self.check_subject(FsOperation::Utimes, path)?;
646        self.inner.utimes_spec(path, atime, mtime, follow_symlinks)
647    }
648
649    fn truncate(&mut self, path: &str, length: u64) -> VfsResult<()> {
650        self.check_subject(FsOperation::Truncate, path)?;
651        self.inner.truncate(path, length)
652    }
653
654    fn pread(&mut self, path: &str, offset: u64, length: usize) -> VfsResult<Vec<u8>> {
655        self.check_subject(FsOperation::Read, path)?;
656        self.inner.pread(path, offset, length)
657    }
658}
secure_exec_kernel/permissions.rs

secure_exec_kernel/
permissions.rs
