1use 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
34pub const CHECK_OUTPUT_TAIL_BYTES: usize = 4096;
37
38pub const CHECK_LOG_FILE: &str = "logs/check.log";
41
42const KILLED_OUTPUT_WAIT: Duration = Duration::from_secs(10);
45
46#[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 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 #[must_use]
81 pub fn binary(&self) -> &str {
82 &self.binary
83 }
84
85 #[must_use]
87 pub fn args(&self) -> &[String] {
88 &self.args
89 }
90
91 #[must_use]
93 pub fn command(&self) -> &str {
94 &self.command
95 }
96
97 #[must_use]
99 pub fn files(&self) -> Option<&Path> {
100 self.files.as_deref()
101 }
102}
103
104#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
106#[serde(rename_all = "snake_case")]
107pub enum CheckResult {
108 Pass,
110 Fail,
112 TimedOut,
114 Error,
117}
118
119#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
121pub struct CheckOutcome {
122 pub result: CheckResult,
123 pub exit_code: Option<i32>,
125 pub duration_ms: u64,
127 pub resource_limit: Option<String>,
129 pub output_tail: String,
131 pub output_log: Option<PathBuf>,
134 pub error: Option<String>,
136 pub containment: String,
139}
140
141#[derive(Debug, Clone)]
144pub struct CheckRunner {
145 session_id: String,
146 policy: CapabilityPolicy,
147 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 sessions_dir: Option<PathBuf>,
156}
157
158impl StagedSession {
159 #[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 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 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 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
331enum Checked {
333 Exited(ShellResult),
334 TimedOut {
336 elapsed: Duration,
337 shell: Option<ShellResult>,
338 },
339 Failed(String),
340}
341
342fn 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#[derive(Debug, Clone, PartialEq, Eq)]
408pub struct TreeEntry {
409 pub relative: PathBuf,
411 pub is_dir: bool,
412 pub mode: u32,
414}
415
416pub 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
465pub 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 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}