Skip to main content

capsule_runtime/
session_check.rs

1//! One command run in a session's work folder after the session has ended, under the containment
2//! the session's own commands had: what `mur eval run` judges a case's work by.
3//!
4//! The check is not part of the session. [`StagedSession::check_runner`] captures, before launch,
5//! what the session's [`crate::sandbox::ShellEnforcement`] is built from; [`CheckRunner::run`]
6//! builds a new enforcement from it once `launch_session` has returned and every process the
7//! session started is dead. The command, its files and its output reach no trace, no provider
8//! request and no file the agent could read while it ran.
9//!
10//! The enforcement is the one `runtime::launch_session` installs: the same capability policy,
11//! declared floor, host probe and `/tmp` mapping, so the same shell allowlist, Landlock scope,
12//! seccomp filter, network namespace and resource limits. Only its scope is new: a cgroup scope,
13//! runtime directory and network namespace of its own, each ended or removed when the check
14//! returns. `$HOME` and `$TMPDIR` are the session's `home/` and `tmp/`, as for its commands.
15
16use std::{
17    path::{Path, PathBuf},
18    sync::{
19        atomic::{AtomicI32, Ordering},
20        mpsc, Arc,
21    },
22    time::{Duration, Instant},
23};
24
25use serde::{Deserialize, Serialize};
26
27use crate::{
28    sandbox::{HostProbe, ShellEnforcement},
29    shell::{ShellExecError, ShellResult},
30    types::{CapabilityPolicy, StagedSession},
31    workdir_fs::WorkdirRoot,
32};
33
34/// How much of the check's output [`CheckOutcome::output_tail`] keeps: the last bytes of stdout
35/// followed by stderr.
36pub const CHECK_OUTPUT_TAIL_BYTES: usize = 4096;
37
38/// Where the check's captured stdout then stderr are written, beneath the session's records
39/// directory.
40pub const CHECK_LOG_FILE: &str = "logs/check.log";
41
42/// How long a timed-out check's command is given, once its processes are killed, to hand back
43/// what it wrote before the outcome is reported without it.
44const KILLED_OUTPUT_WAIT: Duration = Duration::from_secs(10);
45
46/// A command to run in a session's work folder once the session has ended.
47#[derive(Debug, Clone)]
48pub struct SessionCheck {
49    command: String,
50    binary: String,
51    args: Vec<String>,
52    files: Option<PathBuf>,
53    timeout: Duration,
54}
55
56impl SessionCheck {
57    /// `command` split into a binary and its arguments the way the shell tool splits a command
58    /// line: whitespace separates words, quotes group them, a backslash escapes one character,
59    /// and nothing is expanded. `files` is a directory copied into the work folder's root before
60    /// the command runs. Refuses a command with no words and a zero `timeout`.
61    pub fn new(command: &str, files: Option<PathBuf>, timeout: Duration) -> Result<Self, String> {
62        let mut words = crate::shell::split_shell_words(command);
63        if words.is_empty() {
64            return Err("the check command is empty".to_string());
65        }
66        if timeout.is_zero() {
67            return Err("the check timeout is zero".to_string());
68        }
69        let binary = words.remove(0);
70        Ok(Self {
71            command: command.to_string(),
72            binary,
73            args: words,
74            files,
75            timeout,
76        })
77    }
78
79    /// The binary the command runs, which must be in `capabilities.shell.allow`.
80    #[must_use]
81    pub fn binary(&self) -> &str {
82        &self.binary
83    }
84
85    /// The arguments after [`Self::binary`].
86    #[must_use]
87    pub fn args(&self) -> &[String] {
88        &self.args
89    }
90
91    /// The command line as given.
92    #[must_use]
93    pub fn command(&self) -> &str {
94        &self.command
95    }
96
97    /// The directory copied into the work folder before the command runs.
98    #[must_use]
99    pub fn files(&self) -> Option<&Path> {
100        self.files.as_deref()
101    }
102}
103
104/// How a check ended.
105#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
106#[serde(rename_all = "snake_case")]
107pub enum CheckResult {
108    /// The command exited 0.
109    Pass,
110    /// The command exited non-zero, or was killed for a resource limit.
111    Fail,
112    /// The command outran the check's timeout and was killed.
113    TimedOut,
114    /// The command never ran to an exit: its files could not be copied, its enforcement could
115    /// not be built, or it could not be started.
116    Error,
117}
118
119/// What one check did.
120#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
121pub struct CheckOutcome {
122    pub result: CheckResult,
123    /// The command's exit code. `None` when it timed out or never ran.
124    pub exit_code: Option<i32>,
125    /// From the start of the command to its exit or kill; 0 when it never started.
126    pub duration_ms: u64,
127    /// The host resource limit that killed the command, as the shell tool names it.
128    pub resource_limit: Option<String>,
129    /// The last [`CHECK_OUTPUT_TAIL_BYTES`] bytes of stdout followed by stderr.
130    pub output_tail: String,
131    /// The full captured output, [`CHECK_LOG_FILE`] in the session's records directory. `None`
132    /// when the command produced no result to write.
133    pub output_log: Option<PathBuf>,
134    /// Why the result is [`CheckResult::Error`], or what went wrong around a result.
135    pub error: Option<String>,
136    /// The containment class the session's `session_start` recorded as achieved, which the check
137    /// ran under.
138    pub containment: String,
139}
140
141/// What a session's containment was built from, captured before launch, to run a
142/// [`SessionCheck`] under it after the session ends.
143#[derive(Debug, Clone)]
144pub struct CheckRunner {
145    session_id: String,
146    policy: CapabilityPolicy,
147    /// The session's own decision, so the check installs the tier the session's commands ran on.
148    containment: crate::containment::ContainmentDecision,
149    host_probe: HostProbe,
150    temp_mapping: crate::temp_dir::TempMapping,
151    accessible_root: WorkdirRoot,
152    records_root: WorkdirRoot,
153    records_dir: PathBuf,
154    /// `~/.murmur/sessions`, where the session's runtime directory was and the check's goes.
155    sessions_dir: Option<PathBuf>,
156}
157
158impl StagedSession {
159    /// What [`CheckRunner::run`] needs to run a check under this session's containment once the
160    /// session has ended. Taken before `launch_session`, which consumes the session.
161    #[must_use]
162    pub fn check_runner(&self) -> CheckRunner {
163        CheckRunner {
164            session_id: self.session_id.clone(),
165            policy: self.capability_policy.clone(),
166            containment: self.containment,
167            host_probe: self.host_probe.clone(),
168            temp_mapping: self.temp_mapping,
169            accessible_root: self.accessible_root.clone(),
170            records_root: self.records_root.clone(),
171            records_dir: self.records_dir.clone(),
172            sessions_dir: self
173                .runtime_dir
174                .parent()
175                .and_then(Path::parent)
176                .map(Path::to_path_buf),
177        }
178    }
179}
180
181impl CheckRunner {
182    /// Copies `check`'s files into the work folder and runs its command there, under the
183    /// session's containment, then kills everything it started. Every failure is an outcome.
184    ///
185    /// Call only after `launch_session` has returned: the session's processes are dead then, and
186    /// nothing the session started can see the files or the command.
187    pub fn run(&self, check: &SessionCheck) -> CheckOutcome {
188        let containment = self.containment.achieved().as_str().to_string();
189        let error = |error: String| CheckOutcome {
190            result: CheckResult::Error,
191            exit_code: None,
192            duration_ms: 0,
193            resource_limit: None,
194            output_tail: String::new(),
195            output_log: None,
196            error: Some(error),
197            containment: containment.clone(),
198        };
199
200        if let Some(files) = check.files() {
201            if let Err(refusal) = copy_tree_into(files, &self.accessible_root) {
202                return error(format!("could not copy the check's files: {refusal}"));
203            }
204        }
205
206        let checked = match self.enforcement() {
207            Ok((enforcement, runtime_dir)) => {
208                let checked =
209                    run_with_timeout(check, &self.accessible_root, &self.policy, &enforcement);
210                // Whatever the command left running is killed and its namespace ended before the
211                // runtime directory it was told of is removed.
212                enforcement.end_session();
213                drop(runtime_dir);
214                checked
215            }
216            Err(reason) => return error(reason),
217        };
218
219        let (result, exit_code, duration_ms, shell) = match checked {
220            Checked::Exited(shell) => {
221                let result = if shell.exit_code == 0 {
222                    CheckResult::Pass
223                } else {
224                    CheckResult::Fail
225                };
226                (
227                    result,
228                    Some(shell.exit_code),
229                    shell.duration_ms,
230                    Some(shell),
231                )
232            }
233            Checked::TimedOut { elapsed, shell } => (
234                CheckResult::TimedOut,
235                None,
236                elapsed.as_millis().try_into().unwrap_or(u64::MAX),
237                shell,
238            ),
239            Checked::Failed(reason) => return error(reason),
240        };
241
242        let (stdout, stderr) = shell
243            .as_ref()
244            .map(|shell| (shell.stdout.as_str(), shell.stderr.as_str()))
245            .unwrap_or_default();
246        let mut output = Vec::with_capacity(stdout.len() + stderr.len());
247        output.extend_from_slice(stdout.as_bytes());
248        output.extend_from_slice(stderr.as_bytes());
249        let (output_log, log_error) = match self.records_root.write_file_exact_mode(
250            CHECK_LOG_FILE,
251            &output,
252            crate::murmur_home::PRIVATE_FILE_MODE,
253        ) {
254            Ok(()) => (Some(self.records_dir.join(CHECK_LOG_FILE)), None),
255            Err(error) => (
256                None,
257                Some(format!("could not write {CHECK_LOG_FILE}: {error}")),
258            ),
259        };
260        let tail_start = output.len().saturating_sub(CHECK_OUTPUT_TAIL_BYTES);
261
262        CheckOutcome {
263            result,
264            exit_code,
265            duration_ms,
266            resource_limit: shell
267                .as_ref()
268                .and_then(|shell| shell.resource_limit_hit.clone()),
269            output_tail: String::from_utf8_lossy(&output[tail_start..]).into_owned(),
270            output_log,
271            error: log_error,
272            containment,
273        }
274    }
275
276    /// The enforcement `launch_session` builds for a session's commands, rebuilt from what the
277    /// session's was built from, with a cgroup scope, workdir guard and runtime directory of its
278    /// own. The runtime directory is removed when the returned value drops.
279    fn enforcement(&self) -> Result<(ShellEnforcement, crate::runtime_dir::RuntimeDir), String> {
280        let check_id = format!("{}-check", self.session_id);
281        let prepared = crate::runtime::prepare_launch_scope(
282            &self.policy,
283            &check_id,
284            self.accessible_root.path(),
285        )
286        .map_err(|error| error.to_string())?;
287        let temp = self
288            .records_root
289            .open_beneath(crate::temp_dir::SESSION_TEMP_DIR_NAME)
290            .map_err(|error| error.to_string())?;
291        let home = self
292            .records_root
293            .open_beneath(crate::records_dir::HOME_SUBDIR)
294            .map_err(|error| error.to_string())?;
295        let workdir_guard =
296            crate::resources::workdir_guard_max_bytes(&self.policy).map(|max_bytes| {
297                crate::resources::WorkdirGuard::spawn(
298                    &self.accessible_root,
299                    temp.as_ref(),
300                    home.as_ref(),
301                    Some(&self.records_root),
302                    max_bytes,
303                )
304            });
305        let sessions_dir = match &self.sessions_dir {
306            Some(dir) => dir.clone(),
307            None => crate::runtime_dir::sessions_dir().map_err(|error| error.to_string())?,
308        };
309        let runtime_dir =
310            crate::runtime_dir::RuntimeDir::create(&sessions_dir, &check_id, &self.accessible_root)
311                .map_err(|reason| format!("the check's runtime directory: {reason}"))?;
312        let mut roots = runtime_dir
313            .roots()
314            .clone()
315            .with_records(self.records_root.clone());
316        if let Some(temp) = temp {
317            roots = roots.with_temp(temp);
318        }
319        if let Some(home) = home {
320            roots = roots.with_home(home);
321        }
322        let enforcement =
323            ShellEnforcement::resolve(&self.policy, &self.containment, self.host_probe.clone())?
324                .with_host_bounding(prepared.scope, workdir_guard)
325                .with_runtime_dir(roots, None)
326                .with_temp_mapping(self.temp_mapping);
327        Ok((enforcement, runtime_dir))
328    }
329}
330
331/// How the check's command ended, before it is judged.
332enum Checked {
333    Exited(ShellResult),
334    /// Killed at the timeout. `shell` is what it had written, when it handed that back in time.
335    TimedOut {
336        elapsed: Duration,
337        shell: Option<ShellResult>,
338    },
339    Failed(String),
340}
341
342/// Runs the command on a thread of its own and waits at most `check.timeout` for it. At the
343/// timeout every process in the check's cgroup scope is killed, and its process group with them,
344/// which is the only kill where there is no scope.
345fn run_with_timeout(
346    check: &SessionCheck,
347    workdir: &WorkdirRoot,
348    policy: &CapabilityPolicy,
349    enforcement: &ShellEnforcement,
350) -> Checked {
351    let (sender, receiver) = mpsc::channel::<Result<ShellResult, ShellExecError>>();
352    let group = Arc::new(AtomicI32::new(0));
353    let started = Instant::now();
354    {
355        let binary = check.binary.clone();
356        let args = check.args.clone();
357        let workdir = workdir.clone();
358        let policy = policy.clone();
359        let enforcement = enforcement.clone();
360        let group = Arc::clone(&group);
361        let spawned = std::thread::Builder::new()
362            .name("session-check".to_string())
363            .spawn(move || {
364                crate::shell::report_spawned_group_to(group);
365                let args = args.iter().map(String::as_str).collect::<Vec<_>>();
366                let result = crate::shell::execute_shell(
367                    &binary,
368                    &args,
369                    &[],
370                    &workdir,
371                    &policy,
372                    &enforcement,
373                );
374                let _ = sender.send(result);
375            });
376        if let Err(error) = spawned {
377            return Checked::Failed(format!("could not start the check: {error}"));
378        }
379    }
380
381    let settled = |result: Result<ShellResult, ShellExecError>| match result {
382        Ok(shell) => Checked::Exited(shell),
383        Err(error) => Checked::Failed(error.to_string()),
384    };
385    match receiver.recv_timeout(check.timeout) {
386        Ok(result) => settled(result),
387        Err(mpsc::RecvTimeoutError::Disconnected) => {
388            Checked::Failed("the check's thread ended without a result".to_string())
389        }
390        Err(mpsc::RecvTimeoutError::Timeout) => {
391            let elapsed = started.elapsed();
392            enforcement.kill_session_processes();
393            let pgid = group.load(Ordering::SeqCst);
394            if pgid > 0 {
395                crate::formation_launch::signal_group(i64::from(pgid), libc::SIGKILL);
396            }
397            let shell = match receiver.recv_timeout(KILLED_OUTPUT_WAIT) {
398                Ok(Ok(shell)) => Some(shell),
399                _ => None,
400            };
401            Checked::TimedOut { elapsed, shell }
402        }
403    }
404}
405
406/// One entry beneath an operator's directory tree: an eval case's `start` or `check.files`.
407#[derive(Debug, Clone, PartialEq, Eq)]
408pub struct TreeEntry {
409    /// Relative to the tree's root.
410    pub relative: PathBuf,
411    pub is_dir: bool,
412    /// `mode & 0o7777`.
413    pub mode: u32,
414}
415
416/// Every entry beneath `root`, in byte-wise order of the relative path, so a parent comes before
417/// what it holds. Read with no link followed: a symbolic link or a special file anywhere in the
418/// tree is refused, naming it.
419pub fn walk_tree(root: &Path) -> Result<Vec<TreeEntry>, String> {
420    use std::os::unix::{ffi::OsStrExt as _, fs::PermissionsExt as _};
421
422    fn walk(dir: &Path, relative: &Path, out: &mut Vec<TreeEntry>) -> Result<(), String> {
423        let read = |path: &Path, error: std::io::Error| format!("{}: {error}", path.display());
424        for entry in std::fs::read_dir(dir).map_err(|error| read(dir, error))? {
425            let entry = entry.map_err(|error| read(dir, error))?;
426            let path = entry.path();
427            let rel = relative.join(entry.file_name());
428            let meta = std::fs::symlink_metadata(&path).map_err(|error| read(&path, error))?;
429            let mode = meta.permissions().mode() & 0o7777;
430            let file_type = meta.file_type();
431            if file_type.is_symlink() {
432                return Err(format!("{} is a symbolic link", path.display()));
433            }
434            if file_type.is_dir() {
435                out.push(TreeEntry {
436                    relative: rel.clone(),
437                    is_dir: true,
438                    mode,
439                });
440                walk(&path, &rel, out)?;
441            } else if file_type.is_file() {
442                out.push(TreeEntry {
443                    relative: rel,
444                    is_dir: false,
445                    mode,
446                });
447            } else {
448                return Err(format!("{} is a special file", path.display()));
449            }
450        }
451        Ok(())
452    }
453
454    let mut entries = Vec::new();
455    walk(root, Path::new(""), &mut entries)?;
456    entries.sort_by(|a, b| {
457        a.relative
458            .as_os_str()
459            .as_bytes()
460            .cmp(b.relative.as_os_str().as_bytes())
461    });
462    Ok(entries)
463}
464
465/// Copies the tree at `source` into `workdir`'s root: directories and regular files, each
466/// entry's permission bits kept, an existing file overwritten.
467///
468/// The whole of `source` is walked by [`walk_tree`] before anything is written, so a link or
469/// special file in it refuses the copy with the work folder untouched. Every write goes through
470/// `workdir`, so nothing already in the work folder — a link where a directory of the tree goes,
471/// notably — is followed; such a refusal names the path. Each directory is held at owner `rwx`
472/// while it is filled and given its own mode last, deepest first, so a read-only directory is
473/// filled before it is closed.
474pub fn copy_tree_into(source: &Path, workdir: &WorkdirRoot) -> Result<(), String> {
475    const FILLING_DIR_MODE: u32 = 0o700;
476
477    let entries = walk_tree(source)?;
478    for entry in &entries {
479        let rel = entry.relative.to_string_lossy();
480        if entry.is_dir {
481            workdir
482                .create_dir_all(rel.as_ref(), FILLING_DIR_MODE)
483                .and_then(|()| workdir.set_dir_mode(rel.as_ref(), FILLING_DIR_MODE))
484                .map_err(|error| error.to_string())?;
485        } else {
486            let path = source.join(&entry.relative);
487            let bytes =
488                std::fs::read(&path).map_err(|error| format!("{}: {error}", path.display()))?;
489            workdir
490                .write_file_exact_mode(rel.as_ref(), &bytes, entry.mode)
491                .map_err(|error| error.to_string())?;
492        }
493    }
494    for entry in entries.iter().rev().filter(|entry| entry.is_dir) {
495        let rel = entry.relative.to_string_lossy();
496        workdir
497            .set_dir_mode(rel.as_ref(), entry.mode)
498            .map_err(|error| error.to_string())?;
499    }
500    Ok(())
501}
502
503#[cfg(test)]
504mod tests {
505    use super::*;
506
507    #[test]
508    fn a_command_splits_as_the_shell_tool_splits_it() {
509        let command = r#"grep -q "fixed value" 'a b'/c\ d.txt"#;
510        let check = SessionCheck::new(command, None, Duration::from_secs(1)).unwrap();
511        let mut words = crate::shell::split_shell_words(command);
512        assert_eq!(check.binary(), words.remove(0));
513        assert_eq!(check.args(), words.as_slice());
514        assert_eq!(check.binary(), "grep");
515        assert_eq!(check.args(), ["-q", "fixed value", "a b/c d.txt"]);
516        assert_eq!(check.command(), command);
517    }
518
519    #[test]
520    fn an_empty_command_is_refused() {
521        for command in ["", "   ", "\t\n"] {
522            let refused = SessionCheck::new(command, None, Duration::from_secs(1)).unwrap_err();
523            assert!(refused.contains("empty"), "{refused}");
524        }
525    }
526
527    #[test]
528    fn a_zero_timeout_is_refused() {
529        let refused = SessionCheck::new("true", None, Duration::ZERO).unwrap_err();
530        assert!(refused.contains("timeout"), "{refused}");
531    }
532
533    #[test]
534    fn outcomes_serialize_in_snake_case() {
535        let outcome = CheckOutcome {
536            result: CheckResult::TimedOut,
537            exit_code: None,
538            duration_ms: 2000,
539            resource_limit: None,
540            output_tail: String::new(),
541            output_log: None,
542            error: None,
543            containment: "scoped".to_string(),
544        };
545        let json = serde_json::to_value(&outcome).unwrap();
546        assert_eq!(json["result"], "timed_out");
547        assert_eq!(json["containment"], "scoped");
548        let back: CheckOutcome = serde_json::from_value(json).unwrap();
549        assert_eq!(back, outcome);
550    }
551
552    #[test]
553    fn check_files_with_a_link_are_refused_before_anything_is_written() {
554        let source = tempfile::tempdir().unwrap();
555        std::fs::write(source.path().join("a.txt"), "a").unwrap();
556        std::os::unix::fs::symlink("/etc/passwd", source.path().join("z-link")).unwrap();
557        let workdir = tempfile::tempdir().unwrap();
558        let root = WorkdirRoot::open(workdir.path()).unwrap();
559        let refused = copy_tree_into(source.path(), &root).unwrap_err();
560        assert!(refused.contains("z-link"), "{refused}");
561        assert!(!workdir.path().join("a.txt").exists());
562    }
563
564    #[test]
565    fn check_files_keep_their_mode_and_overwrite_what_is_there() {
566        use std::os::unix::fs::PermissionsExt as _;
567        let source = tempfile::tempdir().unwrap();
568        std::fs::create_dir(source.path().join("sub")).unwrap();
569        std::fs::write(source.path().join("sub/run.sh"), "new").unwrap();
570        std::fs::set_permissions(
571            source.path().join("sub/run.sh"),
572            std::fs::Permissions::from_mode(0o751),
573        )
574        .unwrap();
575        let workdir = tempfile::tempdir().unwrap();
576        std::fs::create_dir(workdir.path().join("sub")).unwrap();
577        std::fs::write(workdir.path().join("sub/run.sh"), "old").unwrap();
578        let root = WorkdirRoot::open(workdir.path()).unwrap();
579        copy_tree_into(source.path(), &root).unwrap();
580        let copied = workdir.path().join("sub/run.sh");
581        assert_eq!(std::fs::read_to_string(&copied).unwrap(), "new");
582        assert_eq!(
583            std::fs::metadata(&copied).unwrap().permissions().mode() & 0o7777,
584            0o751
585        );
586    }
587
588    #[test]
589    fn a_read_only_directory_in_check_files_is_filled_then_closed() {
590        use std::os::unix::fs::PermissionsExt as _;
591        let source = tempfile::tempdir().unwrap();
592        std::fs::create_dir(source.path().join("ro")).unwrap();
593        std::fs::write(source.path().join("ro/t.txt"), "t").unwrap();
594        std::fs::set_permissions(
595            source.path().join("ro"),
596            std::fs::Permissions::from_mode(0o555),
597        )
598        .unwrap();
599        let workdir = tempfile::tempdir().unwrap();
600        let root = WorkdirRoot::open(workdir.path()).unwrap();
601        copy_tree_into(source.path(), &root).unwrap();
602        let copied = workdir.path().join("ro");
603        assert_eq!(std::fs::read_to_string(copied.join("t.txt")).unwrap(), "t");
604        assert_eq!(
605            std::fs::metadata(&copied).unwrap().permissions().mode() & 0o7777,
606            0o555
607        );
608        // Copied again over the read-only directory now in the work folder, as a second check
609        // into the same folder would.
610        copy_tree_into(source.path(), &root).unwrap();
611        for dir in [source.path().join("ro"), copied] {
612            std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o755)).unwrap();
613        }
614    }
615
616    #[test]
617    fn a_link_the_agent_left_is_not_followed() {
618        let source = tempfile::tempdir().unwrap();
619        std::fs::create_dir(source.path().join("hidden")).unwrap();
620        std::fs::write(source.path().join("hidden/check.txt"), "x").unwrap();
621        let outside = tempfile::tempdir().unwrap();
622        let workdir = tempfile::tempdir().unwrap();
623        std::os::unix::fs::symlink(outside.path(), workdir.path().join("hidden")).unwrap();
624        let root = WorkdirRoot::open(workdir.path()).unwrap();
625        let refused = copy_tree_into(source.path(), &root).unwrap_err();
626        assert!(refused.contains("hidden"), "{refused}");
627        assert!(std::fs::read_dir(outside.path()).unwrap().next().is_none());
628    }
629}