1#![doc = include_str!("../README.md")]
11#![deny(clippy::all)]
12#![allow(clippy::uninlined_format_args)]
13
14#[cfg(feature = "liteinst")]
18reverie_liteinst::declare_legacy_tool_backing!();
19
20mod backend_stats;
21pub mod build_info;
22pub mod canonical_verdict;
23mod chroot;
24use hermit_record_format::consts;
25pub mod logdiff_report;
26pub mod cpu_profile_admission;
28pub mod e9patch;
29mod error;
30use hermit_record_format::event;
31use hermit_record_format::event_stream;
32pub mod happens_before;
33pub mod host_input_change;
34mod id;
35#[cfg(feature = "liteinst")]
36pub mod in_guest_exits;
37pub mod instruction_map;
38#[cfg(feature = "liteinst")]
39use hermit_record_format::interp;
40pub mod liteinst_bootstrap;
41mod liteinst_constructor;
42pub mod liteinst_record;
43mod metadata;
44pub mod xstate_probe;
45pub use detcore::nonwaiting_write;
48pub mod physical_exit_watch;
49pub mod preemption_admission;
50pub mod proc_mount;
51mod ptrace_completion;
52
53pub use canonical_verdict::Verdict;
54
55pub const RECORD_REPLAY_HASHES_IO_BUFFERS: bool = true;
68
69pub const RECORD_REPLAY_VIRTUALIZES_TIME: bool = false;
84
85pub const HERMIT_VERIFICATION_DIVERGENCE_EXIT: i32 = 1;
91
92pub const HERMIT_INTERNAL_FAILURE_EXIT: i32 = 125;
146
147pub const HERMIT_DEADLINE_EXIT: i32 = 124;
164
165pub const HERMIT_LOG_CAP_EXIT: i32 = 123;
179
180pub const GUEST_PROGRAM_NOT_FOUND_EXIT: i32 = 127;
193
194pub const GUEST_PROGRAM_NOT_EXECUTABLE_EXIT: i32 = 126;
200
201const _: () = assert!(
338 HERMIT_VERIFICATION_DIVERGENCE_EXIT == 1,
339 "1 is the established diff-style result for a completed comparison that diverged"
340);
341const _: () = assert!(
342 HERMIT_INTERNAL_FAILURE_EXIT == 125,
343 "125 is the GNU wrapper-failed convention; 1 is the commonest guest status and 0 is success"
344);
345const _: () = assert!(
346 GUEST_PROGRAM_NOT_FOUND_EXIT == 127,
347 "127 is the GNU command-not-found convention and must stay distinct from 125 and 126"
348);
349const _: () = assert!(
350 GUEST_PROGRAM_NOT_EXECUTABLE_EXIT == 126,
351 "126 is the GNU found-but-not-executable convention and must stay distinct from 125 and 127"
352);
353const _: () = assert!(
354 HERMIT_LOG_CAP_EXIT == 123,
355 "123 is Hermit's log-cap code, reserved for bin/safehermit's log-cap kill as well; see the allocation table"
356);
357const _: () = assert!(
358 HERMIT_LOG_CAP_EXIT != 0
359 && HERMIT_VERIFICATION_DIVERGENCE_EXIT != 0
360 && HERMIT_INTERNAL_FAILURE_EXIT != 0
361 && GUEST_PROGRAM_NOT_FOUND_EXIT != 0
362 && GUEST_PROGRAM_NOT_EXECUTABLE_EXIT != 0,
363 "a failure code of 0 would invert every assert_eq!(code, Some(CONST)) into demanding success"
364);
365mod record;
366use hermit_record_format::record_replay_path;
367mod replay;
368#[cfg(feature = "sabre")]
369mod sabre_bootstrap;
370#[cfg(feature = "sabre")]
371mod sabre_ptrace;
372use hermit_record_format::script;
373mod tracer_thread;
374
375#[cfg(feature = "sabre")]
376use std::ffi::OsStr;
377use std::fs;
378use std::io;
379use std::io::Seek;
380use std::io::SeekFrom;
381use std::io::Write;
382#[cfg(feature = "dbt")]
383use std::os::fd::AsFd;
384use std::os::fd::AsRawFd;
385use std::os::fd::FromRawFd;
386#[cfg(any(feature = "sabre", all(test, feature = "liteinst")))]
387use std::os::unix::ffi::OsStrExt;
388#[cfg(feature = "sabre")]
389use std::os::unix::fs::OpenOptionsExt;
390#[cfg(any(feature = "sabre", feature = "liteinst"))]
391use std::os::unix::fs::PermissionsExt;
392use std::path::Path;
393use std::path::PathBuf;
394#[cfg(feature = "sabre")]
395use std::sync::Arc;
396use std::sync::Mutex;
397#[cfg(feature = "sabre")]
398use std::sync::atomic::AtomicBool;
399use std::time::Duration;
400use std::time::Instant;
401
402use anyhow::anyhow;
403use clap::ValueEnum;
404pub use consts::LAST;
405pub use consts::LAST_RUN;
406use consts::MANIFEST_NAME as RUN_MANIFEST_NAME;
407pub use consts::MANIFEST_NAME;
408use consts::METADATA_NAME;
409pub use consts::METADATA_NAME as RECORDING_METADATA_NAME;
410pub use detcore::Config as DetConfig;
411pub use detcore::Detcore;
412pub use detcore::RecordOrReplay;
413#[doc(hidden)]
414#[cfg(feature = "dbt")]
415pub use detcore_dbt::reverie_dbt_runtime_background_init_v2;
416#[doc(hidden)]
417#[cfg(feature = "dbt")]
418pub use detcore_dbt::reverie_dbt_runtime_background_init_v3;
419#[doc(hidden)]
420#[cfg(feature = "dbt")]
421pub use detcore_dbt::reverie_dbt_runtime_name;
422#[doc(hidden)]
423#[cfg(feature = "dbt")]
424pub use detcore_dbt::reverie_dbt_runtime_pre_syscall;
425#[doc(hidden)]
426#[cfg(feature = "dbt")]
427pub use detcore_dbt::reverie_dbt_runtime_ready;
428#[doc(hidden)]
429#[cfg(feature = "dbt")]
430pub use detcore_dbt::reverie_dbt_runtime_thread_exit;
431#[doc(hidden)]
432#[cfg(feature = "dbt")]
433pub use detcore_dbt::reverie_dbt_runtime_thread_init;
434#[doc(hidden)]
435#[cfg(feature = "dbt")]
436pub use detcore_dbt::reverie_dbt_runtime_totals;
437use detcore_model::bundled_signal_facts;
438pub use error::Context;
439pub use error::Error;
440pub use error::FailureKind;
441pub use error::SerializableError;
442use goblin::elf::Elf;
443use goblin::elf::header;
444use goblin::elf::section_header;
445pub use id::Id;
446use metadata::Metadata;
447pub use ptrace_completion::HermitCleanupStage;
448pub use ptrace_completion::HermitCleanupUnconfirmed;
449pub use ptrace_completion::HermitPtraceFailure;
450pub use ptrace_completion::RecoveryRefusal;
451use record::Record;
452use replay::Replay;
453pub use reverie::ExitStatus;
454#[cfg(feature = "sabre")]
455use reverie::GlobalTool;
456pub use reverie::process;
457pub use reverie::process::Command;
458pub use reverie::process::Mount;
459pub use reverie::process::Namespace;
460pub use reverie::process::Output;
461pub use reverie::process::Stdio;
462pub use script::Shebang;
463use serde::Deserialize;
464use serde::Serialize;
465pub use tracer_thread::launch_on_calling_thread;
466
467enum KvmStdinReservation {
468 Open(fs::File),
469 Closed,
470}
471
472static KVM_STDIN_RESERVATION: Mutex<Option<KvmStdinReservation>> = Mutex::new(None);
473
474pub fn reserve_kvm_stdin(stdin: Option<fs::File>) -> io::Result<()> {
476 let mut reservation = KVM_STDIN_RESERVATION
477 .lock()
478 .map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
479 if reservation.is_some() {
480 return Err(io::Error::new(
481 io::ErrorKind::AlreadyExists,
482 "KVM stdin is already reserved",
483 ));
484 }
485 *reservation = Some(match stdin {
486 Some(file) => KvmStdinReservation::Open(file),
487 None => KvmStdinReservation::Closed,
488 });
489 Ok(())
490}
491
492fn duplicate_current_stdin() -> io::Result<Option<fs::File>> {
493 let duplicate = unsafe { libc::fcntl(libc::STDIN_FILENO, libc::F_DUPFD_CLOEXEC, 3) };
495 if duplicate >= 0 {
496 return Ok(Some(unsafe { fs::File::from_raw_fd(duplicate) }));
498 }
499 let error = io::Error::last_os_error();
500 if error.raw_os_error() == Some(libc::EBADF) {
501 Ok(None)
502 } else {
503 Err(error)
504 }
505}
506
507fn ensure_kvm_stdin_reserved() -> io::Result<()> {
508 let mut reservation = KVM_STDIN_RESERVATION
509 .lock()
510 .map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
511 if reservation.is_none() {
512 *reservation = Some(match duplicate_current_stdin()? {
513 Some(file) => KvmStdinReservation::Open(file),
514 None => KvmStdinReservation::Closed,
515 });
516 }
517 Ok(())
518}
519
520fn reserved_kvm_stdin() -> Result<Option<fs::File>, Error> {
521 ensure_kvm_stdin_reserved()?;
522 let reservation = KVM_STDIN_RESERVATION
523 .lock()
524 .map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
525 match reservation.as_ref() {
526 Some(KvmStdinReservation::Open(file)) => Ok(Some(file.try_clone()?)),
527 Some(KvmStdinReservation::Closed) => Ok(None),
528 None => unreachable!("stdin reservation was initialized above"),
529 }
530}
531
532enum StdinSnapshot {
544 Seekable(fs::File),
545 None,
546}
547
548static OUTPUT_STDIN_SNAPSHOT: Mutex<Option<StdinSnapshot>> = Mutex::new(None);
549
550pub fn reserve_output_stdin_snapshot(stdin: Option<fs::File>) -> io::Result<()> {
560 let snapshot = match stdin {
561 None => StdinSnapshot::None,
562 Some(mut file) => {
563 let is_tty = unsafe { libc::isatty(file.as_raw_fd()) } == 1;
565 if is_tty {
566 StdinSnapshot::None
567 } else {
568 let replay = if file.stream_position().is_ok() {
569 file
572 } else {
573 const BUFFERING_NOTE: &str = "hermit: --verify is buffering stdin from a non-seekable stream so both \
596 runs receive identical input. If this appears to hang, stdin has not \
597 reached end-of-file; pass `< /dev/null` when the guest needs no input.";
598 if nonwaiting_write::diagnostics_must_not_wait() {
599 nonwaiting_write::write_without_waiting(
602 libc::STDERR_FILENO,
603 format!("{BUFFERING_NOTE}\n").as_bytes(),
604 );
605 } else {
606 eprintln!("{BUFFERING_NOTE}");
607 }
608 let mut buffered = tempfile::tempfile()?;
609 io::copy(&mut file, &mut buffered)?;
610 buffered.seek(SeekFrom::Start(0))?;
611 buffered
612 };
613
614 let replay_path = format!("/proc/self/fd/{}", replay.as_raw_fd());
618 StdinSnapshot::Seekable(fs::File::open(replay_path)?)
619 }
620 }
621 };
622 let mut reservation = OUTPUT_STDIN_SNAPSHOT
623 .lock()
624 .map_err(|_| io::Error::other("output stdin snapshot lock is poisoned"))?;
625 if reservation.is_some() {
626 return Err(io::Error::new(
627 io::ErrorKind::AlreadyExists,
628 "output stdin snapshot is already reserved",
629 ));
630 }
631 *reservation = Some(snapshot);
632 Ok(())
633}
634
635fn output_backend_stdin_reservation() -> Result<(bool, Option<fs::File>), Error> {
644 let mut reservation = OUTPUT_STDIN_SNAPSHOT
645 .lock()
646 .map_err(|_| io::Error::other("output stdin snapshot lock is poisoned"))?;
647 match reservation.as_mut() {
648 Some(StdinSnapshot::Seekable(file)) => {
649 file.seek(SeekFrom::Start(0))?;
650 Ok((true, Some(file.try_clone()?)))
651 }
652 Some(StdinSnapshot::None) => Ok((true, None)),
653 None => Ok((false, None)),
654 }
655}
656
657fn output_backend_stdin_file() -> Result<Option<fs::File>, Error> {
658 Ok(output_backend_stdin_reservation()?.1)
659}
660
661pub fn output_backend_stdin() -> Result<Stdio, Error> {
669 match output_backend_stdin_file()? {
670 Some(file) => Ok(Stdio::from(file)),
671 None => Ok(Stdio::null()),
672 }
673}
674
675#[derive(Debug, Serialize, Deserialize)]
677pub struct Recording {
678 pub id: Id,
680
681 pub exit_status: ExitStatus,
683}
684
685#[derive(Clone, Copy, Debug, PartialEq, Eq)]
686enum CapabilityProbe {
687 Namespaces,
688 Ptrace,
689 Seccomp,
690}
691
692fn run_capability_probe(probe: CapabilityProbe) -> Result<bool, Error> {
693 let pid = unsafe { libc::fork() };
695 if pid == -1 {
696 return Err(std::io::Error::last_os_error()).context("Failed to fork capability probe");
697 }
698 if pid == 0 {
699 let supported = match probe {
700 CapabilityProbe::Namespaces => unsafe {
701 libc::unshare(libc::CLONE_NEWUSER | libc::CLONE_NEWPID) == 0
702 },
703 CapabilityProbe::Ptrace => {
704 unsafe {
706 libc::ptrace(
707 libc::PTRACE_TRACEME,
708 0,
709 std::ptr::null_mut::<libc::c_void>(),
710 std::ptr::null_mut::<libc::c_void>(),
711 ) != -1
712 }
713 }
714 CapabilityProbe::Seccomp => {
715 let mut filter = libc::sock_filter {
716 code: 0x06, jt: 0,
718 jf: 0,
719 k: 0x7fff0000, };
721 let program = libc::sock_fprog {
722 len: 1,
723 filter: &mut filter,
724 };
725 unsafe {
727 libc::prctl(libc::PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) == 0
728 && libc::syscall(
729 libc::SYS_seccomp,
730 1, 0,
732 &program,
733 ) == 0
734 }
735 }
736 };
737 unsafe { libc::_exit(i32::from(!supported)) }
739 }
740
741 let mut status = 0;
742 loop {
743 let result = unsafe { libc::waitpid(pid, &mut status, 0) };
745 if result == pid {
746 return Ok(libc::WIFEXITED(status) && libc::WEXITSTATUS(status) == 0);
747 }
748 if result == -1 {
749 let error = std::io::Error::last_os_error();
750 if error.kind() == std::io::ErrorKind::Interrupted {
751 continue;
752 }
753 return Err(error).context("Failed to wait for capability probe");
754 }
755 }
756}
757
758#[derive(Clone, Copy, Debug, PartialEq, Eq)]
763pub enum NamespaceUse {
764 Creates,
766 None,
768}
769
770fn validate_tracing_environment(namespaces: NamespaceUse) -> Result<(), Error> {
771 check_tracing_environment(namespaces, run_capability_probe)
772}
773
774fn check_tracing_environment(
778 namespaces: NamespaceUse,
779 mut probe: impl FnMut(CapabilityProbe) -> Result<bool, Error>,
780) -> Result<(), Error> {
781 if namespaces == NamespaceUse::Creates && !probe(CapabilityProbe::Namespaces)? {
782 anyhow::bail!(
783 "Hermit cannot create its required user and PID namespaces: \
784 unshare(CLONE_NEWUSER | CLONE_NEWPID) was denied. Allow unprivileged user namespaces \
785 and the unshare syscall in the host/container policy."
786 );
787 }
788 if !probe(CapabilityProbe::Ptrace)? {
789 anyhow::bail!(
790 "Hermit cannot use ptrace in this environment: a child PTRACE_TRACEME probe was \
791 denied. Allow same-UID parent-child ptrace in the container seccomp and host \
792 Yama/LSM policy; CAP_SYS_PTRACE is normally not required. Use --namespace-only for \
793 a sandbox smoke test without ptrace (it intercepts only kill, through a seccomp \
794 filter)."
795 );
796 }
797 if !probe(CapabilityProbe::Seccomp)? {
798 anyhow::bail!(
799 "Hermit cannot install its tracee seccomp filter: \
800 seccomp(SECCOMP_SET_MODE_FILTER) was denied. Allow seccomp and \
801 prctl(PR_SET_NO_NEW_PRIVS) in the container policy. --namespace-only also \
802 installs a seccomp filter (on kill), so it cannot run here either."
803 );
804 }
805 Ok(())
806}
807
808#[cfg(feature = "dbt")]
809fn is_dynamorio_sdk(path: &Path) -> bool {
810 path.join("include/dr_api.h").is_file()
811 || path.join("DynamoRIOConfig.cmake").is_file()
812 || path.join("cmake/DynamoRIOConfig.cmake").is_file()
813}
814
815#[cfg(feature = "dbt")]
816fn dynamorio_sdk_available() -> bool {
817 if hermit_resources::resource("dynamorio/bin64/drrun")
818 .is_ok_and(|path| path.is_some_and(|path| path.is_file()))
819 {
820 return true;
821 }
822 if reverie_dbt::bundled_drrun_path().is_file() {
823 return true;
824 }
825 const DEFAULT_ROOTS: [&str; 3] = [
826 "/usr/lib/cmake/DynamoRIO",
827 "/usr/local/lib/cmake/DynamoRIO",
828 "/opt/dynamorio",
829 ];
830
831 ["DYNAMORIO_HOME", "DynamoRIO_DIR"]
832 .into_iter()
833 .filter_map(std::env::var_os)
834 .map(PathBuf::from)
835 .chain(DEFAULT_ROOTS.into_iter().map(PathBuf::from))
836 .any(|path| is_dynamorio_sdk(&path))
837}
838
839#[cfg(feature = "dbt")]
840fn dbt_runtime_unavailable_reason() -> Option<String> {
841 dbt_runtime_unavailable_reason_from(detcore_dbt::runtime_library_path())
842}
843
844#[cfg(feature = "dbt")]
845fn dbt_runtime_unavailable_reason_from(runtime: io::Result<PathBuf>) -> Option<String> {
846 runtime.err().map(|error| {
847 format!(
848 "the Detcore DBT runtime is unavailable: {error}; build the hermit binary and \
849 cdylib in the same target directory"
850 )
851 })
852}
853
854fn validate_preload_constructor_library(
863 path: &Path,
864 label: &str,
865 required: &[&str],
866 initializer_name: &str,
867) -> io::Result<PathBuf> {
868 let bytes = fs::read(path).map_err(|error| {
869 io::Error::new(
870 error.kind(),
871 format!("failed to read {label} {}: {error}", path.display()),
872 )
873 })?;
874 let elf = Elf::parse(&bytes).map_err(|error| {
875 io::Error::new(
876 io::ErrorKind::InvalidData,
877 format!("{label} {} is not an ELF DSO: {error}", path.display()),
878 )
879 })?;
880 if elf.header.e_type != header::ET_DYN || elf.header.e_machine != header::EM_X86_64 {
881 return Err(io::Error::new(
882 io::ErrorKind::InvalidData,
883 format!("{label} {} is not an x86-64 shared object", path.display()),
884 ));
885 }
886
887 for &name in required {
888 if !elf
889 .dynsyms
890 .iter()
891 .any(|symbol| elf.dynstrtab.get_at(symbol.st_name) == Some(name))
892 {
893 return Err(io::Error::new(
894 io::ErrorKind::InvalidData,
895 format!(
896 "{label} {} is missing required export {name}",
897 path.display()
898 ),
899 ));
900 }
901 }
902 if initializer_name == liteinst_constructor::ROOT {
903 liteinst_constructor::validate(&bytes, &elf).map_err(|error| {
904 io::Error::new(
905 error.kind(),
906 format!(
907 "{label} {} has invalid Detcore constructor binding: {error}",
908 path.display()
909 ),
910 )
911 })?;
912 return path.canonicalize();
913 }
914 let (initializer_index, initializer) = elf
915 .dynsyms
916 .iter()
917 .enumerate()
918 .find(|(_, symbol)| elf.dynstrtab.get_at(symbol.st_name) == Some(initializer_name))
919 .ok_or_else(|| {
920 io::Error::other(format!(
921 "checked {label} initializer {initializer_name} disappeared"
922 ))
923 })?;
924 let init_array = elf
925 .section_headers
926 .iter()
927 .find(|section| section.sh_type == section_header::SHT_INIT_ARRAY)
928 .ok_or_else(|| {
929 io::Error::new(
930 io::ErrorKind::InvalidData,
931 format!("{label} {} has no constructor array", path.display()),
932 )
933 })?;
934 let init_start = init_array.sh_addr;
935 let init_end = init_start.saturating_add(init_array.sh_size);
936 let relocated_initializer = elf
937 .dynrelas
938 .iter()
939 .chain(elf.dynrels.iter())
940 .any(|relocation| {
941 (init_start..init_end).contains(&relocation.r_offset)
942 && relocation.r_sym == initializer_index
943 });
944 let init_bytes = usize::try_from(init_array.sh_offset)
945 .ok()
946 .and_then(|start| {
947 usize::try_from(init_array.sh_size)
948 .ok()
949 .and_then(|size| bytes.get(start..start.checked_add(size)?))
950 })
951 .unwrap_or_default();
952 let direct_initializer = init_bytes
953 .as_chunks::<8>()
954 .0
955 .iter()
956 .any(|entry| u64::from_le_bytes(*entry) == initializer.st_value);
957 if !relocated_initializer && !direct_initializer {
958 return Err(io::Error::new(
959 io::ErrorKind::InvalidData,
960 format!(
961 "{label} {} does not register {initializer_name} as a preload constructor",
962 path.display()
963 ),
964 ));
965 }
966 path.canonicalize()
967}
968
969pub const LITEINST_TOOL_RUNTIME_ENV: &str = "HERMIT_LITEINST_TOOL_RUNTIME";
972
973#[doc(hidden)]
988pub fn liteinst_tool_runtime_library_path() -> io::Result<PathBuf> {
989 if let Some(path) = std::env::var_os(LITEINST_TOOL_RUNTIME_ENV) {
990 let path = PathBuf::from(path);
991 if !path.is_file() {
992 return Err(io::Error::new(
993 io::ErrorKind::NotFound,
994 format!("{LITEINST_TOOL_RUNTIME_ENV} does not name a regular file"),
995 ));
996 }
997 return validate_liteinst_tool_runtime_library(&path).map_err(|error| {
998 io::Error::new(
999 error.kind(),
1000 format!("{LITEINST_TOOL_RUNTIME_ENV} is invalid: {error}"),
1001 )
1002 });
1003 }
1004
1005 if let Some(path) = hermit_resources::resource("libdetcore_liteinst.so")? {
1006 if !path.is_file() {
1007 return Err(io::Error::new(
1008 io::ErrorKind::NotFound,
1009 "selected Hermit installation has no finalized in-guest Detcore runtime; \
1010 run `make install-deps` to build and stage the qualified LiteInst runtime",
1011 ));
1012 }
1013 return validate_liteinst_tool_runtime_library(&path);
1014 }
1015
1016 let executable = std::env::current_exe()?;
1017 let directory = executable.parent().ok_or_else(|| {
1018 io::Error::new(
1019 io::ErrorKind::NotFound,
1020 "Hermit executable has no parent directory",
1021 )
1022 })?;
1023 if let Some(path) = [
1024 directory.join("libdetcore_liteinst.so"),
1025 directory.join("deps/libdetcore_liteinst.so"),
1026 ]
1027 .into_iter()
1028 .find(|path| path.is_file())
1029 {
1030 return validate_liteinst_tool_runtime_library(&path);
1031 }
1032 Err(io::Error::new(
1033 io::ErrorKind::NotFound,
1034 format!(
1035 "libdetcore_liteinst.so was not built beside {} or staged as an installed resource",
1036 executable.display()
1037 ),
1038 ))
1039}
1040
1041fn validate_liteinst_tool_runtime_library(path: &Path) -> io::Result<PathBuf> {
1042 validate_preload_constructor_library(
1043 path,
1044 "in-guest Detcore runtime",
1045 &["detcore_liteinst_initialize"],
1046 "detcore_liteinst_initialize",
1047 )
1048}
1049
1050#[derive(Debug, Clone, PartialEq, Eq)]
1058pub struct LiteinstInGuestRefusal {
1059 backend: Backend,
1060 reason: String,
1061}
1062
1063impl LiteinstInGuestRefusal {
1064 pub fn new(reason: impl Into<String>) -> Self {
1066 Self::for_backend(Backend::Liteinst, reason)
1067 }
1068
1069 pub fn for_backend(backend: Backend, reason: impl Into<String>) -> Self {
1073 debug_assert!(backend.is_in_guest_liteinst(), "{backend:?}");
1074 Self {
1075 backend,
1076 reason: reason.into(),
1077 }
1078 }
1079}
1080
1081impl std::fmt::Display for LiteinstInGuestRefusal {
1082 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1083 let runtime = match self.backend {
1084 Backend::InGuestTrap => "in-guest LiteInst, site patching off",
1085 _ => "in-guest LiteInst",
1086 };
1087 write!(
1088 f,
1089 "--backend={} ({runtime}) refuses this run: {}",
1090 self.backend.as_str(),
1091 self.reason
1092 )
1093 }
1094}
1095
1096impl std::error::Error for LiteinstInGuestRefusal {}
1097
1098#[cfg(feature = "liteinst")]
1120fn refuse_in_guest_liteinst_run(
1121 command: &mut Command,
1122 config: &DetConfig,
1123 backend: Backend,
1124) -> Result<(), Error> {
1125 let reason = if let Some(conflict) = in_guest_trap_site_patching_conflict(command, backend) {
1126 Some(conflict)
1127 } else if config.max_timeslice.is_some() {
1128 Some(
1129 "it cannot deliver Detcore's preemption timer yet (the in-guest Tool host refuses \
1130 set_timer with ENOSYS), so the run would fail at its first timeslice; pass \
1131 --max-timeslice=disabled"
1132 .to_owned(),
1133 )
1134 } else if let Some(gap) = in_guest_liteinst_kernel_gap(&running_kernel_release()) {
1135 Some(gap)
1136 } else {
1137 in_guest_liteinst_program_gap(command)?
1138 };
1139 match reason {
1140 Some(reason) => Err(Error::new(LiteinstInGuestRefusal::for_backend(
1141 backend, reason,
1142 ))),
1143 None => {
1144 force_in_guest_site_patching(command, backend);
1145 Ok(())
1146 }
1147 }
1148}
1149
1150pub fn forced_site_patching_value(backend: Backend) -> Option<&'static str> {
1156 match backend {
1157 Backend::InGuestTrap => Some("0"),
1158 _ => None,
1159 }
1160}
1161
1162#[cfg(feature = "liteinst")]
1171fn in_guest_trap_site_patching_conflict(command: &Command, backend: Backend) -> Option<String> {
1172 let forced = forced_site_patching_value(backend)?;
1173 let name = reverie_liteinst::SITE_PATCHING_ENV;
1174 let value = command.get_env(name)?;
1175 (*value != *std::ffi::OsStr::new(forced)).then(|| {
1176 format!(
1177 "the guest environment sets {name}={}, but --backend={} runs with syscall site \
1178 patching off and sets {name}={forced} itself; drop the variable, or select \
1179 --backend=liteinst to patch syscall sites",
1180 value.to_string_lossy(),
1181 backend.as_str()
1182 )
1183 })
1184}
1185
1186#[cfg(feature = "liteinst")]
1193fn force_in_guest_site_patching(command: &mut Command, backend: Backend) {
1194 if let Some(value) = forced_site_patching_value(backend) {
1195 command.env(reverie_liteinst::SITE_PATCHING_ENV, value);
1196 }
1197}
1198
1199#[cfg(feature = "liteinst")]
1203fn in_guest_site_patching_off(backend: Backend) -> bool {
1204 forced_site_patching_value(backend) == Some("0")
1205}
1206
1207#[cfg(feature = "liteinst")]
1212fn in_guest_stats_request(
1213 backend: Backend,
1214 summary_json: &Option<PathBuf>,
1215) -> reverie::BackendStatsRequest {
1216 if backend == Backend::InGuestTrap {
1217 reverie::BackendStatsRequest::ENABLED
1218 } else {
1219 backend_stats::request(summary_json)
1220 }
1221}
1222
1223#[cfg(feature = "liteinst")]
1231fn refuse_in_guest_policy(backend: Backend, refusal: Option<String>) -> Result<(), Error> {
1232 match refusal {
1233 Some(reason) => Err(Error::new(LiteinstInGuestRefusal::for_backend(
1234 backend,
1235 format!("{reason}; --backend=ptrace runs this program"),
1236 ))),
1237 None => Ok(()),
1238 }
1239}
1240
1241#[cfg(feature = "liteinst")]
1260fn in_guest_trap_patching_evidence(
1261 backend: Backend,
1262 dispatch: Option<&reverie::DispatchStats>,
1263 process_reports: u64,
1264) -> Option<String> {
1265 if backend != Backend::InGuestTrap {
1266 return None;
1267 }
1268 let Some(record) = dispatch else {
1269 return Some(
1270 "the run produced no LiteInst dispatch record, so it cannot show that no syscall \
1271 site was patched"
1272 .to_owned(),
1273 );
1274 };
1275 if process_reports == 0 {
1276 return Some(
1277 "no guest process reported LiteInst statistics, so the run's zero patched sites \
1278 are not a measurement and it cannot show that no syscall site was patched"
1279 .to_owned(),
1280 );
1281 }
1282 let shown =
1283 |count: Option<u64>| count.map_or_else(|| "unmeasured".to_owned(), |n| n.to_string());
1284 (record.sites.patched != Some(0) || record.sites.candidates != Some(0)).then(|| {
1285 format!(
1286 "its guests' LiteInst statistics report {} patched and {} candidate syscall sites, \
1287 so it did not run with syscall site patching off and its result is not an \
1288 in-guest-trap result",
1289 shown(record.sites.patched),
1290 shown(record.sites.candidates)
1291 )
1292 })
1293}
1294
1295#[cfg(feature = "liteinst")]
1300fn refuse_in_guest_trap_patching(backend: Backend, evidence: Option<String>) -> Result<(), Error> {
1301 match evidence {
1302 Some(reason) => {
1303 detcore::detlog::record_determinism_loss(&reason);
1304 Err(Error::new(LiteinstInGuestRefusal::for_backend(
1305 backend, reason,
1306 )))
1307 }
1308 None => Ok(()),
1309 }
1310}
1311
1312#[cfg(feature = "native-exec")]
1315#[doc(hidden)]
1316pub fn in_guest_detlog_forward_policy_for_native() -> detcore::detlog::ForwardPolicy {
1317 in_guest_detlog_forward_policy()
1318}
1319
1320#[cfg(feature = "liteinst")]
1324#[doc(hidden)]
1325pub fn native_trap_dispatch_stats(
1326 source: &reverie_liteinst::LiteinstBackendStatsSource,
1327) -> Result<Option<reverie::DispatchStats>, Error> {
1328 let backend = Backend::InGuestTrap;
1329 let record = backend_stats::report(backend, reverie::BackendStatsRequest::ENABLED, source);
1330 let evidence = in_guest_trap_patching_evidence(
1331 backend,
1332 record.as_ref(),
1333 source.snapshot().process_reports(),
1334 );
1335 refuse_in_guest_trap_patching(backend, evidence)?;
1336 Ok(record)
1337}
1338
1339#[cfg(feature = "liteinst")]
1344const IN_GUEST_LITEINST_KERNEL_FLOOR: (u32, u32) = (6, 5);
1345
1346#[cfg(feature = "liteinst")]
1348fn running_kernel_release() -> String {
1349 let mut name: libc::utsname = unsafe { std::mem::zeroed() };
1350 if unsafe { libc::uname(&mut name) } != 0 {
1352 return String::new();
1353 }
1354 unsafe { std::ffi::CStr::from_ptr(name.release.as_ptr()) }
1356 .to_string_lossy()
1357 .into_owned()
1358}
1359
1360#[cfg(feature = "liteinst")]
1364fn in_guest_liteinst_kernel_gap(release: &str) -> Option<String> {
1365 let mut numbers = release
1366 .split(|c: char| !c.is_ascii_digit())
1367 .map(|part| part.parse::<u32>().ok());
1368 let (floor_major, floor_minor) = IN_GUEST_LITEINST_KERNEL_FLOOR;
1369 match (numbers.next().flatten(), numbers.next().flatten()) {
1370 (Some(major), Some(minor)) if (major, minor) >= IN_GUEST_LITEINST_KERNEL_FLOOR => None,
1371 (Some(_), Some(_)) => Some(format!(
1372 "it needs Linux {floor_major}.{floor_minor} or later (SO_PEERPIDFD, which it uses to \
1373 admit each guest process and observe its exit); this kernel is {release}"
1374 )),
1375 _ => Some(format!(
1376 "it needs Linux {floor_major}.{floor_minor} or later (SO_PEERPIDFD), and the kernel \
1377 release {release:?} does not say which version this is"
1378 )),
1379 }
1380}
1381
1382#[cfg(feature = "liteinst")]
1387const MAX_INTERPRETER_DEPTH: usize = 4;
1388
1389#[cfg(feature = "liteinst")]
1430fn in_guest_liteinst_program_gap(command: &mut Command) -> Result<Option<String>, Error> {
1431 use std::io::Read;
1432 use std::os::unix::fs::OpenOptionsExt;
1433
1434 use script::KernelScript;
1435
1436 let mut path = pin_spawn_program(command)?;
1437 for _ in 0..=MAX_INTERPRETER_DEPTH {
1438 let shown = path.display().to_string();
1439 let not_regular = || {
1440 Ok(Some(format!(
1441 "{shown} is not a regular file, and the kernel executes only regular files"
1442 )))
1443 };
1444 if !fs::metadata(&path)
1445 .with_context(|| format!("cannot read guest program {shown}"))?
1446 .is_file()
1447 {
1448 return not_regular();
1449 }
1450 let mut file = fs::OpenOptions::new()
1456 .read(true)
1457 .custom_flags(libc::O_NONBLOCK | libc::O_NOCTTY)
1458 .open(&path)
1459 .with_context(|| format!("cannot read guest program {shown}"))?;
1460 if !file
1461 .metadata()
1462 .with_context(|| format!("cannot read guest program {shown}"))?
1463 .is_file()
1464 {
1465 return not_regular();
1466 }
1467 let mut header = Vec::new();
1468 (&file)
1469 .take(256)
1470 .read_to_end(&mut header)
1471 .with_context(|| format!("cannot read guest program {shown}"))?;
1472 match KernelScript::from_buf(&header) {
1473 KernelScript::Interpreter(interpreter) => {
1474 path = match command.get_current_dir() {
1477 Some(directory) => directory.join(interpreter),
1478 None => interpreter,
1479 };
1480 continue;
1481 }
1482 KernelScript::Declined => {
1483 return Ok(Some(format!(
1484 "{shown} starts with #! but the kernel's script handler declines it (it \
1485 names no interpreter, or the interpreter path fills the first 256 bytes), \
1486 so the kernel would fail the execve or hand the file to another handler \
1487 that need not load the runtime"
1488 )));
1489 }
1490 KernelScript::NotScript => {}
1491 }
1492 let Some(startup) = interp::elf_startup(&mut file)
1493 .with_context(|| format!("cannot read the ELF headers of guest program {shown}"))?
1494 else {
1495 return Ok(Some(format!(
1496 "{shown} is neither an ELF executable nor a #! script, so the kernel would hand \
1497 it to a handler that need not load the runtime"
1498 )));
1499 };
1500 let reason = if !startup.x86_64 {
1501 "is not a 64-bit x86-64 ELF image, so the dynamic loader cannot load the 64-bit \
1502 runtime into it"
1503 } else if !startup.has_interp {
1504 "is statically linked (it has no PT_INTERP), so no dynamic loader runs to load the \
1505 runtime"
1506 } else if is_secure_execution_image(&file, &shown)? {
1507 "is set-user-ID, set-group-ID or has file capabilities, so the kernel runs it in \
1508 secure-execution mode, where the dynamic loader ignores LD_PRELOAD"
1509 } else if startup.has_preinit_array {
1510 "has a DT_PREINIT_ARRAY, whose functions run before the runtime's constructor"
1511 } else {
1512 return Ok(None);
1513 };
1514 return Ok(Some(format!(
1515 "guest program {shown} {reason}, so it would run unmonitored if Hermit launched it"
1516 )));
1517 }
1518 Ok(Some(format!(
1519 "the #! interpreters of guest program {} nest more than {MAX_INTERPRETER_DEPTH} deep",
1520 Path::new(command.get_program()).display()
1521 )))
1522}
1523
1524#[cfg(feature = "liteinst")]
1535fn pin_spawn_program(command: &mut Command) -> Result<PathBuf, Error> {
1536 let arg0 = command.get_arg0().to_owned();
1537 let program = command.find_program().with_context(|| {
1538 format!(
1539 "cannot find guest program {}",
1540 Path::new(command.get_program()).display()
1541 )
1542 })?;
1543 command.program(&program).arg0(arg0);
1544 Ok(program)
1545}
1546
1547#[cfg(feature = "liteinst")]
1551fn is_secure_execution_image(file: &fs::File, shown: &str) -> Result<bool, Error> {
1552 let mode = file
1553 .metadata()
1554 .with_context(|| format!("cannot stat guest program {shown}"))?
1555 .permissions()
1556 .mode();
1557 if mode & 0o4000 != 0 || mode & 0o2010 == 0o2010 {
1558 return Ok(true);
1559 }
1560 let size = unsafe {
1563 libc::fgetxattr(
1564 file.as_raw_fd(),
1565 c"security.capability".as_ptr(),
1566 std::ptr::null_mut(),
1567 0,
1568 )
1569 };
1570 if size >= 0 {
1571 return Ok(true);
1572 }
1573 match io::Error::last_os_error().raw_os_error() {
1574 Some(libc::ENODATA) | Some(libc::ENOTSUP) => Ok(false),
1575 _ => Err(Error::new(io::Error::last_os_error()).context(format!(
1576 "cannot read the file capabilities of guest program {shown}"
1577 ))),
1578 }
1579}
1580
1581#[cfg(feature = "liteinst")]
1585fn refuse_in_guest_liteinst_timeout(
1586 backend: Backend,
1587 timeout: Option<Duration>,
1588) -> Result<(), Error> {
1589 if backend.is_in_guest_liteinst() && timeout.is_some() {
1590 return Err(Error::new(LiteinstInGuestRefusal::for_backend(
1591 backend,
1592 "a wall-clock timeout has not been qualified for the in-guest runtime, whose run \
1593 future does not kill the guest when it is dropped",
1594 )));
1595 }
1596 Ok(())
1597}
1598
1599#[cfg(not(feature = "liteinst"))]
1600fn refuse_in_guest_liteinst_timeout(
1601 _backend: Backend,
1602 _timeout: Option<Duration>,
1603) -> Result<(), Error> {
1604 Ok(())
1605}
1606
1607#[cfg(feature = "liteinst")]
1608fn liteinst_unavailable_reason() -> Option<String> {
1609 liteinst_runtime_unavailable_reason()
1610}
1611
1612#[cfg(not(feature = "liteinst"))]
1617fn liteinst_unavailable_reason() -> Option<String> {
1618 Some(if option_env!("CARGO_PKG_NAME") == Some("hermit-run") {
1619 "this build was compiled without the liteinst backend, which is not included in this registry release; its source-development implementation is on https://github.com/rrnewton/hermit/tree/main. This release has no `liteinst` Cargo feature, and `third-party-backends` does not include LiteInst. LiteInst availability on this machine has not been checked".to_owned()
1620 } else {
1621 "this build was compiled without the liteinst backend: the `liteinst` feature is not enabled; rebuild with `--features liteinst` (or `--features third-party-backends`). This says nothing about whether LiteInst works on this machine -- it has not been checked".to_owned()
1622 })
1623}
1624
1625#[cfg(feature = "liteinst")]
1626fn liteinst_runtime_unavailable_reason() -> Option<String> {
1627 liteinst_tool_runtime_library_path().err().map(|error| {
1628 format!(
1629 "the in-guest Detcore runtime is unavailable: {error}; build it with `cargo build -p detcore-liteinst` in the target directory of this hermit binary, install it as rsrcs/libdetcore_liteinst.so, or name it with {LITEINST_TOOL_RUNTIME_ENV}"
1630 )
1631 })
1632}
1633
1634fn kvm_device_unavailable_reason(path: &Path) -> Option<String> {
1635 fs::OpenOptions::new()
1636 .read(true)
1637 .write(true)
1638 .open(path)
1639 .err()
1640 .map(|error| {
1641 format!(
1642 "cannot open {} read-write: {error}; grant access through the device owner/group \
1643 or root",
1644 path.display()
1645 )
1646 })
1647}
1648
1649#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, ValueEnum)]
1651pub enum Backend {
1652 #[default]
1654 Ptrace,
1655 Dbt,
1657 Liteinst,
1659 InGuestTrap,
1666 Sabre,
1668 Kvm,
1670 E9patch,
1673}
1674
1675#[derive(Debug, Clone, Eq, PartialEq)]
1681pub struct BackendUnavailable {
1682 backend: Backend,
1683 reason: String,
1684}
1685
1686impl BackendUnavailable {
1687 pub fn new(backend: Backend, reason: impl Into<String>) -> Self {
1688 Self {
1689 backend,
1690 reason: reason.into(),
1691 }
1692 }
1693
1694 pub fn backend(&self) -> Backend {
1695 self.backend
1696 }
1697
1698 pub fn reason(&self) -> &str {
1699 &self.reason
1700 }
1701}
1702
1703impl std::fmt::Display for BackendUnavailable {
1704 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1705 write!(
1706 formatter,
1707 "backend `{}` is unavailable: {}",
1708 self.backend.as_str(),
1709 self.reason
1710 )
1711 }
1712}
1713
1714impl std::error::Error for BackendUnavailable {}
1715
1716impl Backend {
1717 const ALL: [Self; 7] = [
1718 Self::Ptrace,
1719 Self::Dbt,
1720 Self::Liteinst,
1721 Self::InGuestTrap,
1722 Self::Sabre,
1723 Self::Kvm,
1724 Self::E9patch,
1725 ];
1726
1727 pub const fn as_str(self) -> &'static str {
1729 match self {
1730 Self::Ptrace => "ptrace",
1731 Self::Dbt => "dbt",
1732 Self::Liteinst => "liteinst",
1733 Self::InGuestTrap => "in-guest-trap",
1734 Self::Sabre => "sabre",
1735 Self::Kvm => "kvm",
1736 Self::E9patch => "e9patch",
1737 }
1738 }
1739
1740 pub const fn is_in_guest_liteinst(self) -> bool {
1746 matches!(self, Self::Liteinst | Self::InGuestTrap)
1747 }
1748
1749 pub const fn runtime_name(self) -> &'static str {
1754 match self {
1755 Self::InGuestTrap => Self::Liteinst.as_str(),
1756 other => other.as_str(),
1757 }
1758 }
1759
1760 fn uses_ptrace_pmu_timers(self) -> bool {
1761 match self {
1762 Self::Ptrace | Self::E9patch => true,
1763 Self::Liteinst | Self::InGuestTrap | Self::Dbt | Self::Sabre | Self::Kvm => false,
1765 }
1766 }
1767
1768 pub fn available() -> impl Iterator<Item = Self> {
1773 Self::ALL
1774 .into_iter()
1775 .filter(|backend| backend.is_available())
1776 }
1777
1778 pub fn is_available(self) -> bool {
1780 self.unavailable_reason().is_none()
1781 }
1782
1783 pub fn ensure_available(self) -> Result<(), Error> {
1785 self.ensure_available_for(NamespaceUse::Creates)
1786 }
1787
1788 pub fn ensure_available_for(self, namespaces: NamespaceUse) -> Result<(), Error> {
1793 if let Some(reason) = self.unavailable_reason_for(namespaces) {
1794 Err(Error::new(BackendUnavailable::new(self, reason)))
1795 } else {
1796 Ok(())
1797 }
1798 }
1799
1800 fn unavailable_reason(self) -> Option<String> {
1801 self.unavailable_reason_for(NamespaceUse::Creates)
1802 }
1803
1804 fn unavailable_reason_for(self, namespaces: NamespaceUse) -> Option<String> {
1805 match self {
1806 Self::Ptrace => validate_tracing_environment(namespaces)
1807 .err()
1808 .map(|error| error.to_string()),
1809 Self::Dbt => dbt_unavailable_reason(),
1810 Self::Liteinst | Self::InGuestTrap => liteinst_unavailable_reason(),
1812 Self::Sabre => sabre_unavailable_reason(),
1814 Self::Kvm => kvm_device_unavailable_reason(Path::new("/dev/kvm")),
1815 Self::E9patch => e9patch_unavailable_reason(),
1816 }
1817 }
1818}
1819
1820struct SkidOvershootReport {
1821 enabled: bool,
1822}
1823
1824#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1833pub struct BackendRunFailure;
1834
1835impl std::fmt::Display for BackendRunFailure {
1836 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1837 f.write_str("the backend failed while running the guest")
1838 }
1839}
1840
1841impl std::error::Error for BackendRunFailure {}
1842
1843#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1849pub struct SkidOvershootError {
1850 count: u64,
1851}
1852
1853impl SkidOvershootError {
1854 pub fn new(count: u64) -> Self {
1855 assert!(
1856 count > 0,
1857 "a skid-overshoot refusal requires a positive count"
1858 );
1859 Self { count }
1860 }
1861
1862 pub fn count(&self) -> u64 {
1863 self.count
1864 }
1865}
1866
1867impl std::fmt::Display for SkidOvershootError {
1868 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1869 write!(
1870 f,
1871 "observed {} {} report(s); refusing the result because precise PMU timer \
1872 delivery passed its target and deterministic execution was not established",
1873 self.count,
1874 reverie::SKID_OVERSHOOT_MARKER
1875 )
1876 }
1877}
1878
1879impl std::error::Error for SkidOvershootError {}
1880
1881fn take_skid_overshoot_error() -> Option<SkidOvershootError> {
1882 let count = reverie::take_skid_overshoot_count();
1883 (count > 0).then(|| SkidOvershootError::new(count))
1884}
1885
1886impl SkidOvershootReport {
1887 fn begin(enabled: bool) -> Self {
1888 if enabled {
1889 let _ = reverie::take_skid_overshoot_count();
1891 }
1892 Self { enabled }
1893 }
1894
1895 fn finish<T>(self, result: Result<T, Error>) -> Result<T, Error> {
1896 if !self.enabled {
1897 return result;
1898 }
1899
1900 let Some(overshoot) = take_skid_overshoot_error() else {
1901 return result;
1902 };
1903 match result {
1904 Ok(_) => Err(Error::new(overshoot)),
1905 Err(error) => Err(error.context(overshoot)),
1906 }
1907 }
1908
1909 fn finish_with_count<T>(self, result: Result<T, Error>) -> Result<(T, u64), Error> {
1910 if !self.enabled {
1911 return result.map(|value| (value, 0));
1912 }
1913
1914 let count = reverie::take_skid_overshoot_count();
1915 match result {
1916 Ok(value) => Ok((value, count)),
1917 Err(error) if count > 0 => Err(error.context(SkidOvershootError::new(count))),
1918 Err(error) => Err(error),
1919 }
1920 }
1921}
1922
1923#[cfg(feature = "sabre")]
1927fn sabre_unavailable_reason() -> Option<String> {
1928 sabre_runtime_unavailable_reason()
1929}
1930
1931#[cfg(not(feature = "sabre"))]
1932fn sabre_unavailable_reason() -> Option<String> {
1933 Some("the `sabre` feature is not enabled in this build; rebuild with `--features sabre` (or `--features third-party-backends`). This says nothing about whether SaBRe works on this machine -- it has not been checked".to_owned())
1934}
1935
1936#[cfg(feature = "e9patch")]
1937fn e9patch_unavailable_reason() -> Option<String> {
1938 validate_tracing_environment(NamespaceUse::Creates)
1941 .err()
1942 .map(|error| error.to_string())
1943 .or_else(e9patch::unavailable_reason)
1944}
1945
1946#[cfg(not(feature = "e9patch"))]
1947fn e9patch_unavailable_reason() -> Option<String> {
1948 Some("the `e9patch` feature is not enabled in this build; rebuild with `--features e9patch` (or `--features third-party-backends`). This says nothing about whether e9patch works on this machine -- it has not been checked".to_owned())
1949}
1950
1951#[cfg(feature = "dbt")]
1952fn dbt_unavailable_reason() -> Option<String> {
1953 if !dynamorio_sdk_available() {
1954 return Some(
1955 "the DynamoRIO runtime was not found; build target/install_pkg, set HERMIT_INSTALL_DIR, or set DYNAMORIO_HOME/DynamoRIO_DIR to a valid SDK"
1956 .to_owned(),
1957 );
1958 }
1959 dbt_runtime_unavailable_reason()
1960}
1961
1962#[cfg(not(feature = "dbt"))]
1963fn dbt_unavailable_reason() -> Option<String> {
1965 Some(dbt_disabled_build_reason(
1966 option_env!("CARGO_PKG_NAME").unwrap_or("hermit"),
1967 ))
1968}
1969
1970#[cfg(not(feature = "dbt"))]
1971fn dbt_disabled_build_reason(package_name: &str) -> String {
1972 if package_name == "hermit-run" {
1973 "the dbt backend is not included in this registry release; use a source build from https://github.com/rrnewton/hermit with `--features dbt`. The registry's `third-party-backends` feature does not include DBT. DynamoRIO availability on this machine has not been checked".to_owned()
1974 } else {
1975 "the `dbt` feature is not enabled in this source build; rebuild with `--features dbt` (or `--features third-party-backends`). DynamoRIO availability on this machine has not been checked".to_owned()
1976 }
1977}
1978
1979#[cfg(feature = "sabre")]
1980const SABRE_BINARY_ENV: &str = "HERMIT_SABRE_BINARY";
1981
1982#[cfg(feature = "sabre")]
1983fn is_executable_file(path: &Path) -> bool {
1984 fs::metadata(path)
1985 .is_ok_and(|metadata| metadata.is_file() && metadata.permissions().mode() & 0o111 != 0)
1986}
1987
1988#[cfg(feature = "sabre")]
1990fn resolve_sabre_binary_from(
1991 override_path: Option<&OsStr>,
1992 packaged_path: Option<&Path>,
1993 executable: &Path,
1994 path_env: &OsStr,
1995) -> Result<PathBuf, Error> {
1996 if let Some(requested) = override_path {
1997 if requested.is_empty() {
1998 return Err(anyhow!("{SABRE_BINARY_ENV} is empty"));
1999 }
2000 let path = PathBuf::from(requested);
2001 return is_executable_file(&path)
2002 .then_some(path.clone())
2003 .ok_or_else(|| {
2004 anyhow!(
2005 "{SABRE_BINARY_ENV}={} is not an executable file",
2006 path.display()
2007 )
2008 });
2009 }
2010
2011 if let Some(path) = packaged_path
2012 && is_executable_file(path)
2013 {
2014 return Ok(path.to_path_buf());
2015 }
2016
2017 let directory = executable
2018 .parent()
2019 .ok_or_else(|| anyhow!("Hermit executable has no parent directory"))?;
2020 let sibling = directory.join("sabre");
2021 let target_build = directory.parent().map(|target| target.join("sabre/sabre"));
2022
2023 if is_executable_file(&sibling) {
2024 return Ok(sibling);
2025 }
2026 if let Some(candidate) = &target_build
2027 && is_executable_file(candidate)
2028 {
2029 return Ok(candidate.clone());
2030 }
2031 if !path_env.is_empty()
2032 && let Some(candidate) = std::env::split_paths(path_env)
2033 .map(|directory| directory.join("sabre"))
2034 .find(|candidate| is_executable_file(candidate))
2035 {
2036 return Ok(candidate);
2037 }
2038
2039 Err(anyhow!(
2040 "SaBRe executable was not found in the Hermit installation, beside {}, or in PATH; set {} or {SABRE_BINARY_ENV}",
2041 executable.display(),
2042 hermit_resources::INSTALL_DIR_ENV
2043 ))
2044}
2045
2046#[cfg(feature = "sabre")]
2047fn resolve_sabre_binary() -> Result<PathBuf, Error> {
2048 let executable =
2049 std::env::current_exe().context("failed to locate running Hermit executable")?;
2050 let override_path = std::env::var_os(SABRE_BINARY_ENV);
2051 let packaged_path = hermit_resources::resource("sabre")?;
2052 let path_env = std::env::var_os("PATH").unwrap_or_default();
2053 resolve_sabre_binary_from(
2054 override_path.as_deref(),
2055 packaged_path.as_deref(),
2056 &executable,
2057 &path_env,
2058 )
2059}
2060
2061#[cfg(feature = "sabre")]
2062const SABRE_RPC_SOCKET_ENV: &str = "REVERIE_SABRE_HERMIT_RPC_SOCKET";
2063#[cfg(feature = "sabre")]
2064const SABRE_DETLOG_FORWARD_ENV: &str = "REVERIE_SABRE_HERMIT_FORWARD_DETLOG";
2065#[cfg(feature = "sabre")]
2068const SABRE_TOOL_OUTPUT_ENV: &str = "REVERIE_SABRE_TOOL_OUTPUT_FD";
2069#[cfg(feature = "liteinst")]
2072const LITEINST_DETLOG_FORWARD_ENV: &str = "HERMIT_LITEINST_FORWARD_DETLOG";
2073#[cfg(feature = "liteinst")]
2075const LITEINST_DETLOG_FORWARD_POLICY_ENV: &str = "HERMIT_LITEINST_FORWARD_DETLOG_POLICY";
2076
2077static IN_GUEST_DETLOG_SINK: Mutex<Option<std::os::fd::OwnedFd>> = Mutex::new(None);
2080
2081#[doc(hidden)]
2089pub fn forward_in_guest_detlogs_to(socket: std::os::fd::OwnedFd) {
2090 *IN_GUEST_DETLOG_SINK.lock().unwrap() = Some(socket);
2091}
2092
2093#[cfg(feature = "liteinst")]
2112fn in_guest_liteinst_launch(
2113 command: &mut Command,
2114 policy: &detcore::detlog::ForwardPolicy,
2115) -> Result<
2116 (
2117 detcore::in_guest_launch::InGuestLaunch,
2118 Option<std::os::fd::OwnedFd>,
2119 ),
2120 Error,
2121> {
2122 command.env_remove(LITEINST_DETLOG_FORWARD_ENV);
2123 command.env_remove(LITEINST_DETLOG_FORWARD_POLICY_ENV);
2124 command.env_remove(detcore::LITEINST_CONFIG_FINGERPRINT_ENV);
2125 let mut launch = detcore::in_guest_launch::InGuestLaunch {
2126 coordinator_fingerprint: Some(detcore::config_wire_fingerprint()),
2127 ..Default::default()
2128 };
2129 if !policy.forwards_any() {
2134 return Ok((launch, None));
2135 }
2136 let Some(duplicate) = inheritable_in_guest_detlog_socket()? else {
2137 return Ok((launch, None));
2138 };
2139 launch.forward_request = Some(detcore::detlog::tool_output_env_value(
2140 duplicate.as_raw_fd(),
2141 )?);
2142 launch.forward_policy = Some(policy.encode());
2143 Ok((launch, Some(duplicate)))
2144}
2145
2146#[cfg(any(feature = "sabre", feature = "liteinst"))]
2151fn inheritable_in_guest_detlog_socket() -> Result<Option<std::os::fd::OwnedFd>, Error> {
2152 let sink = IN_GUEST_DETLOG_SINK.lock().unwrap();
2153 let Some(socket) = sink.as_ref() else {
2154 return Ok(None);
2155 };
2156 let duplicate = unsafe { libc::fcntl(socket.as_raw_fd(), libc::F_DUPFD, 3) };
2158 if duplicate < 0 {
2159 return Err(Error::new(std::io::Error::last_os_error())
2160 .context("duplicating the in-guest DETLOG forwarding socket"));
2161 }
2162 Ok(Some(unsafe {
2164 std::os::fd::OwnedFd::from_raw_fd(duplicate)
2165 }))
2166}
2167#[cfg(feature = "sabre")]
2168const SABRE_PATH_EVIDENCE_ENV: &str = "HERMIT_SABRE_PATH_EVIDENCE";
2169
2170#[cfg(any(feature = "sabre", feature = "liteinst"))]
2176fn in_guest_detlog_forward_policy() -> detcore::detlog::ForwardPolicy {
2177 let directives = std::env::var(tracing_subscriber::EnvFilter::DEFAULT_ENV).unwrap_or_default();
2178 detcore::detlog::ForwardPolicy::from_current_subscriber(&directives)
2179}
2180#[cfg(feature = "sabre")]
2181const SABRE_STAGING_DIRECTORY: &str = "/dev/shm";
2182
2183#[cfg(feature = "sabre")]
2184struct StagedSabreProgram {
2185 path: PathBuf,
2186}
2187
2188#[cfg(feature = "sabre")]
2189impl Drop for StagedSabreProgram {
2190 fn drop(&mut self) {
2191 let _ = fs::remove_file(&self.path);
2192 }
2193}
2194
2195#[cfg(feature = "sabre")]
2196fn sabre_program_needs_neutral_name(program: &Path) -> bool {
2197 program
2198 .file_name()
2199 .is_some_and(|name| name.as_bytes().starts_with(b"ld"))
2200}
2201
2202#[cfg(feature = "sabre")]
2205fn stage_sabre_program_in(
2206 program: &Path,
2207 staging_directory: &Path,
2208) -> Result<Option<StagedSabreProgram>, Error> {
2209 if !sabre_program_needs_neutral_name(program) {
2210 return Ok(None);
2211 }
2212
2213 let path = staging_directory.join(format!("hermit-sabre-program-{}", std::process::id()));
2214 let mut source = fs::File::open(program).map_err(|error| {
2215 anyhow!(
2216 "failed to open SaBRe guest executable {} for neutral-name staging: {error}",
2217 program.display()
2218 )
2219 })?;
2220 let mut staged = fs::OpenOptions::new()
2221 .write(true)
2222 .create_new(true)
2223 .mode(0o700)
2224 .open(&path)
2225 .map_err(|error| {
2226 anyhow!(
2227 "failed to stage SaBRe guest executable {} as {}: {error}",
2228 program.display(),
2229 path.display()
2230 )
2231 })?;
2232 if let Err(error) = io::copy(&mut source, &mut staged) {
2233 let _ = fs::remove_file(&path);
2234 return Err(anyhow!(
2235 "failed to stage SaBRe guest executable {} as {}: {error}",
2236 program.display(),
2237 path.display()
2238 ));
2239 }
2240 drop(staged);
2241
2242 Ok(Some(StagedSabreProgram { path }))
2243}
2244
2245#[cfg(feature = "sabre")]
2247fn sabre_runtime_library_path() -> io::Result<PathBuf> {
2248 if let Some(path) = hermit_resources::resource("libdetcore_sabre.so")?
2249 && path.is_file()
2250 {
2251 return Ok(path);
2252 }
2253
2254 let executable = std::env::current_exe()?;
2255 let directory = executable.parent().ok_or_else(|| {
2256 io::Error::new(
2257 io::ErrorKind::NotFound,
2258 "Hermit executable has no parent directory",
2259 )
2260 })?;
2261 [
2262 directory.join("libdetcore_sabre.so"),
2263 directory.join("deps/libdetcore_sabre.so"),
2264 ]
2265 .into_iter()
2266 .find(|path| path.is_file())
2267 .ok_or_else(|| {
2268 io::Error::new(
2269 io::ErrorKind::NotFound,
2270 format!(
2271 "libdetcore_sabre.so was not built beside {}",
2272 executable.display()
2273 ),
2274 )
2275 })
2276}
2277
2278#[cfg(feature = "sabre")]
2279fn sabre_runtime_unavailable_reason() -> Option<String> {
2280 if let Err(error) = resolve_sabre_binary() {
2281 return Some(error.to_string());
2282 }
2283 sabre_runtime_library_path().err().map(|error| {
2284 format!(
2285 "the Detcore SaBRe plugin is unavailable: {error}; build detcore-sabre and hermit in the same target directory"
2286 )
2287 })
2288}
2289
2290#[cfg(feature = "sabre")]
2293const SABRE_RPC_DISCONNECT_TIMEOUT: Duration = Duration::from_secs(1);
2294
2295#[cfg(feature = "sabre")]
2296async fn wait_for_sabre_rpc_disconnects<T>(
2297 global: &Arc<T>,
2298 timeout: Duration,
2299) -> Result<(), usize> {
2300 let disconnected = tokio::time::timeout(timeout, async {
2301 while Arc::strong_count(global) > 1 {
2302 tokio::time::sleep(Duration::from_millis(1)).await;
2303 }
2304 })
2305 .await;
2306
2307 if disconnected.is_ok() {
2308 return Ok(());
2309 }
2310
2311 let live_references = Arc::strong_count(global).saturating_sub(1);
2312 if live_references == 0 {
2313 Ok(())
2314 } else {
2315 Err(live_references)
2316 }
2317}
2318
2319#[cfg(feature = "sabre")]
2322async fn stop_sabre_rpc_server<E>(
2323 server_task: tokio::task::JoinHandle<Result<(), E>>,
2324) -> Result<(), Error>
2325where
2326 E: std::fmt::Display,
2327{
2328 server_task.abort();
2329 match server_task.await {
2330 Err(error) if error.is_cancelled() => Ok(()),
2331 Err(error) => Err(anyhow!("SaBRe coordinator task failed: {error}")),
2332 Ok(Err(error)) => Err(anyhow!("SaBRe coordinator server failed: {error}")),
2333 Ok(Ok(())) => Err(anyhow!("SaBRe coordinator server stopped unexpectedly")),
2334 }
2335}
2336
2337#[cfg(feature = "sabre")]
2340async fn shutdown_sabre_rpc<T, E>(
2341 server_task: tokio::task::JoinHandle<Result<(), E>>,
2342 global: &Arc<T>,
2343 timeout: Duration,
2344) -> Result<(), Error>
2345where
2346 E: std::fmt::Display,
2347{
2348 let server_result = stop_sabre_rpc_server(server_task).await;
2349 let disconnect_result = wait_for_sabre_rpc_disconnects(global, timeout).await;
2350
2351 server_result?;
2352 disconnect_result.map_err(|live_references| {
2353 anyhow!("SaBRe coordinator stopped with {live_references} live RPC reference(s)")
2354 })
2355}
2356
2357fn ensure_backend_dispatch(backend: Backend) -> Result<(), Error> {
2358 if backend == Backend::Ptrace {
2361 return Ok(());
2362 }
2363 if backend == Backend::E9patch {
2364 return Err(anyhow!(
2365 "backend `e9patch` requires CLI preprocessing; library callers must use \
2366 e9patch::prepare and then select `ptrace`"
2367 ));
2368 }
2369 backend.ensure_available()?;
2372 Err(anyhow!(
2373 "backend `{}` has no Hermit dispatch implementation",
2374 backend.as_str()
2375 ))
2376}
2377
2378#[cfg(feature = "sabre")]
2383async fn run_sabre(
2384 mut command: Command,
2385 config: DetConfig,
2386 print_summary: bool,
2387 print_summary_to_json_file: &Option<PathBuf>,
2388 capture_output: bool,
2389) -> Result<Output, Error> {
2390 let path_evidence_file = std::env::var_os(SABRE_PATH_EVIDENCE_ENV).map(PathBuf::from);
2391 let mut config = config;
2395 let policy = in_guest_detlog_forward_policy();
2396 config.in_guest_detlog_forward_policy = (policy.forwards_any()
2397 && IN_GUEST_DETLOG_SINK.lock().unwrap().is_some())
2398 .then(|| policy.encode());
2399 let sabre = resolve_sabre_binary()?;
2400 config
2405 .launch_image
2406 .get_or_insert(detcore::LaunchImage {
2407 exe: None,
2408 launcher: None,
2409 })
2410 .launcher = Some(PathBuf::from(&sabre));
2411 let plugin = sabre_runtime_library_path()
2412 .map_err(|error| anyhow!("failed to locate the Detcore SaBRe plugin: {error}"))?;
2413 let program = command.find_program().map_err(|error| {
2414 anyhow!(
2415 "failed to resolve SaBRe guest executable {:?}: {error}",
2416 command.get_program()
2417 )
2418 })?;
2419 let staged_program = stage_sabre_program_in(&program, Path::new(SABRE_STAGING_DIRECTORY))?;
2420 let launch_program = staged_program
2421 .as_ref()
2422 .map_or(program.as_path(), |staged| staged.path.as_path());
2423
2424 let bootstrap_launch =
2425 sabre_bootstrap::Launch::new(Path::new(&sabre), launch_program, &config)?;
2426
2427 let socket_dir = tempfile::Builder::new()
2434 .prefix("hermit-sabre-rpc-")
2435 .tempdir_in(Path::new("/tmp"))?;
2436 let socket_path = socket_dir.path().join("coordinator.sock");
2437 let fallback_ready = Arc::new(AtomicBool::new(false));
2438 let global = Arc::new(detcore::GlobalState::init_global_state(&config).await);
2439 let server = reverie_rpc_transport::RpcServer::bind_with_readiness(
2440 &socket_path,
2441 global.clone(),
2442 config.clone(),
2443 fallback_ready.clone(),
2444 )
2445 .map_err(|error| anyhow!("failed to start SaBRe coordinator RPC: {error}"))?;
2446 let server_task = tokio::spawn(async move { server.serve().await });
2447
2448 let mut first_bytes = vec![0u8; 256];
2456 let read = std::fs::File::open(launch_program)
2457 .and_then(|mut file| std::io::Read::read(&mut file, &mut first_bytes))
2458 .map_err(|error| {
2459 anyhow!(
2460 "failed to read SaBRe guest executable {}: {error}",
2461 launch_program.display()
2462 )
2463 })?;
2464 first_bytes.truncate(read);
2465 let arg0 = command.get_arg0().to_owned();
2466 let client = match reverie_sabre_stats::launch::shebang(&first_bytes) {
2467 Some((interpreter, argument)) => {
2468 command.program(&sabre);
2469 command.arg0(OsStr::from_bytes(&interpreter));
2470 let mut words: Vec<&OsStr> = argument
2471 .iter()
2472 .map(|word| OsStr::from_bytes(word))
2473 .collect();
2474 words.push(launch_program.as_os_str());
2475 command.prepend_args(words);
2476 PathBuf::from(OsStr::from_bytes(&interpreter))
2477 }
2478 None => {
2479 command.program(&sabre);
2480 command.arg0(&arg0);
2481 launch_program.to_path_buf()
2482 }
2483 };
2484 let mut launch_settings: Vec<Vec<u8>> = Vec::new();
2485 let mut setting = |name: &str, value: &OsStr| {
2486 let mut entry = name.as_bytes().to_vec();
2487 entry.push(b'=');
2488 entry.extend_from_slice(value.as_bytes());
2489 launch_settings.push(entry);
2490 };
2491 setting(SABRE_RPC_SOCKET_ENV, socket_path.as_os_str());
2492 command.env_remove(SABRE_RPC_SOCKET_ENV);
2493 command.env_remove(sabre_bootstrap::ENVIRONMENT);
2494 if bootstrap_launch.initializes_random() {
2495 setting(sabre_bootstrap::ENVIRONMENT, OsStr::new("1"));
2496 }
2497 setting(
2503 detcore::CONFIG_FINGERPRINT_ENV,
2504 OsStr::new(&detcore::config_wire_fingerprint()),
2505 );
2506 command.env_remove(detcore::CONFIG_FINGERPRINT_ENV);
2507 command.env_remove(SABRE_PATH_EVIDENCE_ENV);
2508 command.env_remove(SABRE_DETLOG_FORWARD_ENV);
2509 command.env_remove(SABRE_TOOL_OUTPUT_ENV);
2513 let detlog_policy = in_guest_detlog_forward_policy();
2514 let mut _detlog_descriptor = None;
2516 if detlog_policy.forwards_any() {
2517 setting(
2518 SABRE_DETLOG_FORWARD_ENV,
2519 OsStr::new(&detlog_policy.encode()),
2520 );
2521 if let Some(socket) = inheritable_in_guest_detlog_socket()? {
2527 setting(
2528 SABRE_TOOL_OUTPUT_ENV,
2529 OsStr::new(&detcore::detlog::tool_output_env_value(socket.as_raw_fd())?),
2530 );
2531 _detlog_descriptor = Some(socket);
2532 }
2533 }
2534 command.env_remove("SABRE_BINARY");
2535 command.env_remove("SABRE_PLUGIN");
2536 let stats = reverie_sabre_stats::SabreStats::create(reverie::BackendStatsRequest::ENABLED)
2542 .map_err(|error| anyhow!("failed to create the SaBRe statistics page: {error}"))?
2543 .expect("an enabled request creates the statistics page");
2544 setting(
2545 reverie_sabre_stats::BACKEND_STATS_ENV,
2546 OsStr::new(&stats.raw_fd().to_string()),
2547 );
2548 command.env_remove(reverie_sabre_stats::BACKEND_STATS_ENV);
2549 let launch_settings: Vec<&[u8]> = launch_settings.iter().map(Vec::as_slice).collect();
2550 let launch_spec = reverie_sabre_stats::launch::spec_bytes(
2551 plugin.as_os_str().as_bytes(),
2552 client.as_os_str().as_bytes(),
2553 &launch_settings,
2554 )
2555 .ok_or_else(|| anyhow!("the SaBRe launch specification is malformed or too large"))?;
2556 let _launch_spec = reverie_sabre_stats::launch::spec_fd(&launch_spec)
2559 .map_err(|error| anyhow!("failed to create the SaBRe launch specification: {error}"))?;
2560
2561 tracing::debug!(
2589 target: "hermit::sabre",
2590 socket = %socket_path.display(),
2591 "SaBRe coordinator RPC socket (per-launch temp path, deliberately not at INFO)",
2592 );
2593 tracing::info!(
2594 target: "hermit::sabre",
2595 guest = %program.display(),
2596 plugin = %plugin.display(),
2597 "launching Detcore guest through SaBRe with coordinator RPC",
2598 );
2599
2600 let supervised = match sabre_ptrace::run(
2601 command.into_std_lossy(),
2602 PathBuf::from(&sabre),
2603 plugin.clone(),
2604 fallback_ready,
2605 global.clone(),
2606 bootstrap_launch,
2607 stats.clone(),
2608 capture_output,
2609 )
2610 .await
2611 {
2612 Ok(supervised) => supervised,
2613 Err(error) => {
2614 global.release_all_physical_process_exits();
2615 global.force_shutdown_with_error();
2616 let _ = shutdown_sabre_rpc(server_task, &global, SABRE_RPC_DISCONNECT_TIMEOUT).await;
2617 return Err(error);
2618 }
2619 };
2620 global.release_all_physical_process_exits();
2624 let detcore_never_engaged = !supervised.path_evidence.guest_rpc_observed;
2630 let requires_forced_shutdown = !supervised.status.success() || detcore_never_engaged;
2631 if requires_forced_shutdown {
2632 global.force_shutdown_with_error();
2633 }
2634 let backend_evidence = sabre_backend_evidence_line(&supervised.path_evidence);
2647 tracing::warn!(target: "hermit::sabre", "{backend_evidence}");
2648 if let Some(path) = path_evidence_file {
2649 let mut file = fs::OpenOptions::new()
2650 .create(true)
2651 .append(true)
2652 .mode(0o600)
2653 .open(&path)
2654 .map_err(|error| {
2655 anyhow!(
2656 "failed to open SaBRe path evidence {}: {error}",
2657 path.display()
2658 )
2659 })?;
2660 serde_json::to_writer(&mut file, &supervised.path_evidence)?;
2661 writeln!(file)?;
2662 }
2663 let output = Output {
2664 status: supervised.status.into(),
2665 stdout: supervised.stdout,
2666 stderr: supervised.stderr,
2667 };
2668
2669 shutdown_sabre_rpc(server_task, &global, SABRE_RPC_DISCONNECT_TIMEOUT).await?;
2670 let mut global = Arc::try_unwrap(global).map_err(|global| {
2671 anyhow!(
2672 "SaBRe coordinator stopped with {} live RPC reference(s)",
2673 Arc::strong_count(&global) - 1
2674 )
2675 })?;
2676 if requires_forced_shutdown {
2677 global.cancel_internal_scheduler().await;
2678 }
2679 let dispatch_stats = backend_stats::report(
2680 Backend::Sabre,
2681 backend_stats::request(print_summary_to_json_file),
2682 &stats,
2683 );
2684 global
2685 .clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
2686 .await;
2687 tracing::info!(
2688 target: "hermit::sabre::fallback",
2689 ptrace_fallback_sites = supervised.path_evidence.ptrace_fallback_sites,
2690 trusted_shared_object_sites = supervised.path_evidence.trusted_shared_object_sites,
2691 guest_rpc_observed = supervised.path_evidence.guest_rpc_observed,
2692 "SaBRe ptrace fallback completed",
2693 );
2694 if detcore_never_engaged {
2695 return Err(Error::new(BackendRunFailure)
2696 .context(sabre_uninstrumented_guest_message(&output.status)));
2697 }
2698 Ok(output)
2699}
2700
2701#[cfg(not(feature = "sabre"))]
2702async fn run_sabre(
2703 _command: Command,
2704 _config: DetConfig,
2705 _print_summary: bool,
2706 _print_summary_to_json_file: &Option<PathBuf>,
2707 _capture_output: bool,
2708) -> Result<Output, Error> {
2709 Backend::Sabre.ensure_available()?;
2710 unreachable!("SaBRe availability must fail when the feature is disabled");
2711}
2712
2713#[cfg(feature = "sabre")]
2716fn sabre_reach_state(guest_rpc_observed: bool, ptrace_fallback_sites: usize) -> &'static str {
2717 match (guest_rpc_observed, ptrace_fallback_sites) {
2718 (false, _) => "no-detcore-reached",
2719 (true, 1..) => "degraded-ptrace-fallback",
2720 (true, 0) => "sabre-exercised",
2721 }
2722}
2723
2724#[cfg(feature = "sabre")]
2737fn sabre_backend_evidence_line(evidence: &sabre_ptrace::PathEvidence) -> String {
2738 format!(
2739 ":: Backend: sabre static rewriting + ptrace runtime; run_mode=run; \
2740 evidence_schema={}; preplugin_coverage=absent; ptrace_fallback_sites={}; \
2741 trusted_shared_object_sites={}; guest_rpc_observed={}; reach_state={}",
2742 evidence.schema,
2743 evidence.ptrace_fallback_sites,
2744 evidence.trusted_shared_object_sites,
2745 evidence.guest_rpc_observed,
2746 sabre_reach_state(evidence.guest_rpc_observed, evidence.ptrace_fallback_sites),
2747 )
2748}
2749
2750#[cfg(feature = "sabre")]
2765fn sabre_uninstrumented_guest_message(status: &ExitStatus) -> String {
2766 format!(
2767 "the SaBRe backend finished ({status:?}) without the guest ever reaching the Detcore \
2768 coordinator: no syscall was intercepted, so this run applied no determinization at all \
2769 and its result is not a Hermit guarantee. This means SaBRe rewrote no syscall site in \
2770 the guest -- most often a statically linked ELF, whose syscall sites SaBRe must patch \
2771 in the client image itself because there is no dynamic loader to intercept."
2772 )
2773}
2774
2775const KVM_GUEST_MEMORY_BYTES: usize = 3 * 1024 * 1024 * 1024;
2790
2791const MAX_SHEBANG_DEPTH: usize = 4;
2794
2795fn resolve_kvm_shebang(
2808 resolved_program: &Path,
2809 mut argv: Vec<String>,
2810) -> Result<(PathBuf, Vec<String>, Vec<u8>), Error> {
2811 let mut load_path = resolved_program.to_path_buf();
2812 let mut image = fs::read(&load_path)
2813 .map_err(|error| anyhow!("failed to read KVM guest executable {load_path:?}: {error}"))?;
2814
2815 let mut depth = 0;
2816 while image.starts_with(b"#!") {
2817 depth += 1;
2818 if depth > MAX_SHEBANG_DEPTH {
2819 return Err(anyhow!(
2820 "too many levels of `#!` interpreter indirection loading {resolved_program:?}"
2821 ));
2822 }
2823 let (interpreter, shebang_args) = Shebang::from_buf(&image)
2824 .ok_or_else(|| anyhow!("malformed `#!` interpreter line in {load_path:?}"))?
2825 .into_parts();
2826 let interpreter_str = interpreter
2827 .to_str()
2828 .ok_or_else(|| anyhow!("non-UTF-8 `#!` interpreter path in {load_path:?}"))?
2829 .to_owned();
2830
2831 let mut rewritten = Vec::with_capacity(argv.len() + shebang_args.len() + 2);
2836 rewritten.push(interpreter_str);
2837 for arg in &shebang_args {
2838 rewritten.push(
2839 arg.to_str()
2840 .ok_or_else(|| anyhow!("non-UTF-8 `#!` interpreter argument in {load_path:?}"))?
2841 .to_owned(),
2842 );
2843 }
2844 rewritten.push(load_path.to_string_lossy().into_owned());
2845 rewritten.extend_from_slice(&argv[1..]);
2846 argv = rewritten;
2847
2848 load_path = interpreter;
2849 image = fs::read(&load_path).map_err(|error| {
2850 anyhow!(
2851 "failed to read `#!` interpreter {load_path:?} for {resolved_program:?}: {error}"
2852 )
2853 })?;
2854 }
2855
2856 Ok((load_path, argv, image))
2857}
2858
2859const CONTAINER_REPLACED_TMP: &str = "/tmp";
2863
2864fn kvm_cwd_resolution_error(requested_cwd: &Path, error: &std::io::Error) -> Error {
2892 let under_replaced_tmp = requested_cwd.starts_with(CONTAINER_REPLACED_TMP)
2893 && requested_cwd != Path::new(CONTAINER_REPLACED_TMP);
2894 if error.kind() == std::io::ErrorKind::NotFound && under_replaced_tmp {
2895 anyhow!(
2896 "failed to resolve KVM guest working directory {:?}: {error}\n\
2897 \n\
2898 This directory may well exist on the host. The container replaces \
2899 {CONTAINER_REPLACED_TMP} with a private, empty tmpfs, so nothing beneath \
2900 {CONTAINER_REPLACED_TMP} is visible to the guest, and resolving the working \
2901 directory happens inside that mount namespace.\n\
2902 Either run from a directory outside {CONTAINER_REPLACED_TMP}, or pass \
2903 --workdir with a path that exists inside the guest.",
2904 requested_cwd
2905 )
2906 } else {
2907 anyhow!(
2908 "failed to resolve KVM guest working directory {:?}: {error}",
2909 requested_cwd
2910 )
2911 }
2912}
2913
2914fn prepare_kvm_mountinfo_config(
2948 config: &mut DetConfig,
2949 namespace: impl FnOnce() -> Result<detcore_model::config::MountNamespaceIdentity, Error>,
2950 capture: impl FnOnce() -> Result<Vec<u64>, Error>,
2951) -> Result<(), Error> {
2952 if !config.mountinfo_mount_ids_captured
2953 && (!config.mountinfo_mount_ids.is_empty()
2954 || !config.mount_id_assignment_order.is_empty()
2955 || config.mountinfo_mount_namespace.is_some())
2956 {
2957 anyhow::bail!("KVM mount identities have no producer-captured namespace");
2958 }
2959 if config.mountinfo_mount_ids_captured {
2960 let Some(producer) = config.mountinfo_mount_namespace else {
2961 anyhow::bail!(
2962 "KVM producer-captured mount identities do not name their mount namespace"
2963 );
2964 };
2965 if config.mountinfo_mount_ids.is_empty()
2968 || !detcore_model::procfs::mount_identity_provenance_is_well_formed(
2969 &config.mountinfo_mount_ids,
2970 &config.mount_id_assignment_order,
2971 )
2972 {
2973 anyhow::bail!(
2974 "KVM producer-captured mount identities are malformed ({} listed, {} assigned)",
2975 config.mountinfo_mount_ids.len(),
2976 config.mount_id_assignment_order.len()
2977 );
2978 }
2979 if let Some(missing) = config
2980 .mountinfo_root_rewrites
2981 .iter()
2982 .map(|rewrite| rewrite.raw_mount_id)
2983 .find(|id| !config.mountinfo_mount_ids.contains(id))
2984 {
2985 anyhow::bail!(
2986 "KVM mount root rewrite names mount {missing}, which the producer's snapshot does \
2987 not have"
2988 );
2989 }
2990 let backend = namespace().context("failed to identify the KVM backend mount namespace")?;
2991 if producer != backend {
2992 anyhow::bail!(
2993 "KVM producer-captured mount identities name another mount namespace \
2994 (captured in {producer:?}, backend in {backend:?})"
2995 );
2996 }
2997 } else {
2998 let order = capture().context("failed to capture the KVM backend mount namespace")?;
2999 config.mountinfo_mount_ids = order;
3000 config.mountinfo_mount_ids_captured = true;
3001 }
3002 if let Some(table) = &config.container_mount_table
3005 && let Some(missing) = table
3006 .mounts
3007 .iter()
3008 .map(|row| row.raw_mount_id)
3009 .find(|id| !config.mountinfo_mount_ids.contains(id))
3010 {
3011 anyhow::bail!(
3012 "KVM container mount table names mount {missing}, which the backend namespace does \
3013 not have"
3014 );
3015 }
3016 config.mountinfo_device_rewrites.clear();
3020 Ok(())
3021}
3022
3023fn kvm_reports_stored_metadata_timestamps(config: &DetConfig) -> bool {
3038 config.virtualize_metadata && config.sequentialize_threads
3039}
3040
3041async fn run_kvm(
3043 command: &Command,
3044 mut config: DetConfig,
3045 print_summary: bool,
3046 print_summary_to_json_file: &Option<PathBuf>,
3047 capture_output: bool,
3048) -> Result<Output, Error> {
3049 let dispatch_started = Instant::now();
3050 if config.container_mount_table.is_none() {
3057 let launch_cwd = command
3058 .get_current_dir()
3059 .map_or_else(|| Path::new(".").to_owned(), Path::to_owned);
3060 let (table, order) = unplanned_container_mount_table(&launch_cwd)?;
3061 if !config.mountinfo_mount_ids_captured
3062 && config.mountinfo_mount_ids.is_empty()
3063 && config.mount_id_assignment_order.is_empty()
3064 && config.mountinfo_mount_namespace.is_none()
3065 {
3066 config.mountinfo_mount_namespace = Some(current_mount_namespace()?);
3067 config.mountinfo_mount_ids = order;
3068 config.mountinfo_mount_ids_captured = true;
3069 }
3070 config.container_mount_table = Some(table);
3071 }
3072 let keep = config
3073 .container_mount_table
3074 .as_ref()
3075 .map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
3076 .unwrap_or_default();
3077 prepare_kvm_mountinfo_config(&mut config, current_mount_namespace, || {
3078 capture_mountinfo_identity_order_keeping(&keep)
3079 })?;
3080 let stdin = if capture_output {
3081 let (snapshot_reserved, snapshot) = output_backend_stdin_reservation()?;
3082 if snapshot_reserved {
3083 snapshot
3084 } else {
3085 reserved_kvm_stdin()?
3090 }
3091 } else {
3092 reserved_kvm_stdin()?
3093 };
3094 let requested_cwd = command
3095 .get_current_dir()
3096 .map(Path::to_owned)
3097 .unwrap_or(std::env::current_dir()?);
3098 let cwd = fs::canonicalize(&requested_cwd)
3099 .map_err(|error| kvm_cwd_resolution_error(&requested_cwd, &error))?;
3100 let program = command
3101 .get_program()
3102 .to_str()
3103 .ok_or_else(|| anyhow!("KVM guest executable path is not valid UTF-8"))?
3104 .to_owned();
3105 if !cwd.is_dir() {
3106 return Err(anyhow!(
3107 "KVM guest working directory is not a directory: {:?}",
3108 cwd
3109 ));
3110 }
3111 let resolved_program = command.find_program().map_err(|error| {
3112 anyhow!("failed to resolve KVM guest executable {program:?} in the guest PATH: {error}")
3113 })?;
3114 let mut argv = Vec::with_capacity(1 + command.get_args().count());
3115 argv.push(program.clone());
3116 for argument in command.get_args() {
3117 argv.push(
3118 argument
3119 .to_str()
3120 .ok_or_else(|| anyhow!("KVM guest argument is not valid UTF-8"))?
3121 .to_owned(),
3122 );
3123 }
3124
3125 let (_interpreter_path, argv, image) = resolve_kvm_shebang(&resolved_program, argv)?;
3127 let program = argv.first().cloned().unwrap_or(program);
3129 let envp = command
3130 .get_captured_envs()
3131 .into_iter()
3132 .map(|(key, value)| {
3133 let key = key
3134 .to_str()
3135 .ok_or_else(|| anyhow!("KVM guest environment key is not valid UTF-8"))?;
3136 let value = value
3137 .to_str()
3138 .ok_or_else(|| anyhow!("KVM guest environment value is not valid UTF-8"))?;
3139 Ok(format!("{key}={value}"))
3140 })
3141 .collect::<Result<Vec<_>, Error>>()?;
3142 tracing::info!(
3143 target: "hermit::kvm",
3144 program = %program,
3145 argv = ?argv,
3146 cwd = %cwd.display(),
3147 env_count = envp.len(),
3148 "launching guest through reverie-kvm",
3149 );
3150 let argv = argv.iter().map(String::as_str).collect::<Vec<_>>();
3151 let envp = envp.iter().map(String::as_str).collect::<Vec<_>>();
3152
3153 let setup_started = Instant::now();
3154 config.has_uts_namespace = false;
3161 let random_seed = config.rng_seed();
3162 let mut backend = reverie_kvm::KvmBackend::new_with_stdin(KVM_GUEST_MEMORY_BYTES, stdin)
3163 .map_err(|error| anyhow!("failed to initialize reverie-kvm: {error}"))?;
3164 backend
3167 .set_root_pid(detcore::ROOT_DETPID.as_raw())
3168 .map_err(|error| anyhow!("failed to configure KVM root PID: {error}"))?;
3169 backend
3172 .set_ids_per_task(reverie::task_ids::HERMIT_PTRACE_IDS_PER_TASK)
3173 .map_err(|error| anyhow!("failed to configure KVM task IDs: {error}"))?;
3174 backend
3179 .install_static_elf_with_exec_context(
3180 &image,
3181 resolved_program.as_os_str(),
3182 &argv,
3183 &envp,
3184 &cwd,
3185 )
3186 .map_err(|error| anyhow!("failed to load KVM guest executable {program:?}: {error}"))?;
3187 drop(image);
3192 backend
3193 .set_random_seed(random_seed)
3194 .map_err(|error| anyhow!("failed to configure KVM guest random seed: {error}"))?;
3195 if kvm_reports_stored_metadata_timestamps(&config) {
3204 backend
3205 .set_host_metadata_timestamps(true)
3206 .map_err(|error| anyhow!("failed to configure KVM metadata timestamps: {error}"))?;
3207 }
3208
3209 let execution_started = Instant::now();
3210 let completion = hermit_run_kvm::run_detcore(&mut backend, config, capture_output)
3211 .await
3212 .map_err(|error| kvm_execution_error(error, None))?;
3213 let cleanup_started = Instant::now();
3214 let result =
3215 finish_kvm_tool_completion(completion, print_summary, print_summary_to_json_file).await;
3216 let teardown_started = Instant::now();
3217 drop(backend);
3219 let teardown_finished = Instant::now();
3220 let (status, stdout, stderr) = result?;
3221
3222 tracing::debug!(
3227 target: "hermit::kvm",
3228 prepare_us = setup_started.duration_since(dispatch_started).as_micros() as u64,
3229 setup_us = execution_started.duration_since(setup_started).as_micros() as u64,
3230 execution_us = cleanup_started.duration_since(execution_started).as_micros() as u64,
3231 cleanup_us = teardown_started.duration_since(cleanup_started).as_micros() as u64,
3232 teardown_us = teardown_finished.duration_since(teardown_started).as_micros() as u64,
3233 lifecycle_us = teardown_finished.duration_since(dispatch_started).as_micros() as u64,
3234 "reverie-kvm lifecycle phase timings",
3235 );
3236
3237 if !capture_output {
3238 std::io::stdout().write_all(&stdout)?;
3239 std::io::stderr().write_all(&stderr)?;
3240 }
3241
3242 Ok(Output {
3243 status,
3244 stdout,
3245 stderr,
3246 })
3247}
3248
3249async fn finish_kvm_tool_completion(
3252 completion: reverie_kvm::ToolRunCompletion<detcore::GlobalState>,
3253 print_summary: bool,
3254 print_summary_to_json_file: &Option<PathBuf>,
3255) -> Result<(ExitStatus, Vec<u8>, Vec<u8>), Error> {
3256 match completion.result {
3257 Ok(output) => {
3258 completion
3259 .global_state
3260 .clean_up(print_summary, print_summary_to_json_file)
3261 .await;
3262 Ok(output)
3263 }
3264 Err(error) => {
3265 let cleanup = completion
3266 .global_state
3267 .clean_up_after_backend_failure()
3268 .await;
3269 Err(kvm_execution_error(error, Some(cleanup)))
3270 }
3271 }
3272}
3273
3274fn kvm_execution_error(
3275 primary: reverie_kvm::Error,
3276 cleanup: Option<detcore::BackendFailureCleanup>,
3277) -> Error {
3278 let message = format!("KVM guest execution failed: {primary}");
3281 let mut error = Error::new(primary).context(BackendRunFailure);
3282 if let Some(cleanup) = cleanup {
3283 if let Err(recording) = cleanup.preemption_recording {
3284 error = error.context(format!("partial preemption recording failed: {recording}"));
3285 }
3286 if let Err(scheduler) = cleanup.scheduler {
3287 error = error.context(scheduler);
3288 }
3289 }
3290 error.context(message)
3291}
3292
3293#[cfg(test)]
3294mod kvm_failure_tests;
3295
3296#[cfg(all(test, feature = "kvm-execution-tests"))]
3297mod kvm_execution_tests;
3298
3299#[cfg(feature = "dbt")]
3301fn dbt_client_thread_start_failed(status: &std::process::ExitStatus) -> bool {
3302 status.code() == Some(reverie_dbt::CLIENT_THREAD_START_FAILURE_EXIT_CODE)
3303}
3304
3305const LEGACY_DBT_DETCONFIG_KEYS: [(&str, bool, &str); 3] = [
3315 (
3316 "use_thread_local_clock_reads",
3317 false,
3318 "detect_host_clock_futex_timeouts",
3319 ),
3320 (
3321 "backend_serializes_fork_children",
3322 false,
3323 "backend_tracks_process_children",
3324 ),
3325 (
3326 "backend_dispatches_thread_tools",
3327 true,
3328 "backend_tracks_process_children",
3329 ),
3330];
3331
3332#[doc(hidden)]
3357pub fn dbt_detconfig_json(config: &DetConfig) -> serde_json::Result<String> {
3358 let legacy = insert_legacy_dbt_detconfig_keys(&detcore::to_legacy_backend_json(config)?)?;
3359 detcore::encode_backend_config_json(legacy, config.backend)
3360}
3361
3362fn insert_legacy_dbt_detconfig_keys(serialized: &str) -> serde_json::Result<String> {
3369 use serde::de::MapAccess;
3370 use serde::ser::Error as _;
3371 use serde::ser::SerializeMap;
3372 use serde_json::value::RawValue;
3373
3374 struct Members<'a>(Vec<(&'a str, &'a RawValue)>);
3377
3378 impl<'de> serde::Deserialize<'de> for Members<'de> {
3379 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
3380 struct MembersVisitor;
3381 impl<'de> serde::de::Visitor<'de> for MembersVisitor {
3382 type Value = Members<'de>;
3383 fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3384 formatter.write_str("a serialized Detcore config object")
3385 }
3386 fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
3387 let mut members = Vec::new();
3388 while let Some(member) = map.next_entry()? {
3389 members.push(member);
3390 }
3391 Ok(Members(members))
3392 }
3393 }
3394 deserializer.deserialize_map(MembersVisitor)
3395 }
3396 }
3397
3398 impl serde::Serialize for Members<'_> {
3399 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
3400 let mut map = serializer.serialize_map(None)?;
3401 for (key, value) in &self.0 {
3402 for (legacy_key, fixed_value, anchor) in LEGACY_DBT_DETCONFIG_KEYS {
3403 if anchor == *key {
3404 map.serialize_entry(legacy_key, &fixed_value)?;
3405 }
3406 }
3407 map.serialize_entry(key, value)?;
3408 }
3409 map.end()
3410 }
3411 }
3412
3413 let members: Members<'_> = serde_json::from_str(serialized)?;
3414 for (legacy_key, _, anchor) in LEGACY_DBT_DETCONFIG_KEYS {
3415 let anchors = members.0.iter().filter(|(key, _)| *key == anchor).count();
3416 if anchors != 1 {
3417 return Err(serde_json::Error::custom(format!(
3418 "cannot place legacy DBT config key {legacy_key:?}: its anchor key {anchor:?} \
3419 appears {anchors} times, expected exactly once"
3420 )));
3421 }
3422 if members.0.iter().any(|(key, _)| *key == legacy_key) {
3423 return Err(serde_json::Error::custom(format!(
3424 "legacy DBT config key {legacy_key:?} is already present; it must come only \
3425 from the fixed legacy table"
3426 )));
3427 }
3428 }
3429 serde_json::to_string(&members)
3430}
3431
3432#[cfg(test)]
3433mod dbt_detconfig_tests {
3434 use std::path::PathBuf;
3435
3436 use clap::Parser;
3437 use detcore_model::config::MountInfoRootRewrite;
3438
3439 use super::Backend;
3440 use super::DetConfig;
3441 use super::dbt_detconfig_json;
3442 use super::insert_legacy_dbt_detconfig_keys;
3443 use super::prepare_backend_config;
3444
3445 const GOLDEN: [(&str, &str); 3] = [
3459 (
3460 "default",
3461 include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-default.json"),
3462 ),
3463 (
3464 "dbt",
3465 include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-dbt.json"),
3466 ),
3467 (
3468 "rich_dbt",
3469 include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-rich_dbt.json"),
3470 ),
3471 ];
3472
3473 fn env_free(epoch: &str, seed: &str) -> DetConfig {
3477 let mut config = DetConfig::parse_from(["hermit", epoch, seed, "--sched-seed=0"]);
3478 config.sched_seed = None;
3479 config
3480 }
3481
3482 fn default_config() -> DetConfig {
3483 env_free("--epoch=2026-01-01T00:00:00Z", "--seed=0")
3484 }
3485
3486 fn rich_config() -> DetConfig {
3490 let mut config = env_free("--epoch=2000-12-31T23:59:59Z", "--seed=7");
3491 config.rng_seed = Some(13);
3492 config.sched_seed = Some(11);
3493 config.clock_multiplier = Some(1.5);
3494 config.chaos = true;
3495 config.record_preemptions_to = Some(PathBuf::from(
3496 "/tmp/a,\"detect_host_clock_futex_timeouts\":true,\"backend_tracks_process_children\":{",
3497 ));
3498 config.mountinfo_root_rewrites = vec![MountInfoRootRewrite {
3499 raw_mount_id: 41,
3500 deterministic_root: b"/".to_vec(),
3501 raw_root_prefix: Some(b"/tmp/x".to_vec()),
3502 deterministic_root_prefix: Some(b"/tmp".to_vec()),
3503 raw_mountpoint_prefix: None,
3504 deterministic_mountpoint_prefix: None,
3505 }];
3506 config.stacktrace_event = vec![(3, Some(PathBuf::from("/s")))];
3507 config
3508 }
3509
3510 fn cases() -> [(&'static str, DetConfig); 3] {
3511 [
3512 ("default", default_config()),
3513 (
3514 "dbt",
3515 prepare_backend_config(default_config(), Backend::Dbt),
3516 ),
3517 (
3518 "rich_dbt",
3519 prepare_backend_config(rich_config(), Backend::Dbt),
3520 ),
3521 ]
3522 }
3523
3524 #[test]
3525 fn default_case_is_config_default_with_pinned_environment_fields() {
3526 let pinned = default_config();
3527 let from_default = DetConfig {
3528 epoch: pinned.epoch,
3529 seed: pinned.seed,
3530 sched_seed: pinned.sched_seed,
3531 ..DetConfig::default()
3532 };
3533 assert_eq!(
3534 serde_json::to_string(&from_default).unwrap(),
3535 serde_json::to_string(&pinned).unwrap()
3536 );
3537 }
3538
3539 #[test]
3540 fn dbt_detconfig_matches_806cf2fa_bytes() {
3541 for ((name, mut config), (golden_name, golden)) in cases().into_iter().zip(GOLDEN) {
3542 config.backend.tool_shares_guest_descriptor_table = false;
3545 config.backend.rediscovers_descriptors_after_exec = false;
3546 config.backend.supports_blocked_wait_signal_interruption = false;
3549 config.backend.delivers_preemption_timer_events = false;
3550 config.backend.runs_guest_code_between_injections = false;
3551 assert_eq!(name, golden_name);
3552 let encoded = dbt_detconfig_json(&config).unwrap();
3553 assert_eq!(
3554 encoded, golden,
3555 "HERMIT_DBT_DETCONFIG for the {name} config differs from the 806cf2fa bytes"
3556 );
3557 }
3558 }
3559
3560 #[test]
3567 fn dbt_detconfig_decodes_to_the_encoded_config() {
3568 for (name, config) in cases() {
3569 let encoded = dbt_detconfig_json(&config).unwrap();
3570 let decoded = detcore::decode_backend_config_json(&encoded)
3571 .unwrap_or_else(|error| panic!("{name}: DBT config does not decode: {error}"));
3572 assert_eq!(
3573 serde_json::to_string(&decoded).unwrap(),
3574 serde_json::to_string(&config).unwrap(),
3575 "{name}: decoded config differs from the encoded one"
3576 );
3577 }
3578 }
3579
3580 #[test]
3581 fn current_dbt_uses_exact_descriptor_facts_without_host_timed_turns() {
3582 let config = prepare_backend_config(default_config(), Backend::Dbt);
3583 assert!(config.backend.tool_shares_guest_descriptor_table);
3584 assert!(config.backend.rediscovers_descriptors_after_exec);
3585 assert!(!config.backend.internal_pipe_turns_are_host_timed);
3586 assert!(!config.backend.loopback_pollers_yield_to_peers);
3587 let encoded = dbt_detconfig_json(&config).unwrap();
3588 assert!(detcore::from_legacy_backend_json(&encoded).is_err());
3589 let decoded = detcore::decode_backend_config_json(&encoded).unwrap();
3590 assert_eq!(decoded.backend, reverie::BackendCapabilities::DBT);
3591 assert_eq!(decoded.backend, config.backend);
3592 }
3593
3594 #[test]
3595 fn dbt_detconfig_keeps_descriptor_facts_independent() {
3596 for mask in 0_u8..16 {
3600 let mut config = prepare_backend_config(default_config(), Backend::Dbt);
3601 config.backend.tool_shares_guest_descriptor_table = mask & 1 != 0;
3602 config.backend.rediscovers_descriptors_after_exec = mask & 2 != 0;
3603 config.backend.internal_pipe_turns_are_host_timed = mask & 4 != 0;
3604 config.backend.loopback_pollers_yield_to_peers = mask & 8 != 0;
3605 let encoded = dbt_detconfig_json(&config).unwrap();
3606 assert_eq!(
3607 detcore::from_legacy_backend_json(&encoded).is_ok(),
3608 mask == 0 || mask == 15,
3609 "only coupled facts fit the legacy form: mask {mask}"
3610 );
3611 let decoded = detcore::decode_backend_config_json(&encoded).unwrap();
3612 assert_eq!(decoded.backend, config.backend, "capability mask {mask}");
3613 assert_eq!(
3614 serde_json::to_string(&decoded).unwrap(),
3615 serde_json::to_string(&config).unwrap(),
3616 "configuration mask {mask}"
3617 );
3618 }
3619 }
3620
3621 #[test]
3622 fn representable_descriptor_facts_keep_the_current_config_bytes() {
3623 for discover in [false, true] {
3624 let mut config = prepare_backend_config(rich_config(), Backend::Dbt);
3625 config.backend.tool_shares_guest_descriptor_table = discover;
3626 config.backend.rediscovers_descriptors_after_exec = discover;
3627 config.backend.internal_pipe_turns_are_host_timed = discover;
3628 config.backend.loopback_pollers_yield_to_peers = discover;
3629 let legacy = detcore::to_legacy_backend_json(&config).unwrap();
3630 assert_eq!(
3631 dbt_detconfig_json(&config).unwrap(),
3632 insert_legacy_dbt_detconfig_keys(&legacy).unwrap()
3633 );
3634 }
3635 }
3636
3637 #[test]
3638 fn versioned_dbt_config_rejects_unknown_or_malformed_envelopes() {
3639 let config = prepare_backend_config(default_config(), Backend::Dbt);
3640 let legacy =
3641 insert_legacy_dbt_detconfig_keys(&detcore::to_legacy_backend_json(&config).unwrap())
3642 .unwrap();
3643 let legacy_backend = detcore::from_legacy_backend_json(&legacy).unwrap().backend;
3644 let backend = serde_json::to_string(&config.backend).unwrap();
3645 let envelope = |version: &str| {
3646 format!(
3647 "{{\"dbt_config_version\":{version},\"config\":{legacy},\"backend\":{backend}}}"
3648 )
3649 };
3650 for version in ["0", "2", "-1", "null", "\"1\""] {
3651 assert!(
3652 detcore::decode_backend_config_json(&envelope(version)).is_err(),
3653 "version {version} must be refused"
3654 );
3655 let tagged_legacy =
3656 legacy.replacen('{', &format!("{{\"dbt_config_version\":{version},"), 1);
3657 assert_eq!(
3658 detcore::decode_backend_config_json(&tagged_legacy)
3659 .unwrap()
3660 .backend,
3661 legacy_backend,
3662 "an unknown legacy key must remain ignored"
3663 );
3664 }
3665 let duplicate = format!(
3666 "{{\"dbt_config_version\":1,\"dbt_config_version\":1,\"config\":{legacy},\"backend\":{backend}}}"
3667 );
3668 assert!(detcore::decode_backend_config_json(&duplicate).is_err());
3669 let missing_backend = format!("{{\"dbt_config_version\":1,\"config\":{legacy}}}");
3670 assert!(detcore::decode_backend_config_json(&missing_backend).is_err());
3671 let missing_config = format!("{{\"dbt_config_version\":1,\"backend\":{backend}}}");
3672 assert!(detcore::decode_backend_config_json(&missing_config).is_err());
3673 for duplicate in [
3674 format!("\"config\":{legacy}"),
3675 format!("\"backend\":{backend}"),
3676 "\"unknown\":true".to_owned(),
3677 ] {
3678 let json = envelope("1").replacen('{', &format!("{{{duplicate},"), 1);
3679 assert!(detcore::decode_backend_config_json(&json).is_err());
3680 }
3681 }
3682
3683 #[test]
3684 fn legacy_key_insertion_refuses_a_missing_repeated_or_present_key() {
3685 let complete = r#"{"a":1,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
3686 assert_eq!(
3687 insert_legacy_dbt_detconfig_keys(complete).unwrap(),
3688 concat!(
3689 r#"{"a":1,"use_thread_local_clock_reads":false,"#,
3690 r#""detect_host_clock_futex_timeouts":false,"#,
3691 r#""backend_serializes_fork_children":false,"#,
3692 r#""backend_dispatches_thread_tools":true,"#,
3693 r#""backend_tracks_process_children":true}"#,
3694 )
3695 );
3696
3697 let missing = r#"{"detect_host_clock_futex_timeouts":false}"#;
3698 let error = insert_legacy_dbt_detconfig_keys(missing).unwrap_err();
3699 assert!(
3700 error.to_string().contains("appears 0 times"),
3701 "unexpected error: {error}"
3702 );
3703
3704 let repeated = r#"{"detect_host_clock_futex_timeouts":false,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
3705 let error = insert_legacy_dbt_detconfig_keys(repeated).unwrap_err();
3706 assert!(
3707 error.to_string().contains("appears 2 times"),
3708 "unexpected error: {error}"
3709 );
3710
3711 let present = r#"{"use_thread_local_clock_reads":true,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
3712 let error = insert_legacy_dbt_detconfig_keys(present).unwrap_err();
3713 assert!(
3714 error.to_string().contains("already present"),
3715 "unexpected error: {error}"
3716 );
3717 }
3718}
3719
3720#[cfg(feature = "dbt")]
3727fn dbt_launched_program(
3728 program: &std::path::Path,
3729 cwd: Option<&std::path::Path>,
3730 path: Option<&std::ffi::OsStr>,
3731 current: &std::path::Path,
3732) -> Option<(PathBuf, PathBuf)> {
3733 use std::os::unix::ffi::OsStrExt;
3734 use std::os::unix::fs::PermissionsExt;
3735 let cwd = cwd.map_or_else(|| current.to_owned(), |cwd| current.join(cwd));
3736 let spelled = if program.as_os_str().as_bytes().contains(&b'/') {
3737 program.to_owned()
3738 } else {
3739 std::env::split_paths(path?)
3740 .map(|directory| cwd.join(directory).join(program))
3741 .find(|candidate| {
3742 candidate.metadata().is_ok_and(|metadata| {
3743 metadata.is_file() && metadata.permissions().mode() & 0o111 != 0
3744 })
3745 })?
3746 };
3747 Some((spelled, cwd))
3748}
3749
3750#[cfg(all(test, feature = "dbt"))]
3751mod dbt_launched_program_tests {
3752 use std::os::unix::fs::PermissionsExt;
3753
3754 use super::*;
3755
3756 fn executable(path: &std::path::Path) {
3757 std::fs::create_dir_all(path.parent().unwrap()).unwrap();
3758 std::fs::write(path, b"").unwrap();
3759 std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).unwrap();
3760 }
3761
3762 #[test]
3763 fn a_relative_path_entry_is_taken_from_the_guests_directory_not_the_launchers() {
3764 let root = tempfile::tempdir().unwrap();
3765 let launcher_dir = root.path().join("launcher");
3766 executable(&launcher_dir.join("bin/prog"));
3769 executable(&root.path().join("guest/bin/prog"));
3770 std::fs::write(root.path().join("guest/plain"), b"").unwrap();
3771 let path = std::ffi::OsStr::new("bin");
3772 let found = |program: &str, cwd: Option<&str>| {
3773 dbt_launched_program(
3774 std::path::Path::new(program),
3775 cwd.map(std::path::Path::new),
3776 Some(path),
3777 &launcher_dir,
3778 )
3779 };
3780 let guest = root.path().join("guest");
3781 let expected = Some((guest.join("bin/prog"), guest.clone()));
3783 assert_eq!(found("prog", Some(guest.to_str().unwrap())), expected);
3784 assert_eq!(
3785 found("prog", Some("../guest")),
3786 Some((
3787 launcher_dir.join("../guest/bin/prog"),
3788 launcher_dir.join("../guest")
3789 ))
3790 );
3791 assert_eq!(
3793 found("prog", None),
3794 Some((launcher_dir.join("bin/prog"), launcher_dir.clone()))
3795 );
3796 assert_eq!(
3798 found("./plain", Some(guest.to_str().unwrap())),
3799 Some((std::path::PathBuf::from("./plain"), guest.clone()))
3800 );
3801 assert_eq!(found("plain", Some(guest.to_str().unwrap())), None);
3803 }
3804}
3805
3806#[cfg(feature = "dbt")]
3815pub fn record_dbt_launched_image(
3816 config: &mut DetConfig,
3817 program: &std::path::Path,
3818 cwd: Option<&std::path::Path>,
3819 path: Option<&std::ffi::OsStr>,
3820) {
3821 let exe = std::env::current_dir()
3822 .ok()
3823 .and_then(|current| dbt_launched_program(program, cwd, path, ¤t))
3824 .and_then(|(spelled, cwd)| {
3825 detcore::exec_record::ExecRecord::resolve(std::path::Path::new("/"), &cwd, &spelled)
3826 })
3827 .map(|record| record.exe);
3828 config
3829 .launch_image
3830 .get_or_insert(detcore::LaunchImage {
3831 exe: None,
3832 launcher: None,
3833 })
3834 .exe = exe;
3835}
3836
3837#[cfg(feature = "dbt")]
3848pub fn declare_dbt_launcher(config: &mut DetConfig, drrun: &std::path::Path) -> Result<(), Error> {
3849 let library = drrun
3850 .parent()
3851 .and_then(std::path::Path::parent)
3852 .unwrap_or(std::path::Path::new("/"))
3853 .join("lib64/release/libdynamorio.so");
3854 if !library.is_file() {
3855 return Err(anyhow!(
3856 "DynamoRIO's library is not at {} beside drrun {}",
3857 library.display(),
3858 drrun.display()
3859 ));
3860 }
3861 config
3862 .launch_image
3863 .get_or_insert(detcore::LaunchImage {
3864 exe: None,
3865 launcher: None,
3866 })
3867 .launcher = Some(library);
3868 Ok(())
3869}
3870
3871#[cfg(feature = "dbt")]
3875async fn run_dbt(
3876 command: Command,
3877 config: DetConfig,
3878 print_summary: bool,
3879 capture_output: bool,
3880) -> Result<Output, Error> {
3881 if !config.sequentialize_threads {
3882 return Err(anyhow!(
3883 "the dbt backend requires sequentialized threads; remove \
3884 --no-sequentialize-threads (or --strace-only) to run under --backend dbt"
3885 ));
3886 }
3887
3888 let (drrun, client) = detcore_dbt::prepare_native_client()
3895 .map_err(|error| anyhow!("failed to prepare the Detcore DynamoRIO client: {error}"))?;
3896 let mut config = config;
3897 declare_dbt_launcher(&mut config, &drrun)?;
3898 record_dbt_launched_image(
3899 &mut config,
3900 std::path::Path::new(command.get_program()),
3901 command.get_current_dir(),
3902 command
3903 .get_captured_envs()
3904 .get(std::ffi::OsStr::new("PATH"))
3905 .map(std::ffi::OsString::as_os_str),
3906 );
3907 let config_json = dbt_detconfig_json(&config)
3908 .map_err(|error| anyhow!("failed to serialize the Detcore config for DBT: {error}"))?;
3909 let panic_on_unsupported_syscalls = config.panic_on_unsupported_syscalls;
3910 let diagnostics = std::fs::File::from(
3912 std::io::stderr()
3913 .as_fd()
3914 .try_clone_to_owned()
3915 .map_err(|error| anyhow!("failed to retain DBT diagnostic stderr: {error}"))?,
3916 );
3917 let mut runner = reverie_dbt::DbtRunner::new(&drrun, &client)
3918 .map_err(|error| {
3919 anyhow!(
3920 "failed to configure the DynamoRIO DBT runner (drrun={}, client={}): {error}",
3921 drrun.display(),
3922 client.display()
3923 )
3924 })?
3925 .summary(print_summary)
3926 .isolated_process_group(panic_on_unsupported_syscalls)
3927 .tool_answers_brk(true)
3928 .diagnostic_file(&diagnostics)
3929 .map_err(|error| anyhow!("failed to configure DBT diagnostic stderr: {error}"))?;
3930 drop(diagnostics);
3931 if panic_on_unsupported_syscalls {
3932 runner = runner.client_argument("-panic-on-unsupported-syscalls");
3933 }
3934
3935 let program = command.get_program().to_owned();
3936 let mut environment = command.get_captured_envs();
3937 environment.insert(detcore_dbt::DETCONFIG_ENV.into(), config_json.into());
3938 let guest = command.into_std_lossy();
3939 tracing::info!(
3940 target: "hermit::dbt",
3941 program = ?program,
3942 drrun = %drrun.display(),
3943 client = %client.display(),
3944 "launching guest through reverie-dbt with Detcore<DbtGuest>",
3945 );
3946
3947 let (status, stdout, stderr, mut global) = if capture_output {
3948 let launch = || {
3949 runner.output_with_environment_and_global::<detcore::GlobalState>(
3950 &guest,
3951 &environment,
3952 config.clone(),
3953 )
3954 };
3955 let (mut output, mut global) = launch()
3956 .await
3957 .map_err(|error| anyhow!("failed to launch drrun ({}): {error}", drrun.display()))?;
3958 if dbt_client_thread_start_failed(&output.status) {
3959 tracing::warn!(
3960 target: "hermit::dbt",
3961 "DynamoRIO client thread failed before guest start; retrying once",
3962 );
3963 global.force_shutdown_with_error();
3964 global.cancel_internal_scheduler().await;
3965 global.clean_up(false, &None).await;
3966 (output, global) = launch().await.map_err(|error| {
3967 anyhow!("failed to launch drrun ({}): {error}", drrun.display())
3968 })?;
3969 }
3970 (output.status, output.stdout, output.stderr, global)
3971 } else {
3972 let launch = || {
3973 runner.status_with_environment_and_global::<detcore::GlobalState>(
3974 &guest,
3975 &environment,
3976 config.clone(),
3977 )
3978 };
3979 let (mut status, mut global) = launch()
3980 .await
3981 .map_err(|error| anyhow!("failed to launch drrun ({}): {error}", drrun.display()))?;
3982 if dbt_client_thread_start_failed(&status) {
3983 tracing::warn!(
3984 target: "hermit::dbt",
3985 "DynamoRIO client thread failed before guest start; retrying once",
3986 );
3987 global.force_shutdown_with_error();
3988 global.cancel_internal_scheduler().await;
3989 global.clean_up(false, &None).await;
3990 (status, global) = launch().await.map_err(|error| {
3991 anyhow!("failed to launch drrun ({}): {error}", drrun.display())
3992 })?;
3993 }
3994 (status, Vec::new(), Vec::new(), global)
3995 };
3996
3997 if !status.success() {
3998 global.force_shutdown_with_error();
3999 global.cancel_internal_scheduler().await;
4000 }
4001 global.clean_up(print_summary, &None).await;
4002 Ok(Output {
4003 status: status.into(),
4004 stdout,
4005 stderr,
4006 })
4007}
4008
4009pub fn run(
4041 command: Command,
4042 config: DetConfig,
4043 print_summary: bool,
4044 print_summary_to_json_file: &Option<PathBuf>,
4045) -> Result<ExitStatus, Error> {
4046 run_with_backend(
4047 command,
4048 config,
4049 print_summary,
4050 print_summary_to_json_file,
4051 Backend::Ptrace,
4052 )
4053}
4054
4055pub fn run_with_backend(
4059 command: Command,
4060 config: DetConfig,
4061 print_summary: bool,
4062 print_summary_to_json_file: &Option<PathBuf>,
4063 backend: Backend,
4064) -> Result<ExitStatus, Error> {
4065 run_with_backend_timeout(
4066 command,
4067 config,
4068 print_summary,
4069 print_summary_to_json_file,
4070 backend,
4071 None,
4072 )
4073}
4074
4075pub fn run_with_backend_timeout(
4094 command: Command,
4095 config: DetConfig,
4096 print_summary: bool,
4097 print_summary_to_json_file: &Option<PathBuf>,
4098 backend: Backend,
4099 timeout: Option<Duration>,
4100) -> Result<ExitStatus, Error> {
4101 if backend == Backend::Ptrace {
4102 let summary_path = print_summary_to_json_file.clone();
4103 let command = tracer_thread::SendCommand::new(command);
4104 return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
4105 let command = command.into_inner();
4106 let report = SkidOvershootReport::begin(true);
4107 let config = prepare_backend_config(config, backend);
4108 let result = dispatch_backend(
4109 command,
4110 config,
4111 print_summary,
4112 &summary_path,
4113 backend,
4114 Some(control),
4115 )
4116 .await;
4117 report.finish(result)
4118 });
4119 }
4120 let skid_overshoot_report = SkidOvershootReport::begin(backend.uses_ptrace_pmu_timers());
4121 if backend == Backend::Kvm {
4122 ensure_kvm_stdin_reserved()?;
4123 }
4124 let config = prepare_backend_config(config, backend);
4125 let result = run_with_backend_inner(
4126 command,
4127 config,
4128 print_summary,
4129 print_summary_to_json_file,
4130 backend,
4131 timeout,
4132 );
4133 skid_overshoot_report.finish(result)
4134}
4135
4136#[doc(hidden)]
4138pub fn prepare_backend_config(mut config: DetConfig, backend: Backend) -> DetConfig {
4139 config.backend = backend_capabilities(backend);
4162 config.guest_may_inherit_a_terminal =
4181 bundled_signal_facts::host_timed_signal_sources_are_physical(&config.backend)
4182 && launcher_may_pass_a_terminal();
4183 config
4184}
4185
4186fn launcher_may_pass_a_terminal() -> bool {
4195 let standard_terminal = (0..=2).any(|fd| unsafe { libc::isatty(fd) } == 1);
4197 may_pass_a_terminal(standard_terminal, controlling_terminal_device())
4198}
4199
4200fn may_pass_a_terminal(standard_terminal: bool, controlling_terminal: Option<i64>) -> bool {
4203 standard_terminal || controlling_terminal != Some(0)
4204}
4205
4206fn controlling_terminal_device() -> Option<i64> {
4210 parse_controlling_terminal_device(&std::fs::read_to_string("/proc/self/stat").ok()?)
4211}
4212
4213fn parse_controlling_terminal_device(stat: &str) -> Option<i64> {
4217 let after_command = stat.get(stat.rfind(')')? + 1..)?;
4218 after_command.split_ascii_whitespace().nth(4)?.parse().ok()
4219}
4220
4221#[doc(hidden)]
4227pub fn backend_capabilities(backend: Backend) -> reverie::BackendCapabilities {
4228 match backend {
4229 Backend::Ptrace | Backend::E9patch => {
4234 <reverie_ptrace::PtraceBackend as reverie::Backend>::capabilities()
4235 }
4236 Backend::Kvm => reverie_kvm::KvmBackend::capabilities(),
4237 Backend::Liteinst | Backend::InGuestTrap => reverie::BackendCapabilities::LITEINST_IN_GUEST,
4240 Backend::Sabre => reverie::BackendCapabilities::SABRE,
4241 Backend::Dbt => reverie::BackendCapabilities::DBT,
4242 }
4243}
4244
4245pub fn backend_delivers_preemption_timer(backend: Backend) -> bool {
4251 backend_capabilities(backend).delivers_preemption_timer_events
4252}
4253
4254#[cfg(feature = "liteinst")]
4268async fn settle_in_guest_exits(
4269 exits: &in_guest_exits::InGuestExitAdmission,
4270 global_state: &detcore::GlobalState,
4271) -> Result<(), Error> {
4272 let drained = exits.drain(std::time::Duration::from_secs(10)).await;
4273 for pid in exits.reported_exits() {
4274 global_state.complete_physical_process_exit(pid);
4275 }
4276 global_state.release_all_physical_process_exits();
4277 let failure = exits.failure().or_else(|| {
4278 drained
4279 .err()
4280 .map(|error| format!("not every in-guest LiteInst guest exit was reported: {error:?}"))
4281 });
4282 match failure {
4283 Some(reason) => {
4284 detcore::detlog::record_determinism_loss(&reason);
4285 Err(Error::msg(reason))
4286 }
4287 None => Ok(()),
4288 }
4289}
4290
4291#[cfg(feature = "liteinst")]
4324fn liteinst_requires_forced_shutdown(status: ExitStatus) -> bool {
4325 match status {
4326 ExitStatus::Signaled(_, _) | ExitStatus::SignaledRaw(_, _) => true,
4328 ExitStatus::Exited(code) => {
4329 (122..=127).contains(&code) || detcore_model::signal_from_exit_status(code).is_some()
4332 }
4333 }
4334}
4335
4336#[derive(Debug)]
4342pub struct GuestTimedOut {
4343 pub limit: Duration,
4345}
4346
4347impl std::fmt::Display for GuestTimedOut {
4348 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4349 write!(
4350 f,
4351 "Guest exceeded the --timeout bound of {} seconds",
4352 self.limit.as_secs()
4353 )
4354 }
4355}
4356
4357impl std::error::Error for GuestTimedOut {}
4358
4359async fn with_run_deadline<F>(timeout: Option<Duration>, guest: F) -> Result<ExitStatus, Error>
4365where
4366 F: std::future::Future<Output = Result<ExitStatus, Error>>,
4367{
4368 match timeout {
4369 None => guest.await,
4370 Some(limit) => match tokio::time::timeout(limit, guest).await {
4371 Ok(result) => result,
4372 Err(_) => Err(Error::new(GuestTimedOut { limit })),
4373 },
4374 }
4375}
4376
4377#[tokio::main(flavor = "current_thread")]
4378async fn run_with_backend_inner(
4379 command: Command,
4380 config: DetConfig,
4381 print_summary: bool,
4382 print_summary_to_json_file: &Option<PathBuf>,
4383 backend: Backend,
4384 timeout: Option<Duration>,
4385) -> Result<ExitStatus, Error> {
4386 refuse_in_guest_liteinst_timeout(backend, timeout)?;
4387 let guest = Box::pin(dispatch_backend(
4391 command,
4392 config,
4393 print_summary,
4394 print_summary_to_json_file,
4395 backend,
4396 None,
4397 ));
4398 with_run_deadline(timeout, guest).await
4399}
4400
4401fn launched_image(command: &Command) -> Option<detcore::LaunchImage> {
4409 let program = command.find_program().ok()?;
4410 let cwd = match command.get_current_dir() {
4411 Some(cwd) => cwd.to_owned(),
4412 None => std::env::current_dir().ok()?,
4413 };
4414 let record = detcore::exec_record::ExecRecord::resolve(Path::new("/"), &cwd, &program)?;
4415 Some(detcore::LaunchImage {
4416 exe: Some(record.exe),
4417 launcher: None,
4418 })
4419}
4420
4421async fn dispatch_backend(
4422 command: Command,
4423 mut config: DetConfig,
4424 print_summary: bool,
4425 print_summary_to_json_file: &Option<PathBuf>,
4426 backend: Backend,
4427 control: Option<std::rc::Rc<ptrace_completion::Control>>,
4428) -> Result<ExitStatus, Error> {
4429 crate::cpu_profile_admission::refuse_unadmitted_launch(&config, backend == Backend::Ptrace)?;
4431 config.launch_image = launched_image(&command);
4432 if backend == Backend::Kvm {
4433 return Ok(run_kvm(
4434 &command,
4435 config,
4436 print_summary,
4437 print_summary_to_json_file,
4438 false,
4439 )
4440 .await?
4441 .status);
4442 }
4443 if backend == Backend::Dbt {
4444 #[cfg(feature = "dbt")]
4445 {
4446 return Ok(run_dbt(command, config, print_summary, false).await?.status);
4447 }
4448 #[cfg(not(feature = "dbt"))]
4449 {
4450 backend.ensure_available()?;
4451 unreachable!("DBT availability must fail when the feature is disabled");
4452 }
4453 }
4454 if backend == Backend::Sabre {
4455 return Ok(run_sabre(
4456 command,
4457 config,
4458 print_summary,
4459 print_summary_to_json_file,
4460 false,
4461 )
4462 .await?
4463 .status);
4464 }
4465 if backend.is_in_guest_liteinst() {
4466 #[cfg(feature = "liteinst")]
4467 {
4468 let stats_request = in_guest_stats_request(backend, print_summary_to_json_file);
4469 let mut command = command;
4470 refuse_in_guest_liteinst_run(&mut command, &config, backend)?;
4471 let (launch, _detlog_descriptor) =
4472 in_guest_liteinst_launch(&mut command, &in_guest_detlog_forward_policy())?;
4473 let tool_data = launch.encode();
4474 let mut config = config;
4477 config.in_guest_detlog_forward_policy = _detlog_descriptor
4478 .is_some()
4479 .then(|| in_guest_detlog_forward_policy().encode());
4480 config.in_guest_site_patching_off = in_guest_site_patching_off(backend);
4481 let preload = liteinst_tool_runtime_library_path()?;
4482 let exits = std::sync::Arc::new(in_guest_exits::InGuestExitAdmission::default());
4483 let (exit_status, mut global_state, dispatch_stats, process_reports) =
4484 reverie_liteinst::LiteinstBackend::with_connection_admission(
4485 exits.clone(),
4486 async {
4487 if stats_request.is_enabled() {
4488 let (exit_status, global_state, source) =
4489 reverie_liteinst::LiteinstBackend::run_with_preload_data_and_stats::<
4490 Detcore,
4491 >(command, config, preload, tool_data)
4492 .await?;
4493 let dispatch_stats =
4494 backend_stats::report(backend, stats_request, &source);
4495 let process_reports = source.snapshot().process_reports();
4496 Ok::<_, reverie::Error>((
4497 exit_status,
4498 global_state,
4499 dispatch_stats,
4500 process_reports,
4501 ))
4502 } else {
4503 let (exit_status, global_state) =
4504 reverie_liteinst::LiteinstBackend::run_with_preload_data::<Detcore>(
4505 command, config, preload, tool_data,
4506 )
4507 .await?;
4508 Ok((exit_status, global_state, None, 0))
4509 }
4510 },
4511 )
4512 .await
4513 .inspect_err(|error| exits.fail_launch(error))?;
4514 let patched =
4515 in_guest_trap_patching_evidence(backend, dispatch_stats.as_ref(), process_reports);
4516 let settled = settle_in_guest_exits(&exits, &global_state).await;
4517 let policy_refusal = global_state.policy_refusal();
4518 if settled.is_err() || liteinst_requires_forced_shutdown(exit_status) {
4519 global_state.force_shutdown_with_error();
4520 global_state.cancel_internal_scheduler().await;
4521 }
4522 global_state
4523 .clean_up_with_dispatch_stats(
4524 print_summary,
4525 print_summary_to_json_file,
4526 dispatch_stats,
4527 )
4528 .await;
4529 refuse_in_guest_policy(backend, policy_refusal)?;
4530 settled?;
4531 refuse_in_guest_trap_patching(backend, patched)?;
4532 return Ok(exit_status);
4533 }
4534 #[cfg(not(feature = "liteinst"))]
4535 {
4536 backend.ensure_available()?;
4537 unreachable!("LiteInst availability must fail when the feature is disabled");
4538 }
4539 }
4540 ensure_backend_dispatch(backend)?;
4541
4542 let stats_request = backend_stats::request(print_summary_to_json_file);
4543 let control = control
4544 .ok_or_else(|| Error::msg("ordinary ptrace requires its retained operation owner"))?;
4545 let tracer = hermit_run_ptrace::spawn_tracer(
4548 command,
4549 config.clone(),
4550 config.gdbserver.then_some(config.gdbserver_port),
4551 config.sequentialize_threads,
4552 stats_request,
4553 )
4554 .await?;
4555 let stats_source = tracer.backend_stats();
4556 let (exit_status, global_state) = ptrace_completion::wait(tracer, control).await?;
4557 let dispatch_stats =
4558 backend_stats::report_if_collected(backend, stats_request, stats_source.as_ref());
4559 global_state
4560 .clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
4561 .await; Ok(exit_status)
4563}
4564
4565pub fn run_with_output(
4569 command: Command,
4570 config: DetConfig,
4571 print_summary: bool,
4572 print_summary_to_json_file: &Option<PathBuf>,
4573) -> Result<Output, Error> {
4574 run_with_output_backend(
4575 command,
4576 config,
4577 print_summary,
4578 print_summary_to_json_file,
4579 Backend::Ptrace,
4580 )
4581}
4582
4583pub fn run_with_output_backend(
4587 command: Command,
4588 config: DetConfig,
4589 print_summary: bool,
4590 print_summary_to_json_file: &Option<PathBuf>,
4591 backend: Backend,
4592) -> Result<Output, Error> {
4593 if backend == Backend::Kvm {
4594 ensure_kvm_stdin_reserved()?;
4595 }
4596 run_with_output_backend_timeout(
4597 command,
4598 config,
4599 print_summary,
4600 print_summary_to_json_file,
4601 backend,
4602 None,
4603 )
4604}
4605
4606pub fn run_with_output_backend_timeout(
4611 command: Command,
4612 config: DetConfig,
4613 print_summary: bool,
4614 print_summary_to_json_file: &Option<PathBuf>,
4615 backend: Backend,
4616 timeout: Option<Duration>,
4617) -> Result<Output, Error> {
4618 if backend == Backend::Ptrace {
4619 let summary_path = print_summary_to_json_file.clone();
4620 let command = tracer_thread::SendCommand::new(command);
4621 return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
4622 let command = command.into_inner();
4623 let report = SkidOvershootReport::begin(true);
4624 let result = Box::pin(dispatch_output_backend(
4627 command,
4628 prepare_backend_config(config, backend),
4629 print_summary,
4630 &summary_path,
4631 backend,
4632 Some(control),
4633 ))
4634 .await;
4635 report.finish(result)
4636 });
4637 }
4638 let (output, skid_overshoots) = run_with_output_backend_timeout_and_skid_overshoots(
4639 command,
4640 config,
4641 print_summary,
4642 print_summary_to_json_file,
4643 backend,
4644 timeout,
4645 )?;
4646 if skid_overshoots > 0 {
4647 return Err(Error::new(SkidOvershootError::new(skid_overshoots)));
4648 }
4649 Ok(output)
4650}
4651
4652#[doc(hidden)]
4657pub fn run_with_output_backend_timeout_and_skid_overshoots(
4658 command: Command,
4659 config: DetConfig,
4660 print_summary: bool,
4661 print_summary_to_json_file: &Option<PathBuf>,
4662 backend: Backend,
4663 timeout: Option<Duration>,
4664) -> Result<(Output, u64), Error> {
4665 if backend == Backend::Ptrace {
4666 let summary_path = print_summary_to_json_file.clone();
4667 let command = tracer_thread::SendCommand::new(command);
4668 return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
4669 let command = command.into_inner();
4670 let report = SkidOvershootReport::begin(true);
4671 let result = Box::pin(dispatch_output_backend(
4672 command,
4673 prepare_backend_config(config, backend),
4674 print_summary,
4675 &summary_path,
4676 backend,
4677 Some(control),
4678 ))
4679 .await;
4680 report.finish_with_count(result)
4681 });
4682 }
4683 let skid_overshoot_report = SkidOvershootReport::begin(backend.uses_ptrace_pmu_timers());
4684 if backend == Backend::Kvm {
4685 ensure_kvm_stdin_reserved()?;
4689 }
4690 let config = prepare_backend_config(config, backend);
4691 let result = run_with_output_backend_inner(
4692 command,
4693 config,
4694 print_summary,
4695 print_summary_to_json_file,
4696 backend,
4697 timeout,
4698 );
4699 skid_overshoot_report.finish_with_count(result)
4700}
4701
4702#[tokio::main(flavor = "current_thread")]
4703async fn run_with_output_backend_inner(
4704 command: Command,
4705 config: DetConfig,
4706 print_summary: bool,
4707 print_summary_to_json_file: &Option<PathBuf>,
4708 backend: Backend,
4709 timeout: Option<Duration>,
4710) -> Result<Output, Error> {
4711 refuse_in_guest_liteinst_timeout(backend, timeout)?;
4712 let guest = Box::pin(dispatch_output_backend(
4715 command,
4716 config,
4717 print_summary,
4718 print_summary_to_json_file,
4719 backend,
4720 None,
4721 ));
4722 match timeout {
4723 None => guest.await,
4724 Some(limit) => match tokio::time::timeout(limit, guest).await {
4725 Ok(result) => result,
4726 Err(_elapsed) => Err(Error::new(GuestTimedOut { limit })),
4727 },
4728 }
4729}
4730
4731async fn dispatch_output_backend(
4732 mut command: Command,
4733 mut config: DetConfig,
4734 print_summary: bool,
4735 print_summary_to_json_file: &Option<PathBuf>,
4736 backend: Backend,
4737 control: Option<std::rc::Rc<ptrace_completion::Control>>,
4738) -> Result<Output, Error> {
4739 crate::cpu_profile_admission::refuse_unadmitted_launch(&config, backend == Backend::Ptrace)?;
4741 config.launch_image = launched_image(&command);
4742 if backend == Backend::Kvm {
4743 return run_kvm(
4744 &command,
4745 config,
4746 print_summary,
4747 print_summary_to_json_file,
4748 true,
4749 )
4750 .await;
4751 }
4752 if backend == Backend::Dbt {
4753 #[cfg(feature = "dbt")]
4754 {
4755 return run_dbt(command, config, print_summary, true).await;
4756 }
4757 #[cfg(not(feature = "dbt"))]
4758 {
4759 backend.ensure_available()?;
4760 unreachable!("DBT availability must fail when the feature is disabled");
4761 }
4762 }
4763 if backend == Backend::Sabre {
4764 #[cfg(not(feature = "sabre"))]
4765 backend.ensure_available()?;
4766 command.stdin(output_backend_stdin()?);
4767 command.stdout(Stdio::piped());
4768 command.stderr(Stdio::piped());
4769 return run_sabre(
4770 command,
4771 config,
4772 print_summary,
4773 print_summary_to_json_file,
4774 true,
4775 )
4776 .await;
4777 }
4778 if backend.is_in_guest_liteinst() {
4779 #[cfg(feature = "liteinst")]
4780 {
4781 command.stdin(output_backend_stdin()?);
4782 let stats_request = in_guest_stats_request(backend, print_summary_to_json_file);
4783 refuse_in_guest_liteinst_run(&mut command, &config, backend)?;
4784 let (launch, _detlog_descriptor) =
4785 in_guest_liteinst_launch(&mut command, &in_guest_detlog_forward_policy())?;
4786 let tool_data = launch.encode();
4787 let mut config = config;
4790 config.in_guest_detlog_forward_policy = _detlog_descriptor
4791 .is_some()
4792 .then(|| in_guest_detlog_forward_policy().encode());
4793 config.in_guest_site_patching_off = in_guest_site_patching_off(backend);
4794 let preload = liteinst_tool_runtime_library_path()?;
4795 let exits = std::sync::Arc::new(in_guest_exits::InGuestExitAdmission::default());
4796 let (output, mut global_state, dispatch_stats, process_reports) =
4797 reverie_liteinst::LiteinstBackend::with_connection_admission(exits.clone(), async {
4798 if stats_request.is_enabled() {
4799 let (output, global_state, source) =
4800 reverie_liteinst::LiteinstBackend::run_with_output_and_preload_data_and_stats::<
4801 Detcore,
4802 >(command, config, preload, tool_data)
4803 .await?;
4804 let dispatch_stats = backend_stats::report(backend, stats_request, &source);
4805 let process_reports = source.snapshot().process_reports();
4806 Ok::<_, reverie::Error>((output, global_state, dispatch_stats, process_reports))
4807 } else {
4808 let (output, global_state) =
4809 reverie_liteinst::LiteinstBackend::run_with_output_and_preload_data::<
4810 Detcore,
4811 >(command, config, preload, tool_data)
4812 .await?;
4813 Ok((output, global_state, None, 0))
4814 }
4815 })
4816 .await
4817 .inspect_err(|error| exits.fail_launch(error))?;
4818 let patched =
4819 in_guest_trap_patching_evidence(backend, dispatch_stats.as_ref(), process_reports);
4820 let settled = settle_in_guest_exits(&exits, &global_state).await;
4821 let policy_refusal = global_state.policy_refusal();
4822 let output = Output {
4823 status: output.status.into(),
4824 stdout: output.stdout,
4825 stderr: output.stderr,
4826 };
4827 let status = output.status;
4828 if settled.is_err() || liteinst_requires_forced_shutdown(status) {
4829 global_state.force_shutdown_with_error();
4830 global_state.cancel_internal_scheduler().await;
4831 }
4832 global_state
4833 .clean_up_with_dispatch_stats(
4834 print_summary,
4835 print_summary_to_json_file,
4836 dispatch_stats,
4837 )
4838 .await;
4839 refuse_in_guest_policy(backend, policy_refusal)?;
4840 settled?;
4841 refuse_in_guest_trap_patching(backend, patched)?;
4842 return Ok(Output {
4843 status,
4844 stdout: output.stdout,
4845 stderr: output.stderr,
4846 });
4847 }
4848 #[cfg(not(feature = "liteinst"))]
4849 {
4850 backend.ensure_available()?;
4851 unreachable!("LiteInst availability must fail when the feature is disabled");
4852 }
4853 }
4854 ensure_backend_dispatch(backend)?;
4855
4856 let stats_request = backend_stats::request(print_summary_to_json_file);
4857 command.stdin(output_backend_stdin()?);
4858 command.stdout(Stdio::piped());
4859 command.stderr(Stdio::piped());
4860 let control = control
4861 .ok_or_else(|| Error::msg("ordinary ptrace requires its retained operation owner"))?;
4862 let tracer = hermit_run_ptrace::spawn_tracer(
4865 command,
4866 config.clone(),
4867 config.gdbserver.then_some(config.gdbserver_port),
4868 config.sequentialize_threads,
4869 stats_request,
4870 )
4871 .await?;
4872 let stats_source = tracer.backend_stats();
4873 let (output, global_state) = ptrace_completion::wait_with_output(tracer, control).await?;
4874 let dispatch_stats =
4875 backend_stats::report_if_collected(backend, stats_request, stats_source.as_ref());
4876 global_state
4877 .clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
4878 .await;
4879 Ok(output)
4880}
4881
4882pub struct HermitData {
4884 data_dir: PathBuf,
4887}
4888
4889fn collect_recording_ids(
4890 entries: impl IntoIterator<Item = io::Result<fs::DirEntry>>,
4891 data_dir: &Path,
4892 mut file_type: impl FnMut(&fs::DirEntry) -> io::Result<fs::FileType>,
4893) -> Result<Vec<Id>, Error> {
4894 let mut recordings = Vec::new();
4895 for entry in entries {
4896 let entry = entry.with_context(|| {
4897 format!(
4898 "Failed to read an entry in recording inventory {}",
4899 data_dir.display()
4900 )
4901 })?;
4902 let path = entry.path();
4903 if file_type(&entry)
4904 .with_context(|| {
4905 format!(
4906 "Failed to inspect recording inventory entry {}",
4907 path.display()
4908 )
4909 })?
4910 .is_dir()
4911 && let Some(id) = entry
4912 .file_name()
4913 .to_str()
4914 .and_then(|name| name.parse::<Id>().ok())
4915 {
4916 recordings.push(id);
4917 }
4918 }
4919 Ok(recordings)
4920}
4921
4922impl Default for HermitData {
4923 fn default() -> Self {
4924 Self::new()
4925 }
4926}
4927
4928impl HermitData {
4929 pub fn new() -> Self {
4932 Self::with_dir(
4933 dirs::cache_dir()
4934 .map_or_else(|| PathBuf::from("/tmp/hermit"), |dir| dir.join("hermit")),
4935 )
4936 }
4937
4938 pub fn with_dir<P>(data_dir: P) -> Self
4941 where
4942 P: Into<PathBuf>,
4943 {
4944 Self {
4945 data_dir: data_dir.into(),
4946 }
4947 }
4948
4949 pub fn data_dir(&self) -> &Path {
4951 &self.data_dir
4952 }
4953
4954 pub fn record(&self, command: Command) -> Result<Recording, Error> {
4969 let store = Self {
4970 data_dir: self.data_dir.clone(),
4971 };
4972 let command = tracer_thread::SendCommand::new(command);
4973 ptrace_completion::run_on_tracer_thread(None, move |control| async move {
4974 let command = command.into_inner();
4975 let data = store.create_recording_dir()?;
4976 let exit_status = record_to_async(
4977 command,
4978 data.path(),
4979 MountProvenance::default(),
4980 None,
4981 None,
4982 None,
4983 detcore_model::cpu_profile::CpuProfile::default(),
4984 control,
4985 )
4986 .await?;
4987 store.commit_recording(data, exit_status)
4988 })
4989 }
4990
4991 pub fn record_with_mountinfo(
4996 &self,
4997 command: Command,
4998 mountinfo_root_rewrites: Vec<detcore_model::config::MountInfoRootRewrite>,
4999 ) -> Result<Recording, Error> {
5000 let store = Self {
5001 data_dir: self.data_dir.clone(),
5002 };
5003 let command = tracer_thread::SendCommand::new(command);
5004 ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5005 let command = command.into_inner();
5006 let data = store.create_recording_dir()?;
5007 let mount_ids = capture_mountinfo_identity_order()?;
5008 let exit_status = record_to_async(
5009 command,
5010 data.path(),
5011 MountProvenance {
5012 root_rewrites: mountinfo_root_rewrites,
5013 container_mount_table: None,
5014 mount_ids: None,
5015 },
5016 Some(mount_ids),
5017 None,
5018 None,
5019 detcore_model::cpu_profile::CpuProfile::default(),
5020 control,
5021 )
5022 .await?;
5023 store.commit_recording(data, exit_status)
5024 })
5025 }
5026
5027 pub fn create_recording_dir(&self) -> Result<tempfile::TempDir, Error> {
5029 let tmp_data_dir = self.data_dir.join("tmp");
5030
5031 fs::create_dir_all(&tmp_data_dir).with_context(|| {
5032 format!(
5033 "Failed to create recording directory: {}",
5034 self.data_dir.display()
5035 )
5036 })?;
5037
5038 Ok(tempfile::TempDir::new_in(tmp_data_dir)?)
5039 }
5040
5041 pub fn commit_recording(
5043 &self,
5044 data: tempfile::TempDir,
5045 exit_status: ExitStatus,
5046 ) -> Result<Recording, Error> {
5047 let id = Id::unique();
5048
5049 fs::rename(data.keep(), self.data_dir.join(id.to_string()))?;
5051
5052 self.note_latest(&id, true)
5053 .with_context(|| format!("Failed to update {:?}", self.data_dir.join(LAST)))?;
5054
5055 Ok(Recording { id, exit_status })
5056 }
5057
5058 pub fn replay(&self, id: Id) -> Result<ExitStatus, Error> {
5063 let data = self.data_dir.join(id.to_string());
5064 replay_from(&data)
5065 }
5066
5067 pub fn replay_with_gdbserver(&self, id: Id, port: u16) -> Result<ExitStatus, Error> {
5072 let data = self.data_dir.join(id.to_string());
5073 replay_with_gdbserver(&data, port)
5074 }
5075
5076 pub fn recordings(&self) -> impl Iterator<Item = Id> + use<> {
5080 fs::read_dir(&self.data_dir)
5081 .ok()
5082 .into_iter()
5083 .flatten()
5084 .filter_map(|entry| {
5085 let entry = entry.ok()?;
5086
5087 if entry.file_type().ok()?.is_dir() {
5088 Some(entry.file_name().to_str()?.parse::<Id>().ok()?)
5089 } else {
5090 None
5091 }
5092 })
5093 }
5094
5095 pub fn try_recordings(&self) -> Result<Vec<Id>, Error> {
5101 let entries = match fs::read_dir(&self.data_dir) {
5102 Ok(entries) => entries,
5103 Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
5104 Err(error) => {
5105 return Err(error).with_context(|| {
5106 format!(
5107 "Failed to read recording inventory in {}",
5108 self.data_dir.display()
5109 )
5110 });
5111 }
5112 };
5113
5114 collect_recording_ids(entries, &self.data_dir, fs::DirEntry::file_type)
5115 }
5116
5117 pub fn recording_metadata(&self, id: Id) -> Result<Metadata, Error> {
5119 Metadata::load(&self.data_dir.join(id.to_string()))
5120 }
5121
5122 pub fn remove(&self, id: Id) -> Result<(), Error> {
5124 let path = self.data_dir.join(id.to_string());
5125
5126 let metadata_path = [METADATA_NAME, RUN_MANIFEST_NAME]
5131 .into_iter()
5132 .map(|name| path.join(name))
5133 .find(|marker| marker.exists())
5134 .unwrap_or_else(|| path.join(METADATA_NAME));
5135 let metadata = fs::metadata(&metadata_path)
5136 .with_context(|| format!("Failed to find {:?}", metadata_path))?;
5137
5138 if !metadata.is_file() {
5139 return Err(anyhow!("{:?} is not a file", metadata_path));
5140 }
5141
5142 fs::remove_dir_all(path)?;
5145
5146 Ok(())
5147 }
5148
5149 pub fn last_id(&self) -> Result<Id, Error> {
5151 Ok(fs::read_to_string(self.data_dir.join(LAST))?.parse()?)
5152 }
5153
5154 pub fn note_latest(&self, id: &Id, asked: bool) -> Result<(), Error> {
5160 let tmp = self.data_dir.join("tmp");
5161 fs::create_dir_all(&tmp)?;
5162 let names = if asked {
5163 &[LAST_RUN, LAST][..]
5164 } else {
5165 &[LAST_RUN][..]
5166 };
5167 for name in names {
5168 let mut file = tempfile::NamedTempFile::new_in(&tmp)?;
5169 write!(file, "{}", id)?;
5170 file.persist(self.data_dir.join(name))?;
5171 }
5172 Ok(())
5173 }
5174}
5175
5176#[derive(Clone, Debug, Default)]
5179pub struct MountProvenance {
5180 pub root_rewrites: Vec<detcore_model::config::MountInfoRootRewrite>,
5183 pub container_mount_table: Option<detcore_model::container_mounts::ContainerMountTable>,
5187 pub mount_ids: Option<Vec<u64>>,
5194}
5195
5196const NS_GET_MNTNS_ID: libc::c_ulong = (2 << 30) | (8 << 16) | (0xb7 << 8) | 5;
5198
5199pub fn current_mount_namespace() -> Result<detcore_model::config::MountNamespaceIdentity, Error> {
5208 use std::os::fd::AsRawFd;
5209 use std::os::unix::fs::MetadataExt;
5210 let file = fs::File::open("/proc/thread-self/ns/mnt")
5211 .context("failed to open this thread's mount namespace")?;
5212 let metadata = file
5213 .metadata()
5214 .context("failed to read this process's mount namespace")?;
5215 let mut id: u64 = 0;
5216 let id =
5219 if unsafe { libc::ioctl(file.as_raw_fd(), NS_GET_MNTNS_ID, &mut id as *mut u64) } == 0 {
5220 Some(id)
5221 } else {
5222 let error = std::io::Error::last_os_error();
5223 match error.raw_os_error() {
5224 Some(libc::ENOTTY | libc::EINVAL) => None,
5225 _ => {
5226 return Err(Error::new(error)
5227 .context("failed to read this process's mount namespace ID"));
5228 }
5229 }
5230 };
5231 Ok(detcore_model::config::MountNamespaceIdentity {
5232 id,
5233 device: metadata.dev(),
5234 inode: metadata.ino(),
5235 })
5236}
5237
5238pub fn thread_mountinfo() -> Result<Vec<u8>, Error> {
5241 fs::read("/proc/thread-self/mountinfo")
5242 .context("Failed to read this thread's mount table (/proc/thread-self/mountinfo)")
5243}
5244
5245fn thread_mount_id_of(path: &Path) -> Option<u64> {
5250 held_mount_id(&hold_path(path, false).ok()?)
5251}
5252
5253fn hold_path(path: &Path, directory: bool) -> nix::Result<std::os::fd::OwnedFd> {
5259 use nix::fcntl::OFlag;
5260 let flags = OFlag::O_PATH
5261 | OFlag::O_CLOEXEC
5262 | if directory {
5263 OFlag::O_DIRECTORY
5264 } else {
5265 OFlag::empty()
5266 };
5267 nix::fcntl::open(path, flags, nix::sys::stat::Mode::empty())
5268}
5269
5270fn held_mount_id(held: &std::os::fd::OwnedFd) -> Option<u64> {
5273 let fdinfo = fs::read(format!("/proc/thread-self/fdinfo/{}", held.as_raw_fd())).ok()?;
5274 detcore_model::procfs::parse_fdinfo_mount_id(&fdinfo)
5275}
5276
5277pub fn capture_mountinfo_identity_order() -> Result<Vec<u64>, Error> {
5280 mountinfo_identity_order_from_raw(&thread_mountinfo()?)
5281}
5282
5283pub fn capture_mountinfo_identity_order_keeping(
5288 keep: &std::collections::BTreeSet<u64>,
5289) -> Result<Vec<u64>, Error> {
5290 mountinfo_identity_order_keeping_from_raw(&thread_mountinfo()?, keep)
5291}
5292
5293pub fn base_mountpoint_mount_ids() -> Vec<(Vec<u8>, u64)> {
5299 detcore_model::container_mounts::BASE_MOUNTPOINTS
5300 .iter()
5301 .filter_map(|mountpoint| {
5302 let id = thread_mount_id_of(Path::new(mountpoint))?;
5303 Some((mountpoint.as_bytes().to_vec(), id))
5304 })
5305 .collect()
5306}
5307
5308pub type UnplannedMountTable = (
5311 detcore_model::container_mounts::ContainerMountTable,
5312 Vec<u64>,
5313);
5314
5315pub fn unplanned_container_mount_table(launch_cwd: &Path) -> Result<UnplannedMountTable, Error> {
5342 unplanned_container_mount_table_with(launch_cwd, thread_mountinfo)
5343}
5344
5345fn unplanned_container_mount_table_with(
5353 launch_cwd: &Path,
5354 read: impl FnOnce() -> Result<Vec<u8>, Error>,
5355) -> Result<UnplannedMountTable, Error> {
5356 let working = hold_path(launch_cwd, true).with_context(|| {
5357 format!(
5358 "the guest's working directory {} cannot be opened for its mount table",
5359 launch_cwd.display()
5360 )
5361 })?;
5362 let tmp = hold_path(Path::new("/tmp"), true).ok();
5364 let base = detcore_model::container_mounts::BASE_MOUNTPOINTS
5365 .iter()
5366 .filter_map(|mountpoint| Some((*mountpoint, hold_path(Path::new(mountpoint), false).ok()?)))
5367 .collect::<Vec<_>>();
5368 let raw = read()?;
5369 let launch = std::iter::once(&working)
5370 .chain(tmp.as_ref())
5371 .map(|held| {
5372 held_mount_id(held)
5373 .ok_or_else(|| anyhow!("a launch directory's mount ID cannot be read"))
5374 })
5375 .collect::<Result<std::collections::BTreeSet<_>, Error>>()?;
5376 let base = base
5377 .iter()
5378 .filter_map(|(mountpoint, held)| {
5379 Some((mountpoint.as_bytes().to_vec(), held_mount_id(held)?))
5380 })
5381 .collect::<Vec<_>>();
5382 unplanned_container_mount_table_from(&raw, &launch, &base)
5383}
5384
5385fn unplanned_container_mount_table_from(
5386 raw: &[u8],
5387 launch: &std::collections::BTreeSet<u64>,
5388 base: &[(Vec<u8>, u64)],
5389) -> Result<UnplannedMountTable, Error> {
5390 use detcore_model::container_mounts::ContainerMountTable;
5391 let rows = detcore_model::container_mounts::parse_container_mounts(raw)
5392 .ok_or_else(|| anyhow!("this thread's mount table has a malformed row"))?;
5393 if let Some(missing) = launch
5394 .iter()
5395 .find(|id| !rows.iter().any(|row| row.raw_mount_id == **id))
5396 {
5397 anyhow::bail!(
5398 "the launch mount {missing} (holding the guest's working directory or /tmp) is not in \
5399 this thread's mount table, read after it was resolved; refusing a table that would \
5400 omit the mount the guest starts on"
5401 );
5402 }
5403 let never = rows
5404 .iter()
5405 .filter(|row| row.is_ephemeral_host_seed())
5406 .map(|row| row.raw_mount_id)
5407 .collect();
5408 let table = ContainerMountTable::select(&rows, launch, base, &never);
5409 let order = mountinfo_identity_order_keeping_from_raw(raw, &table.shown_mount_ids())?;
5410 Ok((table, order))
5411}
5412
5413fn mountinfo_identity_order_from_raw(raw: &[u8]) -> Result<Vec<u64>, Error> {
5418 mountinfo_identity_order_keeping_from_raw(raw, &std::collections::BTreeSet::new())
5419}
5420
5421pub fn mountinfo_identity_order_keeping_from_raw(
5425 raw: &[u8],
5426 keep: &std::collections::BTreeSet<u64>,
5427) -> Result<Vec<u64>, Error> {
5428 let mut kept = Vec::with_capacity(raw.len());
5429 for line in raw.split_inclusive(|byte| *byte == b'\n') {
5430 let body = line.strip_suffix(b"\n").unwrap_or(line);
5431 let id = body
5432 .split(|byte| *byte == b' ')
5433 .next()
5434 .and_then(|field| std::str::from_utf8(field).ok()?.parse::<u64>().ok());
5435 if !detcore_model::procfs::is_ephemeral_host_seed_mount(body)
5436 || id.is_some_and(|id| keep.contains(&id))
5437 {
5438 kept.extend_from_slice(line);
5439 }
5440 }
5441 mountinfo_identity_order_from(&kept)
5442}
5443
5444fn mountinfo_identity_order_from(contents: &[u8]) -> Result<Vec<u64>, Error> {
5445 use std::collections::BTreeSet;
5446
5447 let rows = detcore_model::procfs::parse_mountinfo(contents)
5448 .ok_or_else(|| anyhow!("malformed mountinfo"))?;
5449 let mut visible = Vec::new();
5450 let mut parents = Vec::new();
5451 let mut seen = BTreeSet::new();
5452 for row in rows {
5453 seen.insert(row.raw_mount_id);
5454 visible.push(row.raw_mount_id);
5455 parents.push(row.raw_parent_id);
5456 }
5457 for parent in parents {
5458 if seen.insert(parent) {
5459 visible.push(parent);
5460 }
5461 }
5462 Ok(visible)
5463}
5464
5465impl<'a> From<Option<&'a PathBuf>> for HermitData {
5466 fn from(data_dir: Option<&'a PathBuf>) -> Self {
5467 data_dir.map_or_else(Self::new, Self::with_dir)
5468 }
5469}
5470
5471pub fn record_to(command: Command, dir: &Path) -> Result<ExitStatus, Error> {
5478 let dir = dir.to_owned();
5479 let command = tracer_thread::SendCommand::new(command);
5480 ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5481 let command = command.into_inner();
5482 record_to_async(
5483 command,
5484 &dir,
5485 MountProvenance::default(),
5486 None,
5487 None,
5488 None,
5489 detcore_model::cpu_profile::CpuProfile::default(),
5490 control,
5491 )
5492 .await
5493 })
5494}
5495
5496pub fn record_to_with_mountinfo(
5504 command: Command,
5505 dir: &Path,
5506 mountinfo: MountProvenance,
5507 local_networking: bool,
5508 proc_level: detcore_model::config::ProcLevel,
5509 cpu_profile: detcore_model::cpu_profile::CpuProfile,
5510) -> Result<ExitStatus, Error> {
5511 let dir = dir.to_owned();
5512 let command = tracer_thread::SendCommand::new(command);
5513 ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5514 let command = command.into_inner();
5515 let mut mountinfo = mountinfo;
5516 let mount_ids = match mountinfo.mount_ids.take() {
5517 Some(mount_ids) => mount_ids,
5518 None => capture_mountinfo_identity_order_keeping(
5519 &mountinfo
5520 .container_mount_table
5521 .as_ref()
5522 .map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
5523 .unwrap_or_default(),
5524 )?,
5525 };
5526 record_to_async(
5527 command,
5528 &dir,
5529 mountinfo,
5530 Some(mount_ids),
5531 Some(local_networking),
5532 Some(proc_level),
5533 cpu_profile,
5534 control,
5535 )
5536 .await
5537 })
5538}
5539
5540#[allow(clippy::too_many_arguments)]
5543async fn record_to_async(
5544 command: Command,
5545 dir: &Path,
5546 mountinfo: MountProvenance,
5547 mountinfo_mount_ids: Option<Vec<u64>>,
5548 local_networking: Option<bool>,
5549 proc_level: Option<detcore_model::config::ProcLevel>,
5550 cpu_profile: detcore_model::cpu_profile::CpuProfile,
5551 control: std::rc::Rc<ptrace_completion::Control>,
5552) -> Result<ExitStatus, Error> {
5553 let report = SkidOvershootReport::begin(true);
5554 let result = async {
5555 Record::spawn_with_mountinfo(
5556 command,
5557 dir,
5558 mountinfo,
5559 mountinfo_mount_ids,
5560 local_networking,
5561 proc_level,
5562 cpu_profile,
5563 )
5564 .await?
5565 .wait(control)
5566 .await
5567 }
5568 .await;
5569 report.finish(result)
5570}
5571
5572pub fn record_with_output(command: Command, dir: &Path) -> Result<Output, Error> {
5578 let dir = dir.to_owned();
5579 let command = tracer_thread::SendCommand::new(command);
5580 ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5581 let command = command.into_inner();
5582 record_with_output_async(
5583 command,
5584 &dir,
5585 MountProvenance::default(),
5586 None,
5587 None,
5588 None,
5589 detcore_model::cpu_profile::CpuProfile::default(),
5590 control,
5591 )
5592 .await
5593 })
5594}
5595
5596pub fn record_with_output_with_mountinfo(
5602 command: Command,
5603 dir: &Path,
5604 mountinfo: MountProvenance,
5605 local_networking: bool,
5606 proc_level: detcore_model::config::ProcLevel,
5607 cpu_profile: detcore_model::cpu_profile::CpuProfile,
5608) -> Result<Output, Error> {
5609 let dir = dir.to_owned();
5610 let command = tracer_thread::SendCommand::new(command);
5611 ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5612 let command = command.into_inner();
5613 let mut mountinfo = mountinfo;
5614 let mount_ids = match mountinfo.mount_ids.take() {
5615 Some(mount_ids) => mount_ids,
5616 None => capture_mountinfo_identity_order_keeping(
5617 &mountinfo
5618 .container_mount_table
5619 .as_ref()
5620 .map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
5621 .unwrap_or_default(),
5622 )?,
5623 };
5624 record_with_output_async(
5625 command,
5626 &dir,
5627 mountinfo,
5628 Some(mount_ids),
5629 Some(local_networking),
5630 Some(proc_level),
5631 cpu_profile,
5632 control,
5633 )
5634 .await
5635 })
5636}
5637
5638#[allow(clippy::too_many_arguments)]
5641async fn record_with_output_async(
5642 mut command: Command,
5643 dir: &Path,
5644 mountinfo: MountProvenance,
5645 mountinfo_mount_ids: Option<Vec<u64>>,
5646 local_networking: Option<bool>,
5647 proc_level: Option<detcore_model::config::ProcLevel>,
5648 cpu_profile: detcore_model::cpu_profile::CpuProfile,
5649 control: std::rc::Rc<ptrace_completion::Control>,
5650) -> Result<Output, Error> {
5651 let report = SkidOvershootReport::begin(true);
5652 command.stdin(Stdio::null());
5653 command.stdout(Stdio::piped());
5654 command.stderr(Stdio::piped());
5655 let result = async {
5656 Record::spawn_with_mountinfo(
5657 command,
5658 dir,
5659 mountinfo,
5660 mountinfo_mount_ids,
5661 local_networking,
5662 proc_level,
5663 cpu_profile,
5664 )
5665 .await?
5666 .wait_with_output(control)
5667 .await
5668 }
5669 .await;
5670 report.finish(result)
5671}
5672
5673pub fn replay_from(dir: &Path) -> Result<ExitStatus, Error> {
5679 replay_plain(dir, None, &[])
5680}
5681
5682pub fn replay_with_gdbserver(dir: &Path, port: u16) -> Result<ExitStatus, Error> {
5687 replay_plain(dir, Some(port), &[])
5688}
5689
5690pub fn replay_with_gdbserver_and_mounts(
5695 dir: &Path,
5696 port: u16,
5697 mounts: &[Mount],
5698) -> Result<ExitStatus, Error> {
5699 replay_plain(dir, Some(port), mounts)
5700}
5701
5702fn replay_plain(dir: &Path, port: Option<u16>, mounts: &[Mount]) -> Result<ExitStatus, Error> {
5703 let dir = dir.to_owned();
5704 let mounts = mounts.to_vec();
5705 ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5706 let report = SkidOvershootReport::begin(true);
5707 let result = async {
5708 Replay::spawn(&dir, false, port, &mounts)
5709 .await?
5710 .wait(control)
5711 .await
5712 }
5713 .await;
5714 report.finish(result)
5715 })
5716}
5717
5718pub fn replay_with_output(dir: &Path) -> Result<Output, Error> {
5723 replay_with_output_and_mounts(dir, &[])
5724}
5725
5726pub fn replay_with_output_and_mounts(dir: &Path, mounts: &[Mount]) -> Result<Output, Error> {
5731 let dir = dir.to_owned();
5732 let mounts = mounts.to_vec();
5733 ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5734 let report = SkidOvershootReport::begin(true);
5735 let result = async {
5736 Replay::spawn(&dir, true, None, &mounts)
5737 .await?
5738 .wait_with_output(control)
5739 .await
5740 }
5741 .await;
5742 report.finish(result)
5743 })
5744}
5745
5746#[cfg(test)]
5747mod tests {
5748 use super::*;
5749
5750 static SKID_OVERSHOOT_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
5751
5752 fn check_with_denied(
5756 namespaces: NamespaceUse,
5757 denied: &[CapabilityProbe],
5758 ) -> (Option<String>, Vec<CapabilityProbe>) {
5759 let mut ran = Vec::new();
5760 let result = check_tracing_environment(namespaces, |probe| {
5761 ran.push(probe);
5762 Ok(!denied.contains(&probe))
5763 });
5764 (result.err().map(|error| error.to_string()), ran)
5765 }
5766
5767 #[test]
5772 fn denied_namespaces_refuse_only_a_run_that_creates_them() {
5773 let denied = [CapabilityProbe::Namespaces];
5774 let (refusal, ran) = check_with_denied(NamespaceUse::Creates, &denied);
5775 assert!(
5776 refusal
5777 .as_deref()
5778 .is_some_and(|refusal| refusal.contains("unshare(CLONE_NEWUSER | CLONE_NEWPID)")),
5779 "{refusal:?}"
5780 );
5781 assert_eq!(ran, [CapabilityProbe::Namespaces]);
5782 let (refusal, ran) = check_with_denied(NamespaceUse::None, &denied);
5783 assert_eq!(refusal, None);
5784 assert_eq!(ran, [CapabilityProbe::Ptrace, CapabilityProbe::Seccomp]);
5785 }
5786
5787 #[test]
5790 fn a_run_without_namespaces_still_needs_ptrace_and_seccomp() {
5791 for denied in [CapabilityProbe::Ptrace, CapabilityProbe::Seccomp] {
5792 let (refusal, _) = check_with_denied(NamespaceUse::None, &[denied]);
5793 let expected = match denied {
5794 CapabilityProbe::Ptrace => "PTRACE_TRACEME",
5795 _ => "SECCOMP_SET_MODE_FILTER",
5796 };
5797 assert!(
5798 refusal
5799 .as_deref()
5800 .is_some_and(|refusal| refusal.contains(expected)),
5801 "{denied:?}: {refusal:?}"
5802 );
5803 }
5804 let (refusal, ran) = check_with_denied(NamespaceUse::Creates, &[]);
5805 assert_eq!(refusal, None);
5806 assert_eq!(
5807 ran,
5808 [
5809 CapabilityProbe::Namespaces,
5810 CapabilityProbe::Ptrace,
5811 CapabilityProbe::Seccomp
5812 ]
5813 );
5814 }
5815
5816 #[test]
5821 fn a_manifest_only_recording_can_be_removed() {
5822 let directory = tempfile::tempdir().unwrap();
5823 let data = HermitData::with_dir(directory.path());
5824 let id = Id::unique();
5825 let recording = directory.path().join(id.to_string());
5826 fs::create_dir_all(&recording).unwrap();
5827 assert!(data.remove(id).is_err());
5828 fs::write(recording.join(MANIFEST_NAME), "{}").unwrap();
5829 data.remove(id).unwrap();
5830 assert!(!recording.exists());
5831 }
5832
5833 #[test]
5837 fn identity_capture_excludes_host_seed_mounts_and_keeps_order() {
5838 let raw = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
5839 76 10 0:50 / /mnt/xarfuse/uid-1/e62a203d-seed-nspid4026531836_cgpid16161-ns-4026531832 rw - fuse.squashfuse_ll squashfuse_ll rw\n\
5840 20 10 0:7 / /test rw - tmpfs tmpfs rw\n\
5841 30 10 0:51 / /mnt/xarfuse/stable-release rw - fuse.squashfuse_ll squashfuse_ll rw\n";
5842 let order = mountinfo_identity_order_from_raw(raw).unwrap();
5843 assert!(!order.contains(&76), "seed mount ID captured: {order:?}");
5844 assert_eq!(order, [10, 20, 30, 1]);
5845 assert_eq!(
5846 mountinfo_identity_order_from(raw).unwrap(),
5847 [10, 76, 20, 30, 1],
5848 "control: without the filter the seed ID is captured"
5849 );
5850 }
5851
5852 const NAMESPACE: detcore_model::config::MountNamespaceIdentity =
5854 detcore_model::config::MountNamespaceIdentity {
5855 id: Some(9001),
5856 device: 4,
5857 inode: 4026531840,
5858 };
5859
5860 #[test]
5861 fn kvm_mountinfo_config_preserves_captured_provenance() {
5862 let rewrite = detcore_model::config::MountInfoRootRewrite {
5863 raw_mount_id: 20,
5864 deterministic_root: b"/".to_vec(),
5865 raw_root_prefix: Some(b"/private-source".to_vec()),
5866 deterministic_root_prefix: Some(b"/tmp".to_vec()),
5867 raw_mountpoint_prefix: Some(b"/private-source".to_vec()),
5868 deterministic_mountpoint_prefix: Some(b"/tmp".to_vec()),
5869 };
5870 let mut config = DetConfig {
5871 mountinfo_mount_ids: vec![10, 20, 30],
5872 mountinfo_mount_ids_captured: true,
5873 mountinfo_mount_namespace: Some(NAMESPACE),
5874 mount_id_assignment_order: vec![700, 701],
5875 mountinfo_root_rewrites: vec![rewrite],
5876 mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
5877 ..DetConfig::default()
5878 };
5879 let mut expected = config.clone();
5880 expected.mountinfo_device_rewrites.clear();
5881 let (mut namespaces, mut captures) = (0, 0);
5882 prepare_kvm_mountinfo_config(
5883 &mut config,
5884 || {
5885 namespaces += 1;
5886 Ok(NAMESPACE)
5887 },
5888 || {
5889 captures += 1;
5890 Ok(vec![10, 30])
5891 },
5892 )
5893 .unwrap();
5894 assert_eq!(namespaces, 1, "the backend's namespace must be checked");
5895 assert_eq!(
5896 captures, 0,
5897 "the producer's snapshot is kept; the namespace is not read again"
5898 );
5899 assert_eq!(
5900 serde_json::to_value(&config).unwrap(),
5901 serde_json::to_value(&expected).unwrap(),
5902 "root rewrites, listed and assignment orders and every other setting must remain intact"
5903 );
5904 }
5905
5906 #[test]
5910 fn kvm_mountinfo_config_refuses_malformed_captured_provenance() {
5911 let rewrite = |raw_mount_id| detcore_model::config::MountInfoRootRewrite {
5912 raw_mount_id,
5913 deterministic_root: b"/".to_vec(),
5914 raw_root_prefix: None,
5915 deterministic_root_prefix: None,
5916 raw_mountpoint_prefix: None,
5917 deterministic_mountpoint_prefix: None,
5918 };
5919 let valid = DetConfig {
5920 mountinfo_mount_ids: vec![10, 20, 1],
5921 mountinfo_mount_ids_captured: true,
5922 mountinfo_mount_namespace: Some(NAMESPACE),
5923 mount_id_assignment_order: vec![20],
5924 mountinfo_root_rewrites: vec![rewrite(20)],
5925 ..DetConfig::default()
5926 };
5927 prepare_kvm_mountinfo_config(
5928 &mut valid.clone(),
5929 || Ok(NAMESPACE),
5930 || panic!("captured provenance is not read again"),
5931 )
5932 .unwrap();
5933 let cases = [
5934 (
5935 "duplicate",
5936 DetConfig {
5937 mountinfo_mount_ids: vec![10, 10],
5938 ..valid.clone()
5939 },
5940 "malformed",
5941 ),
5942 (
5943 "empty",
5944 DetConfig {
5945 mountinfo_mount_ids: vec![],
5946 ..valid.clone()
5947 },
5948 "malformed",
5949 ),
5950 (
5951 "assigned twice",
5952 DetConfig {
5953 mount_id_assignment_order: vec![20, 20],
5954 ..valid.clone()
5955 },
5956 "malformed",
5957 ),
5958 (
5959 "zero assigned, unlisted",
5960 DetConfig {
5961 mount_id_assignment_order: vec![0],
5962 ..valid.clone()
5963 },
5964 "malformed",
5965 ),
5966 (
5967 "rewrite outside",
5968 DetConfig {
5969 mountinfo_root_rewrites: vec![rewrite(30)],
5970 ..valid.clone()
5971 },
5972 "root rewrite names mount 30",
5973 ),
5974 ];
5975 for (name, mut config, expected) in cases {
5976 let before = serde_json::to_value(&config).unwrap();
5977 let error = prepare_kvm_mountinfo_config(
5978 &mut config,
5979 || panic!("{name}: malformed provenance is refused before any read"),
5980 || panic!("{name}: captured provenance is not read again"),
5981 )
5982 .unwrap_err();
5983 assert!(error.to_string().contains(expected), "{name}: {error:#}");
5984 assert_eq!(serde_json::to_value(&config).unwrap(), before, "{name}");
5985 }
5986 }
5987
5988 #[test]
5991 fn current_mount_namespace_is_stable_and_names_a_kernel_id_where_reported() {
5992 let first = current_mount_namespace().unwrap();
5993 assert_eq!(current_mount_namespace().unwrap(), first);
5994 assert_ne!(first.inode, 0);
5995 assert_ne!(first.id, Some(0));
5996 }
5997
5998 #[test]
6006 fn kvm_mountinfo_config_keeps_a_snapshot_whose_host_row_left_the_namespace() {
6007 let producer = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
6008 20 10 0:22 / /proc rw - proc proc rw\n\
6009 30 10 0:50 / /data/a rw - tmpfs tmpfs rw\n";
6010 let now = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
6011 20 10 0:22 / /proc rw - proc proc rw\n";
6012 let order = mountinfo_identity_order_from(producer).unwrap();
6013 let mut config = DetConfig {
6014 mountinfo_mount_ids: order.clone(),
6015 mountinfo_mount_ids_captured: true,
6016 mountinfo_mount_namespace: Some(NAMESPACE),
6017 ..DetConfig::default()
6018 };
6019 prepare_kvm_mountinfo_config(
6020 &mut config,
6021 || Ok(NAMESPACE),
6022 || mountinfo_identity_order_from(now),
6023 )
6024 .unwrap();
6025 assert_eq!(config.mountinfo_mount_ids, order);
6026 assert_eq!(config.mountinfo_mount_ids, [10, 20, 30, 1]);
6027 assert!(detcore_model::procfs::mount_ids_are_ordered_subset(
6028 &mountinfo_identity_order_from(now).unwrap(),
6029 &config.mountinfo_mount_ids
6030 ));
6031 }
6032
6033 #[test]
6034 fn kvm_mountinfo_config_refuses_provenance_of_another_namespace() {
6035 let config = DetConfig {
6036 mountinfo_mount_ids: vec![10, 20, 1],
6037 mountinfo_mount_ids_captured: true,
6038 mountinfo_mount_namespace: Some(NAMESPACE),
6039 mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
6040 ..DetConfig::default()
6041 };
6042 for backend in [
6045 detcore_model::config::MountNamespaceIdentity {
6046 id: Some(9002),
6047 ..NAMESPACE
6048 },
6049 detcore_model::config::MountNamespaceIdentity {
6050 inode: NAMESPACE.inode + 1,
6051 ..NAMESPACE
6052 },
6053 detcore_model::config::MountNamespaceIdentity {
6054 device: NAMESPACE.device + 1,
6055 ..NAMESPACE
6056 },
6057 detcore_model::config::MountNamespaceIdentity {
6058 id: None,
6059 ..NAMESPACE
6060 },
6061 ] {
6062 let mut stale = config.clone();
6063 let before = serde_json::to_value(&stale).unwrap();
6064 let error = prepare_kvm_mountinfo_config(
6065 &mut stale,
6066 || Ok(backend),
6067 || panic!("captured provenance is not read again"),
6068 )
6069 .unwrap_err();
6070 assert!(
6071 error.to_string().contains("name another mount namespace"),
6072 "{error:#}"
6073 );
6074 assert_eq!(serde_json::to_value(&stale).unwrap(), before);
6075 }
6076 let mut unnamed = DetConfig {
6077 mountinfo_mount_namespace: None,
6078 ..config.clone()
6079 };
6080 let before = serde_json::to_value(&unnamed).unwrap();
6081 let error = prepare_kvm_mountinfo_config(
6082 &mut unnamed,
6083 || panic!("provenance without a namespace is refused before any read"),
6084 || panic!("provenance without a namespace is refused before any read"),
6085 )
6086 .unwrap_err();
6087 assert!(
6088 error
6089 .to_string()
6090 .contains("do not name their mount namespace"),
6091 "{error:#}"
6092 );
6093 assert_eq!(serde_json::to_value(&unnamed).unwrap(), before);
6094 let mut unreadable = config;
6095 let before = serde_json::to_value(&unreadable).unwrap();
6096 let error = prepare_kvm_mountinfo_config(
6097 &mut unreadable,
6098 || Err(std::io::Error::from(std::io::ErrorKind::PermissionDenied).into()),
6099 || panic!("captured provenance is not read again"),
6100 )
6101 .unwrap_err();
6102 assert!(
6103 error
6104 .downcast_ref::<std::io::Error>()
6105 .is_some_and(|error| error.kind() == std::io::ErrorKind::PermissionDenied)
6106 );
6107 assert_eq!(serde_json::to_value(&unreadable).unwrap(), before);
6108 }
6109
6110 #[test]
6111 fn kvm_mountinfo_config_captures_validated_ambient_namespace() {
6112 let contents = b"80 20 8:1 / / rw - ext4 /dev/root rw\n\
6113 10 80 0:7 / /test rw - tmpfs tmpfs rw\n";
6114 let mut config = DetConfig::default();
6115 let mut expected = config.clone();
6116 expected.mountinfo_mount_ids = vec![80, 10, 20];
6117 expected.mountinfo_mount_ids_captured = true;
6118 prepare_kvm_mountinfo_config(
6119 &mut config,
6120 || panic!("an ambient capture has no producer namespace to compare"),
6121 || mountinfo_identity_order_from(contents),
6122 )
6123 .unwrap();
6124 assert_eq!(
6125 serde_json::to_value(&config).unwrap(),
6126 serde_json::to_value(&expected).unwrap(),
6127 "visible rows precede parent-only IDs and no guest setting changes"
6128 );
6129 assert!(detcore_model::procfs::mount_ids_are_ordered_subset(
6130 &[80, 10],
6131 &config.mountinfo_mount_ids
6132 ));
6133 assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
6134 &[10, 80],
6135 &config.mountinfo_mount_ids
6136 ));
6137 assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
6138 &[80, 99],
6139 &config.mountinfo_mount_ids
6140 ));
6141 assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
6142 &[80, 80],
6143 &config.mountinfo_mount_ids
6144 ));
6145
6146 let mut empty = DetConfig::default();
6147 prepare_kvm_mountinfo_config(
6148 &mut empty,
6149 || panic!("an ambient capture has no producer namespace to compare"),
6150 || mountinfo_identity_order_from(b""),
6151 )
6152 .unwrap();
6153 assert!(empty.mountinfo_mount_ids.is_empty());
6154 assert!(empty.mountinfo_mount_ids_captured);
6155 }
6156
6157 #[test]
6158 fn kvm_mountinfo_config_refuses_missing_or_malformed_capture() {
6159 let valid = b"10 20 8:1 / / rw - ext4 /dev/root rw\n";
6160 let config = DetConfig {
6161 mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
6162 ..DetConfig::default()
6163 };
6164 for contents in [
6165 b"malformed".as_slice(),
6166 b"10 20 8:1 / / rw - ext4 /dev/root rw\n10 20 8:1 / / rw - ext4 /dev/root rw\n",
6167 b"10 20 8:1 / / rw unknown:7 - ext4 /dev/root rw\n",
6168 ] {
6169 let mut candidate = config.clone();
6170 let before = serde_json::to_value(&candidate).unwrap();
6171 let error = prepare_kvm_mountinfo_config(
6172 &mut candidate,
6173 || panic!("an ambient capture has no producer namespace to compare"),
6174 || mountinfo_identity_order_from(contents),
6175 )
6176 .unwrap_err();
6177 assert!(format!("{error:#}").contains("malformed mountinfo"));
6178 assert_eq!(serde_json::to_value(&candidate).unwrap(), before);
6179 }
6180 let mut candidate = config;
6181 let before = serde_json::to_value(&candidate).unwrap();
6182 let error = prepare_kvm_mountinfo_config(
6183 &mut candidate,
6184 || panic!("an ambient capture has no producer namespace to compare"),
6185 || Err(std::io::Error::from(std::io::ErrorKind::PermissionDenied).into()),
6186 )
6187 .unwrap_err();
6188 assert!(
6189 error
6190 .downcast_ref::<std::io::Error>()
6191 .is_some_and(|error| error.kind() == std::io::ErrorKind::PermissionDenied)
6192 );
6193 assert_eq!(serde_json::to_value(&candidate).unwrap(), before);
6194 assert_eq!(mountinfo_identity_order_from(valid).unwrap(), [10, 20]);
6195 }
6196
6197 #[test]
6198 fn kvm_mountinfo_config_refuses_uncaptured_provenance_vectors() {
6199 for (listed, assigned, namespace) in [
6200 (vec![10], vec![], None),
6201 (vec![], vec![700], None),
6202 (vec![], vec![], Some(NAMESPACE)),
6203 ] {
6204 let mut config = DetConfig {
6205 mountinfo_mount_ids: listed,
6206 mount_id_assignment_order: assigned,
6207 mountinfo_mount_namespace: namespace,
6208 ..DetConfig::default()
6209 };
6210 let before = serde_json::to_value(&config).unwrap();
6211 let error = prepare_kvm_mountinfo_config(
6212 &mut config,
6213 || panic!("must not overwrite incomplete provenance"),
6214 || panic!("must not overwrite incomplete provenance"),
6215 )
6216 .unwrap_err();
6217 assert!(error.to_string().contains("no producer-captured namespace"));
6218 assert_eq!(serde_json::to_value(&config).unwrap(), before);
6219 }
6220 }
6221
6222 #[test]
6226 fn kvm_mountinfo_config_refuses_a_mount_table_of_another_namespace() {
6227 let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
6228 20 10 0:22 / /proc rw - proc proc rw\n\
6229 40 10 0:23 / /elsewhere rw - tmpfs tmpfs rw\n";
6230 let rows = detcore_model::container_mounts::parse_container_mounts(namespace).unwrap();
6231 let table = |installed: &[u64]| {
6232 detcore_model::container_mounts::ContainerMountTable::select(
6233 &rows,
6234 &installed.iter().copied().collect(),
6235 &[],
6236 &std::collections::BTreeSet::new(),
6237 )
6238 };
6239 let config = |table| DetConfig {
6240 mountinfo_mount_ids: vec![10, 20, 1],
6241 mountinfo_mount_ids_captured: true,
6242 mountinfo_mount_namespace: Some(NAMESPACE),
6243 container_mount_table: Some(table),
6244 ..DetConfig::default()
6245 };
6246 let snapshot = || -> Result<Vec<u64>, Error> { panic!("the snapshot is kept") };
6247 let mut matching = config(table(&[20]));
6248 prepare_kvm_mountinfo_config(&mut matching, || Ok(NAMESPACE), snapshot).unwrap();
6249 let mut stale = config(table(&[40]));
6250 let error =
6251 prepare_kvm_mountinfo_config(&mut stale, || Ok(NAMESPACE), snapshot).unwrap_err();
6252 assert!(error.to_string().contains("names mount 40"), "{error:#}");
6253 }
6254
6255 #[test]
6260 fn an_unplanned_table_shows_only_the_base_mountpoints() {
6261 let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
6262 20 10 0:22 / /proc rw - proc proc rw\n\
6263 30 10 0:23 / /dev rw - devtmpfs dev rw\n\
6264 40 10 0:24 / /data/eden rw - fuse.edenfs eden rw\n\
6265 41 30 0:25 / /dev/shm rw - tmpfs tmpfs rw\n\
6266 50 10 0:26 / /run/user/1000 rw - tmpfs tmpfs rw\n";
6267 let base = [
6269 (b"/".to_vec(), 10),
6270 (b"/proc".to_vec(), 20),
6271 (b"/dev".to_vec(), 30),
6272 (b"/dev/shm".to_vec(), 41),
6273 (b"/run".to_vec(), 10),
6274 ];
6275 for mountpoint in detcore_model::container_mounts::BASE_MOUNTPOINTS {
6276 assert!(
6277 !mountpoint.bytes().any(|byte| b" \t\n\\".contains(&byte)),
6278 "{mountpoint} needs mountinfo escaping"
6279 );
6280 }
6281 let no_launch = std::collections::BTreeSet::new();
6282 let (table, order) =
6283 unplanned_container_mount_table_from(namespace, &no_launch, &base).unwrap();
6284 assert_eq!(table.shown_mount_ids(), [10, 20, 30, 41].into());
6285 assert_eq!(table.shown_mount_id(40), 10);
6286 assert_eq!(table.shown_mount_id(50), 10);
6287 assert_eq!(order, [10, 20, 30, 40, 41, 50, 1]);
6288 let rendered = String::from_utf8(table.mountinfo()).unwrap();
6289 assert!(!rendered.contains("/data/eden") && !rendered.contains("/run/user"));
6290 let launch = [40].into();
6293 let (table, order) =
6294 unplanned_container_mount_table_from(namespace, &launch, &base).unwrap();
6295 assert_eq!(table.shown_mount_ids(), [10, 20, 30, 40, 41].into());
6296 assert_eq!(table.shown_mount_id(40), 40);
6297 assert_eq!(table.shown_mount_id(50), 10);
6298 assert_eq!(order, [10, 20, 30, 40, 41, 50, 1]);
6299 }
6300
6301 fn rerun_in_user_namespace(name: &str) -> bool {
6308 const CHILD: &str = "HERMIT_TEST_USER_NAMESPACE_CHILD";
6309 if std::env::var_os(CHILD).is_some() {
6310 return false;
6311 }
6312 let probe = std::process::Command::new("unshare")
6313 .args(["--user", "--map-root-user", "--mount", "true"])
6314 .output();
6315 if !probe.as_ref().is_ok_and(|probe| probe.status.success()) {
6316 eprintln!("SKIPPED {name}: user namespaces are unavailable here: {probe:?}");
6317 return true;
6318 }
6319 let output = std::process::Command::new("unshare")
6320 .args(["--user", "--map-root-user", "--mount", "--"])
6321 .arg(std::env::current_exe().unwrap())
6322 .args(["--exact", name, "--nocapture", "--test-threads=1"])
6323 .env(CHILD, "1")
6324 .output()
6325 .expect("run the test under unshare");
6326 let stdout = String::from_utf8_lossy(&output.stdout);
6327 assert!(
6328 output.status.success() && stdout.contains("1 passed"),
6329 "the child failed or ran no test:\n{stdout}\n{}",
6330 String::from_utf8_lossy(&output.stderr)
6331 );
6332 true
6333 }
6334
6335 #[test]
6344 fn a_thread_with_its_own_mount_namespace_captures_its_own_view() {
6345 use std::os::unix::fs::MetadataExt;
6346 if rerun_in_user_namespace(
6347 "tests::a_thread_with_its_own_mount_namespace_captures_its_own_view",
6348 ) {
6349 return;
6350 }
6351 let checked = std::thread::spawn(|| {
6352 assert_eq!(
6354 unsafe { libc::unshare(libc::CLONE_NEWNS) },
6355 0,
6356 "unshare(CLONE_NEWNS): {}",
6357 io::Error::last_os_error()
6358 );
6359 let own = current_mount_namespace().unwrap();
6360 let leader = fs::metadata("/proc/self/ns/mnt").unwrap();
6361 assert_ne!(
6362 own.inode,
6363 leader.ino(),
6364 "the thread kept the leader's namespace"
6365 );
6366 let (table, order) = unplanned_container_mount_table(Path::new(".")).unwrap();
6367 assert!(
6368 table
6369 .mounts
6370 .iter()
6371 .any(|row| row.mountpoint.as_slice() == b"/"),
6372 "the thread's table shows no /: {table:?}"
6373 );
6374 let root = thread_mount_id_of(Path::new("/")).unwrap();
6375 assert!(table.shown_mount_ids().contains(&root));
6376 assert!(table.shown_mount_ids().iter().all(|id| order.contains(id)));
6377 })
6378 .join();
6379 assert!(checked.is_ok(), "the thread's checks failed");
6380 }
6381
6382 #[test]
6391 fn launch_directories_are_held_before_the_mount_table_is_read() {
6392 if rerun_in_user_namespace(
6393 "tests::launch_directories_are_held_before_the_mount_table_is_read",
6394 ) {
6395 return;
6396 }
6397 let directory = tempfile::tempdir().unwrap();
6398 let launch = directory.path().join("launch");
6399 fs::create_dir(&launch).unwrap();
6400 let before = thread_mount_id_of(&launch).unwrap();
6401 let target = launch.clone();
6402 let (table, _) = unplanned_container_mount_table_with(&launch, move || {
6403 let status = std::process::Command::new("mount")
6404 .args(["-t", "tmpfs", "none"])
6405 .arg(&target)
6406 .status()
6407 .expect("run mount");
6408 assert!(status.success(), "mount a tmpfs over the launch directory");
6409 thread_mountinfo()
6410 })
6411 .unwrap();
6412 let over = thread_mount_id_of(&launch).unwrap();
6413 assert_ne!(over, before, "the tmpfs did not cover the launch directory");
6414 assert!(table.shown_mount_ids().contains(&before));
6415 assert!(!table.shown_mount_ids().contains(&over));
6416 let _ = std::process::Command::new("umount").arg(&launch).status();
6417 }
6418
6419 #[test]
6422 fn a_launch_mount_missing_from_the_read_is_refused() {
6423 let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n";
6424 let error = unplanned_container_mount_table_from(namespace, &[99].into(), &[])
6425 .unwrap_err()
6426 .to_string();
6427 assert!(error.contains("launch mount 99"), "{error}");
6428 }
6429
6430 #[test]
6431 fn skid_overshoot_report_covers_success_error_and_disabled_backends() {
6432 let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
6433 let _ = reverie::take_skid_overshoot_count();
6434
6435 reverie::record_skid_overshoot();
6436 let empty_run = SkidOvershootReport::begin(true);
6437 assert_eq!(
6438 reverie::take_skid_overshoot_count(),
6439 0,
6440 "begin must clear evidence from a previous invocation"
6441 );
6442 empty_run.finish(Ok::<_, Error>(())).unwrap();
6443
6444 let success = SkidOvershootReport::begin(true);
6445 reverie::record_skid_overshoot();
6446 reverie::record_skid_overshoot();
6447 let error = success.finish(Ok::<_, Error>(7)).unwrap_err();
6448 assert_eq!(
6449 error
6450 .downcast_ref::<SkidOvershootError>()
6451 .expect("skid refusal must remain typed")
6452 .count(),
6453 2
6454 );
6455 assert!(
6456 error
6457 .to_string()
6458 .contains("observed 2 HERMIT_SKID_OVERSHOOT report(s)"),
6459 "{error:#}"
6460 );
6461 assert!(
6462 error
6463 .to_string()
6464 .contains("deterministic execution was not established"),
6465 "{error:#}"
6466 );
6467 assert_eq!(reverie::take_skid_overshoot_count(), 0);
6468
6469 let error = SkidOvershootReport::begin(true);
6470 reverie::record_skid_overshoot();
6471 let error = error
6472 .finish(Err::<(), _>(anyhow!("guest failed")))
6473 .unwrap_err();
6474 assert!(error.downcast_ref::<SkidOvershootError>().is_some());
6475 let error = format!("{error:#}");
6476 assert!(error.contains("guest failed"), "{error}");
6477 assert!(
6478 error.contains("observed 1 HERMIT_SKID_OVERSHOOT report(s)"),
6479 "{error}"
6480 );
6481 assert_eq!(reverie::take_skid_overshoot_count(), 0);
6482
6483 reverie::record_skid_overshoot();
6484 let disabled = SkidOvershootReport::begin(false);
6485 disabled.finish(Ok::<_, Error>(())).unwrap();
6486 assert_eq!(
6487 reverie::take_skid_overshoot_count(),
6488 1,
6489 "a backend that cannot produce ptrace PMU overshoots must not consume another run's evidence"
6490 );
6491 }
6492
6493 #[test]
6494 fn only_ptrace_hosted_backends_consume_skid_overshoot_reports() {
6495 for backend in [Backend::Ptrace, Backend::E9patch] {
6496 assert!(backend.uses_ptrace_pmu_timers(), "{backend:?}");
6497 }
6498 for backend in [Backend::Dbt, Backend::Sabre, Backend::Kvm] {
6499 assert!(!backend.uses_ptrace_pmu_timers(), "{backend:?}");
6500 }
6501 assert!(!Backend::Liteinst.uses_ptrace_pmu_timers());
6503 assert!(!Backend::InGuestTrap.uses_ptrace_pmu_timers());
6504 }
6505
6506 #[cfg(feature = "liteinst")]
6507 fn write_guest_program(directory: &Path, name: &str, bytes: &[u8], mode: u32) -> PathBuf {
6508 let path = directory.join(name);
6509 fs::write(&path, bytes).unwrap();
6510 fs::set_permissions(&path, fs::Permissions::from_mode(mode)).unwrap();
6511 assert_eq!(
6514 fs::metadata(&path).unwrap().permissions().mode() & 0o7777,
6515 mode,
6516 "{}",
6517 path.display()
6518 );
6519 path
6520 }
6521
6522 #[cfg(feature = "liteinst")]
6523 fn shebang_to(interpreter: &Path) -> Vec<u8> {
6524 let mut script = b"#!".to_vec();
6525 script.extend_from_slice(interpreter.as_os_str().as_bytes());
6526 script.extend_from_slice(b" -e\necho script\n");
6527 script
6528 }
6529
6530 #[test]
6531 #[cfg(feature = "liteinst")]
6532 fn in_guest_liteinst_runs_a_dynamically_linked_x86_64_program() {
6533 use interp::startup_fixtures::dynamic_executable;
6534
6535 let directory = tempfile::tempdir().unwrap();
6536 let program = write_guest_program(
6537 directory.path(),
6538 "dynamic",
6539 &dynamic_executable(false),
6540 0o755,
6541 );
6542 assert_eq!(
6543 in_guest_liteinst_program_gap(&mut Command::new(&program)).unwrap(),
6544 None
6545 );
6546 }
6547
6548 #[test]
6549 #[cfg(feature = "liteinst")]
6550 fn in_guest_liteinst_refuses_programs_that_start_before_the_runtime() {
6551 use interp::startup_fixtures::*;
6552
6553 let directory = tempfile::tempdir().unwrap();
6554 let cases: [(&str, Vec<u8>, &str); 4] = [
6555 (
6556 "static",
6557 elf(EM_X86_64, &[(PT_LOAD, b"code")]),
6558 "is statically linked",
6559 ),
6560 (
6561 "preinit",
6562 dynamic_executable(true),
6563 "has a DT_PREINIT_ARRAY",
6564 ),
6565 (
6566 "aarch64",
6567 elf(EM_AARCH64, &[(PT_INTERP, INTERP)]),
6568 "is not a 64-bit x86-64 ELF image",
6569 ),
6570 (
6571 "text",
6572 b"plain text, no #! line\n".to_vec(),
6573 "is neither an ELF executable nor a #! script",
6574 ),
6575 ];
6576 for (name, bytes, reason) in cases {
6577 let program = write_guest_program(directory.path(), name, &bytes, 0o755);
6578 let gap = in_guest_liteinst_program_gap(&mut Command::new(&program))
6579 .unwrap()
6580 .unwrap_or_else(|| panic!("{name} was not refused"));
6581 assert!(
6582 gap.contains(reason) && gap.contains(&program.display().to_string()),
6583 "{name}: {gap}"
6584 );
6585 }
6586 }
6587
6588 #[tokio::test]
6592 #[cfg(feature = "liteinst")]
6593 async fn a_recorded_in_guest_failure_fails_the_run_and_latches_a_loss() {
6594 use std::os::fd::FromRawFd;
6595
6596 use reverie::GlobalTool;
6597 use reverie_rpc_transport::ConnectionAdmission;
6598
6599 let config = DetConfig::default().with_backend(|backend| {
6600 backend.process_exits_complete_asynchronously = true;
6601 });
6602 let global_state = detcore::GlobalState::init_global_state(&config).await;
6603 let exits = in_guest_exits::InGuestExitAdmission::default();
6604 let fd = unsafe { libc::syscall(libc::SYS_pidfd_open, std::process::id() as i32, 0) };
6606 assert!(fd >= 0);
6607 let pidfd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fd as i32) };
6608 assert!(exits.admit(pidfd).is_err());
6609 let error = settle_in_guest_exits(&exits, &global_state)
6610 .await
6611 .expect_err("a recorded failure must fail the run");
6612 assert!(
6613 error
6614 .to_string()
6615 .starts_with("in-guest LiteInst refused a guest connection:"),
6616 "{error}"
6617 );
6618 assert!(detcore::detlog::determinism_loss().is_some());
6619 }
6620
6621 #[test]
6622 fn in_guest_trap_is_in_guest_liteinst_and_forces_site_patching_off() {
6623 assert!(Backend::Liteinst.is_in_guest_liteinst());
6624 assert!(Backend::InGuestTrap.is_in_guest_liteinst());
6625 for backend in [
6626 Backend::Ptrace,
6627 Backend::Dbt,
6628 Backend::Sabre,
6629 Backend::Kvm,
6630 Backend::E9patch,
6631 ] {
6632 assert!(!backend.is_in_guest_liteinst(), "{backend:?}");
6633 assert_eq!(backend.runtime_name(), backend.as_str(), "{backend:?}");
6634 assert_eq!(forced_site_patching_value(backend), None, "{backend:?}");
6635 }
6636 assert_eq!(Backend::InGuestTrap.as_str(), "in-guest-trap");
6637 assert_eq!(Backend::InGuestTrap.runtime_name(), "liteinst");
6638 assert_eq!(Backend::Liteinst.runtime_name(), "liteinst");
6639 assert_eq!(forced_site_patching_value(Backend::Liteinst), None);
6641 assert_eq!(forced_site_patching_value(Backend::InGuestTrap), Some("0"));
6642 assert_eq!(
6644 <Backend as ValueEnum>::from_str("in-guest-trap", false),
6645 Ok(Backend::InGuestTrap)
6646 );
6647 assert!(Backend::ALL.contains(&Backend::InGuestTrap));
6648 for backend in Backend::ALL {
6649 let name = backend
6650 .to_possible_value()
6651 .expect("every backend is a visible CLI value");
6652 assert_eq!(name.get_name(), backend.as_str(), "{backend:?}");
6653 }
6654 }
6655
6656 #[test]
6662 #[cfg(feature = "liteinst")]
6663 fn in_guest_trap_refuses_a_guest_environment_that_turns_site_patching_on() {
6664 use std::ffi::OsStr;
6665
6666 let name = reverie_liteinst::SITE_PATCHING_ENV;
6667 let mut unset = Command::new("/bin/true");
6668 unset.env_remove(name);
6669 assert_eq!(
6670 in_guest_trap_site_patching_conflict(&unset, Backend::InGuestTrap),
6671 None
6672 );
6673 force_in_guest_site_patching(&mut unset, Backend::InGuestTrap);
6674 assert_eq!(unset.get_env(name).as_deref(), Some(OsStr::new("0")));
6675
6676 let mut zero = Command::new("/bin/true");
6677 zero.env(name, "0");
6678 assert_eq!(
6679 in_guest_trap_site_patching_conflict(&zero, Backend::InGuestTrap),
6680 None
6681 );
6682
6683 for value in ["1", "", "yes", " 0"] {
6684 let mut command = Command::new("/bin/true");
6685 command.env(name, value);
6686 let conflict = in_guest_trap_site_patching_conflict(&command, Backend::InGuestTrap)
6687 .unwrap_or_else(|| panic!("{value:?} was accepted"));
6688 assert!(conflict.contains(&format!("{name}={value},")), "{conflict}");
6689 assert!(conflict.contains("--backend=liteinst"), "{conflict}");
6690 assert!(conflict.contains("drop the variable"), "{conflict}");
6691 let error = refuse_in_guest_liteinst_run(
6694 &mut command,
6695 &DetConfig::default(),
6696 Backend::InGuestTrap,
6697 )
6698 .unwrap_err();
6699 let refusal = error
6700 .downcast_ref::<LiteinstInGuestRefusal>()
6701 .expect("a typed in-guest refusal, which the CLI reports as exit 122");
6702 assert!(
6703 refusal.to_string().starts_with(
6704 "--backend=in-guest-trap (in-guest LiteInst, site patching off) refuses \
6705 this run: the guest environment sets"
6706 ),
6707 "{refusal}"
6708 );
6709 assert_eq!(command.get_env(name).as_deref(), Some(OsStr::new(value)));
6710
6711 let mut liteinst = Command::new("/bin/true");
6713 liteinst.env(name, value);
6714 assert_eq!(
6715 in_guest_trap_site_patching_conflict(&liteinst, Backend::Liteinst),
6716 None
6717 );
6718 force_in_guest_site_patching(&mut liteinst, Backend::Liteinst);
6719 assert_eq!(liteinst.get_env(name).as_deref(), Some(OsStr::new(value)));
6720 }
6721 }
6722
6723 #[test]
6729 #[cfg(feature = "liteinst")]
6730 fn an_in_guest_trap_run_that_patched_a_site_is_refused_after_it_ends() {
6731 let record = |candidates: Option<u64>, patched: Option<u64>| {
6732 reverie::DispatchStats::new(
6733 "in-guest-trap",
6734 reverie::DispatchCounters::ZERO,
6735 reverie::SiteCounters {
6736 candidates,
6737 patched,
6738 fell_back: Some(0),
6739 },
6740 )
6741 };
6742 let clean = record(Some(0), Some(0));
6743 assert_eq!(
6744 in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&clean), 1),
6745 None
6746 );
6747 for (candidates, patched, shown) in [
6748 (Some(3), Some(3), "3 patched and 3 candidate"),
6749 (Some(1), Some(0), "0 patched and 1 candidate"),
6750 (Some(0), None, "unmeasured patched and 0 candidate"),
6751 ] {
6752 let reason = in_guest_trap_patching_evidence(
6753 Backend::InGuestTrap,
6754 Some(&record(candidates, patched)),
6755 1,
6756 )
6757 .unwrap_or_else(|| panic!("{candidates:?} {patched:?} was accepted"));
6758 assert!(reason.contains(shown), "{reason}");
6759 }
6760 assert!(
6761 in_guest_trap_patching_evidence(Backend::InGuestTrap, None, 1)
6762 .is_some_and(|reason| reason.contains("no LiteInst dispatch record"))
6763 );
6764 assert!(
6766 in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&clean), 0)
6767 .is_some_and(|reason| reason.contains("no guest process reported"))
6768 );
6769 let patched = record(Some(3), Some(3));
6770 assert_eq!(
6771 in_guest_trap_patching_evidence(Backend::Liteinst, Some(&patched), 1),
6772 None
6773 );
6774 assert_eq!(
6775 in_guest_trap_patching_evidence(Backend::Liteinst, None, 0),
6776 None
6777 );
6778
6779 refuse_in_guest_trap_patching(Backend::InGuestTrap, None).unwrap();
6780 let error = refuse_in_guest_trap_patching(
6781 Backend::InGuestTrap,
6782 in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&patched), 1),
6783 )
6784 .unwrap_err();
6785 assert!(
6786 error.downcast_ref::<LiteinstInGuestRefusal>().is_some(),
6787 "{error:#}"
6788 );
6789 assert!(
6790 error
6791 .to_string()
6792 .starts_with("--backend=in-guest-trap (in-guest LiteInst, site patching off)"),
6793 "{error:#}"
6794 );
6795 assert!(
6796 detcore::detlog::determinism_loss().is_some_and(|loss| loss.contains("3 patched")),
6797 "the refusal must record a determinism loss"
6798 );
6799 }
6800
6801 #[test]
6805 #[cfg(feature = "liteinst")]
6806 fn only_in_guest_trap_asks_tool_images_to_check_their_runtime() {
6807 for backend in Backend::ALL {
6808 let checks = in_guest_site_patching_off(backend);
6809 assert_eq!(checks, backend == Backend::InGuestTrap, "{backend:?}");
6810 if checks {
6811 assert!(in_guest_stats_request(backend, &None).is_enabled());
6812 }
6813 }
6814 assert!(!in_guest_stats_request(Backend::Liteinst, &None).is_enabled());
6815 }
6816
6817 #[test]
6818 #[cfg(feature = "liteinst")]
6819 fn in_guest_liteinst_refuses_a_kernel_older_than_6_5() {
6820 for release in [
6821 "6.5.0",
6822 "6.5",
6823 "6.10.3-200.fc40.x86_64",
6824 "7.1.3-0_fbk0_rc18",
6825 "10.0",
6826 ] {
6827 assert_eq!(in_guest_liteinst_kernel_gap(release), None, "{release}");
6828 }
6829 for release in ["6.4.16", "5.15.0-91-generic", "4.19"] {
6830 let gap = in_guest_liteinst_kernel_gap(release)
6831 .unwrap_or_else(|| panic!("{release} was not refused"));
6832 assert!(gap.contains("Linux 6.5 or later"), "{gap}");
6833 assert!(gap.contains(release), "{gap}");
6834 }
6835 for release in ["", "unknown", "6"] {
6836 assert!(
6837 in_guest_liteinst_kernel_gap(release).is_some(),
6838 "{release:?}"
6839 );
6840 }
6841 }
6845
6846 #[test]
6847 #[cfg(feature = "liteinst")]
6848 fn in_guest_liteinst_refuses_secure_execution_images() {
6849 use interp::startup_fixtures::dynamic_executable;
6850
6851 let directory = tempfile::tempdir().unwrap();
6852 let bytes = dynamic_executable(false);
6853 let gap = |name: &str, mode: u32| {
6854 let program = write_guest_program(directory.path(), name, &bytes, mode);
6855 in_guest_liteinst_program_gap(&mut Command::new(&program)).unwrap()
6856 };
6857 for (name, mode) in [("setuid", 0o4755), ("setgid", 0o2755)] {
6858 let refusal = gap(name, mode).unwrap_or_else(|| panic!("{name} was not refused"));
6859 assert!(refusal.contains("secure-execution mode"), "{refusal}");
6860 }
6861 assert_eq!(gap("setgid-no-group-exec", 0o2744), None);
6864 }
6865
6866 #[test]
6867 #[cfg(feature = "liteinst")]
6868 fn in_guest_liteinst_checks_scripts_through_their_interpreter() {
6869 use interp::startup_fixtures::*;
6870
6871 let directory = tempfile::tempdir().unwrap();
6872 let dynamic = write_guest_program(
6873 directory.path(),
6874 "dynamic",
6875 &dynamic_executable(false),
6876 0o755,
6877 );
6878 let static_elf = write_guest_program(
6879 directory.path(),
6880 "static",
6881 &elf(EM_X86_64, &[(PT_LOAD, b"code")]),
6882 0o755,
6883 );
6884
6885 let script = write_guest_program(
6886 directory.path(),
6887 "to-static",
6888 &shebang_to(&static_elf),
6889 0o755,
6890 );
6891 let gap = in_guest_liteinst_program_gap(&mut Command::new(&script))
6892 .unwrap()
6893 .expect("a script run by a static interpreter was not refused");
6894 assert!(
6895 gap.contains(&static_elf.display().to_string()) && gap.contains("statically linked"),
6896 "{gap}"
6897 );
6898
6899 let relative = write_guest_program(directory.path(), "relative", b"#!static\n", 0o755);
6901 let gap =
6902 in_guest_liteinst_program_gap(Command::new(&relative).current_dir(directory.path()))
6903 .unwrap()
6904 .expect("a relative static interpreter was not refused");
6905 assert!(gap.contains("statically linked"), "{gap}");
6906
6907 write_guest_program(
6910 directory.path(),
6911 "interp",
6912 &dynamic_executable(false),
6913 0o755,
6914 );
6915 let interp_cr = write_guest_program(
6916 directory.path(),
6917 "interp\r",
6918 &elf(EM_X86_64, &[(PT_LOAD, b"code")]),
6919 0o755,
6920 );
6921 let mut crlf = b"#!".to_vec();
6922 crlf.extend_from_slice(directory.path().join("interp").as_os_str().as_bytes());
6923 crlf.extend_from_slice(b"\r\necho script\r\n");
6924 let crlf = write_guest_program(directory.path(), "crlf", &crlf, 0o755);
6925 let gap = in_guest_liteinst_program_gap(&mut Command::new(&crlf))
6926 .unwrap()
6927 .expect("a CRLF script run by a static interp\\r was not refused");
6928 assert!(
6929 gap.contains(&interp_cr.display().to_string()) && gap.contains("statically linked"),
6930 "{gap}"
6931 );
6932
6933 let mut truncated = b"#!/".to_vec();
6937 truncated.resize(256, b'a');
6938 for (name, bytes) in [
6939 ("empty", b"#! \t\nbody\n".to_vec()),
6940 ("truncated", truncated),
6941 ] {
6942 let program = write_guest_program(directory.path(), name, &bytes, 0o755);
6943 let gap = in_guest_liteinst_program_gap(&mut Command::new(&program))
6944 .unwrap()
6945 .unwrap_or_else(|| panic!("{name} was not refused"));
6946 assert!(
6947 gap.contains("the kernel's script handler declines it"),
6948 "{name}: {gap}"
6949 );
6950 }
6951
6952 let mut target = dynamic;
6954 for level in 1..=5 {
6955 target = write_guest_program(
6956 directory.path(),
6957 &format!("level-{level}"),
6958 &shebang_to(&target),
6959 0o755,
6960 );
6961 let gap = in_guest_liteinst_program_gap(&mut Command::new(&target)).unwrap();
6962 if level <= MAX_INTERPRETER_DEPTH {
6963 assert_eq!(gap, None, "level {level}");
6964 } else {
6965 let gap = gap.expect("five nested scripts were not refused");
6966 assert!(gap.contains("nest more than 4 deep"), "{gap}");
6967 }
6968 }
6969 }
6970
6971 #[test]
6972 #[cfg(feature = "liteinst")]
6973 fn in_guest_liteinst_refuses_a_fifo_without_blocking() {
6974 let directory = tempfile::tempdir().unwrap();
6975 let fifo = directory.path().join("fifo");
6976 let fifo_c = std::ffi::CString::new(fifo.as_os_str().as_bytes()).unwrap();
6977 assert_eq!(unsafe { libc::mkfifo(fifo_c.as_ptr(), 0o700) }, 0);
6978 let script = write_guest_program(directory.path(), "to-fifo", &shebang_to(&fifo), 0o755);
6979 let socket = directory.path().join("socket");
6982 let _listener = std::os::unix::net::UnixListener::bind(&socket).unwrap();
6983 let to_socket =
6984 write_guest_program(directory.path(), "to-socket", &shebang_to(&socket), 0o755);
6985 let device = PathBuf::from("/dev/null");
6986 let to_device =
6987 write_guest_program(directory.path(), "to-device", &shebang_to(&device), 0o755);
6988 let cases = [
6994 (
6995 "program",
6996 PathBuf::from("./fifo"),
6997 Some(directory.path().to_owned()),
6998 fs::canonicalize(&fifo).unwrap(),
6999 ),
7000 ("interpreter", script, None, fifo.clone()),
7001 ("socket interpreter", to_socket, None, socket.clone()),
7002 ("device interpreter", to_device, None, device),
7003 ];
7004 for (name, program, current_dir, shown) in cases {
7005 let (sender, receiver) = std::sync::mpsc::channel();
7006 std::thread::spawn(move || {
7007 let mut command = Command::new(&program);
7008 if let Some(directory) = current_dir {
7009 command.current_dir(directory);
7010 }
7011 let gap = in_guest_liteinst_program_gap(&mut command)
7012 .map_err(|error| format!("{error:#}"));
7013 let _ = sender.send(gap);
7014 });
7015 let gap = receiver
7016 .recv_timeout(std::time::Duration::from_secs(10))
7017 .unwrap_or_else(|_| panic!("{name}: the check blocked on the FIFO"))
7018 .unwrap()
7019 .unwrap_or_else(|| panic!("{name}: the FIFO was not refused"));
7020 assert!(
7021 gap.contains(&format!("{} is not a regular file", shown.display())),
7022 "{name}: {gap}"
7023 );
7024 }
7025 }
7026
7027 #[test]
7028 #[cfg(feature = "liteinst")]
7029 fn in_guest_liteinst_pins_the_program_the_launch_resolves() {
7030 use interp::startup_fixtures::*;
7031
7032 let directory = tempfile::tempdir().unwrap();
7033 let name = "hermit-3520-static";
7035 let static_elf = write_guest_program(
7036 directory.path(),
7037 name,
7038 &elf(EM_X86_64, &[(PT_LOAD, b"code")]),
7039 0o755,
7040 );
7041 let search = format!("/nonexistent-directory:{}", directory.path().display());
7042 let check = |build: &dyn Fn() -> Command| {
7046 let launch = build().find_program();
7047 let mut command = build();
7048 let arg0 = command.get_arg0().to_owned();
7049 let gap = in_guest_liteinst_program_gap(&mut command);
7050 match launch {
7051 Ok(program) => {
7052 let gap = gap.unwrap().expect("the static image was not refused");
7053 assert!(gap.contains("is statically linked"), "{gap}");
7054 assert_eq!(Path::new(command.get_program()), program);
7055 assert_eq!(command.get_arg0(), arg0);
7056 assert_eq!(command.find_program().unwrap(), program);
7058 assert_eq!(
7059 fs::canonicalize(&program).unwrap(),
7060 fs::canonicalize(&static_elf).unwrap()
7061 );
7062 true
7063 }
7064 Err(_) => {
7065 let error = gap.expect_err("the check found what the launch cannot");
7066 assert!(
7067 format!("{error:#}").contains("cannot find guest program"),
7068 "{error:#}"
7069 );
7070 false
7071 }
7072 }
7073 };
7074
7075 assert!(check(&|| {
7077 let mut command = Command::new(format!("./{name}"));
7078 command.current_dir(directory.path());
7079 command
7080 }));
7081 assert!(check(&|| {
7084 let mut command = Command::new(name);
7085 command.env_clear().env("PATH", &search);
7086 command
7087 }));
7088 assert!(!check(&|| {
7091 let mut command = Command::new(name);
7092 command.env("PATH", &search);
7093 command
7094 }));
7095 assert!(!check(&|| {
7098 let mut command = Command::new(name);
7099 command.env_clear().current_dir(directory.path());
7100 command
7101 }));
7102 fs::set_permissions(&static_elf, fs::Permissions::from_mode(0o644)).unwrap();
7105 assert!(!check(&|| {
7106 let mut command = Command::new(name);
7107 command.env_clear().env("PATH", &search);
7108 command
7109 }));
7110 assert!(!check(&|| Command::new(&static_elf)));
7111 assert!(!check(&|| Command::new("hermit-no-such-program-3520")));
7112 }
7113
7114 #[test]
7115 fn skid_overshoot_error_refuses_a_successful_result() {
7116 let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
7117 let _ = reverie::take_skid_overshoot_count();
7118 assert!(take_skid_overshoot_error().is_none());
7119
7120 reverie::record_skid_overshoot();
7121 let error = take_skid_overshoot_error().expect("recorded overshoot must be reported");
7122 assert!(
7123 error
7124 .to_string()
7125 .contains("observed 1 HERMIT_SKID_OVERSHOOT report(s)")
7126 );
7127 assert!(
7128 error
7129 .to_string()
7130 .contains("deterministic execution was not established")
7131 );
7132 assert_eq!(reverie::take_skid_overshoot_count(), 0);
7133 }
7134
7135 #[test]
7136 fn skid_overshoot_report_preserves_success_without_an_overshoot() {
7137 let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
7138 let _ = reverie::take_skid_overshoot_count();
7139
7140 let report = SkidOvershootReport::begin(true);
7141 assert_eq!(report.finish(Ok::<_, Error>(7)).unwrap(), 7);
7142 assert_eq!(reverie::take_skid_overshoot_count(), 0);
7143 }
7144
7145 #[test]
7146 fn skid_overshoot_count_can_cross_the_verify_boundary_with_the_output() {
7147 let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
7148 let _ = reverie::take_skid_overshoot_count();
7149
7150 let report = SkidOvershootReport::begin(true);
7151 reverie::record_skid_overshoot();
7152 let (value, count) = report.finish_with_count(Ok::<_, Error>(7)).unwrap();
7153 assert_eq!(value, 7);
7154 assert_eq!(count, 1);
7155 assert_eq!(reverie::take_skid_overshoot_count(), 0);
7156 }
7157
7158 #[test]
7173 #[cfg(feature = "liteinst")]
7174 fn liteinst_forced_shutdown_covers_every_status_hermit_reserves() {
7175 assert!(
7178 liteinst_requires_forced_shutdown(ExitStatus::Exited(130)),
7179 "128+SIGINT"
7180 );
7181 assert!(
7182 liteinst_requires_forced_shutdown(ExitStatus::Exited(143)),
7183 "128+SIGTERM"
7184 );
7185 assert!(
7186 liteinst_requires_forced_shutdown(ExitStatus::Exited(129)),
7187 "128+SIGHUP"
7188 );
7189
7190 assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(122)));
7192 assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(125)));
7193 assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(127)));
7194
7195 assert!(liteinst_requires_forced_shutdown(ExitStatus::Signaled(
7197 nix::sys::signal::Signal::SIGKILL,
7198 false
7199 )));
7200
7201 assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(0)));
7206 assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(1)));
7207 assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(121)));
7208 assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(128)));
7209 assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(200)));
7210 assert!(
7216 liteinst_requires_forced_shutdown(ExitStatus::Exited(192)),
7217 "128 + SIGRTMAX is still a signal death and must force shutdown"
7218 );
7219 assert!(
7220 !liteinst_requires_forced_shutdown(ExitStatus::Exited(193)),
7221 "above SIGRTMAX the status is the guest's own and must NOT force shutdown"
7222 );
7223 }
7224
7225 #[test]
7229 fn a_cwd_under_tmp_is_explained_by_the_container_tmpfs_not_by_a_missing_directory() {
7230 let error = std::io::Error::from(std::io::ErrorKind::NotFound);
7231 let rendered = format!(
7232 "{}",
7233 super::kvm_cwd_resolution_error(std::path::Path::new("/tmp/agent-checkout"), &error)
7234 );
7235 assert!(
7236 rendered.contains("private, empty tmpfs"),
7237 "must name the mechanism: {rendered}"
7238 );
7239 assert!(
7240 rendered.contains("--workdir"),
7241 "must name a way out: {rendered}"
7242 );
7243 assert!(
7244 rendered.contains("/tmp/agent-checkout"),
7245 "must still name the path asked for: {rendered}"
7246 );
7247 }
7248
7249 #[test]
7253 fn the_tmpfs_explanation_is_withheld_where_it_does_not_apply() {
7254 let not_found = std::io::Error::from(std::io::ErrorKind::NotFound);
7255 let outside_path = std::path::Path::new("/nonexistent-home/wt");
7277 let outside = format!(
7278 "{}",
7279 super::kvm_cwd_resolution_error(outside_path, ¬_found)
7280 );
7281 assert!(!outside.contains("tmpfs"), "not a /tmp path: {outside}");
7282
7283 let tmp_itself = format!(
7286 "{}",
7287 super::kvm_cwd_resolution_error(std::path::Path::new("/tmp"), ¬_found)
7288 );
7289 assert!(!tmp_itself.contains("tmpfs"), "/tmp itself: {tmp_itself}");
7290
7291 let denied = std::io::Error::from(std::io::ErrorKind::PermissionDenied);
7293 let other = format!(
7294 "{}",
7295 super::kvm_cwd_resolution_error(std::path::Path::new("/tmp/x"), &denied)
7296 );
7297 assert!(!other.contains("tmpfs"), "not NotFound: {other}");
7298 }
7299
7300 #[test]
7310 fn an_unbuilt_backend_names_the_flag_and_claims_nothing_about_the_machine() {
7311 let feature_disabled_backends: &[(Backend, &str)] = &[
7312 #[cfg(not(feature = "dbt"))]
7313 (Backend::Dbt, "dbt"),
7314 #[cfg(not(feature = "sabre"))]
7315 (Backend::Sabre, "sabre"),
7316 #[cfg(not(feature = "e9patch"))]
7317 (Backend::E9patch, "e9patch"),
7318 #[cfg(not(feature = "liteinst"))]
7319 (Backend::Liteinst, "liteinst"),
7320 #[cfg(not(feature = "liteinst"))]
7322 (Backend::InGuestTrap, "liteinst"),
7323 ];
7324
7325 for &(backend, feature) in feature_disabled_backends {
7326 let reason = backend
7327 .unavailable_reason()
7328 .expect("a feature-disabled backend must report why it is unavailable");
7329 assert!(
7330 reason.contains(feature),
7331 "{backend:?}: a build-flag message must name the flag to rebuild with, got: {reason}"
7332 );
7333 assert!(
7334 reason.contains("has not been checked"),
7335 "{backend:?}: a build-flag message must not imply the machine was tested, got: {reason}"
7336 );
7337 }
7338 }
7339
7340 #[cfg(not(feature = "dbt"))]
7341 #[test]
7342 fn dbt_registry_diagnostic_redirects_to_a_source_build() {
7343 let reason = super::dbt_disabled_build_reason("hermit-run");
7344 assert!(reason.contains("not included in this registry release"));
7345 assert!(reason.contains("source build from https://github.com/rrnewton/hermit"));
7346 assert!(reason.contains("`third-party-backends` feature does not include DBT"));
7347 assert!(reason.contains("has not been checked"));
7348
7349 let source_reason = super::dbt_disabled_build_reason("hermit");
7350 assert!(source_reason.contains("rebuild with `--features dbt`"));
7351 assert!(!source_reason.contains("not included in this registry release"));
7352 }
7353
7354 #[cfg(not(feature = "sabre"))]
7355 #[tokio::test]
7356 async fn disabled_sabre_dispatch_refuses_before_resolving_the_program() {
7357 let program = "/hermit-missing-disabled-sabre-program";
7358 let error = super::dispatch_backend(
7359 super::Command::new(program),
7360 super::DetConfig::default(),
7361 false,
7362 &None,
7363 Backend::Sabre,
7364 None,
7365 )
7366 .await
7367 .unwrap_err();
7368 assert!(
7369 error
7370 .to_string()
7371 .contains("the `sabre` feature is not enabled")
7372 );
7373 let error = super::dispatch_output_backend(
7374 super::Command::new(program),
7375 super::DetConfig::default(),
7376 false,
7377 &None,
7378 Backend::Sabre,
7379 None,
7380 )
7381 .await
7382 .unwrap_err();
7383 assert!(
7384 error
7385 .to_string()
7386 .contains("the `sabre` feature is not enabled")
7387 );
7388 }
7389
7390 #[test]
7391 #[cfg(feature = "dbt")]
7392 fn a_cold_dbt_runtime_diagnostic_is_not_feature_absence() {
7393 let reason = dbt_runtime_unavailable_reason_from(Err(io::Error::new(
7394 io::ErrorKind::NotFound,
7395 "Hermit DBT runtime was not built beside /cold-target/hermit or in its deps directory",
7396 )))
7397 .expect("a missing cold-target runtime must remain unavailable");
7398
7399 assert!(reason.contains("was not built beside"));
7400 assert!(reason.contains("build the hermit binary and cdylib"));
7401 assert!(!reason.contains("not enabled in this build"));
7402 assert!(!reason.contains("has not been checked"));
7403 }
7404 #[cfg(feature = "sabre")]
7405 use std::ffi::OsStr;
7406 use std::fs;
7407 #[cfg(feature = "sabre")]
7408 use std::os::unix::fs::PermissionsExt;
7409 use std::path::PathBuf;
7410 #[cfg(feature = "sabre")]
7411 use std::sync::Arc;
7412 #[cfg(feature = "sabre")]
7413 use std::time::Duration;
7414
7415 use super::Backend;
7416 #[cfg(any(feature = "sabre", feature = "liteinst"))]
7417 use super::ExitStatus;
7418 use super::HermitData;
7419 use super::Id;
7420 #[cfg(feature = "sabre")]
7421 use super::SABRE_RPC_SOCKET_ENV;
7422 use super::collect_recording_ids;
7423 #[cfg(feature = "dbt")]
7424 use super::dbt_runtime_unavailable_reason;
7425 #[cfg(feature = "dbt")]
7426 use super::dbt_runtime_unavailable_reason_from;
7427 #[cfg(feature = "dbt")]
7428 use super::dynamorio_sdk_available;
7429 use super::ensure_backend_dispatch;
7430 #[cfg(feature = "dbt")]
7431 use super::is_dynamorio_sdk;
7432 use super::kvm_device_unavailable_reason;
7433 #[cfg(feature = "liteinst")]
7434 use super::liteinst_requires_forced_shutdown;
7435 #[cfg(feature = "dbt")]
7436 use super::liteinst_unavailable_reason;
7437 use super::output_backend_stdin_file;
7438 use super::prepare_backend_config;
7439 use super::reserve_output_stdin_snapshot;
7440 use super::resolve_kvm_shebang;
7441 #[cfg(feature = "sabre")]
7442 use super::resolve_sabre_binary_from;
7443 #[cfg(feature = "sabre")]
7444 use super::sabre_backend_evidence_line;
7445 #[cfg(feature = "sabre")]
7446 use super::sabre_program_needs_neutral_name;
7447 #[cfg(feature = "sabre")]
7448 use super::sabre_reach_state;
7449 #[cfg(feature = "sabre")]
7450 use super::sabre_uninstrumented_guest_message;
7451 #[cfg(feature = "sabre")]
7452 use super::shutdown_sabre_rpc;
7453 #[cfg(feature = "sabre")]
7454 use super::stage_sabre_program_in;
7455 #[cfg(feature = "sabre")]
7456 use super::stop_sabre_rpc_server;
7457 #[cfg(feature = "sabre")]
7458 use super::wait_for_sabre_rpc_disconnects;
7459
7460 #[test]
7461 fn recording_inventory_preserves_missing_and_non_recording_cases() {
7462 let parent = tempfile::tempdir().expect("failed to create recording inventory parent");
7463 let missing = parent.path().join("missing");
7464 assert!(
7465 HermitData::with_dir(&missing)
7466 .try_recordings()
7467 .expect("a missing data directory should be empty")
7468 .is_empty()
7469 );
7470
7471 let inventory = parent.path().join("inventory");
7472 fs::create_dir(&inventory).expect("failed to create recording inventory");
7473 let recording: Id = "0123456789abcdef0123456789abcdef"
7474 .parse()
7475 .expect("valid recording ID");
7476 fs::create_dir(inventory.join(recording.to_string()))
7477 .expect("failed to create recording directory");
7478 fs::create_dir(inventory.join("not-a-recording"))
7479 .expect("failed to create invalid-name directory");
7480 fs::write(
7481 inventory.join("fedcba9876543210fedcba9876543210"),
7482 b"not a directory",
7483 )
7484 .expect("failed to create valid-looking non-directory");
7485
7486 assert_eq!(
7487 HermitData::with_dir(&inventory)
7488 .try_recordings()
7489 .expect("recording inventory should be readable"),
7490 vec![recording]
7491 );
7492 assert_eq!(
7493 HermitData::with_dir(&inventory)
7494 .recordings()
7495 .collect::<Vec<_>>(),
7496 vec![recording]
7497 );
7498 }
7499
7500 #[test]
7501 fn recording_inventory_rejects_an_error_after_a_valid_entry() {
7502 let inventory = tempfile::tempdir().expect("failed to create recording inventory");
7503 let recording: Id = "0123456789abcdef0123456789abcdef"
7504 .parse()
7505 .expect("valid recording ID");
7506 fs::create_dir(inventory.path().join(recording.to_string()))
7507 .expect("failed to create recording directory");
7508 let valid_entry = fs::read_dir(inventory.path())
7509 .expect("failed to open recording inventory")
7510 .next()
7511 .expect("missing recording entry")
7512 .expect("failed to read recording entry");
7513
7514 let entries = vec![
7515 Ok(valid_entry),
7516 Err(std::io::Error::other("injected entry failure")),
7517 ];
7518 let error = collect_recording_ids(entries, inventory.path(), fs::DirEntry::file_type)
7519 .expect_err("a partial inventory must not be returned");
7520 assert!(
7521 error
7522 .to_string()
7523 .contains("Failed to read an entry in recording inventory"),
7524 "unexpected error: {error:#}"
7525 );
7526 }
7527
7528 #[test]
7529 fn recording_inventory_rejects_an_entry_inspection_error() {
7530 let inventory = tempfile::tempdir().expect("failed to create recording inventory");
7531 let recording = inventory.path().join("0123456789abcdef0123456789abcdef");
7532 fs::create_dir(&recording).expect("failed to create recording directory");
7533 let entry = fs::read_dir(inventory.path())
7534 .expect("failed to open recording inventory")
7535 .next()
7536 .expect("missing recording entry")
7537 .expect("failed to read recording entry");
7538
7539 let error = collect_recording_ids([Ok(entry)], inventory.path(), |_| {
7540 Err(std::io::Error::other("injected inspection failure"))
7541 })
7542 .expect_err("an uninspectable entry must fail the inventory");
7543 assert!(
7544 error
7545 .to_string()
7546 .contains("Failed to inspect recording inventory entry"),
7547 "unexpected error: {error:#}"
7548 );
7549 }
7550
7551 #[test]
7559 fn output_stdin_snapshot_replays_pipe_to_repeated_runs() {
7560 use std::io::Read;
7561 use std::io::Write;
7562 use std::os::fd::FromRawFd;
7563
7564 let mut fds = [0i32; 2];
7567 assert_eq!(unsafe { libc::pipe(fds.as_mut_ptr()) }, 0);
7568 let read_end = unsafe { fs::File::from_raw_fd(fds[0]) };
7570 let mut write_end = unsafe { fs::File::from_raw_fd(fds[1]) };
7571
7572 let payload = b"int main(){return 0;}\n";
7573 write_end.write_all(payload).unwrap();
7574 drop(write_end);
7576
7577 reserve_output_stdin_snapshot(Some(read_end)).unwrap();
7578
7579 for run in 0..2 {
7582 let mut file = output_backend_stdin_file()
7583 .unwrap()
7584 .unwrap_or_else(|| panic!("run {run}: expected a replayable stdin snapshot"));
7585 let mut got = Vec::new();
7586 file.read_to_end(&mut got).unwrap();
7587 assert_eq!(got, payload, "run {run} stdin replay mismatch");
7588 }
7589
7590 let mut file = output_backend_stdin_file().unwrap().unwrap();
7591 let error = file
7592 .write_all(b"guest-must-not-change-the-snapshot")
7593 .expect_err("the replayed stdin must be read-only");
7594 assert_eq!(error.raw_os_error(), Some(libc::EBADF));
7595 }
7596
7597 #[test]
7598 #[cfg(feature = "liteinst")]
7599 fn liteinst_reserved_failures_require_scheduler_cancellation() {
7600 for status in 122..=127 {
7601 assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(
7602 status
7603 )));
7604 }
7605 assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(121)));
7606 assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(128)));
7607 }
7608
7609 #[test]
7616 #[cfg(feature = "sabre")]
7617 fn uninstrumented_sabre_guest_is_reported_as_no_determinization() {
7618 let message = sabre_uninstrumented_guest_message(&ExitStatus::Exited(0));
7619 assert!(
7620 message.contains("no determinization at all"),
7621 "must not present an uninstrumented run as a weaker guarantee: {message}"
7622 );
7623 assert!(
7624 message.contains("Detcore coordinator"),
7625 "must name the authority that was never reached: {message}"
7626 );
7627 assert!(
7628 message.contains("statically linked ELF"),
7629 "must name the dominant cause so the reader can act: {message}"
7630 );
7631 assert!(
7634 message.contains("Exited(0)"),
7635 "must carry the observed status: {message}"
7636 );
7637 assert!(
7638 sabre_uninstrumented_guest_message(&ExitStatus::Exited(139)).contains("Exited(139)"),
7639 "must carry a failing status too"
7640 );
7641 }
7642
7643 #[test]
7647 #[cfg(feature = "sabre")]
7648 fn sabre_reach_states_are_pairwise_distinct() {
7649 let no_detcore = sabre_reach_state(false, 0);
7650 let degraded = sabre_reach_state(true, 1);
7651 let exercised = sabre_reach_state(true, 0);
7652
7653 assert_eq!(no_detcore, "no-detcore-reached");
7654 assert_eq!(degraded, "degraded-ptrace-fallback");
7655 assert_eq!(exercised, "sabre-exercised");
7656 assert_ne!(no_detcore, degraded);
7657 assert_ne!(no_detcore, exercised);
7658 assert_ne!(degraded, exercised);
7659 assert_eq!(
7660 sabre_reach_state(false, 9),
7661 "no-detcore-reached",
7662 "absence of a guest RPC must dominate any fallback count"
7663 );
7664 }
7665
7666 #[test]
7667 #[cfg(feature = "sabre")]
7668 fn sabre_backend_fact_is_versioned_and_names_preplugin_coverage() {
7669 let exercised = super::sabre_ptrace::PathEvidence {
7670 schema: 1,
7671 guest_rpc_observed: true,
7672 ptrace_fallback_sites: 0,
7673 trusted_shared_object_sites: 2,
7674 trusted_shared_objects: vec!["/usr/lib/libc.so.6".to_owned()],
7675 };
7676 assert_eq!(
7677 sabre_backend_evidence_line(&exercised),
7678 ":: Backend: sabre static rewriting + ptrace runtime; run_mode=run; \
7679 evidence_schema=1; preplugin_coverage=absent; ptrace_fallback_sites=0; \
7680 trusted_shared_object_sites=2; guest_rpc_observed=true; \
7681 reach_state=sabre-exercised"
7682 );
7683
7684 let unengaged = super::sabre_ptrace::PathEvidence {
7685 guest_rpc_observed: false,
7686 ..exercised
7687 };
7688 let fact = sabre_backend_evidence_line(&unengaged);
7689 assert!(fact.contains("preplugin_coverage=absent"));
7690 assert!(fact.contains("reach_state=no-detcore-reached"));
7691 assert!(!fact.contains("reach_state=sabre-exercised"));
7692 }
7693
7694 #[test]
7695 fn liteinst_backend_config_preserves_the_requested_timeslice() {
7696 let config = super::DetConfig::default();
7699 assert!(config.max_timeslice.is_some());
7700 for backend in [Backend::Liteinst, Backend::InGuestTrap] {
7701 assert!(
7702 prepare_backend_config(config.clone(), backend)
7703 .max_timeslice
7704 .is_some(),
7705 "{backend:?}"
7706 );
7707 }
7708 assert!(
7709 prepare_backend_config(config, Backend::Ptrace)
7710 .max_timeslice
7711 .is_some()
7712 );
7713 }
7714
7715 #[test]
7716 fn in_guest_liteinst_cancels_killed_thread_rpcs() {
7717 let config = super::DetConfig::default();
7718 for backend in [Backend::Liteinst, Backend::InGuestTrap] {
7719 assert!(
7720 prepare_backend_config(config.clone(), backend)
7721 .backend
7722 .needs_killed_thread_rpc_cancellation,
7723 "{backend:?}"
7724 );
7725 }
7726 assert!(
7728 !prepare_backend_config(config, Backend::Ptrace)
7729 .backend
7730 .needs_killed_thread_rpc_cancellation
7731 );
7732 }
7733
7734 #[test]
7735 fn sabre_backend_configures_process_local_capabilities() {
7736 let config = super::DetConfig::default();
7737 let sabre = prepare_backend_config(config.clone(), Backend::Sabre).backend;
7738 assert!(sabre.tool_shares_guest_descriptor_table);
7739 assert!(sabre.rediscovers_descriptors_after_exec);
7740 assert!(sabre.internal_pipe_turns_are_host_timed);
7741 assert!(sabre.loopback_pollers_yield_to_peers);
7742 assert!(sabre.guest_clock_reads_bypass_backend);
7743 assert!(sabre.virtualizes_syscall_clobbers);
7744 assert!(sabre.needs_killed_thread_rpc_cancellation);
7745 assert!(sabre.reports_physical_process_exits);
7746 assert!(sabre.signal_interrupts_external_syscalls);
7747 assert!(sabre.tracks_process_children);
7748 assert!(!sabre.runs_exit_robust_list);
7749 assert!(!sabre.requires_thread_directed_process_signals);
7750 assert!(!sabre.defers_vfork_child_registration);
7751 let ptrace = prepare_backend_config(config, Backend::Ptrace).backend;
7752 assert!(!ptrace.tool_shares_guest_descriptor_table);
7753 assert!(!ptrace.rediscovers_descriptors_after_exec);
7754 assert!(!ptrace.internal_pipe_turns_are_host_timed);
7755 assert!(!ptrace.loopback_pollers_yield_to_peers);
7756 assert!(!ptrace.guest_clock_reads_bypass_backend);
7757 assert!(!ptrace.virtualizes_syscall_clobbers);
7758 assert!(!ptrace.needs_killed_thread_rpc_cancellation);
7759 assert!(!ptrace.reports_physical_process_exits);
7760 assert!(!ptrace.signal_interrupts_external_syscalls);
7761 assert!(ptrace.tracks_process_children);
7762 assert!(ptrace.runs_exit_robust_list);
7763 assert!(!ptrace.requires_thread_directed_process_signals);
7764 assert!(!ptrace.defers_vfork_child_registration);
7765 }
7766
7767 #[test]
7768 fn kvm_reports_stored_metadata_timestamps_only_for_sequential_tool_threads() {
7769 let sequential = prepare_backend_config(
7770 super::DetConfig {
7771 sequentialize_threads: true,
7772 virtualize_metadata: true,
7773 ..super::DetConfig::default()
7774 },
7775 Backend::Kvm,
7776 );
7777 assert!(super::kvm_reports_stored_metadata_timestamps(&sequential));
7778
7779 let concurrent = super::DetConfig {
7782 sequentialize_threads: false,
7783 ..sequential.clone()
7784 };
7785 assert!(!super::kvm_reports_stored_metadata_timestamps(&concurrent));
7786
7787 let host_metadata = super::DetConfig {
7789 virtualize_metadata: false,
7790 ..sequential
7791 };
7792 assert!(!super::kvm_reports_stored_metadata_timestamps(
7793 &host_metadata
7794 ));
7795 }
7796
7797 #[test]
7798 fn kvm_backend_config_marks_concurrent_process_children() {
7799 let defaults = super::DetConfig::default();
7800 assert!(!defaults.sequentialize_threads);
7801 let nonsequential = prepare_backend_config(defaults, Backend::Kvm);
7802 assert!(nonsequential.backend.provides_process_signal_control);
7803 assert!(nonsequential.backend.emulates_child_waits);
7804 assert!(!may_observe_signal_dequeues(&nonsequential));
7805 assert!(!requires_signal_control(&nonsequential));
7806
7807 let config = super::DetConfig {
7808 sequentialize_threads: true,
7809 ..super::DetConfig::default()
7810 };
7811 let kvm = prepare_backend_config(config, Backend::Kvm);
7812 assert!(may_observe_signal_dequeues(&kvm));
7813 assert!(requires_signal_control(&kvm));
7814 assert!(kvm.backend.needs_killed_thread_rpc_cancellation);
7815 assert!(kvm.backend.tracks_process_children);
7816 assert!(!kvm.backend.runs_exit_robust_list);
7817 assert!(!kvm.backend.requires_thread_directed_process_signals);
7818 assert!(kvm.backend.defers_vfork_child_registration);
7819
7820 for backend in [
7823 Backend::Ptrace,
7824 Backend::Dbt,
7825 Backend::Sabre,
7826 Backend::Liteinst,
7827 Backend::InGuestTrap,
7828 Backend::E9patch,
7829 ] {
7830 let config = super::DetConfig {
7831 sequentialize_threads: true,
7832 ..super::DetConfig::default()
7833 };
7834 let prepared = prepare_backend_config(config, backend);
7835 assert!(!may_observe_signal_dequeues(&prepared), "{backend:?}");
7836 assert!(!requires_signal_control(&prepared), "{backend:?}");
7837 }
7838 }
7839
7840 fn may_observe_signal_dequeues(config: &DetConfig) -> bool {
7843 <super::Detcore as reverie::Tool>::may_observe_signal_dequeues(config)
7844 }
7845
7846 fn requires_signal_control(config: &DetConfig) -> bool {
7849 <super::Detcore as reverie::Tool>::requires_signal_control(config)
7850 }
7851
7852 fn golden_backend_capabilities(backend: Backend) -> serde_json::Value {
7883 let sabre = backend == Backend::Sabre;
7884 let kvm = backend == Backend::Kvm;
7885 let dbt = backend == Backend::Dbt;
7886 let in_guest_liteinst = matches!(backend, Backend::Liteinst | Backend::InGuestTrap);
7888 serde_json::json!({
7889 "tool_shares_guest_descriptor_table": sabre || dbt,
7890 "rediscovers_descriptors_after_exec": sabre || dbt,
7891 "internal_pipe_turns_are_host_timed": sabre,
7892 "loopback_pollers_yield_to_peers": sabre,
7893 "guest_clock_reads_bypass_backend": sabre,
7894 "virtualizes_syscall_clobbers": sabre,
7895 "needs_killed_thread_rpc_cancellation": in_guest_liteinst || sabre || dbt || kvm,
7896 "reports_physical_process_exits": sabre,
7897 "process_exits_complete_asynchronously": in_guest_liteinst,
7898 "virtualizes_guest_sigalrm": in_guest_liteinst,
7899 "signal_interrupts_external_syscalls": sabre,
7900 "tracks_process_children": !dbt,
7901 "runs_exit_robust_list": matches!(backend, Backend::Ptrace | Backend::E9patch),
7902 "requires_thread_directed_process_signals": dbt,
7903 "supports_parked_write_signal_interruption":
7904 matches!(backend, Backend::Ptrace | Backend::E9patch | Backend::Kvm),
7905 "defers_vfork_child_registration": kvm,
7906 "supports_madvise": !kvm,
7907 "supports_madv_dontneed": true,
7908 "reports_child_exit_publication":
7909 matches!(backend, Backend::Ptrace | Backend::E9patch),
7910 "reports_kernel_child_exit_signals":
7911 matches!(backend, Backend::Ptrace | Backend::E9patch | Backend::Sabre),
7912 "provides_process_signal_control": kvm,
7913 "emulates_child_waits": kvm,
7914 "supports_blocked_wait_signal_interruption":
7917 matches!(backend, Backend::Ptrace | Backend::E9patch),
7918 "delivers_preemption_timer_events":
7919 matches!(backend, Backend::Ptrace | Backend::E9patch),
7920 "runs_guest_code_between_injections": sabre || in_guest_liteinst,
7921 "promotes_open_files_before_native_lifecycle": dbt || in_guest_liteinst,
7922 "reports_sigreturns": matches!(backend, Backend::Ptrace | Backend::E9patch),
7926 })
7927 }
7928
7929 #[test]
7930 fn backend_capabilities_match_the_golden_table() {
7931 for backend in [
7932 Backend::Ptrace,
7933 Backend::Kvm,
7934 Backend::E9patch,
7935 Backend::Liteinst,
7936 Backend::InGuestTrap,
7937 Backend::Sabre,
7938 Backend::Dbt,
7939 ] {
7940 let config = prepare_backend_config(super::DetConfig::default(), backend);
7941 assert_eq!(
7942 serde_json::to_value(config.backend).unwrap(),
7943 golden_backend_capabilities(backend),
7944 "{backend:?}"
7945 );
7946 }
7947 }
7948
7949 #[test]
7950 fn backend_capabilities_are_the_ones_each_backend_reports() {
7951 assert_eq!(
7952 super::backend_capabilities(Backend::Ptrace),
7953 <reverie_ptrace::PtraceBackend as reverie::Backend>::capabilities()
7954 );
7955 assert_eq!(
7956 super::backend_capabilities(Backend::Kvm),
7957 reverie_kvm::KvmBackend::capabilities()
7958 );
7959 #[cfg(feature = "liteinst")]
7960 {
7961 let backing = unsafe {
7965 std::ptr::addr_of!(super::reverie_liteinst_allocator_backing_v1)
7966 .cast::<[u64; 2]>()
7967 .read_volatile()
7968 };
7969 assert_eq!(backing, [1, 1], "host Hermit must declare Legacy backing");
7970 assert_eq!(
7971 super::backend_capabilities(Backend::Liteinst),
7972 <reverie_liteinst::LiteinstBackend as reverie::Backend>::capabilities()
7973 );
7974 assert_eq!(
7976 super::backend_capabilities(Backend::InGuestTrap),
7977 <reverie_liteinst::LiteinstBackend as reverie::Backend>::capabilities()
7978 );
7979 }
7980 #[cfg(feature = "dbt")]
7981 {
7982 assert_eq!(
7983 super::backend_capabilities(Backend::Dbt),
7984 reverie_dbt::DbtRunner::capabilities()
7985 );
7986 assert_eq!(
7989 super::backend_capabilities(Backend::Dbt),
7990 detcore_dbt::backend_capabilities()
7991 );
7992 }
7993 }
7994
7995 fn env_free_detconfig(epoch: &str, seed: &str) -> DetConfig {
7999 use clap::Parser;
8000 let mut config = DetConfig::parse_from(["hermit", epoch, seed, "--sched-seed=0"]);
8001 config.sched_seed = None;
8002 config
8003 }
8004
8005 fn rich_detconfig() -> DetConfig {
8009 let mut config = env_free_detconfig("--epoch=2000-12-31T23:59:59Z", "--seed=7");
8010 config.rng_seed = Some(13);
8011 config.sched_seed = Some(11);
8012 config.clock_multiplier = Some(1.5);
8013 config.chaos = true;
8014 config.record_preemptions_to = Some(std::path::PathBuf::from(
8015 "/tmp/a,\"detect_host_clock_futex_timeouts\":true,\"backend_tracks_process_children\":{",
8016 ));
8017 config.mountinfo_root_rewrites = vec![detcore_model::config::MountInfoRootRewrite {
8018 raw_mount_id: 41,
8019 deterministic_root: b"/".to_vec(),
8020 raw_root_prefix: Some(b"/tmp/x".to_vec()),
8021 deterministic_root_prefix: Some(b"/tmp".to_vec()),
8022 raw_mountpoint_prefix: None,
8023 deterministic_mountpoint_prefix: None,
8024 }];
8025 config.stacktrace_event = vec![(3, Some(std::path::PathBuf::from("/s")))];
8026 config
8027 }
8028
8029 #[test]
8045 fn historical_dbt_capabilities_preserve_legacy_detconfig_bytes() {
8046 let sequential = |mut config: DetConfig| {
8047 config.sequentialize_threads = true;
8048 config
8049 };
8050 let default_config = || env_free_detconfig("--epoch=2026-01-01T00:00:00Z", "--seed=0");
8051 for (name, mut config, before) in [
8052 (
8053 "default",
8054 default_config(),
8055 include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-default.json"),
8056 ),
8057 (
8058 "dbt",
8059 prepare_backend_config(sequential(default_config()), Backend::Dbt),
8060 include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-dbt.json"),
8061 ),
8062 (
8063 "rich_dbt",
8064 prepare_backend_config(sequential(rich_detconfig()), Backend::Dbt),
8065 include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-rich_dbt.json"),
8066 ),
8067 ] {
8068 config.backend.tool_shares_guest_descriptor_table = false;
8069 config.backend.rediscovers_descriptors_after_exec = false;
8070 config.backend.supports_blocked_wait_signal_interruption = false;
8072 config.backend.delivers_preemption_timer_events = false;
8073 config.backend.runs_guest_code_between_injections = false;
8074 assert_eq!(
8075 detcore::to_legacy_backend_json(&config).unwrap(),
8076 before,
8077 "HERMIT_DBT_DETCONFIG for the {name} config changed"
8078 );
8079 let decoded = detcore::from_legacy_backend_json(before).unwrap();
8081 assert_eq!(decoded.backend, config.backend, "{name}");
8082 assert_eq!(
8083 decoded.sequentialize_threads, config.sequentialize_threads,
8084 "{name}"
8085 );
8086 assert_eq!(
8087 detcore::to_legacy_backend_json(&decoded).unwrap(),
8088 before,
8089 "{name}"
8090 );
8091 }
8092 }
8093
8094 const LEGACY_BACKEND_KEYS: [&str; 15] = [
8097 "cpuid_virtualized_by_backend",
8098 "backend_supports_madvise",
8099 "discover_live_file_metadata",
8100 "detect_host_clock_futex_timeouts",
8101 "syscall_clobbers_virtualized_by_backend",
8102 "cancel_killed_thread_rpcs",
8103 "backend_reports_physical_process_exits",
8104 "backend_tracks_process_children",
8105 "backend_runs_exit_robust_list",
8106 "backend_requires_thread_directed_process_signals",
8107 "backend_is_kvm",
8108 "kvm_shared_dequeue_timers",
8109 "backend_supports_parked_write_signal_interruption",
8110 "backend_virtualizes_capability_prctls",
8111 "backend_defers_vfork_child_registration",
8112 ];
8113
8114 #[test]
8126 fn every_backend_encodes_its_current_legacy_projection() {
8127 for (backend, unsequenced, sequential) in [
8128 (Backend::Ptrace, "010000011000100", "010000011000100"),
8129 (Backend::E9patch, "010000011000100", "010000011000100"),
8130 (Backend::Liteinst, "010001010000000", "010001010000000"),
8131 (Backend::InGuestTrap, "010001010000000", "010001010000000"),
8132 (Backend::Sabre, "011111110000000", "011111110000000"),
8133 (Backend::Dbt, "011001000100000", "011001000100000"),
8134 (Backend::Kvm, "000001010010101", "000001010011101"),
8135 ] {
8136 for (sequentialize_threads, expected) in [(false, unsequenced), (true, sequential)] {
8137 let config = prepare_backend_config(
8138 DetConfig {
8139 sequentialize_threads,
8140 ..DetConfig::default()
8141 },
8142 backend,
8143 );
8144 let encoded: serde_json::Map<String, serde_json::Value> =
8145 serde_json::from_str(&detcore::to_legacy_backend_json(&config).unwrap())
8146 .unwrap();
8147 let digits: String = LEGACY_BACKEND_KEYS
8148 .iter()
8149 .map(|key| match encoded.get(*key) {
8150 Some(serde_json::Value::Bool(true)) => '1',
8151 Some(serde_json::Value::Bool(false)) => '0',
8152 other => panic!("{key} encoded as {other:?}"),
8153 })
8154 .collect();
8155 assert_eq!(
8156 digits, expected,
8157 "{backend:?}, sequentialize_threads={sequentialize_threads}"
8158 );
8159 }
8160 }
8161 }
8162
8163 #[test]
8164 fn dbt_backend_config_translates_process_signals_to_host_threads() {
8165 let config = prepare_backend_config(super::DetConfig::default(), Backend::Dbt);
8166 assert!(config.backend.needs_killed_thread_rpc_cancellation);
8167 assert!(!config.backend.tracks_process_children);
8168 assert!(!config.backend.runs_exit_robust_list);
8169 assert!(config.backend.requires_thread_directed_process_signals);
8170 assert!(!config.backend.defers_vfork_child_registration);
8171 }
8172
8173 #[test]
8174 fn backend_write_signal_contract_is_explicit() {
8175 for (backend, supports_interruption) in [
8176 (Backend::Ptrace, true),
8177 (Backend::Dbt, false),
8178 (Backend::Kvm, true),
8179 (Backend::Sabre, false),
8180 (Backend::Liteinst, false),
8181 (Backend::InGuestTrap, false),
8182 (Backend::E9patch, true),
8183 ] {
8184 let config = prepare_backend_config(super::DetConfig::default(), backend);
8185 assert_eq!(
8186 config.backend.supports_parked_write_signal_interruption, supports_interruption,
8187 "unexpected parked-write signal support for {backend:?}"
8188 );
8189 }
8190 }
8191
8192 #[test]
8196 fn backend_timer_delivery_is_explicit() {
8197 for (backend, delivers) in [
8198 (Backend::Ptrace, true),
8199 (Backend::Dbt, false),
8200 (Backend::Kvm, false),
8201 (Backend::Sabre, false),
8202 (Backend::Liteinst, false),
8203 (Backend::InGuestTrap, false),
8204 (Backend::E9patch, true),
8205 ] {
8206 let config = prepare_backend_config(super::DetConfig::default(), backend);
8207 assert_eq!(
8208 config.backend.delivers_preemption_timer_events, delivers,
8209 "unexpected timer delivery for {backend:?}"
8210 );
8211 }
8212 }
8213
8214 #[test]
8217 fn backend_guest_code_between_injections_is_explicit() {
8218 for (backend, runs) in [
8219 (Backend::Ptrace, false),
8220 (Backend::Dbt, false),
8221 (Backend::Kvm, false),
8222 (Backend::Sabre, true),
8223 (Backend::Liteinst, true),
8224 (Backend::InGuestTrap, true),
8225 (Backend::E9patch, false),
8226 ] {
8227 let config = prepare_backend_config(super::DetConfig::default(), backend);
8228 assert_eq!(
8229 config.backend.runs_guest_code_between_injections, runs,
8230 "unexpected guest code between injections for {backend:?}"
8231 );
8232 }
8233 }
8234
8235 #[test]
8236 fn backend_blocked_wait_signal_contract_is_explicit() {
8237 for (backend, supports_interruption) in [
8238 (Backend::Ptrace, true),
8239 (Backend::Dbt, false),
8240 (Backend::Kvm, false),
8241 (Backend::Sabre, false),
8242 (Backend::Liteinst, false),
8243 (Backend::InGuestTrap, false),
8244 (Backend::E9patch, true),
8245 ] {
8246 let config = prepare_backend_config(super::DetConfig::default(), backend);
8247 assert_eq!(
8248 config.backend.supports_blocked_wait_signal_interruption, supports_interruption,
8249 "unexpected blocked-wait signal support for {backend:?}"
8250 );
8251 }
8252 }
8253
8254 #[test]
8259 fn a_launch_may_pass_a_terminal_unless_it_proves_it_has_none() {
8260 assert!(!super::may_pass_a_terminal(false, Some(0)));
8261 assert!(super::may_pass_a_terminal(true, Some(0)));
8262 assert!(super::may_pass_a_terminal(false, Some(34817)));
8263 assert!(super::may_pass_a_terminal(false, None));
8264
8265 let stat = "4242 (a) b (c)) S 1 4242 4242 34817 4242 4194560 0 0 0 0";
8266 assert_eq!(super::parse_controlling_terminal_device(stat), Some(34817));
8267 let stat = "4242 (hermit) S 1 4242 4242 0 -1 4194560 0 0 0 0";
8268 assert_eq!(super::parse_controlling_terminal_device(stat), Some(0));
8269 assert_eq!(
8270 super::parse_controlling_terminal_device("4242 (hermit"),
8271 None
8272 );
8273 assert_eq!(
8274 super::parse_controlling_terminal_device("4242 (hermit) S 1"),
8275 None
8276 );
8277 assert!(super::controlling_terminal_device().is_some());
8278 }
8279
8280 #[test]
8283 fn only_gated_backends_record_an_inherited_terminal() {
8284 for backend in [
8285 Backend::Dbt,
8286 Backend::Kvm,
8287 Backend::Sabre,
8288 Backend::Liteinst,
8289 Backend::InGuestTrap,
8290 Backend::E9patch,
8291 ] {
8292 let config = prepare_backend_config(super::DetConfig::default(), backend);
8293 assert!(
8294 !config.guest_may_inherit_a_terminal,
8295 "unexpected terminal record for {backend:?}"
8296 );
8297 }
8298 let config = prepare_backend_config(super::DetConfig::default(), Backend::Ptrace);
8299 assert_eq!(
8300 config.guest_may_inherit_a_terminal,
8301 super::launcher_may_pass_a_terminal()
8302 );
8303 }
8304
8305 #[test]
8306 fn liteinst_public_dispatch_runs_in_guest_detcore() {
8307 if Backend::Liteinst.ensure_available().is_err() {
8308 return;
8309 }
8310
8311 let config = super::DetConfig {
8315 max_timeslice: None,
8316 ..super::DetConfig::default()
8317 };
8318 let mut command = super::Command::new("/bin/echo");
8319 command.arg("hello");
8320 let output = super::run_with_output_backend(
8321 command,
8322 config.clone(),
8323 false,
8324 &None,
8325 Backend::Liteinst,
8326 )
8327 .expect("run /bin/echo through in-guest LiteInst");
8328 assert_eq!(
8330 output.status,
8331 super::ExitStatus::Exited(0),
8332 "guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
8333 String::from_utf8_lossy(&output.stderr),
8334 String::from_utf8_lossy(&output.stdout),
8335 );
8336 assert_eq!(output.stdout, b"hello\n");
8337
8338 let status = super::run_with_backend(
8339 super::Command::new("/bin/true"),
8340 config,
8341 false,
8342 &None,
8343 Backend::Liteinst,
8344 )
8345 .expect("run /bin/true through in-guest LiteInst");
8346 assert_eq!(status, super::ExitStatus::Exited(0));
8347 }
8348
8349 #[test]
8350 #[cfg(feature = "dbt")]
8351 fn default_and_available_backends_reflect_host_probes() {
8352 assert_eq!(Backend::default(), Backend::Ptrace);
8353 let available = Backend::available().collect::<Vec<_>>();
8354 assert_eq!(
8355 available.contains(&Backend::Ptrace),
8356 Backend::Ptrace.is_available()
8357 );
8358 assert_eq!(
8359 available.contains(&Backend::Dbt),
8360 dynamorio_sdk_available() && dbt_runtime_unavailable_reason().is_none()
8361 );
8362 assert_eq!(
8363 available.contains(&Backend::Liteinst),
8364 liteinst_unavailable_reason().is_none()
8365 );
8366 assert_eq!(
8368 available.contains(&Backend::InGuestTrap),
8369 available.contains(&Backend::Liteinst)
8370 );
8371 assert_eq!(
8372 available.contains(&Backend::Sabre),
8373 Backend::Sabre.is_available()
8374 );
8375 assert_eq!(
8376 available.contains(&Backend::Kvm),
8377 kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_none(),
8378 );
8379 assert_eq!(
8380 available.contains(&Backend::E9patch),
8381 Backend::E9patch.is_available()
8382 );
8383 }
8384
8385 #[test]
8386 #[cfg(feature = "dbt")]
8387 fn dependency_probes_require_usable_paths() {
8388 let temp = tempfile::tempdir().unwrap();
8389 assert!(!is_dynamorio_sdk(temp.path()));
8390 fs::create_dir(temp.path().join("include")).unwrap();
8391 fs::write(temp.path().join("include/dr_api.h"), b"/* marker */").unwrap();
8392 assert!(is_dynamorio_sdk(temp.path()));
8393
8394 let reason = kvm_device_unavailable_reason(temp.path())
8395 .expect("a directory must not pass the read-write KVM device probe");
8396 assert!(reason.contains("read-write"));
8397 }
8398
8399 #[cfg(feature = "sabre")]
8400 fn write_test_executable(path: &std::path::Path) {
8401 fs::create_dir_all(path.parent().unwrap()).unwrap();
8402 fs::write(path, b"test loader").unwrap();
8403 let mut permissions = fs::metadata(path).unwrap().permissions();
8404 permissions.set_mode(0o700);
8405 fs::set_permissions(path, permissions).unwrap();
8406 }
8407
8408 #[test]
8409 #[cfg(feature = "sabre")]
8410 fn sabre_rpc_socket_uses_private_exec_environment() {
8411 assert!(SABRE_RPC_SOCKET_ENV.starts_with("REVERIE_SABRE_"));
8412 }
8413
8414 #[test]
8415 #[cfg(feature = "sabre")]
8416 fn sabre_stages_program_names_that_collide_with_loader_prefix() {
8417 assert!(sabre_program_needs_neutral_name(
8418 PathBuf::from("/usr/bin/ld").as_path()
8419 ));
8420 assert!(sabre_program_needs_neutral_name(
8421 PathBuf::from("/usr/bin/ld.bfd").as_path()
8422 ));
8423 assert!(!sabre_program_needs_neutral_name(
8424 PathBuf::from("/usr/bin/gold").as_path()
8425 ));
8426 }
8427
8428 #[test]
8429 #[cfg(feature = "sabre")]
8430 fn sabre_neutral_name_staging_preserves_program_bytes_and_cleans_up() {
8431 let temp = tempfile::tempdir().unwrap();
8432 let program = temp.path().join("ld.test");
8433 fs::write(&program, b"linker image").unwrap();
8434
8435 let staged = stage_sabre_program_in(&program, temp.path())
8436 .unwrap()
8437 .expect("ld-prefixed program should be staged");
8438 let staged_path = staged.path.clone();
8439 assert_eq!(fs::read(&staged_path).unwrap(), b"linker image");
8440 assert!(
8441 staged_path
8442 .file_name()
8443 .unwrap()
8444 .as_encoded_bytes()
8445 .starts_with(b"hermit-sabre-program-")
8446 );
8447
8448 drop(staged);
8449 assert!(!staged_path.exists());
8450 }
8451
8452 #[tokio::test(start_paused = true)]
8453 #[cfg(feature = "sabre")]
8454 async fn sabre_rpc_disconnect_wait_observes_delayed_release() {
8455 let global = Arc::new(());
8456 let connection = global.clone();
8457 tokio::spawn(async move {
8458 tokio::time::sleep(Duration::from_millis(10)).await;
8459 drop(connection);
8460 });
8461
8462 assert_eq!(
8463 wait_for_sabre_rpc_disconnects(&global, Duration::from_millis(50)).await,
8464 Ok(())
8465 );
8466 }
8467
8468 #[tokio::test(start_paused = true)]
8469 #[cfg(feature = "sabre")]
8470 async fn sabre_rpc_disconnect_wait_reports_stuck_connection() {
8471 let global = Arc::new(());
8472 let _connection = global.clone();
8473
8474 assert_eq!(
8475 wait_for_sabre_rpc_disconnects(&global, Duration::from_millis(10)).await,
8476 Err(1)
8477 );
8478 }
8479
8480 #[tokio::test]
8481 #[cfg(feature = "sabre")]
8482 async fn sabre_rpc_server_intentional_abort_is_clean() {
8483 let server_task = tokio::spawn(std::future::pending::<Result<(), &'static str>>());
8484
8485 assert!(stop_sabre_rpc_server(server_task).await.is_ok());
8486 }
8487
8488 #[tokio::test]
8489 #[cfg(feature = "sabre")]
8490 async fn sabre_rpc_server_failure_is_reported() {
8491 let server_task = tokio::spawn(async { Err::<(), _>("accept failed") });
8492 while !server_task.is_finished() {
8493 tokio::task::yield_now().await;
8494 }
8495
8496 let error = stop_sabre_rpc_server(server_task).await.unwrap_err();
8497 assert!(error.to_string().contains("accept failed"));
8498 }
8499
8500 #[tokio::test(start_paused = true)]
8501 #[cfg(feature = "sabre")]
8502 async fn sabre_rpc_shutdown_drains_connections_after_server_failure() {
8503 let global = Arc::new(());
8504 let connection = global.clone();
8505 tokio::spawn(async move {
8506 tokio::time::sleep(Duration::from_millis(10)).await;
8507 drop(connection);
8508 });
8509 let server_task = tokio::spawn(async { Err::<(), _>("accept failed") });
8510 while !server_task.is_finished() {
8511 tokio::task::yield_now().await;
8512 }
8513
8514 let error = shutdown_sabre_rpc(server_task, &global, Duration::from_millis(50))
8515 .await
8516 .unwrap_err();
8517 assert!(error.to_string().contains("accept failed"));
8518 assert_eq!(Arc::strong_count(&global), 1);
8519 }
8520
8521 #[test]
8522 #[cfg(feature = "sabre")]
8523 fn sabre_binary_resolver_finds_cargo_target_build() {
8524 let temp = tempfile::tempdir().unwrap();
8525 let executable = temp.path().join("target/release/hermit");
8526 let loader = temp.path().join("target/sabre/sabre");
8527 write_test_executable(&loader);
8528
8529 assert_eq!(
8530 resolve_sabre_binary_from(None, None, &executable, OsStr::new("")).unwrap(),
8531 loader
8532 );
8533 }
8534
8535 #[test]
8536 #[cfg(feature = "sabre")]
8537 fn sabre_binary_resolver_uses_packaged_loader() {
8538 let temp = tempfile::tempdir().unwrap();
8539 let executable = temp.path().join("target/release/hermit");
8540 let packaged = temp.path().join("install_pkg/rsrcs/sabre");
8541 write_test_executable(&packaged);
8542
8543 assert_eq!(
8544 resolve_sabre_binary_from(None, Some(&packaged), &executable, OsStr::new("")).unwrap(),
8545 packaged
8546 );
8547 }
8548
8549 #[test]
8550 #[cfg(feature = "sabre")]
8551 fn sabre_binary_resolver_prefers_and_validates_override() {
8552 let temp = tempfile::tempdir().unwrap();
8553 let executable = temp.path().join("target/release/hermit");
8554 let discovered = temp.path().join("target/sabre/sabre");
8555 let requested = temp.path().join("requested-sabre");
8556 write_test_executable(&discovered);
8557 write_test_executable(&requested);
8558
8559 assert_eq!(
8560 resolve_sabre_binary_from(
8561 Some(requested.as_os_str()),
8562 Some(&discovered),
8563 &executable,
8564 OsStr::new(""),
8565 )
8566 .unwrap(),
8567 requested
8568 );
8569
8570 let mut permissions = fs::metadata(&requested).unwrap().permissions();
8571 permissions.set_mode(0o600);
8572 fs::set_permissions(&requested, permissions).unwrap();
8573 let error = resolve_sabre_binary_from(
8574 Some(requested.as_os_str()),
8575 Some(&discovered),
8576 &executable,
8577 OsStr::new(""),
8578 )
8579 .unwrap_err();
8580 assert!(error.to_string().contains("is not an executable file"));
8581 }
8582
8583 #[test]
8584 #[cfg(feature = "dbt")]
8585 fn optional_backends_report_accurate_availability() {
8586 match Backend::Dbt.ensure_available() {
8587 Ok(()) => assert!(
8588 dynamorio_sdk_available() && dbt_runtime_unavailable_reason().is_none(),
8589 "DBT reported available without its SDK and runtime"
8590 ),
8591 Err(dbt_error) => {
8592 let message = dbt_error.to_string();
8593 assert!(
8594 message.contains("DynamoRIO runtime")
8595 || message.contains("Detcore DBT runtime"),
8596 "unexpected DBT availability error: {message}"
8597 );
8598 }
8599 }
8600 assert_eq!(
8601 Backend::Liteinst.ensure_available().is_ok(),
8602 liteinst_unavailable_reason().is_none()
8603 );
8604 assert_eq!(
8605 Backend::InGuestTrap.ensure_available().is_ok(),
8606 liteinst_unavailable_reason().is_none()
8607 );
8608
8609 match Backend::Kvm.ensure_available() {
8610 Ok(()) => assert!(
8611 kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_none(),
8612 "KVM reported available without a usable /dev/kvm",
8613 ),
8614 Err(kvm_error) => {
8615 let message = kvm_error.to_string();
8616 assert!(
8617 message.contains("/dev/kvm"),
8618 "unexpected KVM availability error: {message}",
8619 );
8620 assert!(!message.contains("requires root privileges"));
8621 }
8622 }
8623 }
8624
8625 #[test]
8626 fn public_backend_dispatch_rejects_unprepared_e9patch() {
8627 let error = ensure_backend_dispatch(Backend::E9patch).unwrap_err();
8628 assert!(
8629 error.to_string().contains("requires CLI preprocessing"),
8630 "unexpected error: {error}"
8631 );
8632 }
8633
8634 #[test]
8635 #[cfg(feature = "dbt")]
8636 fn dbt_retries_only_the_pre_guest_bootstrap_failure() {
8637 use std::os::unix::process::ExitStatusExt as _;
8638
8639 let failure = std::process::ExitStatus::from_raw(
8640 reverie_dbt::CLIENT_THREAD_START_FAILURE_EXIT_CODE << 8,
8641 );
8642 assert!(super::dbt_client_thread_start_failed(&failure));
8643 assert!(!super::dbt_client_thread_start_failed(
8644 &std::process::ExitStatus::from_raw(1 << 8)
8645 ));
8646 }
8647
8648 #[test]
8649 #[cfg(feature = "dbt")]
8650 fn dbt_public_dispatch_requires_sequentialized_threads() {
8651 let command = super::Command::new("/bin/true");
8652 let config = super::DetConfig {
8653 sequentialize_threads: false,
8654 ..Default::default()
8655 };
8656
8657 let error = super::run_with_output_backend(command, config, false, &None, Backend::Dbt)
8658 .expect_err("DBT must reject non-sequentialized execution");
8659 assert!(
8660 error
8661 .to_string()
8662 .contains("dbt backend requires sequentialized threads"),
8663 "unexpected error: {error}"
8664 );
8665 }
8666
8667 #[test]
8668 #[cfg(feature = "dbt")]
8669 fn dbt_public_dispatch_runs_echo_through_detcore() {
8670 use clap::Parser;
8671
8672 if Backend::Dbt.ensure_available().is_err() {
8673 return;
8674 }
8675
8676 const CHILD: &str = "HERMIT_TEST_DBT_LIBRARY_DIAGNOSTICS_CHILD";
8679 if std::env::var_os(CHILD).is_none() {
8680 let output = std::process::Command::new(std::env::current_exe().unwrap())
8681 .args([
8682 "--exact",
8683 "tests::dbt_public_dispatch_runs_echo_through_detcore",
8684 "--nocapture",
8685 ])
8686 .env(CHILD, "1")
8687 .output()
8688 .expect("run isolated DBT library output checks");
8689 let diagnostics = String::from_utf8_lossy(&output.stderr);
8690 assert!(output.status.success(), "{output:?}");
8691 assert!(
8692 diagnostics
8693 .lines()
8694 .filter(|line| line.starts_with("reverie-dbt: tool=Detcore "))
8695 .count()
8696 >= 2,
8697 "DBT native summaries did not prove both Detcore dispatches: {diagnostics}"
8698 );
8699 assert!(!diagnostics.contains("guest-stderr"), "{diagnostics}");
8700 return;
8701 }
8702
8703 let mut command = super::Command::new("/bin/echo");
8704 command.arg("hello");
8705 let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
8706 config.sequentialize_threads = true;
8707 config.validate();
8708 let output = super::run_with_output_backend(command, config, true, &None, Backend::Dbt)
8709 .expect("run /bin/echo through DbtGuest<Detcore>");
8710
8711 assert_eq!(
8713 output.status,
8714 super::ExitStatus::Exited(0),
8715 "guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
8716 String::from_utf8_lossy(&output.stderr),
8717 String::from_utf8_lossy(&output.stdout),
8718 );
8719 assert_eq!(output.stdout, b"hello\n");
8720 assert_eq!(output.stderr, b"");
8721
8722 let mut command = super::Command::new("/bin/sh");
8723 command.args(["-c", "printf 'guest-stderr\\n' >&2"]);
8724 let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
8725 config.sequentialize_threads = true;
8726 config.validate();
8727 let output = super::run_with_output_backend(command, config, true, &None, Backend::Dbt)
8728 .expect("capture nonempty guest stderr through DbtGuest<Detcore>");
8729 assert_eq!(output.status, super::ExitStatus::Exited(0), "{output:?}");
8730 assert_eq!(output.stdout, b"");
8731 assert_eq!(output.stderr, b"guest-stderr\n");
8732 }
8733
8734 #[test]
8735 #[cfg(feature = "dbt")]
8736 fn dbt_public_status_dispatch_runs_true_through_detcore() {
8737 use clap::Parser;
8738
8739 if Backend::Dbt.ensure_available().is_err() {
8740 return;
8741 }
8742
8743 let command = super::Command::new("/bin/true");
8744 let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
8745 config.sequentialize_threads = true;
8746 config.validate();
8747 let status = super::run_with_backend(command, config, true, &None, Backend::Dbt)
8748 .expect("run /bin/true through DbtGuest<Detcore>");
8749
8750 assert_eq!(status, super::ExitStatus::Exited(0));
8751 }
8752
8753 #[test]
8754 fn kvm_runs_dynamic_echo_through_detcore() {
8755 use clap::Parser;
8756
8757 if kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_some() {
8758 return;
8759 }
8760
8761 let mut command = super::Command::new("/bin/echo");
8762 command.arg("hello");
8763 let mut config = super::DetConfig::parse_from(["hermit-kvm-test"]);
8764 config.validate();
8765 let output = super::run_with_output_backend(command, config, false, &None, Backend::Kvm)
8766 .expect("run dynamic /bin/echo through KvmGuest<Detcore>");
8767
8768 assert_eq!(
8770 output.status,
8771 super::ExitStatus::Exited(0),
8772 "guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
8773 String::from_utf8_lossy(&output.stderr),
8774 String::from_utf8_lossy(&output.stdout),
8775 );
8776 assert_eq!(output.stdout, b"hello\n");
8777 assert!(output.stderr.is_empty());
8778 }
8779
8780 #[test]
8783 fn detcore_drives_kvm_guest_for_synthetic_syscall() {
8784 use clap::Parser;
8785
8786 const MEMORY_SIZE: usize = 0x10_000;
8787 const ENTRY_POINT: u64 = 0x1000;
8788 const FRAME_ADDRESS: u64 = 0x2000;
8789
8790 let mut backend = match reverie_kvm::KvmBackend::new(MEMORY_SIZE) {
8791 Ok(backend) => backend,
8792 Err(error) => {
8793 eprintln!("skipping KVM Detcore experiment: cannot init VM: {error}");
8794 return;
8795 }
8796 };
8797
8798 backend
8800 .install_syscall(
8801 ENTRY_POINT,
8802 FRAME_ADDRESS,
8803 reverie_kvm::SyscallRequest::new(libc::SYS_getpid as u64, [0; 6]),
8804 )
8805 .expect("install synthetic getpid guest");
8806
8807 let mut config =
8809 super::DetConfig::parse_from(["hermit-kvm-test", "--max-timeslice=disabled"]);
8810 config.validate();
8811
8812 let runtime = tokio::runtime::Builder::new_current_thread()
8813 .enable_all()
8814 .build()
8815 .expect("build tokio runtime");
8816
8817 let outcome = runtime.block_on(async {
8818 backend
8819 .run_with_tool::<super::Detcore, _>(
8820 config,
8821 |request: &reverie_kvm::SyscallRequest, _memory: &reverie_kvm::GuestMemory| {
8823 unsafe {
8826 libc::syscall(
8827 request.number() as libc::c_long,
8828 request.args()[0],
8829 request.args()[1],
8830 request.args()[2],
8831 request.args()[3],
8832 request.args()[4],
8833 request.args()[5],
8834 ) as i64
8835 }
8836 },
8837 )
8838 .await
8839 });
8840
8841 outcome.expect("Detcore drove the synthetic KVM guest to completion");
8844 }
8845
8846 const FAKE_ELF: &[u8] = b"\x7fELF\x02\x01\x01\x00 fake elf body";
8849
8850 fn shebang_tmpdir(tag: &str) -> PathBuf {
8851 let dir = std::env::temp_dir().join(format!(
8852 "hermit-shebang-test-{}-{}",
8853 std::process::id(),
8854 tag
8855 ));
8856 let _ = fs::remove_dir_all(&dir);
8857 fs::create_dir_all(&dir).unwrap();
8858 dir
8859 }
8860
8861 #[test]
8862 fn resolve_shebang_plain_elf_is_unchanged() {
8863 let dir = shebang_tmpdir("plain");
8864 let prog = dir.join("prog");
8865 fs::write(&prog, FAKE_ELF).unwrap();
8866
8867 let argv = vec!["prog".to_owned(), "-a".to_owned()];
8868 let (path, out_argv, image) = resolve_kvm_shebang(&prog, argv).unwrap();
8869 assert_eq!(path, prog);
8870 assert_eq!(out_argv, vec!["prog".to_owned(), "-a".to_owned()]);
8871 assert_eq!(image, FAKE_ELF);
8872 fs::remove_dir_all(&dir).unwrap();
8873 }
8874
8875 #[test]
8876 fn resolve_shebang_single_level_kernel_order() {
8877 let dir = shebang_tmpdir("single");
8878 let interp = dir.join("fakebash");
8879 fs::write(&interp, FAKE_ELF).unwrap();
8880 let script = dir.join("script");
8881 fs::write(&script, format!("#!{} -x\necho hi\n", interp.display())).unwrap();
8883
8884 let argv = vec!["script".to_owned(), "arg1".to_owned()];
8885 let (path, out_argv, image) = resolve_kvm_shebang(&script, argv).unwrap();
8886 assert_eq!(path, interp);
8887 assert_eq!(
8889 out_argv,
8890 vec![
8891 interp.to_string_lossy().into_owned(),
8892 "-x".to_owned(),
8893 script.to_string_lossy().into_owned(),
8894 "arg1".to_owned(),
8895 ]
8896 );
8897 assert_eq!(image, FAKE_ELF);
8898 fs::remove_dir_all(&dir).unwrap();
8899 }
8900
8901 #[test]
8902 fn resolve_shebang_nested_accumulates_like_binfmt_script() {
8903 let dir = shebang_tmpdir("nested");
8904 let interp = dir.join("fakebash");
8905 fs::write(&interp, FAKE_ELF).unwrap();
8906 let mid = dir.join("mid"); fs::write(&mid, format!("#!{}\n", interp.display())).unwrap();
8908 let script = dir.join("script");
8909 fs::write(&script, format!("#!{} -e\n", mid.display())).unwrap();
8910
8911 let argv = vec!["script".to_owned(), "arg1".to_owned()];
8912 let (path, out_argv, image) = resolve_kvm_shebang(&script, argv).unwrap();
8913 assert_eq!(path, interp);
8914 assert_eq!(
8916 out_argv,
8917 vec![
8918 interp.to_string_lossy().into_owned(),
8919 mid.to_string_lossy().into_owned(),
8920 "-e".to_owned(),
8921 script.to_string_lossy().into_owned(),
8922 "arg1".to_owned(),
8923 ]
8924 );
8925 assert_eq!(image, FAKE_ELF);
8926 fs::remove_dir_all(&dir).unwrap();
8927 }
8928
8929 #[test]
8930 fn resolve_shebang_rejects_infinite_recursion() {
8931 let dir = shebang_tmpdir("loop");
8932 let a = dir.join("a");
8933 let b = dir.join("b");
8934 fs::write(&a, format!("#!{}\n", b.display())).unwrap();
8935 fs::write(&b, format!("#!{}\n", a.display())).unwrap();
8936
8937 let argv = vec!["a".to_owned()];
8938 assert!(resolve_kvm_shebang(&a, argv).is_err());
8939 fs::remove_dir_all(&dir).unwrap();
8940 }
8941
8942 mod reverie_pin_reader {
8946 include!("../reverie_pin.rs");
8947
8948 const A: &str = "1111111111111111111111111111111111111111";
8949 const B: &str = "2222222222222222222222222222222222222222";
8950
8951 fn dep(rev: &str) -> String {
8952 format!(
8953 "reverie = {{ git = \"https://github.com/rrnewton/reverie.git\", rev = \"{rev}\" }}\n"
8954 )
8955 }
8956
8957 #[test]
8958 fn a_single_revision_is_read() {
8959 assert_eq!(parse_reverie_pin(&dep(A)).as_deref(), Some(A));
8960 }
8961
8962 #[test]
8963 fn agreeing_revisions_are_read_once() {
8964 let text = format!("{}{}", dep(A), dep(A));
8965 assert_eq!(parse_reverie_pin(&text).as_deref(), Some(A));
8966 }
8967
8968 #[test]
8971 fn disagreeing_revisions_are_refused() {
8972 let text = format!("{}{}", dep(A), dep(B));
8973 assert_eq!(parse_reverie_pin(&text), None);
8974 }
8975
8976 #[test]
8980 fn a_commented_out_dependency_is_not_the_pin() {
8981 let text = format!("# {}{}", dep(B), dep(A));
8982 assert_eq!(
8983 parse_reverie_pin(&text).as_deref(),
8984 Some(A),
8985 "a commented-out revision must not win"
8986 );
8987 }
8988
8989 #[test]
8990 fn a_manifest_naming_no_revision_yields_none() {
8991 assert_eq!(parse_reverie_pin("[dependencies]\nlibc = \"0.2\"\n"), None);
8992 }
8993
8994 #[test]
8997 fn an_unparseable_revision_is_ambiguous() {
8998 let text = format!(
8999 "{}reverie-x = {{ git = \"https://github.com/rrnewton/reverie.git\", rev = \"beef\" }}\n",
9000 dep(A)
9001 );
9002 assert_eq!(parse_reverie_pin(&text), None);
9003 }
9004 }
9005
9006 #[cfg(feature = "sabre")]
9014 #[test]
9015 fn sabre_detlog_forwarding_answers_each_target_as_the_cli_filter_does() {
9016 use detcore::detlog::ForwardPolicy;
9017 use detcore::detlog::info_enabled_for_target;
9018 use tracing::level_filters::LevelFilter;
9019 use tracing_subscriber::layer::SubscriberExt;
9020
9021 use crate::liteinst_bootstrap::EffectiveFilter;
9022
9023 let targets = [
9024 "",
9025 "detcore",
9026 "detcore::random",
9027 "detcore::randomness",
9028 "detcore::tool_local",
9029 "detcore::scheduler",
9030 "detcore::scheduler::runqueue",
9031 "detcore::syscalls::files",
9032 "hermit",
9033 "warn",
9034 ];
9035 let policy_under = |raw: &str, level: LevelFilter| {
9036 let subscriber = tracing_subscriber::registry()
9037 .with(EffectiveFilter::from_directives_lossy(raw, level).into_filter());
9038 tracing::subscriber::with_default(subscriber, || {
9039 let policy = ForwardPolicy::from_current_subscriber(raw);
9040 let subscriber_says: Vec<bool> = targets
9041 .iter()
9042 .map(|target| info_enabled_for_target(target))
9043 .collect();
9044 (policy, subscriber_says)
9045 })
9046 };
9047 for (raw, level) in [
9048 ("warn,detcore::random=info", LevelFilter::WARN),
9049 ("detcore::random=info", LevelFilter::WARN),
9050 ("detcore::random=warn", LevelFilter::INFO),
9051 (
9052 "warn,detcore=info,detcore::scheduler=off",
9053 LevelFilter::WARN,
9054 ),
9055 (
9056 "warn,detcore[work]=info,detcore::random=info",
9057 LevelFilter::WARN,
9058 ),
9059 ("", LevelFilter::INFO),
9060 ("", LevelFilter::WARN),
9061 ] {
9062 let (policy, subscriber_says) = policy_under(raw, level);
9063 for (target, enabled) in targets.iter().zip(subscriber_says) {
9064 assert_eq!(
9065 policy.forwards(target),
9066 enabled,
9067 "RUST_LOG={raw:?} --log={level}: policy {policy:?} disagrees on {target:?}"
9068 );
9069 }
9070 }
9071
9072 let (scoped, subscriber_says) =
9073 policy_under("warn,detcore::random=info", LevelFilter::WARN);
9074 assert!(!subscriber_says[1], "the generic detcore target is off");
9075 assert!(scoped.forwards_any());
9076 assert!(scoped.forwards("detcore::random"));
9077 assert!(!scoped.forwards("detcore::tool_local"));
9078 assert_eq!(policy_under("", LevelFilter::INFO).0, ForwardPolicy::all());
9079 assert!(!policy_under("", LevelFilter::WARN).0.forwards_any());
9080 }
9081
9082 #[cfg(feature = "liteinst")]
9087 #[test]
9088 fn liteinst_launch_hands_the_guest_its_per_target_policy() {
9089 use std::os::fd::AsRawFd;
9090
9091 use detcore::detlog::ForwardPolicy;
9092 use detcore::in_guest_launch::InGuestLaunch;
9093 use reverie::process::Command;
9094
9095 use super::LITEINST_DETLOG_FORWARD_ENV;
9096 use super::LITEINST_DETLOG_FORWARD_POLICY_ENV;
9097 use super::forward_in_guest_detlogs_to;
9098 use super::in_guest_liteinst_launch;
9099
9100 let (sink, _peer) = std::os::unix::net::UnixDatagram::pair().unwrap();
9101 forward_in_guest_detlogs_to(sink.into());
9102 let removed = |command: &Command| {
9103 [
9104 LITEINST_DETLOG_FORWARD_ENV,
9105 LITEINST_DETLOG_FORWARD_POLICY_ENV,
9106 detcore::LITEINST_CONFIG_FINGERPRINT_ENV,
9107 ]
9108 .into_iter()
9109 .all(|key| {
9110 command
9111 .get_envs()
9112 .any(|(name, value)| name == std::ffi::OsStr::new(key) && value.is_none())
9113 })
9114 };
9115
9116 let scoped = ForwardPolicy::decode("0,detcore::random=1").unwrap();
9117 let mut command = Command::new("/bin/true");
9118 let (launch, duplicate) = in_guest_liteinst_launch(&mut command, &scoped).unwrap();
9119 let duplicate = duplicate.expect("a policy that forwards a target requests forwarding");
9120 assert!(removed(&command));
9121 let launch = InGuestLaunch::decode(&launch.encode()).unwrap();
9122 let passed = launch.forward_request.expect("the descriptor is passed");
9123 assert_eq!(
9124 detcore::detlog::tool_output_env_target(&passed),
9125 Some(duplicate.as_raw_fd()),
9126 "{passed}"
9127 );
9128 let sent =
9129 ForwardPolicy::decode(&launch.forward_policy.expect("the policy goes too")).unwrap();
9130 assert_eq!(sent, scoped);
9131 assert!(sent.forwards("detcore::random"));
9132 assert!(!sent.forwards("detcore::tool_local"));
9133 assert_eq!(
9134 launch.coordinator_fingerprint,
9135 Some(detcore::config_wire_fingerprint())
9136 );
9137
9138 let nothing = ForwardPolicy::decode("0").unwrap();
9139 let mut command = Command::new("/bin/true");
9140 command
9141 .env(LITEINST_DETLOG_FORWARD_ENV, "9")
9142 .env(LITEINST_DETLOG_FORWARD_POLICY_ENV, "1")
9143 .env(detcore::LITEINST_CONFIG_FINGERPRINT_ENV, "0000000000000000");
9144 let (launch, duplicate) = in_guest_liteinst_launch(&mut command, ¬hing).unwrap();
9145 assert!(duplicate.is_none());
9146 assert!(removed(&command));
9147 assert_eq!(launch.forward_request, None);
9148 assert_eq!(launch.forward_policy, None);
9149 }
9150
9151 #[test]
9159 fn detlog_forward_policy_matches_real_detlog_emission_under_field_filters() {
9160 use std::sync::Arc;
9161 use std::sync::atomic::AtomicUsize;
9162 use std::sync::atomic::Ordering;
9163
9164 use detcore::detlog::ForwardPolicy;
9165 use tracing::level_filters::LevelFilter;
9166 use tracing_subscriber::layer::SubscriberExt;
9167
9168 use crate::liteinst_bootstrap::EffectiveFilter;
9169
9170 struct Count(Arc<AtomicUsize>);
9171 impl<S: tracing::Subscriber> tracing_subscriber::Layer<S> for Count {
9172 fn on_event(
9173 &self,
9174 _event: &tracing::Event<'_>,
9175 _context: tracing_subscriber::layer::Context<'_, S>,
9176 ) {
9177 self.0.fetch_add(1, Ordering::Relaxed);
9178 }
9179 }
9180
9181 let module = module_path!();
9182 for (raw, level) in [
9183 (format!("info,{module}[{{unused}}]=warn"), LevelFilter::INFO),
9184 (
9185 format!("warn,{module}[{{unused}}]=trace"),
9186 LevelFilter::WARN,
9187 ),
9188 (
9189 format!("info,{module}[{{message}}]=warn"),
9190 LevelFilter::INFO,
9191 ),
9192 (format!("info,{module}=warn"), LevelFilter::INFO),
9193 (format!("warn,{module}=info"), LevelFilter::WARN),
9194 ("info".to_owned(), LevelFilter::INFO),
9195 ("warn".to_owned(), LevelFilter::WARN),
9196 ] {
9197 let emitted = Arc::new(AtomicUsize::new(0));
9198 let subscriber = tracing_subscriber::registry()
9199 .with(EffectiveFilter::from_directives_lossy(&raw, level).into_filter())
9200 .with(Count(emitted.clone()));
9201 let forwards = tracing::subscriber::with_default(subscriber, || {
9202 detcore::detlog!("probe record");
9203 ForwardPolicy::from_current_subscriber(&raw).forwards(module)
9204 });
9205 assert_eq!(
9206 forwards,
9207 emitted.load(Ordering::Relaxed) == 1,
9208 "RUST_LOG={raw:?} --log={level}: the policy and a real detlog! disagree"
9209 );
9210 }
9211 }
9212}