#![doc = include_str!("../README.md")]
#![deny(clippy::all)]
#![allow(clippy::uninlined_format_args)]
#[cfg(feature = "liteinst")]
reverie_liteinst::declare_legacy_tool_backing!();
mod backend_stats;
pub mod build_info;
pub mod canonical_verdict;
mod chroot;
use hermit_record_format::consts;
pub mod logdiff_report;
pub mod cpu_profile_admission;
pub mod e9patch;
mod error;
use hermit_record_format::event;
use hermit_record_format::event_stream;
pub mod happens_before;
pub mod host_input_change;
mod id;
#[cfg(feature = "liteinst")]
pub mod in_guest_exits;
pub mod instruction_map;
#[cfg(feature = "liteinst")]
use hermit_record_format::interp;
pub mod liteinst_bootstrap;
mod liteinst_constructor;
pub mod liteinst_record;
mod metadata;
pub mod xstate_probe;
pub use detcore::nonwaiting_write;
pub mod physical_exit_watch;
pub mod preemption_admission;
pub mod proc_mount;
mod ptrace_completion;
pub use canonical_verdict::Verdict;
pub const RECORD_REPLAY_HASHES_IO_BUFFERS: bool = true;
pub const RECORD_REPLAY_VIRTUALIZES_TIME: bool = false;
pub const HERMIT_VERIFICATION_DIVERGENCE_EXIT: i32 = 1;
pub const HERMIT_INTERNAL_FAILURE_EXIT: i32 = 125;
pub const HERMIT_DEADLINE_EXIT: i32 = 124;
pub const HERMIT_LOG_CAP_EXIT: i32 = 123;
pub const GUEST_PROGRAM_NOT_FOUND_EXIT: i32 = 127;
pub const GUEST_PROGRAM_NOT_EXECUTABLE_EXIT: i32 = 126;
const _: () = assert!(
HERMIT_VERIFICATION_DIVERGENCE_EXIT == 1,
"1 is the established diff-style result for a completed comparison that diverged"
);
const _: () = assert!(
HERMIT_INTERNAL_FAILURE_EXIT == 125,
"125 is the GNU wrapper-failed convention; 1 is the commonest guest status and 0 is success"
);
const _: () = assert!(
GUEST_PROGRAM_NOT_FOUND_EXIT == 127,
"127 is the GNU command-not-found convention and must stay distinct from 125 and 126"
);
const _: () = assert!(
GUEST_PROGRAM_NOT_EXECUTABLE_EXIT == 126,
"126 is the GNU found-but-not-executable convention and must stay distinct from 125 and 127"
);
const _: () = assert!(
HERMIT_LOG_CAP_EXIT == 123,
"123 is Hermit's log-cap code, reserved for bin/safehermit's log-cap kill as well; see the allocation table"
);
const _: () = assert!(
HERMIT_LOG_CAP_EXIT != 0
&& HERMIT_VERIFICATION_DIVERGENCE_EXIT != 0
&& HERMIT_INTERNAL_FAILURE_EXIT != 0
&& GUEST_PROGRAM_NOT_FOUND_EXIT != 0
&& GUEST_PROGRAM_NOT_EXECUTABLE_EXIT != 0,
"a failure code of 0 would invert every assert_eq!(code, Some(CONST)) into demanding success"
);
mod record;
use hermit_record_format::record_replay_path;
mod replay;
#[cfg(feature = "sabre")]
mod sabre_bootstrap;
#[cfg(feature = "sabre")]
mod sabre_ptrace;
use hermit_record_format::script;
mod tracer_thread;
#[cfg(feature = "sabre")]
use std::ffi::OsStr;
use std::fs;
use std::io;
use std::io::Seek;
use std::io::SeekFrom;
use std::io::Write;
#[cfg(feature = "dbt")]
use std::os::fd::AsFd;
use std::os::fd::AsRawFd;
use std::os::fd::FromRawFd;
#[cfg(any(feature = "sabre", all(test, feature = "liteinst")))]
use std::os::unix::ffi::OsStrExt;
#[cfg(feature = "sabre")]
use std::os::unix::fs::OpenOptionsExt;
#[cfg(any(feature = "sabre", feature = "liteinst"))]
use std::os::unix::fs::PermissionsExt;
use std::path::Path;
use std::path::PathBuf;
#[cfg(feature = "sabre")]
use std::sync::Arc;
use std::sync::Mutex;
#[cfg(feature = "sabre")]
use std::sync::atomic::AtomicBool;
use std::time::Duration;
use std::time::Instant;
use anyhow::anyhow;
use clap::ValueEnum;
pub use consts::LAST;
pub use consts::LAST_RUN;
use consts::MANIFEST_NAME as RUN_MANIFEST_NAME;
pub use consts::MANIFEST_NAME;
use consts::METADATA_NAME;
pub use consts::METADATA_NAME as RECORDING_METADATA_NAME;
pub use detcore::Config as DetConfig;
pub use detcore::Detcore;
pub use detcore::RecordOrReplay;
#[doc(hidden)]
#[cfg(feature = "dbt")]
pub use detcore_dbt::reverie_dbt_runtime_background_init_v2;
#[doc(hidden)]
#[cfg(feature = "dbt")]
pub use detcore_dbt::reverie_dbt_runtime_background_init_v3;
#[doc(hidden)]
#[cfg(feature = "dbt")]
pub use detcore_dbt::reverie_dbt_runtime_name;
#[doc(hidden)]
#[cfg(feature = "dbt")]
pub use detcore_dbt::reverie_dbt_runtime_pre_syscall;
#[doc(hidden)]
#[cfg(feature = "dbt")]
pub use detcore_dbt::reverie_dbt_runtime_ready;
#[doc(hidden)]
#[cfg(feature = "dbt")]
pub use detcore_dbt::reverie_dbt_runtime_thread_exit;
#[doc(hidden)]
#[cfg(feature = "dbt")]
pub use detcore_dbt::reverie_dbt_runtime_thread_init;
#[doc(hidden)]
#[cfg(feature = "dbt")]
pub use detcore_dbt::reverie_dbt_runtime_totals;
use detcore_model::bundled_signal_facts;
pub use error::Context;
pub use error::Error;
pub use error::FailureKind;
pub use error::SerializableError;
use goblin::elf::Elf;
use goblin::elf::header;
use goblin::elf::section_header;
pub use id::Id;
use metadata::Metadata;
pub use ptrace_completion::HermitCleanupStage;
pub use ptrace_completion::HermitCleanupUnconfirmed;
pub use ptrace_completion::HermitPtraceFailure;
pub use ptrace_completion::RecoveryRefusal;
use record::Record;
use replay::Replay;
pub use reverie::ExitStatus;
#[cfg(feature = "sabre")]
use reverie::GlobalTool;
pub use reverie::process;
pub use reverie::process::Command;
pub use reverie::process::Mount;
pub use reverie::process::Namespace;
pub use reverie::process::Output;
pub use reverie::process::Stdio;
pub use script::Shebang;
use serde::Deserialize;
use serde::Serialize;
pub use tracer_thread::launch_on_calling_thread;
enum KvmStdinReservation {
Open(fs::File),
Closed,
}
static KVM_STDIN_RESERVATION: Mutex<Option<KvmStdinReservation>> = Mutex::new(None);
pub fn reserve_kvm_stdin(stdin: Option<fs::File>) -> io::Result<()> {
let mut reservation = KVM_STDIN_RESERVATION
.lock()
.map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
if reservation.is_some() {
return Err(io::Error::new(
io::ErrorKind::AlreadyExists,
"KVM stdin is already reserved",
));
}
*reservation = Some(match stdin {
Some(file) => KvmStdinReservation::Open(file),
None => KvmStdinReservation::Closed,
});
Ok(())
}
fn duplicate_current_stdin() -> io::Result<Option<fs::File>> {
let duplicate = unsafe { libc::fcntl(libc::STDIN_FILENO, libc::F_DUPFD_CLOEXEC, 3) };
if duplicate >= 0 {
return Ok(Some(unsafe { fs::File::from_raw_fd(duplicate) }));
}
let error = io::Error::last_os_error();
if error.raw_os_error() == Some(libc::EBADF) {
Ok(None)
} else {
Err(error)
}
}
fn ensure_kvm_stdin_reserved() -> io::Result<()> {
let mut reservation = KVM_STDIN_RESERVATION
.lock()
.map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
if reservation.is_none() {
*reservation = Some(match duplicate_current_stdin()? {
Some(file) => KvmStdinReservation::Open(file),
None => KvmStdinReservation::Closed,
});
}
Ok(())
}
fn reserved_kvm_stdin() -> Result<Option<fs::File>, Error> {
ensure_kvm_stdin_reserved()?;
let reservation = KVM_STDIN_RESERVATION
.lock()
.map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
match reservation.as_ref() {
Some(KvmStdinReservation::Open(file)) => Ok(Some(file.try_clone()?)),
Some(KvmStdinReservation::Closed) => Ok(None),
None => unreachable!("stdin reservation was initialized above"),
}
}
enum StdinSnapshot {
Seekable(fs::File),
None,
}
static OUTPUT_STDIN_SNAPSHOT: Mutex<Option<StdinSnapshot>> = Mutex::new(None);
pub fn reserve_output_stdin_snapshot(stdin: Option<fs::File>) -> io::Result<()> {
let snapshot = match stdin {
None => StdinSnapshot::None,
Some(mut file) => {
let is_tty = unsafe { libc::isatty(file.as_raw_fd()) } == 1;
if is_tty {
StdinSnapshot::None
} else {
let replay = if file.stream_position().is_ok() {
file
} else {
const BUFFERING_NOTE: &str = "hermit: --verify is buffering stdin from a non-seekable stream so both \
runs receive identical input. If this appears to hang, stdin has not \
reached end-of-file; pass `< /dev/null` when the guest needs no input.";
if nonwaiting_write::diagnostics_must_not_wait() {
nonwaiting_write::write_without_waiting(
libc::STDERR_FILENO,
format!("{BUFFERING_NOTE}\n").as_bytes(),
);
} else {
eprintln!("{BUFFERING_NOTE}");
}
let mut buffered = tempfile::tempfile()?;
io::copy(&mut file, &mut buffered)?;
buffered.seek(SeekFrom::Start(0))?;
buffered
};
let replay_path = format!("/proc/self/fd/{}", replay.as_raw_fd());
StdinSnapshot::Seekable(fs::File::open(replay_path)?)
}
}
};
let mut reservation = OUTPUT_STDIN_SNAPSHOT
.lock()
.map_err(|_| io::Error::other("output stdin snapshot lock is poisoned"))?;
if reservation.is_some() {
return Err(io::Error::new(
io::ErrorKind::AlreadyExists,
"output stdin snapshot is already reserved",
));
}
*reservation = Some(snapshot);
Ok(())
}
fn output_backend_stdin_reservation() -> Result<(bool, Option<fs::File>), Error> {
let mut reservation = OUTPUT_STDIN_SNAPSHOT
.lock()
.map_err(|_| io::Error::other("output stdin snapshot lock is poisoned"))?;
match reservation.as_mut() {
Some(StdinSnapshot::Seekable(file)) => {
file.seek(SeekFrom::Start(0))?;
Ok((true, Some(file.try_clone()?)))
}
Some(StdinSnapshot::None) => Ok((true, None)),
None => Ok((false, None)),
}
}
fn output_backend_stdin_file() -> Result<Option<fs::File>, Error> {
Ok(output_backend_stdin_reservation()?.1)
}
pub fn output_backend_stdin() -> Result<Stdio, Error> {
match output_backend_stdin_file()? {
Some(file) => Ok(Stdio::from(file)),
None => Ok(Stdio::null()),
}
}
#[derive(Debug, Serialize, Deserialize)]
pub struct Recording {
pub id: Id,
pub exit_status: ExitStatus,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum CapabilityProbe {
Namespaces,
Ptrace,
Seccomp,
}
fn run_capability_probe(probe: CapabilityProbe) -> Result<bool, Error> {
let pid = unsafe { libc::fork() };
if pid == -1 {
return Err(std::io::Error::last_os_error()).context("Failed to fork capability probe");
}
if pid == 0 {
let supported = match probe {
CapabilityProbe::Namespaces => unsafe {
libc::unshare(libc::CLONE_NEWUSER | libc::CLONE_NEWPID) == 0
},
CapabilityProbe::Ptrace => {
unsafe {
libc::ptrace(
libc::PTRACE_TRACEME,
0,
std::ptr::null_mut::<libc::c_void>(),
std::ptr::null_mut::<libc::c_void>(),
) != -1
}
}
CapabilityProbe::Seccomp => {
let mut filter = libc::sock_filter {
code: 0x06, jt: 0,
jf: 0,
k: 0x7fff0000, };
let program = libc::sock_fprog {
len: 1,
filter: &mut filter,
};
unsafe {
libc::prctl(libc::PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) == 0
&& libc::syscall(
libc::SYS_seccomp,
1, 0,
&program,
) == 0
}
}
};
unsafe { libc::_exit(i32::from(!supported)) }
}
let mut status = 0;
loop {
let result = unsafe { libc::waitpid(pid, &mut status, 0) };
if result == pid {
return Ok(libc::WIFEXITED(status) && libc::WEXITSTATUS(status) == 0);
}
if result == -1 {
let error = std::io::Error::last_os_error();
if error.kind() == std::io::ErrorKind::Interrupted {
continue;
}
return Err(error).context("Failed to wait for capability probe");
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum NamespaceUse {
Creates,
None,
}
fn validate_tracing_environment(namespaces: NamespaceUse) -> Result<(), Error> {
check_tracing_environment(namespaces, run_capability_probe)
}
fn check_tracing_environment(
namespaces: NamespaceUse,
mut probe: impl FnMut(CapabilityProbe) -> Result<bool, Error>,
) -> Result<(), Error> {
if namespaces == NamespaceUse::Creates && !probe(CapabilityProbe::Namespaces)? {
anyhow::bail!(
"Hermit cannot create its required user and PID namespaces: \
unshare(CLONE_NEWUSER | CLONE_NEWPID) was denied. Allow unprivileged user namespaces \
and the unshare syscall in the host/container policy."
);
}
if !probe(CapabilityProbe::Ptrace)? {
anyhow::bail!(
"Hermit cannot use ptrace in this environment: a child PTRACE_TRACEME probe was \
denied. Allow same-UID parent-child ptrace in the container seccomp and host \
Yama/LSM policy; CAP_SYS_PTRACE is normally not required. Use --namespace-only for \
a sandbox smoke test without ptrace (it intercepts only kill, through a seccomp \
filter)."
);
}
if !probe(CapabilityProbe::Seccomp)? {
anyhow::bail!(
"Hermit cannot install its tracee seccomp filter: \
seccomp(SECCOMP_SET_MODE_FILTER) was denied. Allow seccomp and \
prctl(PR_SET_NO_NEW_PRIVS) in the container policy. --namespace-only also \
installs a seccomp filter (on kill), so it cannot run here either."
);
}
Ok(())
}
#[cfg(feature = "dbt")]
fn is_dynamorio_sdk(path: &Path) -> bool {
path.join("include/dr_api.h").is_file()
|| path.join("DynamoRIOConfig.cmake").is_file()
|| path.join("cmake/DynamoRIOConfig.cmake").is_file()
}
#[cfg(feature = "dbt")]
fn dynamorio_sdk_available() -> bool {
if hermit_resources::resource("dynamorio/bin64/drrun")
.is_ok_and(|path| path.is_some_and(|path| path.is_file()))
{
return true;
}
if reverie_dbt::bundled_drrun_path().is_file() {
return true;
}
const DEFAULT_ROOTS: [&str; 3] = [
"/usr/lib/cmake/DynamoRIO",
"/usr/local/lib/cmake/DynamoRIO",
"/opt/dynamorio",
];
["DYNAMORIO_HOME", "DynamoRIO_DIR"]
.into_iter()
.filter_map(std::env::var_os)
.map(PathBuf::from)
.chain(DEFAULT_ROOTS.into_iter().map(PathBuf::from))
.any(|path| is_dynamorio_sdk(&path))
}
#[cfg(feature = "dbt")]
fn dbt_runtime_unavailable_reason() -> Option<String> {
dbt_runtime_unavailable_reason_from(detcore_dbt::runtime_library_path())
}
#[cfg(feature = "dbt")]
fn dbt_runtime_unavailable_reason_from(runtime: io::Result<PathBuf>) -> Option<String> {
runtime.err().map(|error| {
format!(
"the Detcore DBT runtime is unavailable: {error}; build the hermit binary and \
cdylib in the same target directory"
)
})
}
fn validate_preload_constructor_library(
path: &Path,
label: &str,
required: &[&str],
initializer_name: &str,
) -> io::Result<PathBuf> {
let bytes = fs::read(path).map_err(|error| {
io::Error::new(
error.kind(),
format!("failed to read {label} {}: {error}", path.display()),
)
})?;
let elf = Elf::parse(&bytes).map_err(|error| {
io::Error::new(
io::ErrorKind::InvalidData,
format!("{label} {} is not an ELF DSO: {error}", path.display()),
)
})?;
if elf.header.e_type != header::ET_DYN || elf.header.e_machine != header::EM_X86_64 {
return Err(io::Error::new(
io::ErrorKind::InvalidData,
format!("{label} {} is not an x86-64 shared object", path.display()),
));
}
for &name in required {
if !elf
.dynsyms
.iter()
.any(|symbol| elf.dynstrtab.get_at(symbol.st_name) == Some(name))
{
return Err(io::Error::new(
io::ErrorKind::InvalidData,
format!(
"{label} {} is missing required export {name}",
path.display()
),
));
}
}
if initializer_name == liteinst_constructor::ROOT {
liteinst_constructor::validate(&bytes, &elf).map_err(|error| {
io::Error::new(
error.kind(),
format!(
"{label} {} has invalid Detcore constructor binding: {error}",
path.display()
),
)
})?;
return path.canonicalize();
}
let (initializer_index, initializer) = elf
.dynsyms
.iter()
.enumerate()
.find(|(_, symbol)| elf.dynstrtab.get_at(symbol.st_name) == Some(initializer_name))
.ok_or_else(|| {
io::Error::other(format!(
"checked {label} initializer {initializer_name} disappeared"
))
})?;
let init_array = elf
.section_headers
.iter()
.find(|section| section.sh_type == section_header::SHT_INIT_ARRAY)
.ok_or_else(|| {
io::Error::new(
io::ErrorKind::InvalidData,
format!("{label} {} has no constructor array", path.display()),
)
})?;
let init_start = init_array.sh_addr;
let init_end = init_start.saturating_add(init_array.sh_size);
let relocated_initializer = elf
.dynrelas
.iter()
.chain(elf.dynrels.iter())
.any(|relocation| {
(init_start..init_end).contains(&relocation.r_offset)
&& relocation.r_sym == initializer_index
});
let init_bytes = usize::try_from(init_array.sh_offset)
.ok()
.and_then(|start| {
usize::try_from(init_array.sh_size)
.ok()
.and_then(|size| bytes.get(start..start.checked_add(size)?))
})
.unwrap_or_default();
let direct_initializer = init_bytes
.as_chunks::<8>()
.0
.iter()
.any(|entry| u64::from_le_bytes(*entry) == initializer.st_value);
if !relocated_initializer && !direct_initializer {
return Err(io::Error::new(
io::ErrorKind::InvalidData,
format!(
"{label} {} does not register {initializer_name} as a preload constructor",
path.display()
),
));
}
path.canonicalize()
}
pub const LITEINST_TOOL_RUNTIME_ENV: &str = "HERMIT_LITEINST_TOOL_RUNTIME";
#[doc(hidden)]
pub fn liteinst_tool_runtime_library_path() -> io::Result<PathBuf> {
if let Some(path) = std::env::var_os(LITEINST_TOOL_RUNTIME_ENV) {
let path = PathBuf::from(path);
if !path.is_file() {
return Err(io::Error::new(
io::ErrorKind::NotFound,
format!("{LITEINST_TOOL_RUNTIME_ENV} does not name a regular file"),
));
}
return validate_liteinst_tool_runtime_library(&path).map_err(|error| {
io::Error::new(
error.kind(),
format!("{LITEINST_TOOL_RUNTIME_ENV} is invalid: {error}"),
)
});
}
if let Some(path) = hermit_resources::resource("libdetcore_liteinst.so")? {
if !path.is_file() {
return Err(io::Error::new(
io::ErrorKind::NotFound,
"selected Hermit installation has no finalized in-guest Detcore runtime; \
run `make install-deps` to build and stage the qualified LiteInst runtime",
));
}
return validate_liteinst_tool_runtime_library(&path);
}
let executable = std::env::current_exe()?;
let directory = executable.parent().ok_or_else(|| {
io::Error::new(
io::ErrorKind::NotFound,
"Hermit executable has no parent directory",
)
})?;
if let Some(path) = [
directory.join("libdetcore_liteinst.so"),
directory.join("deps/libdetcore_liteinst.so"),
]
.into_iter()
.find(|path| path.is_file())
{
return validate_liteinst_tool_runtime_library(&path);
}
Err(io::Error::new(
io::ErrorKind::NotFound,
format!(
"libdetcore_liteinst.so was not built beside {} or staged as an installed resource",
executable.display()
),
))
}
fn validate_liteinst_tool_runtime_library(path: &Path) -> io::Result<PathBuf> {
validate_preload_constructor_library(
path,
"in-guest Detcore runtime",
&["detcore_liteinst_initialize"],
"detcore_liteinst_initialize",
)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LiteinstInGuestRefusal {
backend: Backend,
reason: String,
}
impl LiteinstInGuestRefusal {
pub fn new(reason: impl Into<String>) -> Self {
Self::for_backend(Backend::Liteinst, reason)
}
pub fn for_backend(backend: Backend, reason: impl Into<String>) -> Self {
debug_assert!(backend.is_in_guest_liteinst(), "{backend:?}");
Self {
backend,
reason: reason.into(),
}
}
}
impl std::fmt::Display for LiteinstInGuestRefusal {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let runtime = match self.backend {
Backend::InGuestTrap => "in-guest LiteInst, site patching off",
_ => "in-guest LiteInst",
};
write!(
f,
"--backend={} ({runtime}) refuses this run: {}",
self.backend.as_str(),
self.reason
)
}
}
impl std::error::Error for LiteinstInGuestRefusal {}
#[cfg(feature = "liteinst")]
fn refuse_in_guest_liteinst_run(
command: &mut Command,
config: &DetConfig,
backend: Backend,
) -> Result<(), Error> {
let reason = if let Some(conflict) = in_guest_trap_site_patching_conflict(command, backend) {
Some(conflict)
} else if config.max_timeslice.is_some() {
Some(
"it cannot deliver Detcore's preemption timer yet (the in-guest Tool host refuses \
set_timer with ENOSYS), so the run would fail at its first timeslice; pass \
--max-timeslice=disabled"
.to_owned(),
)
} else if let Some(gap) = in_guest_liteinst_kernel_gap(&running_kernel_release()) {
Some(gap)
} else {
in_guest_liteinst_program_gap(command)?
};
match reason {
Some(reason) => Err(Error::new(LiteinstInGuestRefusal::for_backend(
backend, reason,
))),
None => {
force_in_guest_site_patching(command, backend);
Ok(())
}
}
}
pub fn forced_site_patching_value(backend: Backend) -> Option<&'static str> {
match backend {
Backend::InGuestTrap => Some("0"),
_ => None,
}
}
#[cfg(feature = "liteinst")]
fn in_guest_trap_site_patching_conflict(command: &Command, backend: Backend) -> Option<String> {
let forced = forced_site_patching_value(backend)?;
let name = reverie_liteinst::SITE_PATCHING_ENV;
let value = command.get_env(name)?;
(*value != *std::ffi::OsStr::new(forced)).then(|| {
format!(
"the guest environment sets {name}={}, but --backend={} runs with syscall site \
patching off and sets {name}={forced} itself; drop the variable, or select \
--backend=liteinst to patch syscall sites",
value.to_string_lossy(),
backend.as_str()
)
})
}
#[cfg(feature = "liteinst")]
fn force_in_guest_site_patching(command: &mut Command, backend: Backend) {
if let Some(value) = forced_site_patching_value(backend) {
command.env(reverie_liteinst::SITE_PATCHING_ENV, value);
}
}
#[cfg(feature = "liteinst")]
fn in_guest_site_patching_off(backend: Backend) -> bool {
forced_site_patching_value(backend) == Some("0")
}
#[cfg(feature = "liteinst")]
fn in_guest_stats_request(
backend: Backend,
summary_json: &Option<PathBuf>,
) -> reverie::BackendStatsRequest {
if backend == Backend::InGuestTrap {
reverie::BackendStatsRequest::ENABLED
} else {
backend_stats::request(summary_json)
}
}
#[cfg(feature = "liteinst")]
fn refuse_in_guest_policy(backend: Backend, refusal: Option<String>) -> Result<(), Error> {
match refusal {
Some(reason) => Err(Error::new(LiteinstInGuestRefusal::for_backend(
backend,
format!("{reason}; --backend=ptrace runs this program"),
))),
None => Ok(()),
}
}
#[cfg(feature = "liteinst")]
fn in_guest_trap_patching_evidence(
backend: Backend,
dispatch: Option<&reverie::DispatchStats>,
process_reports: u64,
) -> Option<String> {
if backend != Backend::InGuestTrap {
return None;
}
let Some(record) = dispatch else {
return Some(
"the run produced no LiteInst dispatch record, so it cannot show that no syscall \
site was patched"
.to_owned(),
);
};
if process_reports == 0 {
return Some(
"no guest process reported LiteInst statistics, so the run's zero patched sites \
are not a measurement and it cannot show that no syscall site was patched"
.to_owned(),
);
}
let shown =
|count: Option<u64>| count.map_or_else(|| "unmeasured".to_owned(), |n| n.to_string());
(record.sites.patched != Some(0) || record.sites.candidates != Some(0)).then(|| {
format!(
"its guests' LiteInst statistics report {} patched and {} candidate syscall sites, \
so it did not run with syscall site patching off and its result is not an \
in-guest-trap result",
shown(record.sites.patched),
shown(record.sites.candidates)
)
})
}
#[cfg(feature = "liteinst")]
fn refuse_in_guest_trap_patching(backend: Backend, evidence: Option<String>) -> Result<(), Error> {
match evidence {
Some(reason) => {
detcore::detlog::record_determinism_loss(&reason);
Err(Error::new(LiteinstInGuestRefusal::for_backend(
backend, reason,
)))
}
None => Ok(()),
}
}
#[cfg(feature = "native-exec")]
#[doc(hidden)]
pub fn in_guest_detlog_forward_policy_for_native() -> detcore::detlog::ForwardPolicy {
in_guest_detlog_forward_policy()
}
#[cfg(feature = "liteinst")]
#[doc(hidden)]
pub fn native_trap_dispatch_stats(
source: &reverie_liteinst::LiteinstBackendStatsSource,
) -> Result<Option<reverie::DispatchStats>, Error> {
let backend = Backend::InGuestTrap;
let record = backend_stats::report(backend, reverie::BackendStatsRequest::ENABLED, source);
let evidence = in_guest_trap_patching_evidence(
backend,
record.as_ref(),
source.snapshot().process_reports(),
);
refuse_in_guest_trap_patching(backend, evidence)?;
Ok(record)
}
#[cfg(feature = "liteinst")]
const IN_GUEST_LITEINST_KERNEL_FLOOR: (u32, u32) = (6, 5);
#[cfg(feature = "liteinst")]
fn running_kernel_release() -> String {
let mut name: libc::utsname = unsafe { std::mem::zeroed() };
if unsafe { libc::uname(&mut name) } != 0 {
return String::new();
}
unsafe { std::ffi::CStr::from_ptr(name.release.as_ptr()) }
.to_string_lossy()
.into_owned()
}
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_kernel_gap(release: &str) -> Option<String> {
let mut numbers = release
.split(|c: char| !c.is_ascii_digit())
.map(|part| part.parse::<u32>().ok());
let (floor_major, floor_minor) = IN_GUEST_LITEINST_KERNEL_FLOOR;
match (numbers.next().flatten(), numbers.next().flatten()) {
(Some(major), Some(minor)) if (major, minor) >= IN_GUEST_LITEINST_KERNEL_FLOOR => None,
(Some(_), Some(_)) => Some(format!(
"it needs Linux {floor_major}.{floor_minor} or later (SO_PEERPIDFD, which it uses to \
admit each guest process and observe its exit); this kernel is {release}"
)),
_ => Some(format!(
"it needs Linux {floor_major}.{floor_minor} or later (SO_PEERPIDFD), and the kernel \
release {release:?} does not say which version this is"
)),
}
}
#[cfg(feature = "liteinst")]
const MAX_INTERPRETER_DEPTH: usize = 4;
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_program_gap(command: &mut Command) -> Result<Option<String>, Error> {
use std::io::Read;
use std::os::unix::fs::OpenOptionsExt;
use script::KernelScript;
let mut path = pin_spawn_program(command)?;
for _ in 0..=MAX_INTERPRETER_DEPTH {
let shown = path.display().to_string();
let not_regular = || {
Ok(Some(format!(
"{shown} is not a regular file, and the kernel executes only regular files"
)))
};
if !fs::metadata(&path)
.with_context(|| format!("cannot read guest program {shown}"))?
.is_file()
{
return not_regular();
}
let mut file = fs::OpenOptions::new()
.read(true)
.custom_flags(libc::O_NONBLOCK | libc::O_NOCTTY)
.open(&path)
.with_context(|| format!("cannot read guest program {shown}"))?;
if !file
.metadata()
.with_context(|| format!("cannot read guest program {shown}"))?
.is_file()
{
return not_regular();
}
let mut header = Vec::new();
(&file)
.take(256)
.read_to_end(&mut header)
.with_context(|| format!("cannot read guest program {shown}"))?;
match KernelScript::from_buf(&header) {
KernelScript::Interpreter(interpreter) => {
path = match command.get_current_dir() {
Some(directory) => directory.join(interpreter),
None => interpreter,
};
continue;
}
KernelScript::Declined => {
return Ok(Some(format!(
"{shown} starts with #! but the kernel's script handler declines it (it \
names no interpreter, or the interpreter path fills the first 256 bytes), \
so the kernel would fail the execve or hand the file to another handler \
that need not load the runtime"
)));
}
KernelScript::NotScript => {}
}
let Some(startup) = interp::elf_startup(&mut file)
.with_context(|| format!("cannot read the ELF headers of guest program {shown}"))?
else {
return Ok(Some(format!(
"{shown} is neither an ELF executable nor a #! script, so the kernel would hand \
it to a handler that need not load the runtime"
)));
};
let reason = if !startup.x86_64 {
"is not a 64-bit x86-64 ELF image, so the dynamic loader cannot load the 64-bit \
runtime into it"
} else if !startup.has_interp {
"is statically linked (it has no PT_INTERP), so no dynamic loader runs to load the \
runtime"
} else if is_secure_execution_image(&file, &shown)? {
"is set-user-ID, set-group-ID or has file capabilities, so the kernel runs it in \
secure-execution mode, where the dynamic loader ignores LD_PRELOAD"
} else if startup.has_preinit_array {
"has a DT_PREINIT_ARRAY, whose functions run before the runtime's constructor"
} else {
return Ok(None);
};
return Ok(Some(format!(
"guest program {shown} {reason}, so it would run unmonitored if Hermit launched it"
)));
}
Ok(Some(format!(
"the #! interpreters of guest program {} nest more than {MAX_INTERPRETER_DEPTH} deep",
Path::new(command.get_program()).display()
)))
}
#[cfg(feature = "liteinst")]
fn pin_spawn_program(command: &mut Command) -> Result<PathBuf, Error> {
let arg0 = command.get_arg0().to_owned();
let program = command.find_program().with_context(|| {
format!(
"cannot find guest program {}",
Path::new(command.get_program()).display()
)
})?;
command.program(&program).arg0(arg0);
Ok(program)
}
#[cfg(feature = "liteinst")]
fn is_secure_execution_image(file: &fs::File, shown: &str) -> Result<bool, Error> {
let mode = file
.metadata()
.with_context(|| format!("cannot stat guest program {shown}"))?
.permissions()
.mode();
if mode & 0o4000 != 0 || mode & 0o2010 == 0o2010 {
return Ok(true);
}
let size = unsafe {
libc::fgetxattr(
file.as_raw_fd(),
c"security.capability".as_ptr(),
std::ptr::null_mut(),
0,
)
};
if size >= 0 {
return Ok(true);
}
match io::Error::last_os_error().raw_os_error() {
Some(libc::ENODATA) | Some(libc::ENOTSUP) => Ok(false),
_ => Err(Error::new(io::Error::last_os_error()).context(format!(
"cannot read the file capabilities of guest program {shown}"
))),
}
}
#[cfg(feature = "liteinst")]
fn refuse_in_guest_liteinst_timeout(
backend: Backend,
timeout: Option<Duration>,
) -> Result<(), Error> {
if backend.is_in_guest_liteinst() && timeout.is_some() {
return Err(Error::new(LiteinstInGuestRefusal::for_backend(
backend,
"a wall-clock timeout has not been qualified for the in-guest runtime, whose run \
future does not kill the guest when it is dropped",
)));
}
Ok(())
}
#[cfg(not(feature = "liteinst"))]
fn refuse_in_guest_liteinst_timeout(
_backend: Backend,
_timeout: Option<Duration>,
) -> Result<(), Error> {
Ok(())
}
#[cfg(feature = "liteinst")]
fn liteinst_unavailable_reason() -> Option<String> {
liteinst_runtime_unavailable_reason()
}
#[cfg(not(feature = "liteinst"))]
fn liteinst_unavailable_reason() -> Option<String> {
Some(if option_env!("CARGO_PKG_NAME") == Some("hermit-run") {
"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()
} else {
"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()
})
}
#[cfg(feature = "liteinst")]
fn liteinst_runtime_unavailable_reason() -> Option<String> {
liteinst_tool_runtime_library_path().err().map(|error| {
format!(
"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}"
)
})
}
fn kvm_device_unavailable_reason(path: &Path) -> Option<String> {
fs::OpenOptions::new()
.read(true)
.write(true)
.open(path)
.err()
.map(|error| {
format!(
"cannot open {} read-write: {error}; grant access through the device owner/group \
or root",
path.display()
)
})
}
#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, ValueEnum)]
pub enum Backend {
#[default]
Ptrace,
Dbt,
Liteinst,
InGuestTrap,
Sabre,
Kvm,
E9patch,
}
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct BackendUnavailable {
backend: Backend,
reason: String,
}
impl BackendUnavailable {
pub fn new(backend: Backend, reason: impl Into<String>) -> Self {
Self {
backend,
reason: reason.into(),
}
}
pub fn backend(&self) -> Backend {
self.backend
}
pub fn reason(&self) -> &str {
&self.reason
}
}
impl std::fmt::Display for BackendUnavailable {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
formatter,
"backend `{}` is unavailable: {}",
self.backend.as_str(),
self.reason
)
}
}
impl std::error::Error for BackendUnavailable {}
impl Backend {
const ALL: [Self; 7] = [
Self::Ptrace,
Self::Dbt,
Self::Liteinst,
Self::InGuestTrap,
Self::Sabre,
Self::Kvm,
Self::E9patch,
];
pub const fn as_str(self) -> &'static str {
match self {
Self::Ptrace => "ptrace",
Self::Dbt => "dbt",
Self::Liteinst => "liteinst",
Self::InGuestTrap => "in-guest-trap",
Self::Sabre => "sabre",
Self::Kvm => "kvm",
Self::E9patch => "e9patch",
}
}
pub const fn is_in_guest_liteinst(self) -> bool {
matches!(self, Self::Liteinst | Self::InGuestTrap)
}
pub const fn runtime_name(self) -> &'static str {
match self {
Self::InGuestTrap => Self::Liteinst.as_str(),
other => other.as_str(),
}
}
fn uses_ptrace_pmu_timers(self) -> bool {
match self {
Self::Ptrace | Self::E9patch => true,
Self::Liteinst | Self::InGuestTrap | Self::Dbt | Self::Sabre | Self::Kvm => false,
}
}
pub fn available() -> impl Iterator<Item = Self> {
Self::ALL
.into_iter()
.filter(|backend| backend.is_available())
}
pub fn is_available(self) -> bool {
self.unavailable_reason().is_none()
}
pub fn ensure_available(self) -> Result<(), Error> {
self.ensure_available_for(NamespaceUse::Creates)
}
pub fn ensure_available_for(self, namespaces: NamespaceUse) -> Result<(), Error> {
if let Some(reason) = self.unavailable_reason_for(namespaces) {
Err(Error::new(BackendUnavailable::new(self, reason)))
} else {
Ok(())
}
}
fn unavailable_reason(self) -> Option<String> {
self.unavailable_reason_for(NamespaceUse::Creates)
}
fn unavailable_reason_for(self, namespaces: NamespaceUse) -> Option<String> {
match self {
Self::Ptrace => validate_tracing_environment(namespaces)
.err()
.map(|error| error.to_string()),
Self::Dbt => dbt_unavailable_reason(),
Self::Liteinst | Self::InGuestTrap => liteinst_unavailable_reason(),
Self::Sabre => sabre_unavailable_reason(),
Self::Kvm => kvm_device_unavailable_reason(Path::new("/dev/kvm")),
Self::E9patch => e9patch_unavailable_reason(),
}
}
}
struct SkidOvershootReport {
enabled: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BackendRunFailure;
impl std::fmt::Display for BackendRunFailure {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("the backend failed while running the guest")
}
}
impl std::error::Error for BackendRunFailure {}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SkidOvershootError {
count: u64,
}
impl SkidOvershootError {
pub fn new(count: u64) -> Self {
assert!(
count > 0,
"a skid-overshoot refusal requires a positive count"
);
Self { count }
}
pub fn count(&self) -> u64 {
self.count
}
}
impl std::fmt::Display for SkidOvershootError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"observed {} {} report(s); refusing the result because precise PMU timer \
delivery passed its target and deterministic execution was not established",
self.count,
reverie::SKID_OVERSHOOT_MARKER
)
}
}
impl std::error::Error for SkidOvershootError {}
fn take_skid_overshoot_error() -> Option<SkidOvershootError> {
let count = reverie::take_skid_overshoot_count();
(count > 0).then(|| SkidOvershootError::new(count))
}
impl SkidOvershootReport {
fn begin(enabled: bool) -> Self {
if enabled {
let _ = reverie::take_skid_overshoot_count();
}
Self { enabled }
}
fn finish<T>(self, result: Result<T, Error>) -> Result<T, Error> {
if !self.enabled {
return result;
}
let Some(overshoot) = take_skid_overshoot_error() else {
return result;
};
match result {
Ok(_) => Err(Error::new(overshoot)),
Err(error) => Err(error.context(overshoot)),
}
}
fn finish_with_count<T>(self, result: Result<T, Error>) -> Result<(T, u64), Error> {
if !self.enabled {
return result.map(|value| (value, 0));
}
let count = reverie::take_skid_overshoot_count();
match result {
Ok(value) => Ok((value, count)),
Err(error) if count > 0 => Err(error.context(SkidOvershootError::new(count))),
Err(error) => Err(error),
}
}
}
#[cfg(feature = "sabre")]
fn sabre_unavailable_reason() -> Option<String> {
sabre_runtime_unavailable_reason()
}
#[cfg(not(feature = "sabre"))]
fn sabre_unavailable_reason() -> Option<String> {
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())
}
#[cfg(feature = "e9patch")]
fn e9patch_unavailable_reason() -> Option<String> {
validate_tracing_environment(NamespaceUse::Creates)
.err()
.map(|error| error.to_string())
.or_else(e9patch::unavailable_reason)
}
#[cfg(not(feature = "e9patch"))]
fn e9patch_unavailable_reason() -> Option<String> {
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())
}
#[cfg(feature = "dbt")]
fn dbt_unavailable_reason() -> Option<String> {
if !dynamorio_sdk_available() {
return Some(
"the DynamoRIO runtime was not found; build target/install_pkg, set HERMIT_INSTALL_DIR, or set DYNAMORIO_HOME/DynamoRIO_DIR to a valid SDK"
.to_owned(),
);
}
dbt_runtime_unavailable_reason()
}
#[cfg(not(feature = "dbt"))]
fn dbt_unavailable_reason() -> Option<String> {
Some(dbt_disabled_build_reason(
option_env!("CARGO_PKG_NAME").unwrap_or("hermit"),
))
}
#[cfg(not(feature = "dbt"))]
fn dbt_disabled_build_reason(package_name: &str) -> String {
if package_name == "hermit-run" {
"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()
} else {
"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()
}
}
#[cfg(feature = "sabre")]
const SABRE_BINARY_ENV: &str = "HERMIT_SABRE_BINARY";
#[cfg(feature = "sabre")]
fn is_executable_file(path: &Path) -> bool {
fs::metadata(path)
.is_ok_and(|metadata| metadata.is_file() && metadata.permissions().mode() & 0o111 != 0)
}
#[cfg(feature = "sabre")]
fn resolve_sabre_binary_from(
override_path: Option<&OsStr>,
packaged_path: Option<&Path>,
executable: &Path,
path_env: &OsStr,
) -> Result<PathBuf, Error> {
if let Some(requested) = override_path {
if requested.is_empty() {
return Err(anyhow!("{SABRE_BINARY_ENV} is empty"));
}
let path = PathBuf::from(requested);
return is_executable_file(&path)
.then_some(path.clone())
.ok_or_else(|| {
anyhow!(
"{SABRE_BINARY_ENV}={} is not an executable file",
path.display()
)
});
}
if let Some(path) = packaged_path
&& is_executable_file(path)
{
return Ok(path.to_path_buf());
}
let directory = executable
.parent()
.ok_or_else(|| anyhow!("Hermit executable has no parent directory"))?;
let sibling = directory.join("sabre");
let target_build = directory.parent().map(|target| target.join("sabre/sabre"));
if is_executable_file(&sibling) {
return Ok(sibling);
}
if let Some(candidate) = &target_build
&& is_executable_file(candidate)
{
return Ok(candidate.clone());
}
if !path_env.is_empty()
&& let Some(candidate) = std::env::split_paths(path_env)
.map(|directory| directory.join("sabre"))
.find(|candidate| is_executable_file(candidate))
{
return Ok(candidate);
}
Err(anyhow!(
"SaBRe executable was not found in the Hermit installation, beside {}, or in PATH; set {} or {SABRE_BINARY_ENV}",
executable.display(),
hermit_resources::INSTALL_DIR_ENV
))
}
#[cfg(feature = "sabre")]
fn resolve_sabre_binary() -> Result<PathBuf, Error> {
let executable =
std::env::current_exe().context("failed to locate running Hermit executable")?;
let override_path = std::env::var_os(SABRE_BINARY_ENV);
let packaged_path = hermit_resources::resource("sabre")?;
let path_env = std::env::var_os("PATH").unwrap_or_default();
resolve_sabre_binary_from(
override_path.as_deref(),
packaged_path.as_deref(),
&executable,
&path_env,
)
}
#[cfg(feature = "sabre")]
const SABRE_RPC_SOCKET_ENV: &str = "REVERIE_SABRE_HERMIT_RPC_SOCKET";
#[cfg(feature = "sabre")]
const SABRE_DETLOG_FORWARD_ENV: &str = "REVERIE_SABRE_HERMIT_FORWARD_DETLOG";
#[cfg(feature = "sabre")]
const SABRE_TOOL_OUTPUT_ENV: &str = "REVERIE_SABRE_TOOL_OUTPUT_FD";
#[cfg(feature = "liteinst")]
const LITEINST_DETLOG_FORWARD_ENV: &str = "HERMIT_LITEINST_FORWARD_DETLOG";
#[cfg(feature = "liteinst")]
const LITEINST_DETLOG_FORWARD_POLICY_ENV: &str = "HERMIT_LITEINST_FORWARD_DETLOG_POLICY";
static IN_GUEST_DETLOG_SINK: Mutex<Option<std::os::fd::OwnedFd>> = Mutex::new(None);
#[doc(hidden)]
pub fn forward_in_guest_detlogs_to(socket: std::os::fd::OwnedFd) {
*IN_GUEST_DETLOG_SINK.lock().unwrap() = Some(socket);
}
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_launch(
command: &mut Command,
policy: &detcore::detlog::ForwardPolicy,
) -> Result<
(
detcore::in_guest_launch::InGuestLaunch,
Option<std::os::fd::OwnedFd>,
),
Error,
> {
command.env_remove(LITEINST_DETLOG_FORWARD_ENV);
command.env_remove(LITEINST_DETLOG_FORWARD_POLICY_ENV);
command.env_remove(detcore::LITEINST_CONFIG_FINGERPRINT_ENV);
let mut launch = detcore::in_guest_launch::InGuestLaunch {
coordinator_fingerprint: Some(detcore::config_wire_fingerprint()),
..Default::default()
};
if !policy.forwards_any() {
return Ok((launch, None));
}
let Some(duplicate) = inheritable_in_guest_detlog_socket()? else {
return Ok((launch, None));
};
launch.forward_request = Some(detcore::detlog::tool_output_env_value(
duplicate.as_raw_fd(),
)?);
launch.forward_policy = Some(policy.encode());
Ok((launch, Some(duplicate)))
}
#[cfg(any(feature = "sabre", feature = "liteinst"))]
fn inheritable_in_guest_detlog_socket() -> Result<Option<std::os::fd::OwnedFd>, Error> {
let sink = IN_GUEST_DETLOG_SINK.lock().unwrap();
let Some(socket) = sink.as_ref() else {
return Ok(None);
};
let duplicate = unsafe { libc::fcntl(socket.as_raw_fd(), libc::F_DUPFD, 3) };
if duplicate < 0 {
return Err(Error::new(std::io::Error::last_os_error())
.context("duplicating the in-guest DETLOG forwarding socket"));
}
Ok(Some(unsafe {
std::os::fd::OwnedFd::from_raw_fd(duplicate)
}))
}
#[cfg(feature = "sabre")]
const SABRE_PATH_EVIDENCE_ENV: &str = "HERMIT_SABRE_PATH_EVIDENCE";
#[cfg(any(feature = "sabre", feature = "liteinst"))]
fn in_guest_detlog_forward_policy() -> detcore::detlog::ForwardPolicy {
let directives = std::env::var(tracing_subscriber::EnvFilter::DEFAULT_ENV).unwrap_or_default();
detcore::detlog::ForwardPolicy::from_current_subscriber(&directives)
}
#[cfg(feature = "sabre")]
const SABRE_STAGING_DIRECTORY: &str = "/dev/shm";
#[cfg(feature = "sabre")]
struct StagedSabreProgram {
path: PathBuf,
}
#[cfg(feature = "sabre")]
impl Drop for StagedSabreProgram {
fn drop(&mut self) {
let _ = fs::remove_file(&self.path);
}
}
#[cfg(feature = "sabre")]
fn sabre_program_needs_neutral_name(program: &Path) -> bool {
program
.file_name()
.is_some_and(|name| name.as_bytes().starts_with(b"ld"))
}
#[cfg(feature = "sabre")]
fn stage_sabre_program_in(
program: &Path,
staging_directory: &Path,
) -> Result<Option<StagedSabreProgram>, Error> {
if !sabre_program_needs_neutral_name(program) {
return Ok(None);
}
let path = staging_directory.join(format!("hermit-sabre-program-{}", std::process::id()));
let mut source = fs::File::open(program).map_err(|error| {
anyhow!(
"failed to open SaBRe guest executable {} for neutral-name staging: {error}",
program.display()
)
})?;
let mut staged = fs::OpenOptions::new()
.write(true)
.create_new(true)
.mode(0o700)
.open(&path)
.map_err(|error| {
anyhow!(
"failed to stage SaBRe guest executable {} as {}: {error}",
program.display(),
path.display()
)
})?;
if let Err(error) = io::copy(&mut source, &mut staged) {
let _ = fs::remove_file(&path);
return Err(anyhow!(
"failed to stage SaBRe guest executable {} as {}: {error}",
program.display(),
path.display()
));
}
drop(staged);
Ok(Some(StagedSabreProgram { path }))
}
#[cfg(feature = "sabre")]
fn sabre_runtime_library_path() -> io::Result<PathBuf> {
if let Some(path) = hermit_resources::resource("libdetcore_sabre.so")?
&& path.is_file()
{
return Ok(path);
}
let executable = std::env::current_exe()?;
let directory = executable.parent().ok_or_else(|| {
io::Error::new(
io::ErrorKind::NotFound,
"Hermit executable has no parent directory",
)
})?;
[
directory.join("libdetcore_sabre.so"),
directory.join("deps/libdetcore_sabre.so"),
]
.into_iter()
.find(|path| path.is_file())
.ok_or_else(|| {
io::Error::new(
io::ErrorKind::NotFound,
format!(
"libdetcore_sabre.so was not built beside {}",
executable.display()
),
)
})
}
#[cfg(feature = "sabre")]
fn sabre_runtime_unavailable_reason() -> Option<String> {
if let Err(error) = resolve_sabre_binary() {
return Some(error.to_string());
}
sabre_runtime_library_path().err().map(|error| {
format!(
"the Detcore SaBRe plugin is unavailable: {error}; build detcore-sabre and hermit in the same target directory"
)
})
}
#[cfg(feature = "sabre")]
const SABRE_RPC_DISCONNECT_TIMEOUT: Duration = Duration::from_secs(1);
#[cfg(feature = "sabre")]
async fn wait_for_sabre_rpc_disconnects<T>(
global: &Arc<T>,
timeout: Duration,
) -> Result<(), usize> {
let disconnected = tokio::time::timeout(timeout, async {
while Arc::strong_count(global) > 1 {
tokio::time::sleep(Duration::from_millis(1)).await;
}
})
.await;
if disconnected.is_ok() {
return Ok(());
}
let live_references = Arc::strong_count(global).saturating_sub(1);
if live_references == 0 {
Ok(())
} else {
Err(live_references)
}
}
#[cfg(feature = "sabre")]
async fn stop_sabre_rpc_server<E>(
server_task: tokio::task::JoinHandle<Result<(), E>>,
) -> Result<(), Error>
where
E: std::fmt::Display,
{
server_task.abort();
match server_task.await {
Err(error) if error.is_cancelled() => Ok(()),
Err(error) => Err(anyhow!("SaBRe coordinator task failed: {error}")),
Ok(Err(error)) => Err(anyhow!("SaBRe coordinator server failed: {error}")),
Ok(Ok(())) => Err(anyhow!("SaBRe coordinator server stopped unexpectedly")),
}
}
#[cfg(feature = "sabre")]
async fn shutdown_sabre_rpc<T, E>(
server_task: tokio::task::JoinHandle<Result<(), E>>,
global: &Arc<T>,
timeout: Duration,
) -> Result<(), Error>
where
E: std::fmt::Display,
{
let server_result = stop_sabre_rpc_server(server_task).await;
let disconnect_result = wait_for_sabre_rpc_disconnects(global, timeout).await;
server_result?;
disconnect_result.map_err(|live_references| {
anyhow!("SaBRe coordinator stopped with {live_references} live RPC reference(s)")
})
}
fn ensure_backend_dispatch(backend: Backend) -> Result<(), Error> {
if backend == Backend::Ptrace {
return Ok(());
}
if backend == Backend::E9patch {
return Err(anyhow!(
"backend `e9patch` requires CLI preprocessing; library callers must use \
e9patch::prepare and then select `ptrace`"
));
}
backend.ensure_available()?;
Err(anyhow!(
"backend `{}` has no Hermit dispatch implementation",
backend.as_str()
))
}
#[cfg(feature = "sabre")]
async fn run_sabre(
mut command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
capture_output: bool,
) -> Result<Output, Error> {
let path_evidence_file = std::env::var_os(SABRE_PATH_EVIDENCE_ENV).map(PathBuf::from);
let mut config = config;
let policy = in_guest_detlog_forward_policy();
config.in_guest_detlog_forward_policy = (policy.forwards_any()
&& IN_GUEST_DETLOG_SINK.lock().unwrap().is_some())
.then(|| policy.encode());
let sabre = resolve_sabre_binary()?;
config
.launch_image
.get_or_insert(detcore::LaunchImage {
exe: None,
launcher: None,
})
.launcher = Some(PathBuf::from(&sabre));
let plugin = sabre_runtime_library_path()
.map_err(|error| anyhow!("failed to locate the Detcore SaBRe plugin: {error}"))?;
let program = command.find_program().map_err(|error| {
anyhow!(
"failed to resolve SaBRe guest executable {:?}: {error}",
command.get_program()
)
})?;
let staged_program = stage_sabre_program_in(&program, Path::new(SABRE_STAGING_DIRECTORY))?;
let launch_program = staged_program
.as_ref()
.map_or(program.as_path(), |staged| staged.path.as_path());
let bootstrap_launch =
sabre_bootstrap::Launch::new(Path::new(&sabre), launch_program, &config)?;
let socket_dir = tempfile::Builder::new()
.prefix("hermit-sabre-rpc-")
.tempdir_in(Path::new("/tmp"))?;
let socket_path = socket_dir.path().join("coordinator.sock");
let fallback_ready = Arc::new(AtomicBool::new(false));
let global = Arc::new(detcore::GlobalState::init_global_state(&config).await);
let server = reverie_rpc_transport::RpcServer::bind_with_readiness(
&socket_path,
global.clone(),
config.clone(),
fallback_ready.clone(),
)
.map_err(|error| anyhow!("failed to start SaBRe coordinator RPC: {error}"))?;
let server_task = tokio::spawn(async move { server.serve().await });
let mut first_bytes = vec![0u8; 256];
let read = std::fs::File::open(launch_program)
.and_then(|mut file| std::io::Read::read(&mut file, &mut first_bytes))
.map_err(|error| {
anyhow!(
"failed to read SaBRe guest executable {}: {error}",
launch_program.display()
)
})?;
first_bytes.truncate(read);
let arg0 = command.get_arg0().to_owned();
let client = match reverie_sabre_stats::launch::shebang(&first_bytes) {
Some((interpreter, argument)) => {
command.program(&sabre);
command.arg0(OsStr::from_bytes(&interpreter));
let mut words: Vec<&OsStr> = argument
.iter()
.map(|word| OsStr::from_bytes(word))
.collect();
words.push(launch_program.as_os_str());
command.prepend_args(words);
PathBuf::from(OsStr::from_bytes(&interpreter))
}
None => {
command.program(&sabre);
command.arg0(&arg0);
launch_program.to_path_buf()
}
};
let mut launch_settings: Vec<Vec<u8>> = Vec::new();
let mut setting = |name: &str, value: &OsStr| {
let mut entry = name.as_bytes().to_vec();
entry.push(b'=');
entry.extend_from_slice(value.as_bytes());
launch_settings.push(entry);
};
setting(SABRE_RPC_SOCKET_ENV, socket_path.as_os_str());
command.env_remove(SABRE_RPC_SOCKET_ENV);
command.env_remove(sabre_bootstrap::ENVIRONMENT);
if bootstrap_launch.initializes_random() {
setting(sabre_bootstrap::ENVIRONMENT, OsStr::new("1"));
}
setting(
detcore::CONFIG_FINGERPRINT_ENV,
OsStr::new(&detcore::config_wire_fingerprint()),
);
command.env_remove(detcore::CONFIG_FINGERPRINT_ENV);
command.env_remove(SABRE_PATH_EVIDENCE_ENV);
command.env_remove(SABRE_DETLOG_FORWARD_ENV);
command.env_remove(SABRE_TOOL_OUTPUT_ENV);
let detlog_policy = in_guest_detlog_forward_policy();
let mut _detlog_descriptor = None;
if detlog_policy.forwards_any() {
setting(
SABRE_DETLOG_FORWARD_ENV,
OsStr::new(&detlog_policy.encode()),
);
if let Some(socket) = inheritable_in_guest_detlog_socket()? {
setting(
SABRE_TOOL_OUTPUT_ENV,
OsStr::new(&detcore::detlog::tool_output_env_value(socket.as_raw_fd())?),
);
_detlog_descriptor = Some(socket);
}
}
command.env_remove("SABRE_BINARY");
command.env_remove("SABRE_PLUGIN");
let stats = reverie_sabre_stats::SabreStats::create(reverie::BackendStatsRequest::ENABLED)
.map_err(|error| anyhow!("failed to create the SaBRe statistics page: {error}"))?
.expect("an enabled request creates the statistics page");
setting(
reverie_sabre_stats::BACKEND_STATS_ENV,
OsStr::new(&stats.raw_fd().to_string()),
);
command.env_remove(reverie_sabre_stats::BACKEND_STATS_ENV);
let launch_settings: Vec<&[u8]> = launch_settings.iter().map(Vec::as_slice).collect();
let launch_spec = reverie_sabre_stats::launch::spec_bytes(
plugin.as_os_str().as_bytes(),
client.as_os_str().as_bytes(),
&launch_settings,
)
.ok_or_else(|| anyhow!("the SaBRe launch specification is malformed or too large"))?;
let _launch_spec = reverie_sabre_stats::launch::spec_fd(&launch_spec)
.map_err(|error| anyhow!("failed to create the SaBRe launch specification: {error}"))?;
tracing::debug!(
target: "hermit::sabre",
socket = %socket_path.display(),
"SaBRe coordinator RPC socket (per-launch temp path, deliberately not at INFO)",
);
tracing::info!(
target: "hermit::sabre",
guest = %program.display(),
plugin = %plugin.display(),
"launching Detcore guest through SaBRe with coordinator RPC",
);
let supervised = match sabre_ptrace::run(
command.into_std_lossy(),
PathBuf::from(&sabre),
plugin.clone(),
fallback_ready,
global.clone(),
bootstrap_launch,
stats.clone(),
capture_output,
)
.await
{
Ok(supervised) => supervised,
Err(error) => {
global.release_all_physical_process_exits();
global.force_shutdown_with_error();
let _ = shutdown_sabre_rpc(server_task, &global, SABRE_RPC_DISCONNECT_TIMEOUT).await;
return Err(error);
}
};
global.release_all_physical_process_exits();
let detcore_never_engaged = !supervised.path_evidence.guest_rpc_observed;
let requires_forced_shutdown = !supervised.status.success() || detcore_never_engaged;
if requires_forced_shutdown {
global.force_shutdown_with_error();
}
let backend_evidence = sabre_backend_evidence_line(&supervised.path_evidence);
tracing::warn!(target: "hermit::sabre", "{backend_evidence}");
if let Some(path) = path_evidence_file {
let mut file = fs::OpenOptions::new()
.create(true)
.append(true)
.mode(0o600)
.open(&path)
.map_err(|error| {
anyhow!(
"failed to open SaBRe path evidence {}: {error}",
path.display()
)
})?;
serde_json::to_writer(&mut file, &supervised.path_evidence)?;
writeln!(file)?;
}
let output = Output {
status: supervised.status.into(),
stdout: supervised.stdout,
stderr: supervised.stderr,
};
shutdown_sabre_rpc(server_task, &global, SABRE_RPC_DISCONNECT_TIMEOUT).await?;
let mut global = Arc::try_unwrap(global).map_err(|global| {
anyhow!(
"SaBRe coordinator stopped with {} live RPC reference(s)",
Arc::strong_count(&global) - 1
)
})?;
if requires_forced_shutdown {
global.cancel_internal_scheduler().await;
}
let dispatch_stats = backend_stats::report(
Backend::Sabre,
backend_stats::request(print_summary_to_json_file),
&stats,
);
global
.clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
.await;
tracing::info!(
target: "hermit::sabre::fallback",
ptrace_fallback_sites = supervised.path_evidence.ptrace_fallback_sites,
trusted_shared_object_sites = supervised.path_evidence.trusted_shared_object_sites,
guest_rpc_observed = supervised.path_evidence.guest_rpc_observed,
"SaBRe ptrace fallback completed",
);
if detcore_never_engaged {
return Err(Error::new(BackendRunFailure)
.context(sabre_uninstrumented_guest_message(&output.status)));
}
Ok(output)
}
#[cfg(not(feature = "sabre"))]
async fn run_sabre(
_command: Command,
_config: DetConfig,
_print_summary: bool,
_print_summary_to_json_file: &Option<PathBuf>,
_capture_output: bool,
) -> Result<Output, Error> {
Backend::Sabre.ensure_available()?;
unreachable!("SaBRe availability must fail when the feature is disabled");
}
#[cfg(feature = "sabre")]
fn sabre_reach_state(guest_rpc_observed: bool, ptrace_fallback_sites: usize) -> &'static str {
match (guest_rpc_observed, ptrace_fallback_sites) {
(false, _) => "no-detcore-reached",
(true, 1..) => "degraded-ptrace-fallback",
(true, 0) => "sabre-exercised",
}
}
#[cfg(feature = "sabre")]
fn sabre_backend_evidence_line(evidence: &sabre_ptrace::PathEvidence) -> String {
format!(
":: Backend: sabre static rewriting + ptrace runtime; run_mode=run; \
evidence_schema={}; preplugin_coverage=absent; ptrace_fallback_sites={}; \
trusted_shared_object_sites={}; guest_rpc_observed={}; reach_state={}",
evidence.schema,
evidence.ptrace_fallback_sites,
evidence.trusted_shared_object_sites,
evidence.guest_rpc_observed,
sabre_reach_state(evidence.guest_rpc_observed, evidence.ptrace_fallback_sites),
)
}
#[cfg(feature = "sabre")]
fn sabre_uninstrumented_guest_message(status: &ExitStatus) -> String {
format!(
"the SaBRe backend finished ({status:?}) without the guest ever reaching the Detcore \
coordinator: no syscall was intercepted, so this run applied no determinization at all \
and its result is not a Hermit guarantee. This means SaBRe rewrote no syscall site in \
the guest -- most often a statically linked ELF, whose syscall sites SaBRe must patch \
in the client image itself because there is no dynamic loader to intercept."
)
}
const KVM_GUEST_MEMORY_BYTES: usize = 3 * 1024 * 1024 * 1024;
const MAX_SHEBANG_DEPTH: usize = 4;
fn resolve_kvm_shebang(
resolved_program: &Path,
mut argv: Vec<String>,
) -> Result<(PathBuf, Vec<String>, Vec<u8>), Error> {
let mut load_path = resolved_program.to_path_buf();
let mut image = fs::read(&load_path)
.map_err(|error| anyhow!("failed to read KVM guest executable {load_path:?}: {error}"))?;
let mut depth = 0;
while image.starts_with(b"#!") {
depth += 1;
if depth > MAX_SHEBANG_DEPTH {
return Err(anyhow!(
"too many levels of `#!` interpreter indirection loading {resolved_program:?}"
));
}
let (interpreter, shebang_args) = Shebang::from_buf(&image)
.ok_or_else(|| anyhow!("malformed `#!` interpreter line in {load_path:?}"))?
.into_parts();
let interpreter_str = interpreter
.to_str()
.ok_or_else(|| anyhow!("non-UTF-8 `#!` interpreter path in {load_path:?}"))?
.to_owned();
let mut rewritten = Vec::with_capacity(argv.len() + shebang_args.len() + 2);
rewritten.push(interpreter_str);
for arg in &shebang_args {
rewritten.push(
arg.to_str()
.ok_or_else(|| anyhow!("non-UTF-8 `#!` interpreter argument in {load_path:?}"))?
.to_owned(),
);
}
rewritten.push(load_path.to_string_lossy().into_owned());
rewritten.extend_from_slice(&argv[1..]);
argv = rewritten;
load_path = interpreter;
image = fs::read(&load_path).map_err(|error| {
anyhow!(
"failed to read `#!` interpreter {load_path:?} for {resolved_program:?}: {error}"
)
})?;
}
Ok((load_path, argv, image))
}
const CONTAINER_REPLACED_TMP: &str = "/tmp";
fn kvm_cwd_resolution_error(requested_cwd: &Path, error: &std::io::Error) -> Error {
let under_replaced_tmp = requested_cwd.starts_with(CONTAINER_REPLACED_TMP)
&& requested_cwd != Path::new(CONTAINER_REPLACED_TMP);
if error.kind() == std::io::ErrorKind::NotFound && under_replaced_tmp {
anyhow!(
"failed to resolve KVM guest working directory {:?}: {error}\n\
\n\
This directory may well exist on the host. The container replaces \
{CONTAINER_REPLACED_TMP} with a private, empty tmpfs, so nothing beneath \
{CONTAINER_REPLACED_TMP} is visible to the guest, and resolving the working \
directory happens inside that mount namespace.\n\
Either run from a directory outside {CONTAINER_REPLACED_TMP}, or pass \
--workdir with a path that exists inside the guest.",
requested_cwd
)
} else {
anyhow!(
"failed to resolve KVM guest working directory {:?}: {error}",
requested_cwd
)
}
}
fn prepare_kvm_mountinfo_config(
config: &mut DetConfig,
namespace: impl FnOnce() -> Result<detcore_model::config::MountNamespaceIdentity, Error>,
capture: impl FnOnce() -> Result<Vec<u64>, Error>,
) -> Result<(), Error> {
if !config.mountinfo_mount_ids_captured
&& (!config.mountinfo_mount_ids.is_empty()
|| !config.mount_id_assignment_order.is_empty()
|| config.mountinfo_mount_namespace.is_some())
{
anyhow::bail!("KVM mount identities have no producer-captured namespace");
}
if config.mountinfo_mount_ids_captured {
let Some(producer) = config.mountinfo_mount_namespace else {
anyhow::bail!(
"KVM producer-captured mount identities do not name their mount namespace"
);
};
if config.mountinfo_mount_ids.is_empty()
|| !detcore_model::procfs::mount_identity_provenance_is_well_formed(
&config.mountinfo_mount_ids,
&config.mount_id_assignment_order,
)
{
anyhow::bail!(
"KVM producer-captured mount identities are malformed ({} listed, {} assigned)",
config.mountinfo_mount_ids.len(),
config.mount_id_assignment_order.len()
);
}
if let Some(missing) = config
.mountinfo_root_rewrites
.iter()
.map(|rewrite| rewrite.raw_mount_id)
.find(|id| !config.mountinfo_mount_ids.contains(id))
{
anyhow::bail!(
"KVM mount root rewrite names mount {missing}, which the producer's snapshot does \
not have"
);
}
let backend = namespace().context("failed to identify the KVM backend mount namespace")?;
if producer != backend {
anyhow::bail!(
"KVM producer-captured mount identities name another mount namespace \
(captured in {producer:?}, backend in {backend:?})"
);
}
} else {
let order = capture().context("failed to capture the KVM backend mount namespace")?;
config.mountinfo_mount_ids = order;
config.mountinfo_mount_ids_captured = true;
}
if let Some(table) = &config.container_mount_table
&& let Some(missing) = table
.mounts
.iter()
.map(|row| row.raw_mount_id)
.find(|id| !config.mountinfo_mount_ids.contains(id))
{
anyhow::bail!(
"KVM container mount table names mount {missing}, which the backend namespace does \
not have"
);
}
config.mountinfo_device_rewrites.clear();
Ok(())
}
fn kvm_reports_stored_metadata_timestamps(config: &DetConfig) -> bool {
config.virtualize_metadata && config.sequentialize_threads
}
async fn run_kvm(
command: &Command,
mut config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
capture_output: bool,
) -> Result<Output, Error> {
let dispatch_started = Instant::now();
if config.container_mount_table.is_none() {
let launch_cwd = command
.get_current_dir()
.map_or_else(|| Path::new(".").to_owned(), Path::to_owned);
let (table, order) = unplanned_container_mount_table(&launch_cwd)?;
if !config.mountinfo_mount_ids_captured
&& config.mountinfo_mount_ids.is_empty()
&& config.mount_id_assignment_order.is_empty()
&& config.mountinfo_mount_namespace.is_none()
{
config.mountinfo_mount_namespace = Some(current_mount_namespace()?);
config.mountinfo_mount_ids = order;
config.mountinfo_mount_ids_captured = true;
}
config.container_mount_table = Some(table);
}
let keep = config
.container_mount_table
.as_ref()
.map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
.unwrap_or_default();
prepare_kvm_mountinfo_config(&mut config, current_mount_namespace, || {
capture_mountinfo_identity_order_keeping(&keep)
})?;
let stdin = if capture_output {
let (snapshot_reserved, snapshot) = output_backend_stdin_reservation()?;
if snapshot_reserved {
snapshot
} else {
reserved_kvm_stdin()?
}
} else {
reserved_kvm_stdin()?
};
let requested_cwd = command
.get_current_dir()
.map(Path::to_owned)
.unwrap_or(std::env::current_dir()?);
let cwd = fs::canonicalize(&requested_cwd)
.map_err(|error| kvm_cwd_resolution_error(&requested_cwd, &error))?;
let program = command
.get_program()
.to_str()
.ok_or_else(|| anyhow!("KVM guest executable path is not valid UTF-8"))?
.to_owned();
if !cwd.is_dir() {
return Err(anyhow!(
"KVM guest working directory is not a directory: {:?}",
cwd
));
}
let resolved_program = command.find_program().map_err(|error| {
anyhow!("failed to resolve KVM guest executable {program:?} in the guest PATH: {error}")
})?;
let mut argv = Vec::with_capacity(1 + command.get_args().count());
argv.push(program.clone());
for argument in command.get_args() {
argv.push(
argument
.to_str()
.ok_or_else(|| anyhow!("KVM guest argument is not valid UTF-8"))?
.to_owned(),
);
}
let (_interpreter_path, argv, image) = resolve_kvm_shebang(&resolved_program, argv)?;
let program = argv.first().cloned().unwrap_or(program);
let envp = command
.get_captured_envs()
.into_iter()
.map(|(key, value)| {
let key = key
.to_str()
.ok_or_else(|| anyhow!("KVM guest environment key is not valid UTF-8"))?;
let value = value
.to_str()
.ok_or_else(|| anyhow!("KVM guest environment value is not valid UTF-8"))?;
Ok(format!("{key}={value}"))
})
.collect::<Result<Vec<_>, Error>>()?;
tracing::info!(
target: "hermit::kvm",
program = %program,
argv = ?argv,
cwd = %cwd.display(),
env_count = envp.len(),
"launching guest through reverie-kvm",
);
let argv = argv.iter().map(String::as_str).collect::<Vec<_>>();
let envp = envp.iter().map(String::as_str).collect::<Vec<_>>();
let setup_started = Instant::now();
config.has_uts_namespace = false;
let random_seed = config.rng_seed();
let mut backend = reverie_kvm::KvmBackend::new_with_stdin(KVM_GUEST_MEMORY_BYTES, stdin)
.map_err(|error| anyhow!("failed to initialize reverie-kvm: {error}"))?;
backend
.set_root_pid(detcore::ROOT_DETPID.as_raw())
.map_err(|error| anyhow!("failed to configure KVM root PID: {error}"))?;
backend
.set_ids_per_task(reverie::task_ids::HERMIT_PTRACE_IDS_PER_TASK)
.map_err(|error| anyhow!("failed to configure KVM task IDs: {error}"))?;
backend
.install_static_elf_with_exec_context(
&image,
resolved_program.as_os_str(),
&argv,
&envp,
&cwd,
)
.map_err(|error| anyhow!("failed to load KVM guest executable {program:?}: {error}"))?;
drop(image);
backend
.set_random_seed(random_seed)
.map_err(|error| anyhow!("failed to configure KVM guest random seed: {error}"))?;
if kvm_reports_stored_metadata_timestamps(&config) {
backend
.set_host_metadata_timestamps(true)
.map_err(|error| anyhow!("failed to configure KVM metadata timestamps: {error}"))?;
}
let execution_started = Instant::now();
let completion = hermit_run_kvm::run_detcore(&mut backend, config, capture_output)
.await
.map_err(|error| kvm_execution_error(error, None))?;
let cleanup_started = Instant::now();
let result =
finish_kvm_tool_completion(completion, print_summary, print_summary_to_json_file).await;
let teardown_started = Instant::now();
drop(backend);
let teardown_finished = Instant::now();
let (status, stdout, stderr) = result?;
tracing::debug!(
target: "hermit::kvm",
prepare_us = setup_started.duration_since(dispatch_started).as_micros() as u64,
setup_us = execution_started.duration_since(setup_started).as_micros() as u64,
execution_us = cleanup_started.duration_since(execution_started).as_micros() as u64,
cleanup_us = teardown_started.duration_since(cleanup_started).as_micros() as u64,
teardown_us = teardown_finished.duration_since(teardown_started).as_micros() as u64,
lifecycle_us = teardown_finished.duration_since(dispatch_started).as_micros() as u64,
"reverie-kvm lifecycle phase timings",
);
if !capture_output {
std::io::stdout().write_all(&stdout)?;
std::io::stderr().write_all(&stderr)?;
}
Ok(Output {
status,
stdout,
stderr,
})
}
async fn finish_kvm_tool_completion(
completion: reverie_kvm::ToolRunCompletion<detcore::GlobalState>,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
) -> Result<(ExitStatus, Vec<u8>, Vec<u8>), Error> {
match completion.result {
Ok(output) => {
completion
.global_state
.clean_up(print_summary, print_summary_to_json_file)
.await;
Ok(output)
}
Err(error) => {
let cleanup = completion
.global_state
.clean_up_after_backend_failure()
.await;
Err(kvm_execution_error(error, Some(cleanup)))
}
}
}
fn kvm_execution_error(
primary: reverie_kvm::Error,
cleanup: Option<detcore::BackendFailureCleanup>,
) -> Error {
let message = format!("KVM guest execution failed: {primary}");
let mut error = Error::new(primary).context(BackendRunFailure);
if let Some(cleanup) = cleanup {
if let Err(recording) = cleanup.preemption_recording {
error = error.context(format!("partial preemption recording failed: {recording}"));
}
if let Err(scheduler) = cleanup.scheduler {
error = error.context(scheduler);
}
}
error.context(message)
}
#[cfg(test)]
mod kvm_failure_tests;
#[cfg(all(test, feature = "kvm-execution-tests"))]
mod kvm_execution_tests;
#[cfg(feature = "dbt")]
fn dbt_client_thread_start_failed(status: &std::process::ExitStatus) -> bool {
status.code() == Some(reverie_dbt::CLIENT_THREAD_START_FAILURE_EXIT_CODE)
}
const LEGACY_DBT_DETCONFIG_KEYS: [(&str, bool, &str); 3] = [
(
"use_thread_local_clock_reads",
false,
"detect_host_clock_futex_timeouts",
),
(
"backend_serializes_fork_children",
false,
"backend_tracks_process_children",
),
(
"backend_dispatches_thread_tools",
true,
"backend_tracks_process_children",
),
];
#[doc(hidden)]
pub fn dbt_detconfig_json(config: &DetConfig) -> serde_json::Result<String> {
let legacy = insert_legacy_dbt_detconfig_keys(&detcore::to_legacy_backend_json(config)?)?;
detcore::encode_backend_config_json(legacy, config.backend)
}
fn insert_legacy_dbt_detconfig_keys(serialized: &str) -> serde_json::Result<String> {
use serde::de::MapAccess;
use serde::ser::Error as _;
use serde::ser::SerializeMap;
use serde_json::value::RawValue;
struct Members<'a>(Vec<(&'a str, &'a RawValue)>);
impl<'de> serde::Deserialize<'de> for Members<'de> {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
struct MembersVisitor;
impl<'de> serde::de::Visitor<'de> for MembersVisitor {
type Value = Members<'de>;
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("a serialized Detcore config object")
}
fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
let mut members = Vec::new();
while let Some(member) = map.next_entry()? {
members.push(member);
}
Ok(Members(members))
}
}
deserializer.deserialize_map(MembersVisitor)
}
}
impl serde::Serialize for Members<'_> {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
let mut map = serializer.serialize_map(None)?;
for (key, value) in &self.0 {
for (legacy_key, fixed_value, anchor) in LEGACY_DBT_DETCONFIG_KEYS {
if anchor == *key {
map.serialize_entry(legacy_key, &fixed_value)?;
}
}
map.serialize_entry(key, value)?;
}
map.end()
}
}
let members: Members<'_> = serde_json::from_str(serialized)?;
for (legacy_key, _, anchor) in LEGACY_DBT_DETCONFIG_KEYS {
let anchors = members.0.iter().filter(|(key, _)| *key == anchor).count();
if anchors != 1 {
return Err(serde_json::Error::custom(format!(
"cannot place legacy DBT config key {legacy_key:?}: its anchor key {anchor:?} \
appears {anchors} times, expected exactly once"
)));
}
if members.0.iter().any(|(key, _)| *key == legacy_key) {
return Err(serde_json::Error::custom(format!(
"legacy DBT config key {legacy_key:?} is already present; it must come only \
from the fixed legacy table"
)));
}
}
serde_json::to_string(&members)
}
#[cfg(test)]
mod dbt_detconfig_tests {
use std::path::PathBuf;
use clap::Parser;
use detcore_model::config::MountInfoRootRewrite;
use super::Backend;
use super::DetConfig;
use super::dbt_detconfig_json;
use super::insert_legacy_dbt_detconfig_keys;
use super::prepare_backend_config;
const GOLDEN: [(&str, &str); 3] = [
(
"default",
include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-default.json"),
),
(
"dbt",
include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-dbt.json"),
),
(
"rich_dbt",
include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-rich_dbt.json"),
),
];
fn env_free(epoch: &str, seed: &str) -> DetConfig {
let mut config = DetConfig::parse_from(["hermit", epoch, seed, "--sched-seed=0"]);
config.sched_seed = None;
config
}
fn default_config() -> DetConfig {
env_free("--epoch=2026-01-01T00:00:00Z", "--seed=0")
}
fn rich_config() -> DetConfig {
let mut config = env_free("--epoch=2000-12-31T23:59:59Z", "--seed=7");
config.rng_seed = Some(13);
config.sched_seed = Some(11);
config.clock_multiplier = Some(1.5);
config.chaos = true;
config.record_preemptions_to = Some(PathBuf::from(
"/tmp/a,\"detect_host_clock_futex_timeouts\":true,\"backend_tracks_process_children\":{",
));
config.mountinfo_root_rewrites = vec![MountInfoRootRewrite {
raw_mount_id: 41,
deterministic_root: b"/".to_vec(),
raw_root_prefix: Some(b"/tmp/x".to_vec()),
deterministic_root_prefix: Some(b"/tmp".to_vec()),
raw_mountpoint_prefix: None,
deterministic_mountpoint_prefix: None,
}];
config.stacktrace_event = vec![(3, Some(PathBuf::from("/s")))];
config
}
fn cases() -> [(&'static str, DetConfig); 3] {
[
("default", default_config()),
(
"dbt",
prepare_backend_config(default_config(), Backend::Dbt),
),
(
"rich_dbt",
prepare_backend_config(rich_config(), Backend::Dbt),
),
]
}
#[test]
fn default_case_is_config_default_with_pinned_environment_fields() {
let pinned = default_config();
let from_default = DetConfig {
epoch: pinned.epoch,
seed: pinned.seed,
sched_seed: pinned.sched_seed,
..DetConfig::default()
};
assert_eq!(
serde_json::to_string(&from_default).unwrap(),
serde_json::to_string(&pinned).unwrap()
);
}
#[test]
fn dbt_detconfig_matches_806cf2fa_bytes() {
for ((name, mut config), (golden_name, golden)) in cases().into_iter().zip(GOLDEN) {
config.backend.tool_shares_guest_descriptor_table = false;
config.backend.rediscovers_descriptors_after_exec = false;
config.backend.supports_blocked_wait_signal_interruption = false;
config.backend.delivers_preemption_timer_events = false;
config.backend.runs_guest_code_between_injections = false;
assert_eq!(name, golden_name);
let encoded = dbt_detconfig_json(&config).unwrap();
assert_eq!(
encoded, golden,
"HERMIT_DBT_DETCONFIG for the {name} config differs from the 806cf2fa bytes"
);
}
}
#[test]
fn dbt_detconfig_decodes_to_the_encoded_config() {
for (name, config) in cases() {
let encoded = dbt_detconfig_json(&config).unwrap();
let decoded = detcore::decode_backend_config_json(&encoded)
.unwrap_or_else(|error| panic!("{name}: DBT config does not decode: {error}"));
assert_eq!(
serde_json::to_string(&decoded).unwrap(),
serde_json::to_string(&config).unwrap(),
"{name}: decoded config differs from the encoded one"
);
}
}
#[test]
fn current_dbt_uses_exact_descriptor_facts_without_host_timed_turns() {
let config = prepare_backend_config(default_config(), Backend::Dbt);
assert!(config.backend.tool_shares_guest_descriptor_table);
assert!(config.backend.rediscovers_descriptors_after_exec);
assert!(!config.backend.internal_pipe_turns_are_host_timed);
assert!(!config.backend.loopback_pollers_yield_to_peers);
let encoded = dbt_detconfig_json(&config).unwrap();
assert!(detcore::from_legacy_backend_json(&encoded).is_err());
let decoded = detcore::decode_backend_config_json(&encoded).unwrap();
assert_eq!(decoded.backend, reverie::BackendCapabilities::DBT);
assert_eq!(decoded.backend, config.backend);
}
#[test]
fn dbt_detconfig_keeps_descriptor_facts_independent() {
for mask in 0_u8..16 {
let mut config = prepare_backend_config(default_config(), Backend::Dbt);
config.backend.tool_shares_guest_descriptor_table = mask & 1 != 0;
config.backend.rediscovers_descriptors_after_exec = mask & 2 != 0;
config.backend.internal_pipe_turns_are_host_timed = mask & 4 != 0;
config.backend.loopback_pollers_yield_to_peers = mask & 8 != 0;
let encoded = dbt_detconfig_json(&config).unwrap();
assert_eq!(
detcore::from_legacy_backend_json(&encoded).is_ok(),
mask == 0 || mask == 15,
"only coupled facts fit the legacy form: mask {mask}"
);
let decoded = detcore::decode_backend_config_json(&encoded).unwrap();
assert_eq!(decoded.backend, config.backend, "capability mask {mask}");
assert_eq!(
serde_json::to_string(&decoded).unwrap(),
serde_json::to_string(&config).unwrap(),
"configuration mask {mask}"
);
}
}
#[test]
fn representable_descriptor_facts_keep_the_current_config_bytes() {
for discover in [false, true] {
let mut config = prepare_backend_config(rich_config(), Backend::Dbt);
config.backend.tool_shares_guest_descriptor_table = discover;
config.backend.rediscovers_descriptors_after_exec = discover;
config.backend.internal_pipe_turns_are_host_timed = discover;
config.backend.loopback_pollers_yield_to_peers = discover;
let legacy = detcore::to_legacy_backend_json(&config).unwrap();
assert_eq!(
dbt_detconfig_json(&config).unwrap(),
insert_legacy_dbt_detconfig_keys(&legacy).unwrap()
);
}
}
#[test]
fn versioned_dbt_config_rejects_unknown_or_malformed_envelopes() {
let config = prepare_backend_config(default_config(), Backend::Dbt);
let legacy =
insert_legacy_dbt_detconfig_keys(&detcore::to_legacy_backend_json(&config).unwrap())
.unwrap();
let legacy_backend = detcore::from_legacy_backend_json(&legacy).unwrap().backend;
let backend = serde_json::to_string(&config.backend).unwrap();
let envelope = |version: &str| {
format!(
"{{\"dbt_config_version\":{version},\"config\":{legacy},\"backend\":{backend}}}"
)
};
for version in ["0", "2", "-1", "null", "\"1\""] {
assert!(
detcore::decode_backend_config_json(&envelope(version)).is_err(),
"version {version} must be refused"
);
let tagged_legacy =
legacy.replacen('{', &format!("{{\"dbt_config_version\":{version},"), 1);
assert_eq!(
detcore::decode_backend_config_json(&tagged_legacy)
.unwrap()
.backend,
legacy_backend,
"an unknown legacy key must remain ignored"
);
}
let duplicate = format!(
"{{\"dbt_config_version\":1,\"dbt_config_version\":1,\"config\":{legacy},\"backend\":{backend}}}"
);
assert!(detcore::decode_backend_config_json(&duplicate).is_err());
let missing_backend = format!("{{\"dbt_config_version\":1,\"config\":{legacy}}}");
assert!(detcore::decode_backend_config_json(&missing_backend).is_err());
let missing_config = format!("{{\"dbt_config_version\":1,\"backend\":{backend}}}");
assert!(detcore::decode_backend_config_json(&missing_config).is_err());
for duplicate in [
format!("\"config\":{legacy}"),
format!("\"backend\":{backend}"),
"\"unknown\":true".to_owned(),
] {
let json = envelope("1").replacen('{', &format!("{{{duplicate},"), 1);
assert!(detcore::decode_backend_config_json(&json).is_err());
}
}
#[test]
fn legacy_key_insertion_refuses_a_missing_repeated_or_present_key() {
let complete = r#"{"a":1,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
assert_eq!(
insert_legacy_dbt_detconfig_keys(complete).unwrap(),
concat!(
r#"{"a":1,"use_thread_local_clock_reads":false,"#,
r#""detect_host_clock_futex_timeouts":false,"#,
r#""backend_serializes_fork_children":false,"#,
r#""backend_dispatches_thread_tools":true,"#,
r#""backend_tracks_process_children":true}"#,
)
);
let missing = r#"{"detect_host_clock_futex_timeouts":false}"#;
let error = insert_legacy_dbt_detconfig_keys(missing).unwrap_err();
assert!(
error.to_string().contains("appears 0 times"),
"unexpected error: {error}"
);
let repeated = r#"{"detect_host_clock_futex_timeouts":false,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
let error = insert_legacy_dbt_detconfig_keys(repeated).unwrap_err();
assert!(
error.to_string().contains("appears 2 times"),
"unexpected error: {error}"
);
let present = r#"{"use_thread_local_clock_reads":true,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
let error = insert_legacy_dbt_detconfig_keys(present).unwrap_err();
assert!(
error.to_string().contains("already present"),
"unexpected error: {error}"
);
}
}
#[cfg(feature = "dbt")]
fn dbt_launched_program(
program: &std::path::Path,
cwd: Option<&std::path::Path>,
path: Option<&std::ffi::OsStr>,
current: &std::path::Path,
) -> Option<(PathBuf, PathBuf)> {
use std::os::unix::ffi::OsStrExt;
use std::os::unix::fs::PermissionsExt;
let cwd = cwd.map_or_else(|| current.to_owned(), |cwd| current.join(cwd));
let spelled = if program.as_os_str().as_bytes().contains(&b'/') {
program.to_owned()
} else {
std::env::split_paths(path?)
.map(|directory| cwd.join(directory).join(program))
.find(|candidate| {
candidate.metadata().is_ok_and(|metadata| {
metadata.is_file() && metadata.permissions().mode() & 0o111 != 0
})
})?
};
Some((spelled, cwd))
}
#[cfg(all(test, feature = "dbt"))]
mod dbt_launched_program_tests {
use std::os::unix::fs::PermissionsExt;
use super::*;
fn executable(path: &std::path::Path) {
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, b"").unwrap();
std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).unwrap();
}
#[test]
fn a_relative_path_entry_is_taken_from_the_guests_directory_not_the_launchers() {
let root = tempfile::tempdir().unwrap();
let launcher_dir = root.path().join("launcher");
executable(&launcher_dir.join("bin/prog"));
executable(&root.path().join("guest/bin/prog"));
std::fs::write(root.path().join("guest/plain"), b"").unwrap();
let path = std::ffi::OsStr::new("bin");
let found = |program: &str, cwd: Option<&str>| {
dbt_launched_program(
std::path::Path::new(program),
cwd.map(std::path::Path::new),
Some(path),
&launcher_dir,
)
};
let guest = root.path().join("guest");
let expected = Some((guest.join("bin/prog"), guest.clone()));
assert_eq!(found("prog", Some(guest.to_str().unwrap())), expected);
assert_eq!(
found("prog", Some("../guest")),
Some((
launcher_dir.join("../guest/bin/prog"),
launcher_dir.join("../guest")
))
);
assert_eq!(
found("prog", None),
Some((launcher_dir.join("bin/prog"), launcher_dir.clone()))
);
assert_eq!(
found("./plain", Some(guest.to_str().unwrap())),
Some((std::path::PathBuf::from("./plain"), guest.clone()))
);
assert_eq!(found("plain", Some(guest.to_str().unwrap())), None);
}
}
#[cfg(feature = "dbt")]
pub fn record_dbt_launched_image(
config: &mut DetConfig,
program: &std::path::Path,
cwd: Option<&std::path::Path>,
path: Option<&std::ffi::OsStr>,
) {
let exe = std::env::current_dir()
.ok()
.and_then(|current| dbt_launched_program(program, cwd, path, ¤t))
.and_then(|(spelled, cwd)| {
detcore::exec_record::ExecRecord::resolve(std::path::Path::new("/"), &cwd, &spelled)
})
.map(|record| record.exe);
config
.launch_image
.get_or_insert(detcore::LaunchImage {
exe: None,
launcher: None,
})
.exe = exe;
}
#[cfg(feature = "dbt")]
pub fn declare_dbt_launcher(config: &mut DetConfig, drrun: &std::path::Path) -> Result<(), Error> {
let library = drrun
.parent()
.and_then(std::path::Path::parent)
.unwrap_or(std::path::Path::new("/"))
.join("lib64/release/libdynamorio.so");
if !library.is_file() {
return Err(anyhow!(
"DynamoRIO's library is not at {} beside drrun {}",
library.display(),
drrun.display()
));
}
config
.launch_image
.get_or_insert(detcore::LaunchImage {
exe: None,
launcher: None,
})
.launcher = Some(library);
Ok(())
}
#[cfg(feature = "dbt")]
async fn run_dbt(
command: Command,
config: DetConfig,
print_summary: bool,
capture_output: bool,
) -> Result<Output, Error> {
if !config.sequentialize_threads {
return Err(anyhow!(
"the dbt backend requires sequentialized threads; remove \
--no-sequentialize-threads (or --strace-only) to run under --backend dbt"
));
}
let (drrun, client) = detcore_dbt::prepare_native_client()
.map_err(|error| anyhow!("failed to prepare the Detcore DynamoRIO client: {error}"))?;
let mut config = config;
declare_dbt_launcher(&mut config, &drrun)?;
record_dbt_launched_image(
&mut config,
std::path::Path::new(command.get_program()),
command.get_current_dir(),
command
.get_captured_envs()
.get(std::ffi::OsStr::new("PATH"))
.map(std::ffi::OsString::as_os_str),
);
let config_json = dbt_detconfig_json(&config)
.map_err(|error| anyhow!("failed to serialize the Detcore config for DBT: {error}"))?;
let panic_on_unsupported_syscalls = config.panic_on_unsupported_syscalls;
let diagnostics = std::fs::File::from(
std::io::stderr()
.as_fd()
.try_clone_to_owned()
.map_err(|error| anyhow!("failed to retain DBT diagnostic stderr: {error}"))?,
);
let mut runner = reverie_dbt::DbtRunner::new(&drrun, &client)
.map_err(|error| {
anyhow!(
"failed to configure the DynamoRIO DBT runner (drrun={}, client={}): {error}",
drrun.display(),
client.display()
)
})?
.summary(print_summary)
.isolated_process_group(panic_on_unsupported_syscalls)
.tool_answers_brk(true)
.diagnostic_file(&diagnostics)
.map_err(|error| anyhow!("failed to configure DBT diagnostic stderr: {error}"))?;
drop(diagnostics);
if panic_on_unsupported_syscalls {
runner = runner.client_argument("-panic-on-unsupported-syscalls");
}
let program = command.get_program().to_owned();
let mut environment = command.get_captured_envs();
environment.insert(detcore_dbt::DETCONFIG_ENV.into(), config_json.into());
let guest = command.into_std_lossy();
tracing::info!(
target: "hermit::dbt",
program = ?program,
drrun = %drrun.display(),
client = %client.display(),
"launching guest through reverie-dbt with Detcore<DbtGuest>",
);
let (status, stdout, stderr, mut global) = if capture_output {
let launch = || {
runner.output_with_environment_and_global::<detcore::GlobalState>(
&guest,
&environment,
config.clone(),
)
};
let (mut output, mut global) = launch()
.await
.map_err(|error| anyhow!("failed to launch drrun ({}): {error}", drrun.display()))?;
if dbt_client_thread_start_failed(&output.status) {
tracing::warn!(
target: "hermit::dbt",
"DynamoRIO client thread failed before guest start; retrying once",
);
global.force_shutdown_with_error();
global.cancel_internal_scheduler().await;
global.clean_up(false, &None).await;
(output, global) = launch().await.map_err(|error| {
anyhow!("failed to launch drrun ({}): {error}", drrun.display())
})?;
}
(output.status, output.stdout, output.stderr, global)
} else {
let launch = || {
runner.status_with_environment_and_global::<detcore::GlobalState>(
&guest,
&environment,
config.clone(),
)
};
let (mut status, mut global) = launch()
.await
.map_err(|error| anyhow!("failed to launch drrun ({}): {error}", drrun.display()))?;
if dbt_client_thread_start_failed(&status) {
tracing::warn!(
target: "hermit::dbt",
"DynamoRIO client thread failed before guest start; retrying once",
);
global.force_shutdown_with_error();
global.cancel_internal_scheduler().await;
global.clean_up(false, &None).await;
(status, global) = launch().await.map_err(|error| {
anyhow!("failed to launch drrun ({}): {error}", drrun.display())
})?;
}
(status, Vec::new(), Vec::new(), global)
};
if !status.success() {
global.force_shutdown_with_error();
global.cancel_internal_scheduler().await;
}
global.clean_up(print_summary, &None).await;
Ok(Output {
status: status.into(),
stdout,
stderr,
})
}
pub fn run(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
) -> Result<ExitStatus, Error> {
run_with_backend(
command,
config,
print_summary,
print_summary_to_json_file,
Backend::Ptrace,
)
}
pub fn run_with_backend(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
) -> Result<ExitStatus, Error> {
run_with_backend_timeout(
command,
config,
print_summary,
print_summary_to_json_file,
backend,
None,
)
}
pub fn run_with_backend_timeout(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
timeout: Option<Duration>,
) -> Result<ExitStatus, Error> {
if backend == Backend::Ptrace {
let summary_path = print_summary_to_json_file.clone();
let command = tracer_thread::SendCommand::new(command);
return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
let command = command.into_inner();
let report = SkidOvershootReport::begin(true);
let config = prepare_backend_config(config, backend);
let result = dispatch_backend(
command,
config,
print_summary,
&summary_path,
backend,
Some(control),
)
.await;
report.finish(result)
});
}
let skid_overshoot_report = SkidOvershootReport::begin(backend.uses_ptrace_pmu_timers());
if backend == Backend::Kvm {
ensure_kvm_stdin_reserved()?;
}
let config = prepare_backend_config(config, backend);
let result = run_with_backend_inner(
command,
config,
print_summary,
print_summary_to_json_file,
backend,
timeout,
);
skid_overshoot_report.finish(result)
}
#[doc(hidden)]
pub fn prepare_backend_config(mut config: DetConfig, backend: Backend) -> DetConfig {
config.backend = backend_capabilities(backend);
config.guest_may_inherit_a_terminal =
bundled_signal_facts::host_timed_signal_sources_are_physical(&config.backend)
&& launcher_may_pass_a_terminal();
config
}
fn launcher_may_pass_a_terminal() -> bool {
let standard_terminal = (0..=2).any(|fd| unsafe { libc::isatty(fd) } == 1);
may_pass_a_terminal(standard_terminal, controlling_terminal_device())
}
fn may_pass_a_terminal(standard_terminal: bool, controlling_terminal: Option<i64>) -> bool {
standard_terminal || controlling_terminal != Some(0)
}
fn controlling_terminal_device() -> Option<i64> {
parse_controlling_terminal_device(&std::fs::read_to_string("/proc/self/stat").ok()?)
}
fn parse_controlling_terminal_device(stat: &str) -> Option<i64> {
let after_command = stat.get(stat.rfind(')')? + 1..)?;
after_command.split_ascii_whitespace().nth(4)?.parse().ok()
}
#[doc(hidden)]
pub fn backend_capabilities(backend: Backend) -> reverie::BackendCapabilities {
match backend {
Backend::Ptrace | Backend::E9patch => {
<reverie_ptrace::PtraceBackend as reverie::Backend>::capabilities()
}
Backend::Kvm => reverie_kvm::KvmBackend::capabilities(),
Backend::Liteinst | Backend::InGuestTrap => reverie::BackendCapabilities::LITEINST_IN_GUEST,
Backend::Sabre => reverie::BackendCapabilities::SABRE,
Backend::Dbt => reverie::BackendCapabilities::DBT,
}
}
pub fn backend_delivers_preemption_timer(backend: Backend) -> bool {
backend_capabilities(backend).delivers_preemption_timer_events
}
#[cfg(feature = "liteinst")]
async fn settle_in_guest_exits(
exits: &in_guest_exits::InGuestExitAdmission,
global_state: &detcore::GlobalState,
) -> Result<(), Error> {
let drained = exits.drain(std::time::Duration::from_secs(10)).await;
for pid in exits.reported_exits() {
global_state.complete_physical_process_exit(pid);
}
global_state.release_all_physical_process_exits();
let failure = exits.failure().or_else(|| {
drained
.err()
.map(|error| format!("not every in-guest LiteInst guest exit was reported: {error:?}"))
});
match failure {
Some(reason) => {
detcore::detlog::record_determinism_loss(&reason);
Err(Error::msg(reason))
}
None => Ok(()),
}
}
#[cfg(feature = "liteinst")]
fn liteinst_requires_forced_shutdown(status: ExitStatus) -> bool {
match status {
ExitStatus::Signaled(_, _) | ExitStatus::SignaledRaw(_, _) => true,
ExitStatus::Exited(code) => {
(122..=127).contains(&code) || detcore_model::signal_from_exit_status(code).is_some()
}
}
}
#[derive(Debug)]
pub struct GuestTimedOut {
pub limit: Duration,
}
impl std::fmt::Display for GuestTimedOut {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"Guest exceeded the --timeout bound of {} seconds",
self.limit.as_secs()
)
}
}
impl std::error::Error for GuestTimedOut {}
async fn with_run_deadline<F>(timeout: Option<Duration>, guest: F) -> Result<ExitStatus, Error>
where
F: std::future::Future<Output = Result<ExitStatus, Error>>,
{
match timeout {
None => guest.await,
Some(limit) => match tokio::time::timeout(limit, guest).await {
Ok(result) => result,
Err(_) => Err(Error::new(GuestTimedOut { limit })),
},
}
}
#[tokio::main(flavor = "current_thread")]
async fn run_with_backend_inner(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
timeout: Option<Duration>,
) -> Result<ExitStatus, Error> {
refuse_in_guest_liteinst_timeout(backend, timeout)?;
let guest = Box::pin(dispatch_backend(
command,
config,
print_summary,
print_summary_to_json_file,
backend,
None,
));
with_run_deadline(timeout, guest).await
}
fn launched_image(command: &Command) -> Option<detcore::LaunchImage> {
let program = command.find_program().ok()?;
let cwd = match command.get_current_dir() {
Some(cwd) => cwd.to_owned(),
None => std::env::current_dir().ok()?,
};
let record = detcore::exec_record::ExecRecord::resolve(Path::new("/"), &cwd, &program)?;
Some(detcore::LaunchImage {
exe: Some(record.exe),
launcher: None,
})
}
async fn dispatch_backend(
command: Command,
mut config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
control: Option<std::rc::Rc<ptrace_completion::Control>>,
) -> Result<ExitStatus, Error> {
crate::cpu_profile_admission::refuse_unadmitted_launch(&config, backend == Backend::Ptrace)?;
config.launch_image = launched_image(&command);
if backend == Backend::Kvm {
return Ok(run_kvm(
&command,
config,
print_summary,
print_summary_to_json_file,
false,
)
.await?
.status);
}
if backend == Backend::Dbt {
#[cfg(feature = "dbt")]
{
return Ok(run_dbt(command, config, print_summary, false).await?.status);
}
#[cfg(not(feature = "dbt"))]
{
backend.ensure_available()?;
unreachable!("DBT availability must fail when the feature is disabled");
}
}
if backend == Backend::Sabre {
return Ok(run_sabre(
command,
config,
print_summary,
print_summary_to_json_file,
false,
)
.await?
.status);
}
if backend.is_in_guest_liteinst() {
#[cfg(feature = "liteinst")]
{
let stats_request = in_guest_stats_request(backend, print_summary_to_json_file);
let mut command = command;
refuse_in_guest_liteinst_run(&mut command, &config, backend)?;
let (launch, _detlog_descriptor) =
in_guest_liteinst_launch(&mut command, &in_guest_detlog_forward_policy())?;
let tool_data = launch.encode();
let mut config = config;
config.in_guest_detlog_forward_policy = _detlog_descriptor
.is_some()
.then(|| in_guest_detlog_forward_policy().encode());
config.in_guest_site_patching_off = in_guest_site_patching_off(backend);
let preload = liteinst_tool_runtime_library_path()?;
let exits = std::sync::Arc::new(in_guest_exits::InGuestExitAdmission::default());
let (exit_status, mut global_state, dispatch_stats, process_reports) =
reverie_liteinst::LiteinstBackend::with_connection_admission(
exits.clone(),
async {
if stats_request.is_enabled() {
let (exit_status, global_state, source) =
reverie_liteinst::LiteinstBackend::run_with_preload_data_and_stats::<
Detcore,
>(command, config, preload, tool_data)
.await?;
let dispatch_stats =
backend_stats::report(backend, stats_request, &source);
let process_reports = source.snapshot().process_reports();
Ok::<_, reverie::Error>((
exit_status,
global_state,
dispatch_stats,
process_reports,
))
} else {
let (exit_status, global_state) =
reverie_liteinst::LiteinstBackend::run_with_preload_data::<Detcore>(
command, config, preload, tool_data,
)
.await?;
Ok((exit_status, global_state, None, 0))
}
},
)
.await
.inspect_err(|error| exits.fail_launch(error))?;
let patched =
in_guest_trap_patching_evidence(backend, dispatch_stats.as_ref(), process_reports);
let settled = settle_in_guest_exits(&exits, &global_state).await;
let policy_refusal = global_state.policy_refusal();
if settled.is_err() || liteinst_requires_forced_shutdown(exit_status) {
global_state.force_shutdown_with_error();
global_state.cancel_internal_scheduler().await;
}
global_state
.clean_up_with_dispatch_stats(
print_summary,
print_summary_to_json_file,
dispatch_stats,
)
.await;
refuse_in_guest_policy(backend, policy_refusal)?;
settled?;
refuse_in_guest_trap_patching(backend, patched)?;
return Ok(exit_status);
}
#[cfg(not(feature = "liteinst"))]
{
backend.ensure_available()?;
unreachable!("LiteInst availability must fail when the feature is disabled");
}
}
ensure_backend_dispatch(backend)?;
let stats_request = backend_stats::request(print_summary_to_json_file);
let control = control
.ok_or_else(|| Error::msg("ordinary ptrace requires its retained operation owner"))?;
let tracer = hermit_run_ptrace::spawn_tracer(
command,
config.clone(),
config.gdbserver.then_some(config.gdbserver_port),
config.sequentialize_threads,
stats_request,
)
.await?;
let stats_source = tracer.backend_stats();
let (exit_status, global_state) = ptrace_completion::wait(tracer, control).await?;
let dispatch_stats =
backend_stats::report_if_collected(backend, stats_request, stats_source.as_ref());
global_state
.clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
.await; Ok(exit_status)
}
pub fn run_with_output(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
) -> Result<Output, Error> {
run_with_output_backend(
command,
config,
print_summary,
print_summary_to_json_file,
Backend::Ptrace,
)
}
pub fn run_with_output_backend(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
) -> Result<Output, Error> {
if backend == Backend::Kvm {
ensure_kvm_stdin_reserved()?;
}
run_with_output_backend_timeout(
command,
config,
print_summary,
print_summary_to_json_file,
backend,
None,
)
}
pub fn run_with_output_backend_timeout(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
timeout: Option<Duration>,
) -> Result<Output, Error> {
if backend == Backend::Ptrace {
let summary_path = print_summary_to_json_file.clone();
let command = tracer_thread::SendCommand::new(command);
return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
let command = command.into_inner();
let report = SkidOvershootReport::begin(true);
let result = Box::pin(dispatch_output_backend(
command,
prepare_backend_config(config, backend),
print_summary,
&summary_path,
backend,
Some(control),
))
.await;
report.finish(result)
});
}
let (output, skid_overshoots) = run_with_output_backend_timeout_and_skid_overshoots(
command,
config,
print_summary,
print_summary_to_json_file,
backend,
timeout,
)?;
if skid_overshoots > 0 {
return Err(Error::new(SkidOvershootError::new(skid_overshoots)));
}
Ok(output)
}
#[doc(hidden)]
pub fn run_with_output_backend_timeout_and_skid_overshoots(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
timeout: Option<Duration>,
) -> Result<(Output, u64), Error> {
if backend == Backend::Ptrace {
let summary_path = print_summary_to_json_file.clone();
let command = tracer_thread::SendCommand::new(command);
return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
let command = command.into_inner();
let report = SkidOvershootReport::begin(true);
let result = Box::pin(dispatch_output_backend(
command,
prepare_backend_config(config, backend),
print_summary,
&summary_path,
backend,
Some(control),
))
.await;
report.finish_with_count(result)
});
}
let skid_overshoot_report = SkidOvershootReport::begin(backend.uses_ptrace_pmu_timers());
if backend == Backend::Kvm {
ensure_kvm_stdin_reserved()?;
}
let config = prepare_backend_config(config, backend);
let result = run_with_output_backend_inner(
command,
config,
print_summary,
print_summary_to_json_file,
backend,
timeout,
);
skid_overshoot_report.finish_with_count(result)
}
#[tokio::main(flavor = "current_thread")]
async fn run_with_output_backend_inner(
command: Command,
config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
timeout: Option<Duration>,
) -> Result<Output, Error> {
refuse_in_guest_liteinst_timeout(backend, timeout)?;
let guest = Box::pin(dispatch_output_backend(
command,
config,
print_summary,
print_summary_to_json_file,
backend,
None,
));
match timeout {
None => guest.await,
Some(limit) => match tokio::time::timeout(limit, guest).await {
Ok(result) => result,
Err(_elapsed) => Err(Error::new(GuestTimedOut { limit })),
},
}
}
async fn dispatch_output_backend(
mut command: Command,
mut config: DetConfig,
print_summary: bool,
print_summary_to_json_file: &Option<PathBuf>,
backend: Backend,
control: Option<std::rc::Rc<ptrace_completion::Control>>,
) -> Result<Output, Error> {
crate::cpu_profile_admission::refuse_unadmitted_launch(&config, backend == Backend::Ptrace)?;
config.launch_image = launched_image(&command);
if backend == Backend::Kvm {
return run_kvm(
&command,
config,
print_summary,
print_summary_to_json_file,
true,
)
.await;
}
if backend == Backend::Dbt {
#[cfg(feature = "dbt")]
{
return run_dbt(command, config, print_summary, true).await;
}
#[cfg(not(feature = "dbt"))]
{
backend.ensure_available()?;
unreachable!("DBT availability must fail when the feature is disabled");
}
}
if backend == Backend::Sabre {
#[cfg(not(feature = "sabre"))]
backend.ensure_available()?;
command.stdin(output_backend_stdin()?);
command.stdout(Stdio::piped());
command.stderr(Stdio::piped());
return run_sabre(
command,
config,
print_summary,
print_summary_to_json_file,
true,
)
.await;
}
if backend.is_in_guest_liteinst() {
#[cfg(feature = "liteinst")]
{
command.stdin(output_backend_stdin()?);
let stats_request = in_guest_stats_request(backend, print_summary_to_json_file);
refuse_in_guest_liteinst_run(&mut command, &config, backend)?;
let (launch, _detlog_descriptor) =
in_guest_liteinst_launch(&mut command, &in_guest_detlog_forward_policy())?;
let tool_data = launch.encode();
let mut config = config;
config.in_guest_detlog_forward_policy = _detlog_descriptor
.is_some()
.then(|| in_guest_detlog_forward_policy().encode());
config.in_guest_site_patching_off = in_guest_site_patching_off(backend);
let preload = liteinst_tool_runtime_library_path()?;
let exits = std::sync::Arc::new(in_guest_exits::InGuestExitAdmission::default());
let (output, mut global_state, dispatch_stats, process_reports) =
reverie_liteinst::LiteinstBackend::with_connection_admission(exits.clone(), async {
if stats_request.is_enabled() {
let (output, global_state, source) =
reverie_liteinst::LiteinstBackend::run_with_output_and_preload_data_and_stats::<
Detcore,
>(command, config, preload, tool_data)
.await?;
let dispatch_stats = backend_stats::report(backend, stats_request, &source);
let process_reports = source.snapshot().process_reports();
Ok::<_, reverie::Error>((output, global_state, dispatch_stats, process_reports))
} else {
let (output, global_state) =
reverie_liteinst::LiteinstBackend::run_with_output_and_preload_data::<
Detcore,
>(command, config, preload, tool_data)
.await?;
Ok((output, global_state, None, 0))
}
})
.await
.inspect_err(|error| exits.fail_launch(error))?;
let patched =
in_guest_trap_patching_evidence(backend, dispatch_stats.as_ref(), process_reports);
let settled = settle_in_guest_exits(&exits, &global_state).await;
let policy_refusal = global_state.policy_refusal();
let output = Output {
status: output.status.into(),
stdout: output.stdout,
stderr: output.stderr,
};
let status = output.status;
if settled.is_err() || liteinst_requires_forced_shutdown(status) {
global_state.force_shutdown_with_error();
global_state.cancel_internal_scheduler().await;
}
global_state
.clean_up_with_dispatch_stats(
print_summary,
print_summary_to_json_file,
dispatch_stats,
)
.await;
refuse_in_guest_policy(backend, policy_refusal)?;
settled?;
refuse_in_guest_trap_patching(backend, patched)?;
return Ok(Output {
status,
stdout: output.stdout,
stderr: output.stderr,
});
}
#[cfg(not(feature = "liteinst"))]
{
backend.ensure_available()?;
unreachable!("LiteInst availability must fail when the feature is disabled");
}
}
ensure_backend_dispatch(backend)?;
let stats_request = backend_stats::request(print_summary_to_json_file);
command.stdin(output_backend_stdin()?);
command.stdout(Stdio::piped());
command.stderr(Stdio::piped());
let control = control
.ok_or_else(|| Error::msg("ordinary ptrace requires its retained operation owner"))?;
let tracer = hermit_run_ptrace::spawn_tracer(
command,
config.clone(),
config.gdbserver.then_some(config.gdbserver_port),
config.sequentialize_threads,
stats_request,
)
.await?;
let stats_source = tracer.backend_stats();
let (output, global_state) = ptrace_completion::wait_with_output(tracer, control).await?;
let dispatch_stats =
backend_stats::report_if_collected(backend, stats_request, stats_source.as_ref());
global_state
.clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
.await;
Ok(output)
}
pub struct HermitData {
data_dir: PathBuf,
}
fn collect_recording_ids(
entries: impl IntoIterator<Item = io::Result<fs::DirEntry>>,
data_dir: &Path,
mut file_type: impl FnMut(&fs::DirEntry) -> io::Result<fs::FileType>,
) -> Result<Vec<Id>, Error> {
let mut recordings = Vec::new();
for entry in entries {
let entry = entry.with_context(|| {
format!(
"Failed to read an entry in recording inventory {}",
data_dir.display()
)
})?;
let path = entry.path();
if file_type(&entry)
.with_context(|| {
format!(
"Failed to inspect recording inventory entry {}",
path.display()
)
})?
.is_dir()
&& let Some(id) = entry
.file_name()
.to_str()
.and_then(|name| name.parse::<Id>().ok())
{
recordings.push(id);
}
}
Ok(recordings)
}
impl Default for HermitData {
fn default() -> Self {
Self::new()
}
}
impl HermitData {
pub fn new() -> Self {
Self::with_dir(
dirs::cache_dir()
.map_or_else(|| PathBuf::from("/tmp/hermit"), |dir| dir.join("hermit")),
)
}
pub fn with_dir<P>(data_dir: P) -> Self
where
P: Into<PathBuf>,
{
Self {
data_dir: data_dir.into(),
}
}
pub fn data_dir(&self) -> &Path {
&self.data_dir
}
pub fn record(&self, command: Command) -> Result<Recording, Error> {
let store = Self {
data_dir: self.data_dir.clone(),
};
let command = tracer_thread::SendCommand::new(command);
ptrace_completion::run_on_tracer_thread(None, move |control| async move {
let command = command.into_inner();
let data = store.create_recording_dir()?;
let exit_status = record_to_async(
command,
data.path(),
MountProvenance::default(),
None,
None,
None,
detcore_model::cpu_profile::CpuProfile::default(),
control,
)
.await?;
store.commit_recording(data, exit_status)
})
}
pub fn record_with_mountinfo(
&self,
command: Command,
mountinfo_root_rewrites: Vec<detcore_model::config::MountInfoRootRewrite>,
) -> Result<Recording, Error> {
let store = Self {
data_dir: self.data_dir.clone(),
};
let command = tracer_thread::SendCommand::new(command);
ptrace_completion::run_on_tracer_thread(None, move |control| async move {
let command = command.into_inner();
let data = store.create_recording_dir()?;
let mount_ids = capture_mountinfo_identity_order()?;
let exit_status = record_to_async(
command,
data.path(),
MountProvenance {
root_rewrites: mountinfo_root_rewrites,
container_mount_table: None,
mount_ids: None,
},
Some(mount_ids),
None,
None,
detcore_model::cpu_profile::CpuProfile::default(),
control,
)
.await?;
store.commit_recording(data, exit_status)
})
}
pub fn create_recording_dir(&self) -> Result<tempfile::TempDir, Error> {
let tmp_data_dir = self.data_dir.join("tmp");
fs::create_dir_all(&tmp_data_dir).with_context(|| {
format!(
"Failed to create recording directory: {}",
self.data_dir.display()
)
})?;
Ok(tempfile::TempDir::new_in(tmp_data_dir)?)
}
pub fn commit_recording(
&self,
data: tempfile::TempDir,
exit_status: ExitStatus,
) -> Result<Recording, Error> {
let id = Id::unique();
fs::rename(data.keep(), self.data_dir.join(id.to_string()))?;
self.note_latest(&id, true)
.with_context(|| format!("Failed to update {:?}", self.data_dir.join(LAST)))?;
Ok(Recording { id, exit_status })
}
pub fn replay(&self, id: Id) -> Result<ExitStatus, Error> {
let data = self.data_dir.join(id.to_string());
replay_from(&data)
}
pub fn replay_with_gdbserver(&self, id: Id, port: u16) -> Result<ExitStatus, Error> {
let data = self.data_dir.join(id.to_string());
replay_with_gdbserver(&data, port)
}
pub fn recordings(&self) -> impl Iterator<Item = Id> + use<> {
fs::read_dir(&self.data_dir)
.ok()
.into_iter()
.flatten()
.filter_map(|entry| {
let entry = entry.ok()?;
if entry.file_type().ok()?.is_dir() {
Some(entry.file_name().to_str()?.parse::<Id>().ok()?)
} else {
None
}
})
}
pub fn try_recordings(&self) -> Result<Vec<Id>, Error> {
let entries = match fs::read_dir(&self.data_dir) {
Ok(entries) => entries,
Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
Err(error) => {
return Err(error).with_context(|| {
format!(
"Failed to read recording inventory in {}",
self.data_dir.display()
)
});
}
};
collect_recording_ids(entries, &self.data_dir, fs::DirEntry::file_type)
}
pub fn recording_metadata(&self, id: Id) -> Result<Metadata, Error> {
Metadata::load(&self.data_dir.join(id.to_string()))
}
pub fn remove(&self, id: Id) -> Result<(), Error> {
let path = self.data_dir.join(id.to_string());
let metadata_path = [METADATA_NAME, RUN_MANIFEST_NAME]
.into_iter()
.map(|name| path.join(name))
.find(|marker| marker.exists())
.unwrap_or_else(|| path.join(METADATA_NAME));
let metadata = fs::metadata(&metadata_path)
.with_context(|| format!("Failed to find {:?}", metadata_path))?;
if !metadata.is_file() {
return Err(anyhow!("{:?} is not a file", metadata_path));
}
fs::remove_dir_all(path)?;
Ok(())
}
pub fn last_id(&self) -> Result<Id, Error> {
Ok(fs::read_to_string(self.data_dir.join(LAST))?.parse()?)
}
pub fn note_latest(&self, id: &Id, asked: bool) -> Result<(), Error> {
let tmp = self.data_dir.join("tmp");
fs::create_dir_all(&tmp)?;
let names = if asked {
&[LAST_RUN, LAST][..]
} else {
&[LAST_RUN][..]
};
for name in names {
let mut file = tempfile::NamedTempFile::new_in(&tmp)?;
write!(file, "{}", id)?;
file.persist(self.data_dir.join(name))?;
}
Ok(())
}
}
#[derive(Clone, Debug, Default)]
pub struct MountProvenance {
pub root_rewrites: Vec<detcore_model::config::MountInfoRootRewrite>,
pub container_mount_table: Option<detcore_model::container_mounts::ContainerMountTable>,
pub mount_ids: Option<Vec<u64>>,
}
const NS_GET_MNTNS_ID: libc::c_ulong = (2 << 30) | (8 << 16) | (0xb7 << 8) | 5;
pub fn current_mount_namespace() -> Result<detcore_model::config::MountNamespaceIdentity, Error> {
use std::os::fd::AsRawFd;
use std::os::unix::fs::MetadataExt;
let file = fs::File::open("/proc/thread-self/ns/mnt")
.context("failed to open this thread's mount namespace")?;
let metadata = file
.metadata()
.context("failed to read this process's mount namespace")?;
let mut id: u64 = 0;
let id =
if unsafe { libc::ioctl(file.as_raw_fd(), NS_GET_MNTNS_ID, &mut id as *mut u64) } == 0 {
Some(id)
} else {
let error = std::io::Error::last_os_error();
match error.raw_os_error() {
Some(libc::ENOTTY | libc::EINVAL) => None,
_ => {
return Err(Error::new(error)
.context("failed to read this process's mount namespace ID"));
}
}
};
Ok(detcore_model::config::MountNamespaceIdentity {
id,
device: metadata.dev(),
inode: metadata.ino(),
})
}
pub fn thread_mountinfo() -> Result<Vec<u8>, Error> {
fs::read("/proc/thread-self/mountinfo")
.context("Failed to read this thread's mount table (/proc/thread-self/mountinfo)")
}
fn thread_mount_id_of(path: &Path) -> Option<u64> {
held_mount_id(&hold_path(path, false).ok()?)
}
fn hold_path(path: &Path, directory: bool) -> nix::Result<std::os::fd::OwnedFd> {
use nix::fcntl::OFlag;
let flags = OFlag::O_PATH
| OFlag::O_CLOEXEC
| if directory {
OFlag::O_DIRECTORY
} else {
OFlag::empty()
};
nix::fcntl::open(path, flags, nix::sys::stat::Mode::empty())
}
fn held_mount_id(held: &std::os::fd::OwnedFd) -> Option<u64> {
let fdinfo = fs::read(format!("/proc/thread-self/fdinfo/{}", held.as_raw_fd())).ok()?;
detcore_model::procfs::parse_fdinfo_mount_id(&fdinfo)
}
pub fn capture_mountinfo_identity_order() -> Result<Vec<u64>, Error> {
mountinfo_identity_order_from_raw(&thread_mountinfo()?)
}
pub fn capture_mountinfo_identity_order_keeping(
keep: &std::collections::BTreeSet<u64>,
) -> Result<Vec<u64>, Error> {
mountinfo_identity_order_keeping_from_raw(&thread_mountinfo()?, keep)
}
pub fn base_mountpoint_mount_ids() -> Vec<(Vec<u8>, u64)> {
detcore_model::container_mounts::BASE_MOUNTPOINTS
.iter()
.filter_map(|mountpoint| {
let id = thread_mount_id_of(Path::new(mountpoint))?;
Some((mountpoint.as_bytes().to_vec(), id))
})
.collect()
}
pub type UnplannedMountTable = (
detcore_model::container_mounts::ContainerMountTable,
Vec<u64>,
);
pub fn unplanned_container_mount_table(launch_cwd: &Path) -> Result<UnplannedMountTable, Error> {
unplanned_container_mount_table_with(launch_cwd, thread_mountinfo)
}
fn unplanned_container_mount_table_with(
launch_cwd: &Path,
read: impl FnOnce() -> Result<Vec<u8>, Error>,
) -> Result<UnplannedMountTable, Error> {
let working = hold_path(launch_cwd, true).with_context(|| {
format!(
"the guest's working directory {} cannot be opened for its mount table",
launch_cwd.display()
)
})?;
let tmp = hold_path(Path::new("/tmp"), true).ok();
let base = detcore_model::container_mounts::BASE_MOUNTPOINTS
.iter()
.filter_map(|mountpoint| Some((*mountpoint, hold_path(Path::new(mountpoint), false).ok()?)))
.collect::<Vec<_>>();
let raw = read()?;
let launch = std::iter::once(&working)
.chain(tmp.as_ref())
.map(|held| {
held_mount_id(held)
.ok_or_else(|| anyhow!("a launch directory's mount ID cannot be read"))
})
.collect::<Result<std::collections::BTreeSet<_>, Error>>()?;
let base = base
.iter()
.filter_map(|(mountpoint, held)| {
Some((mountpoint.as_bytes().to_vec(), held_mount_id(held)?))
})
.collect::<Vec<_>>();
unplanned_container_mount_table_from(&raw, &launch, &base)
}
fn unplanned_container_mount_table_from(
raw: &[u8],
launch: &std::collections::BTreeSet<u64>,
base: &[(Vec<u8>, u64)],
) -> Result<UnplannedMountTable, Error> {
use detcore_model::container_mounts::ContainerMountTable;
let rows = detcore_model::container_mounts::parse_container_mounts(raw)
.ok_or_else(|| anyhow!("this thread's mount table has a malformed row"))?;
if let Some(missing) = launch
.iter()
.find(|id| !rows.iter().any(|row| row.raw_mount_id == **id))
{
anyhow::bail!(
"the launch mount {missing} (holding the guest's working directory or /tmp) is not in \
this thread's mount table, read after it was resolved; refusing a table that would \
omit the mount the guest starts on"
);
}
let never = rows
.iter()
.filter(|row| row.is_ephemeral_host_seed())
.map(|row| row.raw_mount_id)
.collect();
let table = ContainerMountTable::select(&rows, launch, base, &never);
let order = mountinfo_identity_order_keeping_from_raw(raw, &table.shown_mount_ids())?;
Ok((table, order))
}
fn mountinfo_identity_order_from_raw(raw: &[u8]) -> Result<Vec<u64>, Error> {
mountinfo_identity_order_keeping_from_raw(raw, &std::collections::BTreeSet::new())
}
pub fn mountinfo_identity_order_keeping_from_raw(
raw: &[u8],
keep: &std::collections::BTreeSet<u64>,
) -> Result<Vec<u64>, Error> {
let mut kept = Vec::with_capacity(raw.len());
for line in raw.split_inclusive(|byte| *byte == b'\n') {
let body = line.strip_suffix(b"\n").unwrap_or(line);
let id = body
.split(|byte| *byte == b' ')
.next()
.and_then(|field| std::str::from_utf8(field).ok()?.parse::<u64>().ok());
if !detcore_model::procfs::is_ephemeral_host_seed_mount(body)
|| id.is_some_and(|id| keep.contains(&id))
{
kept.extend_from_slice(line);
}
}
mountinfo_identity_order_from(&kept)
}
fn mountinfo_identity_order_from(contents: &[u8]) -> Result<Vec<u64>, Error> {
use std::collections::BTreeSet;
let rows = detcore_model::procfs::parse_mountinfo(contents)
.ok_or_else(|| anyhow!("malformed mountinfo"))?;
let mut visible = Vec::new();
let mut parents = Vec::new();
let mut seen = BTreeSet::new();
for row in rows {
seen.insert(row.raw_mount_id);
visible.push(row.raw_mount_id);
parents.push(row.raw_parent_id);
}
for parent in parents {
if seen.insert(parent) {
visible.push(parent);
}
}
Ok(visible)
}
impl<'a> From<Option<&'a PathBuf>> for HermitData {
fn from(data_dir: Option<&'a PathBuf>) -> Self {
data_dir.map_or_else(Self::new, Self::with_dir)
}
}
pub fn record_to(command: Command, dir: &Path) -> Result<ExitStatus, Error> {
let dir = dir.to_owned();
let command = tracer_thread::SendCommand::new(command);
ptrace_completion::run_on_tracer_thread(None, move |control| async move {
let command = command.into_inner();
record_to_async(
command,
&dir,
MountProvenance::default(),
None,
None,
None,
detcore_model::cpu_profile::CpuProfile::default(),
control,
)
.await
})
}
pub fn record_to_with_mountinfo(
command: Command,
dir: &Path,
mountinfo: MountProvenance,
local_networking: bool,
proc_level: detcore_model::config::ProcLevel,
cpu_profile: detcore_model::cpu_profile::CpuProfile,
) -> Result<ExitStatus, Error> {
let dir = dir.to_owned();
let command = tracer_thread::SendCommand::new(command);
ptrace_completion::run_on_tracer_thread(None, move |control| async move {
let command = command.into_inner();
let mut mountinfo = mountinfo;
let mount_ids = match mountinfo.mount_ids.take() {
Some(mount_ids) => mount_ids,
None => capture_mountinfo_identity_order_keeping(
&mountinfo
.container_mount_table
.as_ref()
.map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
.unwrap_or_default(),
)?,
};
record_to_async(
command,
&dir,
mountinfo,
Some(mount_ids),
Some(local_networking),
Some(proc_level),
cpu_profile,
control,
)
.await
})
}
#[allow(clippy::too_many_arguments)]
async fn record_to_async(
command: Command,
dir: &Path,
mountinfo: MountProvenance,
mountinfo_mount_ids: Option<Vec<u64>>,
local_networking: Option<bool>,
proc_level: Option<detcore_model::config::ProcLevel>,
cpu_profile: detcore_model::cpu_profile::CpuProfile,
control: std::rc::Rc<ptrace_completion::Control>,
) -> Result<ExitStatus, Error> {
let report = SkidOvershootReport::begin(true);
let result = async {
Record::spawn_with_mountinfo(
command,
dir,
mountinfo,
mountinfo_mount_ids,
local_networking,
proc_level,
cpu_profile,
)
.await?
.wait(control)
.await
}
.await;
report.finish(result)
}
pub fn record_with_output(command: Command, dir: &Path) -> Result<Output, Error> {
let dir = dir.to_owned();
let command = tracer_thread::SendCommand::new(command);
ptrace_completion::run_on_tracer_thread(None, move |control| async move {
let command = command.into_inner();
record_with_output_async(
command,
&dir,
MountProvenance::default(),
None,
None,
None,
detcore_model::cpu_profile::CpuProfile::default(),
control,
)
.await
})
}
pub fn record_with_output_with_mountinfo(
command: Command,
dir: &Path,
mountinfo: MountProvenance,
local_networking: bool,
proc_level: detcore_model::config::ProcLevel,
cpu_profile: detcore_model::cpu_profile::CpuProfile,
) -> Result<Output, Error> {
let dir = dir.to_owned();
let command = tracer_thread::SendCommand::new(command);
ptrace_completion::run_on_tracer_thread(None, move |control| async move {
let command = command.into_inner();
let mut mountinfo = mountinfo;
let mount_ids = match mountinfo.mount_ids.take() {
Some(mount_ids) => mount_ids,
None => capture_mountinfo_identity_order_keeping(
&mountinfo
.container_mount_table
.as_ref()
.map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
.unwrap_or_default(),
)?,
};
record_with_output_async(
command,
&dir,
mountinfo,
Some(mount_ids),
Some(local_networking),
Some(proc_level),
cpu_profile,
control,
)
.await
})
}
#[allow(clippy::too_many_arguments)]
async fn record_with_output_async(
mut command: Command,
dir: &Path,
mountinfo: MountProvenance,
mountinfo_mount_ids: Option<Vec<u64>>,
local_networking: Option<bool>,
proc_level: Option<detcore_model::config::ProcLevel>,
cpu_profile: detcore_model::cpu_profile::CpuProfile,
control: std::rc::Rc<ptrace_completion::Control>,
) -> Result<Output, Error> {
let report = SkidOvershootReport::begin(true);
command.stdin(Stdio::null());
command.stdout(Stdio::piped());
command.stderr(Stdio::piped());
let result = async {
Record::spawn_with_mountinfo(
command,
dir,
mountinfo,
mountinfo_mount_ids,
local_networking,
proc_level,
cpu_profile,
)
.await?
.wait_with_output(control)
.await
}
.await;
report.finish(result)
}
pub fn replay_from(dir: &Path) -> Result<ExitStatus, Error> {
replay_plain(dir, None, &[])
}
pub fn replay_with_gdbserver(dir: &Path, port: u16) -> Result<ExitStatus, Error> {
replay_plain(dir, Some(port), &[])
}
pub fn replay_with_gdbserver_and_mounts(
dir: &Path,
port: u16,
mounts: &[Mount],
) -> Result<ExitStatus, Error> {
replay_plain(dir, Some(port), mounts)
}
fn replay_plain(dir: &Path, port: Option<u16>, mounts: &[Mount]) -> Result<ExitStatus, Error> {
let dir = dir.to_owned();
let mounts = mounts.to_vec();
ptrace_completion::run_on_tracer_thread(None, move |control| async move {
let report = SkidOvershootReport::begin(true);
let result = async {
Replay::spawn(&dir, false, port, &mounts)
.await?
.wait(control)
.await
}
.await;
report.finish(result)
})
}
pub fn replay_with_output(dir: &Path) -> Result<Output, Error> {
replay_with_output_and_mounts(dir, &[])
}
pub fn replay_with_output_and_mounts(dir: &Path, mounts: &[Mount]) -> Result<Output, Error> {
let dir = dir.to_owned();
let mounts = mounts.to_vec();
ptrace_completion::run_on_tracer_thread(None, move |control| async move {
let report = SkidOvershootReport::begin(true);
let result = async {
Replay::spawn(&dir, true, None, &mounts)
.await?
.wait_with_output(control)
.await
}
.await;
report.finish(result)
})
}
#[cfg(test)]
mod tests {
use super::*;
static SKID_OVERSHOOT_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
fn check_with_denied(
namespaces: NamespaceUse,
denied: &[CapabilityProbe],
) -> (Option<String>, Vec<CapabilityProbe>) {
let mut ran = Vec::new();
let result = check_tracing_environment(namespaces, |probe| {
ran.push(probe);
Ok(!denied.contains(&probe))
});
(result.err().map(|error| error.to_string()), ran)
}
#[test]
fn denied_namespaces_refuse_only_a_run_that_creates_them() {
let denied = [CapabilityProbe::Namespaces];
let (refusal, ran) = check_with_denied(NamespaceUse::Creates, &denied);
assert!(
refusal
.as_deref()
.is_some_and(|refusal| refusal.contains("unshare(CLONE_NEWUSER | CLONE_NEWPID)")),
"{refusal:?}"
);
assert_eq!(ran, [CapabilityProbe::Namespaces]);
let (refusal, ran) = check_with_denied(NamespaceUse::None, &denied);
assert_eq!(refusal, None);
assert_eq!(ran, [CapabilityProbe::Ptrace, CapabilityProbe::Seccomp]);
}
#[test]
fn a_run_without_namespaces_still_needs_ptrace_and_seccomp() {
for denied in [CapabilityProbe::Ptrace, CapabilityProbe::Seccomp] {
let (refusal, _) = check_with_denied(NamespaceUse::None, &[denied]);
let expected = match denied {
CapabilityProbe::Ptrace => "PTRACE_TRACEME",
_ => "SECCOMP_SET_MODE_FILTER",
};
assert!(
refusal
.as_deref()
.is_some_and(|refusal| refusal.contains(expected)),
"{denied:?}: {refusal:?}"
);
}
let (refusal, ran) = check_with_denied(NamespaceUse::Creates, &[]);
assert_eq!(refusal, None);
assert_eq!(
ran,
[
CapabilityProbe::Namespaces,
CapabilityProbe::Ptrace,
CapabilityProbe::Seccomp
]
);
}
#[test]
fn a_manifest_only_recording_can_be_removed() {
let directory = tempfile::tempdir().unwrap();
let data = HermitData::with_dir(directory.path());
let id = Id::unique();
let recording = directory.path().join(id.to_string());
fs::create_dir_all(&recording).unwrap();
assert!(data.remove(id).is_err());
fs::write(recording.join(MANIFEST_NAME), "{}").unwrap();
data.remove(id).unwrap();
assert!(!recording.exists());
}
#[test]
fn identity_capture_excludes_host_seed_mounts_and_keeps_order() {
let raw = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
76 10 0:50 / /mnt/xarfuse/uid-1/e62a203d-seed-nspid4026531836_cgpid16161-ns-4026531832 rw - fuse.squashfuse_ll squashfuse_ll rw\n\
20 10 0:7 / /test rw - tmpfs tmpfs rw\n\
30 10 0:51 / /mnt/xarfuse/stable-release rw - fuse.squashfuse_ll squashfuse_ll rw\n";
let order = mountinfo_identity_order_from_raw(raw).unwrap();
assert!(!order.contains(&76), "seed mount ID captured: {order:?}");
assert_eq!(order, [10, 20, 30, 1]);
assert_eq!(
mountinfo_identity_order_from(raw).unwrap(),
[10, 76, 20, 30, 1],
"control: without the filter the seed ID is captured"
);
}
const NAMESPACE: detcore_model::config::MountNamespaceIdentity =
detcore_model::config::MountNamespaceIdentity {
id: Some(9001),
device: 4,
inode: 4026531840,
};
#[test]
fn kvm_mountinfo_config_preserves_captured_provenance() {
let rewrite = detcore_model::config::MountInfoRootRewrite {
raw_mount_id: 20,
deterministic_root: b"/".to_vec(),
raw_root_prefix: Some(b"/private-source".to_vec()),
deterministic_root_prefix: Some(b"/tmp".to_vec()),
raw_mountpoint_prefix: Some(b"/private-source".to_vec()),
deterministic_mountpoint_prefix: Some(b"/tmp".to_vec()),
};
let mut config = DetConfig {
mountinfo_mount_ids: vec![10, 20, 30],
mountinfo_mount_ids_captured: true,
mountinfo_mount_namespace: Some(NAMESPACE),
mount_id_assignment_order: vec![700, 701],
mountinfo_root_rewrites: vec![rewrite],
mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
..DetConfig::default()
};
let mut expected = config.clone();
expected.mountinfo_device_rewrites.clear();
let (mut namespaces, mut captures) = (0, 0);
prepare_kvm_mountinfo_config(
&mut config,
|| {
namespaces += 1;
Ok(NAMESPACE)
},
|| {
captures += 1;
Ok(vec![10, 30])
},
)
.unwrap();
assert_eq!(namespaces, 1, "the backend's namespace must be checked");
assert_eq!(
captures, 0,
"the producer's snapshot is kept; the namespace is not read again"
);
assert_eq!(
serde_json::to_value(&config).unwrap(),
serde_json::to_value(&expected).unwrap(),
"root rewrites, listed and assignment orders and every other setting must remain intact"
);
}
#[test]
fn kvm_mountinfo_config_refuses_malformed_captured_provenance() {
let rewrite = |raw_mount_id| detcore_model::config::MountInfoRootRewrite {
raw_mount_id,
deterministic_root: b"/".to_vec(),
raw_root_prefix: None,
deterministic_root_prefix: None,
raw_mountpoint_prefix: None,
deterministic_mountpoint_prefix: None,
};
let valid = DetConfig {
mountinfo_mount_ids: vec![10, 20, 1],
mountinfo_mount_ids_captured: true,
mountinfo_mount_namespace: Some(NAMESPACE),
mount_id_assignment_order: vec![20],
mountinfo_root_rewrites: vec![rewrite(20)],
..DetConfig::default()
};
prepare_kvm_mountinfo_config(
&mut valid.clone(),
|| Ok(NAMESPACE),
|| panic!("captured provenance is not read again"),
)
.unwrap();
let cases = [
(
"duplicate",
DetConfig {
mountinfo_mount_ids: vec![10, 10],
..valid.clone()
},
"malformed",
),
(
"empty",
DetConfig {
mountinfo_mount_ids: vec![],
..valid.clone()
},
"malformed",
),
(
"assigned twice",
DetConfig {
mount_id_assignment_order: vec![20, 20],
..valid.clone()
},
"malformed",
),
(
"zero assigned, unlisted",
DetConfig {
mount_id_assignment_order: vec![0],
..valid.clone()
},
"malformed",
),
(
"rewrite outside",
DetConfig {
mountinfo_root_rewrites: vec![rewrite(30)],
..valid.clone()
},
"root rewrite names mount 30",
),
];
for (name, mut config, expected) in cases {
let before = serde_json::to_value(&config).unwrap();
let error = prepare_kvm_mountinfo_config(
&mut config,
|| panic!("{name}: malformed provenance is refused before any read"),
|| panic!("{name}: captured provenance is not read again"),
)
.unwrap_err();
assert!(error.to_string().contains(expected), "{name}: {error:#}");
assert_eq!(serde_json::to_value(&config).unwrap(), before, "{name}");
}
}
#[test]
fn current_mount_namespace_is_stable_and_names_a_kernel_id_where_reported() {
let first = current_mount_namespace().unwrap();
assert_eq!(current_mount_namespace().unwrap(), first);
assert_ne!(first.inode, 0);
assert_ne!(first.id, Some(0));
}
#[test]
fn kvm_mountinfo_config_keeps_a_snapshot_whose_host_row_left_the_namespace() {
let producer = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
20 10 0:22 / /proc rw - proc proc rw\n\
30 10 0:50 / /data/a rw - tmpfs tmpfs rw\n";
let now = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
20 10 0:22 / /proc rw - proc proc rw\n";
let order = mountinfo_identity_order_from(producer).unwrap();
let mut config = DetConfig {
mountinfo_mount_ids: order.clone(),
mountinfo_mount_ids_captured: true,
mountinfo_mount_namespace: Some(NAMESPACE),
..DetConfig::default()
};
prepare_kvm_mountinfo_config(
&mut config,
|| Ok(NAMESPACE),
|| mountinfo_identity_order_from(now),
)
.unwrap();
assert_eq!(config.mountinfo_mount_ids, order);
assert_eq!(config.mountinfo_mount_ids, [10, 20, 30, 1]);
assert!(detcore_model::procfs::mount_ids_are_ordered_subset(
&mountinfo_identity_order_from(now).unwrap(),
&config.mountinfo_mount_ids
));
}
#[test]
fn kvm_mountinfo_config_refuses_provenance_of_another_namespace() {
let config = DetConfig {
mountinfo_mount_ids: vec![10, 20, 1],
mountinfo_mount_ids_captured: true,
mountinfo_mount_namespace: Some(NAMESPACE),
mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
..DetConfig::default()
};
for backend in [
detcore_model::config::MountNamespaceIdentity {
id: Some(9002),
..NAMESPACE
},
detcore_model::config::MountNamespaceIdentity {
inode: NAMESPACE.inode + 1,
..NAMESPACE
},
detcore_model::config::MountNamespaceIdentity {
device: NAMESPACE.device + 1,
..NAMESPACE
},
detcore_model::config::MountNamespaceIdentity {
id: None,
..NAMESPACE
},
] {
let mut stale = config.clone();
let before = serde_json::to_value(&stale).unwrap();
let error = prepare_kvm_mountinfo_config(
&mut stale,
|| Ok(backend),
|| panic!("captured provenance is not read again"),
)
.unwrap_err();
assert!(
error.to_string().contains("name another mount namespace"),
"{error:#}"
);
assert_eq!(serde_json::to_value(&stale).unwrap(), before);
}
let mut unnamed = DetConfig {
mountinfo_mount_namespace: None,
..config.clone()
};
let before = serde_json::to_value(&unnamed).unwrap();
let error = prepare_kvm_mountinfo_config(
&mut unnamed,
|| panic!("provenance without a namespace is refused before any read"),
|| panic!("provenance without a namespace is refused before any read"),
)
.unwrap_err();
assert!(
error
.to_string()
.contains("do not name their mount namespace"),
"{error:#}"
);
assert_eq!(serde_json::to_value(&unnamed).unwrap(), before);
let mut unreadable = config;
let before = serde_json::to_value(&unreadable).unwrap();
let error = prepare_kvm_mountinfo_config(
&mut unreadable,
|| Err(std::io::Error::from(std::io::ErrorKind::PermissionDenied).into()),
|| panic!("captured provenance is not read again"),
)
.unwrap_err();
assert!(
error
.downcast_ref::<std::io::Error>()
.is_some_and(|error| error.kind() == std::io::ErrorKind::PermissionDenied)
);
assert_eq!(serde_json::to_value(&unreadable).unwrap(), before);
}
#[test]
fn kvm_mountinfo_config_captures_validated_ambient_namespace() {
let contents = b"80 20 8:1 / / rw - ext4 /dev/root rw\n\
10 80 0:7 / /test rw - tmpfs tmpfs rw\n";
let mut config = DetConfig::default();
let mut expected = config.clone();
expected.mountinfo_mount_ids = vec![80, 10, 20];
expected.mountinfo_mount_ids_captured = true;
prepare_kvm_mountinfo_config(
&mut config,
|| panic!("an ambient capture has no producer namespace to compare"),
|| mountinfo_identity_order_from(contents),
)
.unwrap();
assert_eq!(
serde_json::to_value(&config).unwrap(),
serde_json::to_value(&expected).unwrap(),
"visible rows precede parent-only IDs and no guest setting changes"
);
assert!(detcore_model::procfs::mount_ids_are_ordered_subset(
&[80, 10],
&config.mountinfo_mount_ids
));
assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
&[10, 80],
&config.mountinfo_mount_ids
));
assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
&[80, 99],
&config.mountinfo_mount_ids
));
assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
&[80, 80],
&config.mountinfo_mount_ids
));
let mut empty = DetConfig::default();
prepare_kvm_mountinfo_config(
&mut empty,
|| panic!("an ambient capture has no producer namespace to compare"),
|| mountinfo_identity_order_from(b""),
)
.unwrap();
assert!(empty.mountinfo_mount_ids.is_empty());
assert!(empty.mountinfo_mount_ids_captured);
}
#[test]
fn kvm_mountinfo_config_refuses_missing_or_malformed_capture() {
let valid = b"10 20 8:1 / / rw - ext4 /dev/root rw\n";
let config = DetConfig {
mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
..DetConfig::default()
};
for contents in [
b"malformed".as_slice(),
b"10 20 8:1 / / rw - ext4 /dev/root rw\n10 20 8:1 / / rw - ext4 /dev/root rw\n",
b"10 20 8:1 / / rw unknown:7 - ext4 /dev/root rw\n",
] {
let mut candidate = config.clone();
let before = serde_json::to_value(&candidate).unwrap();
let error = prepare_kvm_mountinfo_config(
&mut candidate,
|| panic!("an ambient capture has no producer namespace to compare"),
|| mountinfo_identity_order_from(contents),
)
.unwrap_err();
assert!(format!("{error:#}").contains("malformed mountinfo"));
assert_eq!(serde_json::to_value(&candidate).unwrap(), before);
}
let mut candidate = config;
let before = serde_json::to_value(&candidate).unwrap();
let error = prepare_kvm_mountinfo_config(
&mut candidate,
|| panic!("an ambient capture has no producer namespace to compare"),
|| Err(std::io::Error::from(std::io::ErrorKind::PermissionDenied).into()),
)
.unwrap_err();
assert!(
error
.downcast_ref::<std::io::Error>()
.is_some_and(|error| error.kind() == std::io::ErrorKind::PermissionDenied)
);
assert_eq!(serde_json::to_value(&candidate).unwrap(), before);
assert_eq!(mountinfo_identity_order_from(valid).unwrap(), [10, 20]);
}
#[test]
fn kvm_mountinfo_config_refuses_uncaptured_provenance_vectors() {
for (listed, assigned, namespace) in [
(vec![10], vec![], None),
(vec![], vec![700], None),
(vec![], vec![], Some(NAMESPACE)),
] {
let mut config = DetConfig {
mountinfo_mount_ids: listed,
mount_id_assignment_order: assigned,
mountinfo_mount_namespace: namespace,
..DetConfig::default()
};
let before = serde_json::to_value(&config).unwrap();
let error = prepare_kvm_mountinfo_config(
&mut config,
|| panic!("must not overwrite incomplete provenance"),
|| panic!("must not overwrite incomplete provenance"),
)
.unwrap_err();
assert!(error.to_string().contains("no producer-captured namespace"));
assert_eq!(serde_json::to_value(&config).unwrap(), before);
}
}
#[test]
fn kvm_mountinfo_config_refuses_a_mount_table_of_another_namespace() {
let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
20 10 0:22 / /proc rw - proc proc rw\n\
40 10 0:23 / /elsewhere rw - tmpfs tmpfs rw\n";
let rows = detcore_model::container_mounts::parse_container_mounts(namespace).unwrap();
let table = |installed: &[u64]| {
detcore_model::container_mounts::ContainerMountTable::select(
&rows,
&installed.iter().copied().collect(),
&[],
&std::collections::BTreeSet::new(),
)
};
let config = |table| DetConfig {
mountinfo_mount_ids: vec![10, 20, 1],
mountinfo_mount_ids_captured: true,
mountinfo_mount_namespace: Some(NAMESPACE),
container_mount_table: Some(table),
..DetConfig::default()
};
let snapshot = || -> Result<Vec<u64>, Error> { panic!("the snapshot is kept") };
let mut matching = config(table(&[20]));
prepare_kvm_mountinfo_config(&mut matching, || Ok(NAMESPACE), snapshot).unwrap();
let mut stale = config(table(&[40]));
let error =
prepare_kvm_mountinfo_config(&mut stale, || Ok(NAMESPACE), snapshot).unwrap_err();
assert!(error.to_string().contains("names mount 40"), "{error:#}");
}
#[test]
fn an_unplanned_table_shows_only_the_base_mountpoints() {
let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
20 10 0:22 / /proc rw - proc proc rw\n\
30 10 0:23 / /dev rw - devtmpfs dev rw\n\
40 10 0:24 / /data/eden rw - fuse.edenfs eden rw\n\
41 30 0:25 / /dev/shm rw - tmpfs tmpfs rw\n\
50 10 0:26 / /run/user/1000 rw - tmpfs tmpfs rw\n";
let base = [
(b"/".to_vec(), 10),
(b"/proc".to_vec(), 20),
(b"/dev".to_vec(), 30),
(b"/dev/shm".to_vec(), 41),
(b"/run".to_vec(), 10),
];
for mountpoint in detcore_model::container_mounts::BASE_MOUNTPOINTS {
assert!(
!mountpoint.bytes().any(|byte| b" \t\n\\".contains(&byte)),
"{mountpoint} needs mountinfo escaping"
);
}
let no_launch = std::collections::BTreeSet::new();
let (table, order) =
unplanned_container_mount_table_from(namespace, &no_launch, &base).unwrap();
assert_eq!(table.shown_mount_ids(), [10, 20, 30, 41].into());
assert_eq!(table.shown_mount_id(40), 10);
assert_eq!(table.shown_mount_id(50), 10);
assert_eq!(order, [10, 20, 30, 40, 41, 50, 1]);
let rendered = String::from_utf8(table.mountinfo()).unwrap();
assert!(!rendered.contains("/data/eden") && !rendered.contains("/run/user"));
let launch = [40].into();
let (table, order) =
unplanned_container_mount_table_from(namespace, &launch, &base).unwrap();
assert_eq!(table.shown_mount_ids(), [10, 20, 30, 40, 41].into());
assert_eq!(table.shown_mount_id(40), 40);
assert_eq!(table.shown_mount_id(50), 10);
assert_eq!(order, [10, 20, 30, 40, 41, 50, 1]);
}
fn rerun_in_user_namespace(name: &str) -> bool {
const CHILD: &str = "HERMIT_TEST_USER_NAMESPACE_CHILD";
if std::env::var_os(CHILD).is_some() {
return false;
}
let probe = std::process::Command::new("unshare")
.args(["--user", "--map-root-user", "--mount", "true"])
.output();
if !probe.as_ref().is_ok_and(|probe| probe.status.success()) {
eprintln!("SKIPPED {name}: user namespaces are unavailable here: {probe:?}");
return true;
}
let output = std::process::Command::new("unshare")
.args(["--user", "--map-root-user", "--mount", "--"])
.arg(std::env::current_exe().unwrap())
.args(["--exact", name, "--nocapture", "--test-threads=1"])
.env(CHILD, "1")
.output()
.expect("run the test under unshare");
let stdout = String::from_utf8_lossy(&output.stdout);
assert!(
output.status.success() && stdout.contains("1 passed"),
"the child failed or ran no test:\n{stdout}\n{}",
String::from_utf8_lossy(&output.stderr)
);
true
}
#[test]
fn a_thread_with_its_own_mount_namespace_captures_its_own_view() {
use std::os::unix::fs::MetadataExt;
if rerun_in_user_namespace(
"tests::a_thread_with_its_own_mount_namespace_captures_its_own_view",
) {
return;
}
let checked = std::thread::spawn(|| {
assert_eq!(
unsafe { libc::unshare(libc::CLONE_NEWNS) },
0,
"unshare(CLONE_NEWNS): {}",
io::Error::last_os_error()
);
let own = current_mount_namespace().unwrap();
let leader = fs::metadata("/proc/self/ns/mnt").unwrap();
assert_ne!(
own.inode,
leader.ino(),
"the thread kept the leader's namespace"
);
let (table, order) = unplanned_container_mount_table(Path::new(".")).unwrap();
assert!(
table
.mounts
.iter()
.any(|row| row.mountpoint.as_slice() == b"/"),
"the thread's table shows no /: {table:?}"
);
let root = thread_mount_id_of(Path::new("/")).unwrap();
assert!(table.shown_mount_ids().contains(&root));
assert!(table.shown_mount_ids().iter().all(|id| order.contains(id)));
})
.join();
assert!(checked.is_ok(), "the thread's checks failed");
}
#[test]
fn launch_directories_are_held_before_the_mount_table_is_read() {
if rerun_in_user_namespace(
"tests::launch_directories_are_held_before_the_mount_table_is_read",
) {
return;
}
let directory = tempfile::tempdir().unwrap();
let launch = directory.path().join("launch");
fs::create_dir(&launch).unwrap();
let before = thread_mount_id_of(&launch).unwrap();
let target = launch.clone();
let (table, _) = unplanned_container_mount_table_with(&launch, move || {
let status = std::process::Command::new("mount")
.args(["-t", "tmpfs", "none"])
.arg(&target)
.status()
.expect("run mount");
assert!(status.success(), "mount a tmpfs over the launch directory");
thread_mountinfo()
})
.unwrap();
let over = thread_mount_id_of(&launch).unwrap();
assert_ne!(over, before, "the tmpfs did not cover the launch directory");
assert!(table.shown_mount_ids().contains(&before));
assert!(!table.shown_mount_ids().contains(&over));
let _ = std::process::Command::new("umount").arg(&launch).status();
}
#[test]
fn a_launch_mount_missing_from_the_read_is_refused() {
let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n";
let error = unplanned_container_mount_table_from(namespace, &[99].into(), &[])
.unwrap_err()
.to_string();
assert!(error.contains("launch mount 99"), "{error}");
}
#[test]
fn skid_overshoot_report_covers_success_error_and_disabled_backends() {
let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
let _ = reverie::take_skid_overshoot_count();
reverie::record_skid_overshoot();
let empty_run = SkidOvershootReport::begin(true);
assert_eq!(
reverie::take_skid_overshoot_count(),
0,
"begin must clear evidence from a previous invocation"
);
empty_run.finish(Ok::<_, Error>(())).unwrap();
let success = SkidOvershootReport::begin(true);
reverie::record_skid_overshoot();
reverie::record_skid_overshoot();
let error = success.finish(Ok::<_, Error>(7)).unwrap_err();
assert_eq!(
error
.downcast_ref::<SkidOvershootError>()
.expect("skid refusal must remain typed")
.count(),
2
);
assert!(
error
.to_string()
.contains("observed 2 HERMIT_SKID_OVERSHOOT report(s)"),
"{error:#}"
);
assert!(
error
.to_string()
.contains("deterministic execution was not established"),
"{error:#}"
);
assert_eq!(reverie::take_skid_overshoot_count(), 0);
let error = SkidOvershootReport::begin(true);
reverie::record_skid_overshoot();
let error = error
.finish(Err::<(), _>(anyhow!("guest failed")))
.unwrap_err();
assert!(error.downcast_ref::<SkidOvershootError>().is_some());
let error = format!("{error:#}");
assert!(error.contains("guest failed"), "{error}");
assert!(
error.contains("observed 1 HERMIT_SKID_OVERSHOOT report(s)"),
"{error}"
);
assert_eq!(reverie::take_skid_overshoot_count(), 0);
reverie::record_skid_overshoot();
let disabled = SkidOvershootReport::begin(false);
disabled.finish(Ok::<_, Error>(())).unwrap();
assert_eq!(
reverie::take_skid_overshoot_count(),
1,
"a backend that cannot produce ptrace PMU overshoots must not consume another run's evidence"
);
}
#[test]
fn only_ptrace_hosted_backends_consume_skid_overshoot_reports() {
for backend in [Backend::Ptrace, Backend::E9patch] {
assert!(backend.uses_ptrace_pmu_timers(), "{backend:?}");
}
for backend in [Backend::Dbt, Backend::Sabre, Backend::Kvm] {
assert!(!backend.uses_ptrace_pmu_timers(), "{backend:?}");
}
assert!(!Backend::Liteinst.uses_ptrace_pmu_timers());
assert!(!Backend::InGuestTrap.uses_ptrace_pmu_timers());
}
#[cfg(feature = "liteinst")]
fn write_guest_program(directory: &Path, name: &str, bytes: &[u8], mode: u32) -> PathBuf {
let path = directory.join(name);
fs::write(&path, bytes).unwrap();
fs::set_permissions(&path, fs::Permissions::from_mode(mode)).unwrap();
assert_eq!(
fs::metadata(&path).unwrap().permissions().mode() & 0o7777,
mode,
"{}",
path.display()
);
path
}
#[cfg(feature = "liteinst")]
fn shebang_to(interpreter: &Path) -> Vec<u8> {
let mut script = b"#!".to_vec();
script.extend_from_slice(interpreter.as_os_str().as_bytes());
script.extend_from_slice(b" -e\necho script\n");
script
}
#[test]
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_runs_a_dynamically_linked_x86_64_program() {
use interp::startup_fixtures::dynamic_executable;
let directory = tempfile::tempdir().unwrap();
let program = write_guest_program(
directory.path(),
"dynamic",
&dynamic_executable(false),
0o755,
);
assert_eq!(
in_guest_liteinst_program_gap(&mut Command::new(&program)).unwrap(),
None
);
}
#[test]
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_refuses_programs_that_start_before_the_runtime() {
use interp::startup_fixtures::*;
let directory = tempfile::tempdir().unwrap();
let cases: [(&str, Vec<u8>, &str); 4] = [
(
"static",
elf(EM_X86_64, &[(PT_LOAD, b"code")]),
"is statically linked",
),
(
"preinit",
dynamic_executable(true),
"has a DT_PREINIT_ARRAY",
),
(
"aarch64",
elf(EM_AARCH64, &[(PT_INTERP, INTERP)]),
"is not a 64-bit x86-64 ELF image",
),
(
"text",
b"plain text, no #! line\n".to_vec(),
"is neither an ELF executable nor a #! script",
),
];
for (name, bytes, reason) in cases {
let program = write_guest_program(directory.path(), name, &bytes, 0o755);
let gap = in_guest_liteinst_program_gap(&mut Command::new(&program))
.unwrap()
.unwrap_or_else(|| panic!("{name} was not refused"));
assert!(
gap.contains(reason) && gap.contains(&program.display().to_string()),
"{name}: {gap}"
);
}
}
#[tokio::test]
#[cfg(feature = "liteinst")]
async fn a_recorded_in_guest_failure_fails_the_run_and_latches_a_loss() {
use std::os::fd::FromRawFd;
use reverie::GlobalTool;
use reverie_rpc_transport::ConnectionAdmission;
let config = DetConfig::default().with_backend(|backend| {
backend.process_exits_complete_asynchronously = true;
});
let global_state = detcore::GlobalState::init_global_state(&config).await;
let exits = in_guest_exits::InGuestExitAdmission::default();
let fd = unsafe { libc::syscall(libc::SYS_pidfd_open, std::process::id() as i32, 0) };
assert!(fd >= 0);
let pidfd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fd as i32) };
assert!(exits.admit(pidfd).is_err());
let error = settle_in_guest_exits(&exits, &global_state)
.await
.expect_err("a recorded failure must fail the run");
assert!(
error
.to_string()
.starts_with("in-guest LiteInst refused a guest connection:"),
"{error}"
);
assert!(detcore::detlog::determinism_loss().is_some());
}
#[test]
fn in_guest_trap_is_in_guest_liteinst_and_forces_site_patching_off() {
assert!(Backend::Liteinst.is_in_guest_liteinst());
assert!(Backend::InGuestTrap.is_in_guest_liteinst());
for backend in [
Backend::Ptrace,
Backend::Dbt,
Backend::Sabre,
Backend::Kvm,
Backend::E9patch,
] {
assert!(!backend.is_in_guest_liteinst(), "{backend:?}");
assert_eq!(backend.runtime_name(), backend.as_str(), "{backend:?}");
assert_eq!(forced_site_patching_value(backend), None, "{backend:?}");
}
assert_eq!(Backend::InGuestTrap.as_str(), "in-guest-trap");
assert_eq!(Backend::InGuestTrap.runtime_name(), "liteinst");
assert_eq!(Backend::Liteinst.runtime_name(), "liteinst");
assert_eq!(forced_site_patching_value(Backend::Liteinst), None);
assert_eq!(forced_site_patching_value(Backend::InGuestTrap), Some("0"));
assert_eq!(
<Backend as ValueEnum>::from_str("in-guest-trap", false),
Ok(Backend::InGuestTrap)
);
assert!(Backend::ALL.contains(&Backend::InGuestTrap));
for backend in Backend::ALL {
let name = backend
.to_possible_value()
.expect("every backend is a visible CLI value");
assert_eq!(name.get_name(), backend.as_str(), "{backend:?}");
}
}
#[test]
#[cfg(feature = "liteinst")]
fn in_guest_trap_refuses_a_guest_environment_that_turns_site_patching_on() {
use std::ffi::OsStr;
let name = reverie_liteinst::SITE_PATCHING_ENV;
let mut unset = Command::new("/bin/true");
unset.env_remove(name);
assert_eq!(
in_guest_trap_site_patching_conflict(&unset, Backend::InGuestTrap),
None
);
force_in_guest_site_patching(&mut unset, Backend::InGuestTrap);
assert_eq!(unset.get_env(name).as_deref(), Some(OsStr::new("0")));
let mut zero = Command::new("/bin/true");
zero.env(name, "0");
assert_eq!(
in_guest_trap_site_patching_conflict(&zero, Backend::InGuestTrap),
None
);
for value in ["1", "", "yes", " 0"] {
let mut command = Command::new("/bin/true");
command.env(name, value);
let conflict = in_guest_trap_site_patching_conflict(&command, Backend::InGuestTrap)
.unwrap_or_else(|| panic!("{value:?} was accepted"));
assert!(conflict.contains(&format!("{name}={value},")), "{conflict}");
assert!(conflict.contains("--backend=liteinst"), "{conflict}");
assert!(conflict.contains("drop the variable"), "{conflict}");
let error = refuse_in_guest_liteinst_run(
&mut command,
&DetConfig::default(),
Backend::InGuestTrap,
)
.unwrap_err();
let refusal = error
.downcast_ref::<LiteinstInGuestRefusal>()
.expect("a typed in-guest refusal, which the CLI reports as exit 122");
assert!(
refusal.to_string().starts_with(
"--backend=in-guest-trap (in-guest LiteInst, site patching off) refuses \
this run: the guest environment sets"
),
"{refusal}"
);
assert_eq!(command.get_env(name).as_deref(), Some(OsStr::new(value)));
let mut liteinst = Command::new("/bin/true");
liteinst.env(name, value);
assert_eq!(
in_guest_trap_site_patching_conflict(&liteinst, Backend::Liteinst),
None
);
force_in_guest_site_patching(&mut liteinst, Backend::Liteinst);
assert_eq!(liteinst.get_env(name).as_deref(), Some(OsStr::new(value)));
}
}
#[test]
#[cfg(feature = "liteinst")]
fn an_in_guest_trap_run_that_patched_a_site_is_refused_after_it_ends() {
let record = |candidates: Option<u64>, patched: Option<u64>| {
reverie::DispatchStats::new(
"in-guest-trap",
reverie::DispatchCounters::ZERO,
reverie::SiteCounters {
candidates,
patched,
fell_back: Some(0),
},
)
};
let clean = record(Some(0), Some(0));
assert_eq!(
in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&clean), 1),
None
);
for (candidates, patched, shown) in [
(Some(3), Some(3), "3 patched and 3 candidate"),
(Some(1), Some(0), "0 patched and 1 candidate"),
(Some(0), None, "unmeasured patched and 0 candidate"),
] {
let reason = in_guest_trap_patching_evidence(
Backend::InGuestTrap,
Some(&record(candidates, patched)),
1,
)
.unwrap_or_else(|| panic!("{candidates:?} {patched:?} was accepted"));
assert!(reason.contains(shown), "{reason}");
}
assert!(
in_guest_trap_patching_evidence(Backend::InGuestTrap, None, 1)
.is_some_and(|reason| reason.contains("no LiteInst dispatch record"))
);
assert!(
in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&clean), 0)
.is_some_and(|reason| reason.contains("no guest process reported"))
);
let patched = record(Some(3), Some(3));
assert_eq!(
in_guest_trap_patching_evidence(Backend::Liteinst, Some(&patched), 1),
None
);
assert_eq!(
in_guest_trap_patching_evidence(Backend::Liteinst, None, 0),
None
);
refuse_in_guest_trap_patching(Backend::InGuestTrap, None).unwrap();
let error = refuse_in_guest_trap_patching(
Backend::InGuestTrap,
in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&patched), 1),
)
.unwrap_err();
assert!(
error.downcast_ref::<LiteinstInGuestRefusal>().is_some(),
"{error:#}"
);
assert!(
error
.to_string()
.starts_with("--backend=in-guest-trap (in-guest LiteInst, site patching off)"),
"{error:#}"
);
assert!(
detcore::detlog::determinism_loss().is_some_and(|loss| loss.contains("3 patched")),
"the refusal must record a determinism loss"
);
}
#[test]
#[cfg(feature = "liteinst")]
fn only_in_guest_trap_asks_tool_images_to_check_their_runtime() {
for backend in Backend::ALL {
let checks = in_guest_site_patching_off(backend);
assert_eq!(checks, backend == Backend::InGuestTrap, "{backend:?}");
if checks {
assert!(in_guest_stats_request(backend, &None).is_enabled());
}
}
assert!(!in_guest_stats_request(Backend::Liteinst, &None).is_enabled());
}
#[test]
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_refuses_a_kernel_older_than_6_5() {
for release in [
"6.5.0",
"6.5",
"6.10.3-200.fc40.x86_64",
"7.1.3-0_fbk0_rc18",
"10.0",
] {
assert_eq!(in_guest_liteinst_kernel_gap(release), None, "{release}");
}
for release in ["6.4.16", "5.15.0-91-generic", "4.19"] {
let gap = in_guest_liteinst_kernel_gap(release)
.unwrap_or_else(|| panic!("{release} was not refused"));
assert!(gap.contains("Linux 6.5 or later"), "{gap}");
assert!(gap.contains(release), "{gap}");
}
for release in ["", "unknown", "6"] {
assert!(
in_guest_liteinst_kernel_gap(release).is_some(),
"{release:?}"
);
}
}
#[test]
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_refuses_secure_execution_images() {
use interp::startup_fixtures::dynamic_executable;
let directory = tempfile::tempdir().unwrap();
let bytes = dynamic_executable(false);
let gap = |name: &str, mode: u32| {
let program = write_guest_program(directory.path(), name, &bytes, mode);
in_guest_liteinst_program_gap(&mut Command::new(&program)).unwrap()
};
for (name, mode) in [("setuid", 0o4755), ("setgid", 0o2755)] {
let refusal = gap(name, mode).unwrap_or_else(|| panic!("{name} was not refused"));
assert!(refusal.contains("secure-execution mode"), "{refusal}");
}
assert_eq!(gap("setgid-no-group-exec", 0o2744), None);
}
#[test]
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_checks_scripts_through_their_interpreter() {
use interp::startup_fixtures::*;
let directory = tempfile::tempdir().unwrap();
let dynamic = write_guest_program(
directory.path(),
"dynamic",
&dynamic_executable(false),
0o755,
);
let static_elf = write_guest_program(
directory.path(),
"static",
&elf(EM_X86_64, &[(PT_LOAD, b"code")]),
0o755,
);
let script = write_guest_program(
directory.path(),
"to-static",
&shebang_to(&static_elf),
0o755,
);
let gap = in_guest_liteinst_program_gap(&mut Command::new(&script))
.unwrap()
.expect("a script run by a static interpreter was not refused");
assert!(
gap.contains(&static_elf.display().to_string()) && gap.contains("statically linked"),
"{gap}"
);
let relative = write_guest_program(directory.path(), "relative", b"#!static\n", 0o755);
let gap =
in_guest_liteinst_program_gap(Command::new(&relative).current_dir(directory.path()))
.unwrap()
.expect("a relative static interpreter was not refused");
assert!(gap.contains("statically linked"), "{gap}");
write_guest_program(
directory.path(),
"interp",
&dynamic_executable(false),
0o755,
);
let interp_cr = write_guest_program(
directory.path(),
"interp\r",
&elf(EM_X86_64, &[(PT_LOAD, b"code")]),
0o755,
);
let mut crlf = b"#!".to_vec();
crlf.extend_from_slice(directory.path().join("interp").as_os_str().as_bytes());
crlf.extend_from_slice(b"\r\necho script\r\n");
let crlf = write_guest_program(directory.path(), "crlf", &crlf, 0o755);
let gap = in_guest_liteinst_program_gap(&mut Command::new(&crlf))
.unwrap()
.expect("a CRLF script run by a static interp\\r was not refused");
assert!(
gap.contains(&interp_cr.display().to_string()) && gap.contains("statically linked"),
"{gap}"
);
let mut truncated = b"#!/".to_vec();
truncated.resize(256, b'a');
for (name, bytes) in [
("empty", b"#! \t\nbody\n".to_vec()),
("truncated", truncated),
] {
let program = write_guest_program(directory.path(), name, &bytes, 0o755);
let gap = in_guest_liteinst_program_gap(&mut Command::new(&program))
.unwrap()
.unwrap_or_else(|| panic!("{name} was not refused"));
assert!(
gap.contains("the kernel's script handler declines it"),
"{name}: {gap}"
);
}
let mut target = dynamic;
for level in 1..=5 {
target = write_guest_program(
directory.path(),
&format!("level-{level}"),
&shebang_to(&target),
0o755,
);
let gap = in_guest_liteinst_program_gap(&mut Command::new(&target)).unwrap();
if level <= MAX_INTERPRETER_DEPTH {
assert_eq!(gap, None, "level {level}");
} else {
let gap = gap.expect("five nested scripts were not refused");
assert!(gap.contains("nest more than 4 deep"), "{gap}");
}
}
}
#[test]
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_refuses_a_fifo_without_blocking() {
let directory = tempfile::tempdir().unwrap();
let fifo = directory.path().join("fifo");
let fifo_c = std::ffi::CString::new(fifo.as_os_str().as_bytes()).unwrap();
assert_eq!(unsafe { libc::mkfifo(fifo_c.as_ptr(), 0o700) }, 0);
let script = write_guest_program(directory.path(), "to-fifo", &shebang_to(&fifo), 0o755);
let socket = directory.path().join("socket");
let _listener = std::os::unix::net::UnixListener::bind(&socket).unwrap();
let to_socket =
write_guest_program(directory.path(), "to-socket", &shebang_to(&socket), 0o755);
let device = PathBuf::from("/dev/null");
let to_device =
write_guest_program(directory.path(), "to-device", &shebang_to(&device), 0o755);
let cases = [
(
"program",
PathBuf::from("./fifo"),
Some(directory.path().to_owned()),
fs::canonicalize(&fifo).unwrap(),
),
("interpreter", script, None, fifo.clone()),
("socket interpreter", to_socket, None, socket.clone()),
("device interpreter", to_device, None, device),
];
for (name, program, current_dir, shown) in cases {
let (sender, receiver) = std::sync::mpsc::channel();
std::thread::spawn(move || {
let mut command = Command::new(&program);
if let Some(directory) = current_dir {
command.current_dir(directory);
}
let gap = in_guest_liteinst_program_gap(&mut command)
.map_err(|error| format!("{error:#}"));
let _ = sender.send(gap);
});
let gap = receiver
.recv_timeout(std::time::Duration::from_secs(10))
.unwrap_or_else(|_| panic!("{name}: the check blocked on the FIFO"))
.unwrap()
.unwrap_or_else(|| panic!("{name}: the FIFO was not refused"));
assert!(
gap.contains(&format!("{} is not a regular file", shown.display())),
"{name}: {gap}"
);
}
}
#[test]
#[cfg(feature = "liteinst")]
fn in_guest_liteinst_pins_the_program_the_launch_resolves() {
use interp::startup_fixtures::*;
let directory = tempfile::tempdir().unwrap();
let name = "hermit-3520-static";
let static_elf = write_guest_program(
directory.path(),
name,
&elf(EM_X86_64, &[(PT_LOAD, b"code")]),
0o755,
);
let search = format!("/nonexistent-directory:{}", directory.path().display());
let check = |build: &dyn Fn() -> Command| {
let launch = build().find_program();
let mut command = build();
let arg0 = command.get_arg0().to_owned();
let gap = in_guest_liteinst_program_gap(&mut command);
match launch {
Ok(program) => {
let gap = gap.unwrap().expect("the static image was not refused");
assert!(gap.contains("is statically linked"), "{gap}");
assert_eq!(Path::new(command.get_program()), program);
assert_eq!(command.get_arg0(), arg0);
assert_eq!(command.find_program().unwrap(), program);
assert_eq!(
fs::canonicalize(&program).unwrap(),
fs::canonicalize(&static_elf).unwrap()
);
true
}
Err(_) => {
let error = gap.expect_err("the check found what the launch cannot");
assert!(
format!("{error:#}").contains("cannot find guest program"),
"{error:#}"
);
false
}
}
};
assert!(check(&|| {
let mut command = Command::new(format!("./{name}"));
command.current_dir(directory.path());
command
}));
assert!(check(&|| {
let mut command = Command::new(name);
command.env_clear().env("PATH", &search);
command
}));
assert!(!check(&|| {
let mut command = Command::new(name);
command.env("PATH", &search);
command
}));
assert!(!check(&|| {
let mut command = Command::new(name);
command.env_clear().current_dir(directory.path());
command
}));
fs::set_permissions(&static_elf, fs::Permissions::from_mode(0o644)).unwrap();
assert!(!check(&|| {
let mut command = Command::new(name);
command.env_clear().env("PATH", &search);
command
}));
assert!(!check(&|| Command::new(&static_elf)));
assert!(!check(&|| Command::new("hermit-no-such-program-3520")));
}
#[test]
fn skid_overshoot_error_refuses_a_successful_result() {
let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
let _ = reverie::take_skid_overshoot_count();
assert!(take_skid_overshoot_error().is_none());
reverie::record_skid_overshoot();
let error = take_skid_overshoot_error().expect("recorded overshoot must be reported");
assert!(
error
.to_string()
.contains("observed 1 HERMIT_SKID_OVERSHOOT report(s)")
);
assert!(
error
.to_string()
.contains("deterministic execution was not established")
);
assert_eq!(reverie::take_skid_overshoot_count(), 0);
}
#[test]
fn skid_overshoot_report_preserves_success_without_an_overshoot() {
let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
let _ = reverie::take_skid_overshoot_count();
let report = SkidOvershootReport::begin(true);
assert_eq!(report.finish(Ok::<_, Error>(7)).unwrap(), 7);
assert_eq!(reverie::take_skid_overshoot_count(), 0);
}
#[test]
fn skid_overshoot_count_can_cross_the_verify_boundary_with_the_output() {
let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
let _ = reverie::take_skid_overshoot_count();
let report = SkidOvershootReport::begin(true);
reverie::record_skid_overshoot();
let (value, count) = report.finish_with_count(Ok::<_, Error>(7)).unwrap();
assert_eq!(value, 7);
assert_eq!(count, 1);
assert_eq!(reverie::take_skid_overshoot_count(), 0);
}
#[test]
#[cfg(feature = "liteinst")]
fn liteinst_forced_shutdown_covers_every_status_hermit_reserves() {
assert!(
liteinst_requires_forced_shutdown(ExitStatus::Exited(130)),
"128+SIGINT"
);
assert!(
liteinst_requires_forced_shutdown(ExitStatus::Exited(143)),
"128+SIGTERM"
);
assert!(
liteinst_requires_forced_shutdown(ExitStatus::Exited(129)),
"128+SIGHUP"
);
assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(122)));
assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(125)));
assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(127)));
assert!(liteinst_requires_forced_shutdown(ExitStatus::Signaled(
nix::sys::signal::Signal::SIGKILL,
false
)));
assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(0)));
assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(1)));
assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(121)));
assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(128)));
assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(200)));
assert!(
liteinst_requires_forced_shutdown(ExitStatus::Exited(192)),
"128 + SIGRTMAX is still a signal death and must force shutdown"
);
assert!(
!liteinst_requires_forced_shutdown(ExitStatus::Exited(193)),
"above SIGRTMAX the status is the guest's own and must NOT force shutdown"
);
}
#[test]
fn a_cwd_under_tmp_is_explained_by_the_container_tmpfs_not_by_a_missing_directory() {
let error = std::io::Error::from(std::io::ErrorKind::NotFound);
let rendered = format!(
"{}",
super::kvm_cwd_resolution_error(std::path::Path::new("/tmp/agent-checkout"), &error)
);
assert!(
rendered.contains("private, empty tmpfs"),
"must name the mechanism: {rendered}"
);
assert!(
rendered.contains("--workdir"),
"must name a way out: {rendered}"
);
assert!(
rendered.contains("/tmp/agent-checkout"),
"must still name the path asked for: {rendered}"
);
}
#[test]
fn the_tmpfs_explanation_is_withheld_where_it_does_not_apply() {
let not_found = std::io::Error::from(std::io::ErrorKind::NotFound);
let outside_path = std::path::Path::new("/nonexistent-home/wt");
let outside = format!(
"{}",
super::kvm_cwd_resolution_error(outside_path, ¬_found)
);
assert!(!outside.contains("tmpfs"), "not a /tmp path: {outside}");
let tmp_itself = format!(
"{}",
super::kvm_cwd_resolution_error(std::path::Path::new("/tmp"), ¬_found)
);
assert!(!tmp_itself.contains("tmpfs"), "/tmp itself: {tmp_itself}");
let denied = std::io::Error::from(std::io::ErrorKind::PermissionDenied);
let other = format!(
"{}",
super::kvm_cwd_resolution_error(std::path::Path::new("/tmp/x"), &denied)
);
assert!(!other.contains("tmpfs"), "not NotFound: {other}");
}
#[test]
fn an_unbuilt_backend_names_the_flag_and_claims_nothing_about_the_machine() {
let feature_disabled_backends: &[(Backend, &str)] = &[
#[cfg(not(feature = "dbt"))]
(Backend::Dbt, "dbt"),
#[cfg(not(feature = "sabre"))]
(Backend::Sabre, "sabre"),
#[cfg(not(feature = "e9patch"))]
(Backend::E9patch, "e9patch"),
#[cfg(not(feature = "liteinst"))]
(Backend::Liteinst, "liteinst"),
#[cfg(not(feature = "liteinst"))]
(Backend::InGuestTrap, "liteinst"),
];
for &(backend, feature) in feature_disabled_backends {
let reason = backend
.unavailable_reason()
.expect("a feature-disabled backend must report why it is unavailable");
assert!(
reason.contains(feature),
"{backend:?}: a build-flag message must name the flag to rebuild with, got: {reason}"
);
assert!(
reason.contains("has not been checked"),
"{backend:?}: a build-flag message must not imply the machine was tested, got: {reason}"
);
}
}
#[cfg(not(feature = "dbt"))]
#[test]
fn dbt_registry_diagnostic_redirects_to_a_source_build() {
let reason = super::dbt_disabled_build_reason("hermit-run");
assert!(reason.contains("not included in this registry release"));
assert!(reason.contains("source build from https://github.com/rrnewton/hermit"));
assert!(reason.contains("`third-party-backends` feature does not include DBT"));
assert!(reason.contains("has not been checked"));
let source_reason = super::dbt_disabled_build_reason("hermit");
assert!(source_reason.contains("rebuild with `--features dbt`"));
assert!(!source_reason.contains("not included in this registry release"));
}
#[cfg(not(feature = "sabre"))]
#[tokio::test]
async fn disabled_sabre_dispatch_refuses_before_resolving_the_program() {
let program = "/hermit-missing-disabled-sabre-program";
let error = super::dispatch_backend(
super::Command::new(program),
super::DetConfig::default(),
false,
&None,
Backend::Sabre,
None,
)
.await
.unwrap_err();
assert!(
error
.to_string()
.contains("the `sabre` feature is not enabled")
);
let error = super::dispatch_output_backend(
super::Command::new(program),
super::DetConfig::default(),
false,
&None,
Backend::Sabre,
None,
)
.await
.unwrap_err();
assert!(
error
.to_string()
.contains("the `sabre` feature is not enabled")
);
}
#[test]
#[cfg(feature = "dbt")]
fn a_cold_dbt_runtime_diagnostic_is_not_feature_absence() {
let reason = dbt_runtime_unavailable_reason_from(Err(io::Error::new(
io::ErrorKind::NotFound,
"Hermit DBT runtime was not built beside /cold-target/hermit or in its deps directory",
)))
.expect("a missing cold-target runtime must remain unavailable");
assert!(reason.contains("was not built beside"));
assert!(reason.contains("build the hermit binary and cdylib"));
assert!(!reason.contains("not enabled in this build"));
assert!(!reason.contains("has not been checked"));
}
#[cfg(feature = "sabre")]
use std::ffi::OsStr;
use std::fs;
#[cfg(feature = "sabre")]
use std::os::unix::fs::PermissionsExt;
use std::path::PathBuf;
#[cfg(feature = "sabre")]
use std::sync::Arc;
#[cfg(feature = "sabre")]
use std::time::Duration;
use super::Backend;
#[cfg(any(feature = "sabre", feature = "liteinst"))]
use super::ExitStatus;
use super::HermitData;
use super::Id;
#[cfg(feature = "sabre")]
use super::SABRE_RPC_SOCKET_ENV;
use super::collect_recording_ids;
#[cfg(feature = "dbt")]
use super::dbt_runtime_unavailable_reason;
#[cfg(feature = "dbt")]
use super::dbt_runtime_unavailable_reason_from;
#[cfg(feature = "dbt")]
use super::dynamorio_sdk_available;
use super::ensure_backend_dispatch;
#[cfg(feature = "dbt")]
use super::is_dynamorio_sdk;
use super::kvm_device_unavailable_reason;
#[cfg(feature = "liteinst")]
use super::liteinst_requires_forced_shutdown;
#[cfg(feature = "dbt")]
use super::liteinst_unavailable_reason;
use super::output_backend_stdin_file;
use super::prepare_backend_config;
use super::reserve_output_stdin_snapshot;
use super::resolve_kvm_shebang;
#[cfg(feature = "sabre")]
use super::resolve_sabre_binary_from;
#[cfg(feature = "sabre")]
use super::sabre_backend_evidence_line;
#[cfg(feature = "sabre")]
use super::sabre_program_needs_neutral_name;
#[cfg(feature = "sabre")]
use super::sabre_reach_state;
#[cfg(feature = "sabre")]
use super::sabre_uninstrumented_guest_message;
#[cfg(feature = "sabre")]
use super::shutdown_sabre_rpc;
#[cfg(feature = "sabre")]
use super::stage_sabre_program_in;
#[cfg(feature = "sabre")]
use super::stop_sabre_rpc_server;
#[cfg(feature = "sabre")]
use super::wait_for_sabre_rpc_disconnects;
#[test]
fn recording_inventory_preserves_missing_and_non_recording_cases() {
let parent = tempfile::tempdir().expect("failed to create recording inventory parent");
let missing = parent.path().join("missing");
assert!(
HermitData::with_dir(&missing)
.try_recordings()
.expect("a missing data directory should be empty")
.is_empty()
);
let inventory = parent.path().join("inventory");
fs::create_dir(&inventory).expect("failed to create recording inventory");
let recording: Id = "0123456789abcdef0123456789abcdef"
.parse()
.expect("valid recording ID");
fs::create_dir(inventory.join(recording.to_string()))
.expect("failed to create recording directory");
fs::create_dir(inventory.join("not-a-recording"))
.expect("failed to create invalid-name directory");
fs::write(
inventory.join("fedcba9876543210fedcba9876543210"),
b"not a directory",
)
.expect("failed to create valid-looking non-directory");
assert_eq!(
HermitData::with_dir(&inventory)
.try_recordings()
.expect("recording inventory should be readable"),
vec![recording]
);
assert_eq!(
HermitData::with_dir(&inventory)
.recordings()
.collect::<Vec<_>>(),
vec![recording]
);
}
#[test]
fn recording_inventory_rejects_an_error_after_a_valid_entry() {
let inventory = tempfile::tempdir().expect("failed to create recording inventory");
let recording: Id = "0123456789abcdef0123456789abcdef"
.parse()
.expect("valid recording ID");
fs::create_dir(inventory.path().join(recording.to_string()))
.expect("failed to create recording directory");
let valid_entry = fs::read_dir(inventory.path())
.expect("failed to open recording inventory")
.next()
.expect("missing recording entry")
.expect("failed to read recording entry");
let entries = vec![
Ok(valid_entry),
Err(std::io::Error::other("injected entry failure")),
];
let error = collect_recording_ids(entries, inventory.path(), fs::DirEntry::file_type)
.expect_err("a partial inventory must not be returned");
assert!(
error
.to_string()
.contains("Failed to read an entry in recording inventory"),
"unexpected error: {error:#}"
);
}
#[test]
fn recording_inventory_rejects_an_entry_inspection_error() {
let inventory = tempfile::tempdir().expect("failed to create recording inventory");
let recording = inventory.path().join("0123456789abcdef0123456789abcdef");
fs::create_dir(&recording).expect("failed to create recording directory");
let entry = fs::read_dir(inventory.path())
.expect("failed to open recording inventory")
.next()
.expect("missing recording entry")
.expect("failed to read recording entry");
let error = collect_recording_ids([Ok(entry)], inventory.path(), |_| {
Err(std::io::Error::other("injected inspection failure"))
})
.expect_err("an uninspectable entry must fail the inventory");
assert!(
error
.to_string()
.contains("Failed to inspect recording inventory entry"),
"unexpected error: {error:#}"
);
}
#[test]
fn output_stdin_snapshot_replays_pipe_to_repeated_runs() {
use std::io::Read;
use std::io::Write;
use std::os::fd::FromRawFd;
let mut fds = [0i32; 2];
assert_eq!(unsafe { libc::pipe(fds.as_mut_ptr()) }, 0);
let read_end = unsafe { fs::File::from_raw_fd(fds[0]) };
let mut write_end = unsafe { fs::File::from_raw_fd(fds[1]) };
let payload = b"int main(){return 0;}\n";
write_end.write_all(payload).unwrap();
drop(write_end);
reserve_output_stdin_snapshot(Some(read_end)).unwrap();
for run in 0..2 {
let mut file = output_backend_stdin_file()
.unwrap()
.unwrap_or_else(|| panic!("run {run}: expected a replayable stdin snapshot"));
let mut got = Vec::new();
file.read_to_end(&mut got).unwrap();
assert_eq!(got, payload, "run {run} stdin replay mismatch");
}
let mut file = output_backend_stdin_file().unwrap().unwrap();
let error = file
.write_all(b"guest-must-not-change-the-snapshot")
.expect_err("the replayed stdin must be read-only");
assert_eq!(error.raw_os_error(), Some(libc::EBADF));
}
#[test]
#[cfg(feature = "liteinst")]
fn liteinst_reserved_failures_require_scheduler_cancellation() {
for status in 122..=127 {
assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(
status
)));
}
assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(121)));
assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(128)));
}
#[test]
#[cfg(feature = "sabre")]
fn uninstrumented_sabre_guest_is_reported_as_no_determinization() {
let message = sabre_uninstrumented_guest_message(&ExitStatus::Exited(0));
assert!(
message.contains("no determinization at all"),
"must not present an uninstrumented run as a weaker guarantee: {message}"
);
assert!(
message.contains("Detcore coordinator"),
"must name the authority that was never reached: {message}"
);
assert!(
message.contains("statically linked ELF"),
"must name the dominant cause so the reader can act: {message}"
);
assert!(
message.contains("Exited(0)"),
"must carry the observed status: {message}"
);
assert!(
sabre_uninstrumented_guest_message(&ExitStatus::Exited(139)).contains("Exited(139)"),
"must carry a failing status too"
);
}
#[test]
#[cfg(feature = "sabre")]
fn sabre_reach_states_are_pairwise_distinct() {
let no_detcore = sabre_reach_state(false, 0);
let degraded = sabre_reach_state(true, 1);
let exercised = sabre_reach_state(true, 0);
assert_eq!(no_detcore, "no-detcore-reached");
assert_eq!(degraded, "degraded-ptrace-fallback");
assert_eq!(exercised, "sabre-exercised");
assert_ne!(no_detcore, degraded);
assert_ne!(no_detcore, exercised);
assert_ne!(degraded, exercised);
assert_eq!(
sabre_reach_state(false, 9),
"no-detcore-reached",
"absence of a guest RPC must dominate any fallback count"
);
}
#[test]
#[cfg(feature = "sabre")]
fn sabre_backend_fact_is_versioned_and_names_preplugin_coverage() {
let exercised = super::sabre_ptrace::PathEvidence {
schema: 1,
guest_rpc_observed: true,
ptrace_fallback_sites: 0,
trusted_shared_object_sites: 2,
trusted_shared_objects: vec!["/usr/lib/libc.so.6".to_owned()],
};
assert_eq!(
sabre_backend_evidence_line(&exercised),
":: Backend: sabre static rewriting + ptrace runtime; run_mode=run; \
evidence_schema=1; preplugin_coverage=absent; ptrace_fallback_sites=0; \
trusted_shared_object_sites=2; guest_rpc_observed=true; \
reach_state=sabre-exercised"
);
let unengaged = super::sabre_ptrace::PathEvidence {
guest_rpc_observed: false,
..exercised
};
let fact = sabre_backend_evidence_line(&unengaged);
assert!(fact.contains("preplugin_coverage=absent"));
assert!(fact.contains("reach_state=no-detcore-reached"));
assert!(!fact.contains("reach_state=sabre-exercised"));
}
#[test]
fn liteinst_backend_config_preserves_the_requested_timeslice() {
let config = super::DetConfig::default();
assert!(config.max_timeslice.is_some());
for backend in [Backend::Liteinst, Backend::InGuestTrap] {
assert!(
prepare_backend_config(config.clone(), backend)
.max_timeslice
.is_some(),
"{backend:?}"
);
}
assert!(
prepare_backend_config(config, Backend::Ptrace)
.max_timeslice
.is_some()
);
}
#[test]
fn in_guest_liteinst_cancels_killed_thread_rpcs() {
let config = super::DetConfig::default();
for backend in [Backend::Liteinst, Backend::InGuestTrap] {
assert!(
prepare_backend_config(config.clone(), backend)
.backend
.needs_killed_thread_rpc_cancellation,
"{backend:?}"
);
}
assert!(
!prepare_backend_config(config, Backend::Ptrace)
.backend
.needs_killed_thread_rpc_cancellation
);
}
#[test]
fn sabre_backend_configures_process_local_capabilities() {
let config = super::DetConfig::default();
let sabre = prepare_backend_config(config.clone(), Backend::Sabre).backend;
assert!(sabre.tool_shares_guest_descriptor_table);
assert!(sabre.rediscovers_descriptors_after_exec);
assert!(sabre.internal_pipe_turns_are_host_timed);
assert!(sabre.loopback_pollers_yield_to_peers);
assert!(sabre.guest_clock_reads_bypass_backend);
assert!(sabre.virtualizes_syscall_clobbers);
assert!(sabre.needs_killed_thread_rpc_cancellation);
assert!(sabre.reports_physical_process_exits);
assert!(sabre.signal_interrupts_external_syscalls);
assert!(sabre.tracks_process_children);
assert!(!sabre.runs_exit_robust_list);
assert!(!sabre.requires_thread_directed_process_signals);
assert!(!sabre.defers_vfork_child_registration);
let ptrace = prepare_backend_config(config, Backend::Ptrace).backend;
assert!(!ptrace.tool_shares_guest_descriptor_table);
assert!(!ptrace.rediscovers_descriptors_after_exec);
assert!(!ptrace.internal_pipe_turns_are_host_timed);
assert!(!ptrace.loopback_pollers_yield_to_peers);
assert!(!ptrace.guest_clock_reads_bypass_backend);
assert!(!ptrace.virtualizes_syscall_clobbers);
assert!(!ptrace.needs_killed_thread_rpc_cancellation);
assert!(!ptrace.reports_physical_process_exits);
assert!(!ptrace.signal_interrupts_external_syscalls);
assert!(ptrace.tracks_process_children);
assert!(ptrace.runs_exit_robust_list);
assert!(!ptrace.requires_thread_directed_process_signals);
assert!(!ptrace.defers_vfork_child_registration);
}
#[test]
fn kvm_reports_stored_metadata_timestamps_only_for_sequential_tool_threads() {
let sequential = prepare_backend_config(
super::DetConfig {
sequentialize_threads: true,
virtualize_metadata: true,
..super::DetConfig::default()
},
Backend::Kvm,
);
assert!(super::kvm_reports_stored_metadata_timestamps(&sequential));
let concurrent = super::DetConfig {
sequentialize_threads: false,
..sequential.clone()
};
assert!(!super::kvm_reports_stored_metadata_timestamps(&concurrent));
let host_metadata = super::DetConfig {
virtualize_metadata: false,
..sequential
};
assert!(!super::kvm_reports_stored_metadata_timestamps(
&host_metadata
));
}
#[test]
fn kvm_backend_config_marks_concurrent_process_children() {
let defaults = super::DetConfig::default();
assert!(!defaults.sequentialize_threads);
let nonsequential = prepare_backend_config(defaults, Backend::Kvm);
assert!(nonsequential.backend.provides_process_signal_control);
assert!(nonsequential.backend.emulates_child_waits);
assert!(!may_observe_signal_dequeues(&nonsequential));
assert!(!requires_signal_control(&nonsequential));
let config = super::DetConfig {
sequentialize_threads: true,
..super::DetConfig::default()
};
let kvm = prepare_backend_config(config, Backend::Kvm);
assert!(may_observe_signal_dequeues(&kvm));
assert!(requires_signal_control(&kvm));
assert!(kvm.backend.needs_killed_thread_rpc_cancellation);
assert!(kvm.backend.tracks_process_children);
assert!(!kvm.backend.runs_exit_robust_list);
assert!(!kvm.backend.requires_thread_directed_process_signals);
assert!(kvm.backend.defers_vfork_child_registration);
for backend in [
Backend::Ptrace,
Backend::Dbt,
Backend::Sabre,
Backend::Liteinst,
Backend::InGuestTrap,
Backend::E9patch,
] {
let config = super::DetConfig {
sequentialize_threads: true,
..super::DetConfig::default()
};
let prepared = prepare_backend_config(config, backend);
assert!(!may_observe_signal_dequeues(&prepared), "{backend:?}");
assert!(!requires_signal_control(&prepared), "{backend:?}");
}
}
fn may_observe_signal_dequeues(config: &DetConfig) -> bool {
<super::Detcore as reverie::Tool>::may_observe_signal_dequeues(config)
}
fn requires_signal_control(config: &DetConfig) -> bool {
<super::Detcore as reverie::Tool>::requires_signal_control(config)
}
fn golden_backend_capabilities(backend: Backend) -> serde_json::Value {
let sabre = backend == Backend::Sabre;
let kvm = backend == Backend::Kvm;
let dbt = backend == Backend::Dbt;
let in_guest_liteinst = matches!(backend, Backend::Liteinst | Backend::InGuestTrap);
serde_json::json!({
"tool_shares_guest_descriptor_table": sabre || dbt,
"rediscovers_descriptors_after_exec": sabre || dbt,
"internal_pipe_turns_are_host_timed": sabre,
"loopback_pollers_yield_to_peers": sabre,
"guest_clock_reads_bypass_backend": sabre,
"virtualizes_syscall_clobbers": sabre,
"needs_killed_thread_rpc_cancellation": in_guest_liteinst || sabre || dbt || kvm,
"reports_physical_process_exits": sabre,
"process_exits_complete_asynchronously": in_guest_liteinst,
"virtualizes_guest_sigalrm": in_guest_liteinst,
"signal_interrupts_external_syscalls": sabre,
"tracks_process_children": !dbt,
"runs_exit_robust_list": matches!(backend, Backend::Ptrace | Backend::E9patch),
"requires_thread_directed_process_signals": dbt,
"supports_parked_write_signal_interruption":
matches!(backend, Backend::Ptrace | Backend::E9patch | Backend::Kvm),
"defers_vfork_child_registration": kvm,
"supports_madvise": !kvm,
"supports_madv_dontneed": true,
"reports_child_exit_publication":
matches!(backend, Backend::Ptrace | Backend::E9patch),
"reports_kernel_child_exit_signals":
matches!(backend, Backend::Ptrace | Backend::E9patch | Backend::Sabre),
"provides_process_signal_control": kvm,
"emulates_child_waits": kvm,
"supports_blocked_wait_signal_interruption":
matches!(backend, Backend::Ptrace | Backend::E9patch),
"delivers_preemption_timer_events":
matches!(backend, Backend::Ptrace | Backend::E9patch),
"runs_guest_code_between_injections": sabre || in_guest_liteinst,
"promotes_open_files_before_native_lifecycle": dbt || in_guest_liteinst,
"reports_sigreturns": matches!(backend, Backend::Ptrace | Backend::E9patch),
})
}
#[test]
fn backend_capabilities_match_the_golden_table() {
for backend in [
Backend::Ptrace,
Backend::Kvm,
Backend::E9patch,
Backend::Liteinst,
Backend::InGuestTrap,
Backend::Sabre,
Backend::Dbt,
] {
let config = prepare_backend_config(super::DetConfig::default(), backend);
assert_eq!(
serde_json::to_value(config.backend).unwrap(),
golden_backend_capabilities(backend),
"{backend:?}"
);
}
}
#[test]
fn backend_capabilities_are_the_ones_each_backend_reports() {
assert_eq!(
super::backend_capabilities(Backend::Ptrace),
<reverie_ptrace::PtraceBackend as reverie::Backend>::capabilities()
);
assert_eq!(
super::backend_capabilities(Backend::Kvm),
reverie_kvm::KvmBackend::capabilities()
);
#[cfg(feature = "liteinst")]
{
let backing = unsafe {
std::ptr::addr_of!(super::reverie_liteinst_allocator_backing_v1)
.cast::<[u64; 2]>()
.read_volatile()
};
assert_eq!(backing, [1, 1], "host Hermit must declare Legacy backing");
assert_eq!(
super::backend_capabilities(Backend::Liteinst),
<reverie_liteinst::LiteinstBackend as reverie::Backend>::capabilities()
);
assert_eq!(
super::backend_capabilities(Backend::InGuestTrap),
<reverie_liteinst::LiteinstBackend as reverie::Backend>::capabilities()
);
}
#[cfg(feature = "dbt")]
{
assert_eq!(
super::backend_capabilities(Backend::Dbt),
reverie_dbt::DbtRunner::capabilities()
);
assert_eq!(
super::backend_capabilities(Backend::Dbt),
detcore_dbt::backend_capabilities()
);
}
}
fn env_free_detconfig(epoch: &str, seed: &str) -> DetConfig {
use clap::Parser;
let mut config = DetConfig::parse_from(["hermit", epoch, seed, "--sched-seed=0"]);
config.sched_seed = None;
config
}
fn rich_detconfig() -> DetConfig {
let mut config = env_free_detconfig("--epoch=2000-12-31T23:59:59Z", "--seed=7");
config.rng_seed = Some(13);
config.sched_seed = Some(11);
config.clock_multiplier = Some(1.5);
config.chaos = true;
config.record_preemptions_to = Some(std::path::PathBuf::from(
"/tmp/a,\"detect_host_clock_futex_timeouts\":true,\"backend_tracks_process_children\":{",
));
config.mountinfo_root_rewrites = vec![detcore_model::config::MountInfoRootRewrite {
raw_mount_id: 41,
deterministic_root: b"/".to_vec(),
raw_root_prefix: Some(b"/tmp/x".to_vec()),
deterministic_root_prefix: Some(b"/tmp".to_vec()),
raw_mountpoint_prefix: None,
deterministic_mountpoint_prefix: None,
}];
config.stacktrace_event = vec![(3, Some(std::path::PathBuf::from("/s")))];
config
}
#[test]
fn historical_dbt_capabilities_preserve_legacy_detconfig_bytes() {
let sequential = |mut config: DetConfig| {
config.sequentialize_threads = true;
config
};
let default_config = || env_free_detconfig("--epoch=2026-01-01T00:00:00Z", "--seed=0");
for (name, mut config, before) in [
(
"default",
default_config(),
include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-default.json"),
),
(
"dbt",
prepare_backend_config(sequential(default_config()), Backend::Dbt),
include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-dbt.json"),
),
(
"rich_dbt",
prepare_backend_config(sequential(rich_detconfig()), Backend::Dbt),
include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-rich_dbt.json"),
),
] {
config.backend.tool_shares_guest_descriptor_table = false;
config.backend.rediscovers_descriptors_after_exec = false;
config.backend.supports_blocked_wait_signal_interruption = false;
config.backend.delivers_preemption_timer_events = false;
config.backend.runs_guest_code_between_injections = false;
assert_eq!(
detcore::to_legacy_backend_json(&config).unwrap(),
before,
"HERMIT_DBT_DETCONFIG for the {name} config changed"
);
let decoded = detcore::from_legacy_backend_json(before).unwrap();
assert_eq!(decoded.backend, config.backend, "{name}");
assert_eq!(
decoded.sequentialize_threads, config.sequentialize_threads,
"{name}"
);
assert_eq!(
detcore::to_legacy_backend_json(&decoded).unwrap(),
before,
"{name}"
);
}
}
const LEGACY_BACKEND_KEYS: [&str; 15] = [
"cpuid_virtualized_by_backend",
"backend_supports_madvise",
"discover_live_file_metadata",
"detect_host_clock_futex_timeouts",
"syscall_clobbers_virtualized_by_backend",
"cancel_killed_thread_rpcs",
"backend_reports_physical_process_exits",
"backend_tracks_process_children",
"backend_runs_exit_robust_list",
"backend_requires_thread_directed_process_signals",
"backend_is_kvm",
"kvm_shared_dequeue_timers",
"backend_supports_parked_write_signal_interruption",
"backend_virtualizes_capability_prctls",
"backend_defers_vfork_child_registration",
];
#[test]
fn every_backend_encodes_its_current_legacy_projection() {
for (backend, unsequenced, sequential) in [
(Backend::Ptrace, "010000011000100", "010000011000100"),
(Backend::E9patch, "010000011000100", "010000011000100"),
(Backend::Liteinst, "010001010000000", "010001010000000"),
(Backend::InGuestTrap, "010001010000000", "010001010000000"),
(Backend::Sabre, "011111110000000", "011111110000000"),
(Backend::Dbt, "011001000100000", "011001000100000"),
(Backend::Kvm, "000001010010101", "000001010011101"),
] {
for (sequentialize_threads, expected) in [(false, unsequenced), (true, sequential)] {
let config = prepare_backend_config(
DetConfig {
sequentialize_threads,
..DetConfig::default()
},
backend,
);
let encoded: serde_json::Map<String, serde_json::Value> =
serde_json::from_str(&detcore::to_legacy_backend_json(&config).unwrap())
.unwrap();
let digits: String = LEGACY_BACKEND_KEYS
.iter()
.map(|key| match encoded.get(*key) {
Some(serde_json::Value::Bool(true)) => '1',
Some(serde_json::Value::Bool(false)) => '0',
other => panic!("{key} encoded as {other:?}"),
})
.collect();
assert_eq!(
digits, expected,
"{backend:?}, sequentialize_threads={sequentialize_threads}"
);
}
}
}
#[test]
fn dbt_backend_config_translates_process_signals_to_host_threads() {
let config = prepare_backend_config(super::DetConfig::default(), Backend::Dbt);
assert!(config.backend.needs_killed_thread_rpc_cancellation);
assert!(!config.backend.tracks_process_children);
assert!(!config.backend.runs_exit_robust_list);
assert!(config.backend.requires_thread_directed_process_signals);
assert!(!config.backend.defers_vfork_child_registration);
}
#[test]
fn backend_write_signal_contract_is_explicit() {
for (backend, supports_interruption) in [
(Backend::Ptrace, true),
(Backend::Dbt, false),
(Backend::Kvm, true),
(Backend::Sabre, false),
(Backend::Liteinst, false),
(Backend::InGuestTrap, false),
(Backend::E9patch, true),
] {
let config = prepare_backend_config(super::DetConfig::default(), backend);
assert_eq!(
config.backend.supports_parked_write_signal_interruption, supports_interruption,
"unexpected parked-write signal support for {backend:?}"
);
}
}
#[test]
fn backend_timer_delivery_is_explicit() {
for (backend, delivers) in [
(Backend::Ptrace, true),
(Backend::Dbt, false),
(Backend::Kvm, false),
(Backend::Sabre, false),
(Backend::Liteinst, false),
(Backend::InGuestTrap, false),
(Backend::E9patch, true),
] {
let config = prepare_backend_config(super::DetConfig::default(), backend);
assert_eq!(
config.backend.delivers_preemption_timer_events, delivers,
"unexpected timer delivery for {backend:?}"
);
}
}
#[test]
fn backend_guest_code_between_injections_is_explicit() {
for (backend, runs) in [
(Backend::Ptrace, false),
(Backend::Dbt, false),
(Backend::Kvm, false),
(Backend::Sabre, true),
(Backend::Liteinst, true),
(Backend::InGuestTrap, true),
(Backend::E9patch, false),
] {
let config = prepare_backend_config(super::DetConfig::default(), backend);
assert_eq!(
config.backend.runs_guest_code_between_injections, runs,
"unexpected guest code between injections for {backend:?}"
);
}
}
#[test]
fn backend_blocked_wait_signal_contract_is_explicit() {
for (backend, supports_interruption) in [
(Backend::Ptrace, true),
(Backend::Dbt, false),
(Backend::Kvm, false),
(Backend::Sabre, false),
(Backend::Liteinst, false),
(Backend::InGuestTrap, false),
(Backend::E9patch, true),
] {
let config = prepare_backend_config(super::DetConfig::default(), backend);
assert_eq!(
config.backend.supports_blocked_wait_signal_interruption, supports_interruption,
"unexpected blocked-wait signal support for {backend:?}"
);
}
}
#[test]
fn a_launch_may_pass_a_terminal_unless_it_proves_it_has_none() {
assert!(!super::may_pass_a_terminal(false, Some(0)));
assert!(super::may_pass_a_terminal(true, Some(0)));
assert!(super::may_pass_a_terminal(false, Some(34817)));
assert!(super::may_pass_a_terminal(false, None));
let stat = "4242 (a) b (c)) S 1 4242 4242 34817 4242 4194560 0 0 0 0";
assert_eq!(super::parse_controlling_terminal_device(stat), Some(34817));
let stat = "4242 (hermit) S 1 4242 4242 0 -1 4194560 0 0 0 0";
assert_eq!(super::parse_controlling_terminal_device(stat), Some(0));
assert_eq!(
super::parse_controlling_terminal_device("4242 (hermit"),
None
);
assert_eq!(
super::parse_controlling_terminal_device("4242 (hermit) S 1"),
None
);
assert!(super::controlling_terminal_device().is_some());
}
#[test]
fn only_gated_backends_record_an_inherited_terminal() {
for backend in [
Backend::Dbt,
Backend::Kvm,
Backend::Sabre,
Backend::Liteinst,
Backend::InGuestTrap,
Backend::E9patch,
] {
let config = prepare_backend_config(super::DetConfig::default(), backend);
assert!(
!config.guest_may_inherit_a_terminal,
"unexpected terminal record for {backend:?}"
);
}
let config = prepare_backend_config(super::DetConfig::default(), Backend::Ptrace);
assert_eq!(
config.guest_may_inherit_a_terminal,
super::launcher_may_pass_a_terminal()
);
}
#[test]
fn liteinst_public_dispatch_runs_in_guest_detcore() {
if Backend::Liteinst.ensure_available().is_err() {
return;
}
let config = super::DetConfig {
max_timeslice: None,
..super::DetConfig::default()
};
let mut command = super::Command::new("/bin/echo");
command.arg("hello");
let output = super::run_with_output_backend(
command,
config.clone(),
false,
&None,
Backend::Liteinst,
)
.expect("run /bin/echo through in-guest LiteInst");
assert_eq!(
output.status,
super::ExitStatus::Exited(0),
"guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
String::from_utf8_lossy(&output.stderr),
String::from_utf8_lossy(&output.stdout),
);
assert_eq!(output.stdout, b"hello\n");
let status = super::run_with_backend(
super::Command::new("/bin/true"),
config,
false,
&None,
Backend::Liteinst,
)
.expect("run /bin/true through in-guest LiteInst");
assert_eq!(status, super::ExitStatus::Exited(0));
}
#[test]
#[cfg(feature = "dbt")]
fn default_and_available_backends_reflect_host_probes() {
assert_eq!(Backend::default(), Backend::Ptrace);
let available = Backend::available().collect::<Vec<_>>();
assert_eq!(
available.contains(&Backend::Ptrace),
Backend::Ptrace.is_available()
);
assert_eq!(
available.contains(&Backend::Dbt),
dynamorio_sdk_available() && dbt_runtime_unavailable_reason().is_none()
);
assert_eq!(
available.contains(&Backend::Liteinst),
liteinst_unavailable_reason().is_none()
);
assert_eq!(
available.contains(&Backend::InGuestTrap),
available.contains(&Backend::Liteinst)
);
assert_eq!(
available.contains(&Backend::Sabre),
Backend::Sabre.is_available()
);
assert_eq!(
available.contains(&Backend::Kvm),
kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_none(),
);
assert_eq!(
available.contains(&Backend::E9patch),
Backend::E9patch.is_available()
);
}
#[test]
#[cfg(feature = "dbt")]
fn dependency_probes_require_usable_paths() {
let temp = tempfile::tempdir().unwrap();
assert!(!is_dynamorio_sdk(temp.path()));
fs::create_dir(temp.path().join("include")).unwrap();
fs::write(temp.path().join("include/dr_api.h"), b"/* marker */").unwrap();
assert!(is_dynamorio_sdk(temp.path()));
let reason = kvm_device_unavailable_reason(temp.path())
.expect("a directory must not pass the read-write KVM device probe");
assert!(reason.contains("read-write"));
}
#[cfg(feature = "sabre")]
fn write_test_executable(path: &std::path::Path) {
fs::create_dir_all(path.parent().unwrap()).unwrap();
fs::write(path, b"test loader").unwrap();
let mut permissions = fs::metadata(path).unwrap().permissions();
permissions.set_mode(0o700);
fs::set_permissions(path, permissions).unwrap();
}
#[test]
#[cfg(feature = "sabre")]
fn sabre_rpc_socket_uses_private_exec_environment() {
assert!(SABRE_RPC_SOCKET_ENV.starts_with("REVERIE_SABRE_"));
}
#[test]
#[cfg(feature = "sabre")]
fn sabre_stages_program_names_that_collide_with_loader_prefix() {
assert!(sabre_program_needs_neutral_name(
PathBuf::from("/usr/bin/ld").as_path()
));
assert!(sabre_program_needs_neutral_name(
PathBuf::from("/usr/bin/ld.bfd").as_path()
));
assert!(!sabre_program_needs_neutral_name(
PathBuf::from("/usr/bin/gold").as_path()
));
}
#[test]
#[cfg(feature = "sabre")]
fn sabre_neutral_name_staging_preserves_program_bytes_and_cleans_up() {
let temp = tempfile::tempdir().unwrap();
let program = temp.path().join("ld.test");
fs::write(&program, b"linker image").unwrap();
let staged = stage_sabre_program_in(&program, temp.path())
.unwrap()
.expect("ld-prefixed program should be staged");
let staged_path = staged.path.clone();
assert_eq!(fs::read(&staged_path).unwrap(), b"linker image");
assert!(
staged_path
.file_name()
.unwrap()
.as_encoded_bytes()
.starts_with(b"hermit-sabre-program-")
);
drop(staged);
assert!(!staged_path.exists());
}
#[tokio::test(start_paused = true)]
#[cfg(feature = "sabre")]
async fn sabre_rpc_disconnect_wait_observes_delayed_release() {
let global = Arc::new(());
let connection = global.clone();
tokio::spawn(async move {
tokio::time::sleep(Duration::from_millis(10)).await;
drop(connection);
});
assert_eq!(
wait_for_sabre_rpc_disconnects(&global, Duration::from_millis(50)).await,
Ok(())
);
}
#[tokio::test(start_paused = true)]
#[cfg(feature = "sabre")]
async fn sabre_rpc_disconnect_wait_reports_stuck_connection() {
let global = Arc::new(());
let _connection = global.clone();
assert_eq!(
wait_for_sabre_rpc_disconnects(&global, Duration::from_millis(10)).await,
Err(1)
);
}
#[tokio::test]
#[cfg(feature = "sabre")]
async fn sabre_rpc_server_intentional_abort_is_clean() {
let server_task = tokio::spawn(std::future::pending::<Result<(), &'static str>>());
assert!(stop_sabre_rpc_server(server_task).await.is_ok());
}
#[tokio::test]
#[cfg(feature = "sabre")]
async fn sabre_rpc_server_failure_is_reported() {
let server_task = tokio::spawn(async { Err::<(), _>("accept failed") });
while !server_task.is_finished() {
tokio::task::yield_now().await;
}
let error = stop_sabre_rpc_server(server_task).await.unwrap_err();
assert!(error.to_string().contains("accept failed"));
}
#[tokio::test(start_paused = true)]
#[cfg(feature = "sabre")]
async fn sabre_rpc_shutdown_drains_connections_after_server_failure() {
let global = Arc::new(());
let connection = global.clone();
tokio::spawn(async move {
tokio::time::sleep(Duration::from_millis(10)).await;
drop(connection);
});
let server_task = tokio::spawn(async { Err::<(), _>("accept failed") });
while !server_task.is_finished() {
tokio::task::yield_now().await;
}
let error = shutdown_sabre_rpc(server_task, &global, Duration::from_millis(50))
.await
.unwrap_err();
assert!(error.to_string().contains("accept failed"));
assert_eq!(Arc::strong_count(&global), 1);
}
#[test]
#[cfg(feature = "sabre")]
fn sabre_binary_resolver_finds_cargo_target_build() {
let temp = tempfile::tempdir().unwrap();
let executable = temp.path().join("target/release/hermit");
let loader = temp.path().join("target/sabre/sabre");
write_test_executable(&loader);
assert_eq!(
resolve_sabre_binary_from(None, None, &executable, OsStr::new("")).unwrap(),
loader
);
}
#[test]
#[cfg(feature = "sabre")]
fn sabre_binary_resolver_uses_packaged_loader() {
let temp = tempfile::tempdir().unwrap();
let executable = temp.path().join("target/release/hermit");
let packaged = temp.path().join("install_pkg/rsrcs/sabre");
write_test_executable(&packaged);
assert_eq!(
resolve_sabre_binary_from(None, Some(&packaged), &executable, OsStr::new("")).unwrap(),
packaged
);
}
#[test]
#[cfg(feature = "sabre")]
fn sabre_binary_resolver_prefers_and_validates_override() {
let temp = tempfile::tempdir().unwrap();
let executable = temp.path().join("target/release/hermit");
let discovered = temp.path().join("target/sabre/sabre");
let requested = temp.path().join("requested-sabre");
write_test_executable(&discovered);
write_test_executable(&requested);
assert_eq!(
resolve_sabre_binary_from(
Some(requested.as_os_str()),
Some(&discovered),
&executable,
OsStr::new(""),
)
.unwrap(),
requested
);
let mut permissions = fs::metadata(&requested).unwrap().permissions();
permissions.set_mode(0o600);
fs::set_permissions(&requested, permissions).unwrap();
let error = resolve_sabre_binary_from(
Some(requested.as_os_str()),
Some(&discovered),
&executable,
OsStr::new(""),
)
.unwrap_err();
assert!(error.to_string().contains("is not an executable file"));
}
#[test]
#[cfg(feature = "dbt")]
fn optional_backends_report_accurate_availability() {
match Backend::Dbt.ensure_available() {
Ok(()) => assert!(
dynamorio_sdk_available() && dbt_runtime_unavailable_reason().is_none(),
"DBT reported available without its SDK and runtime"
),
Err(dbt_error) => {
let message = dbt_error.to_string();
assert!(
message.contains("DynamoRIO runtime")
|| message.contains("Detcore DBT runtime"),
"unexpected DBT availability error: {message}"
);
}
}
assert_eq!(
Backend::Liteinst.ensure_available().is_ok(),
liteinst_unavailable_reason().is_none()
);
assert_eq!(
Backend::InGuestTrap.ensure_available().is_ok(),
liteinst_unavailable_reason().is_none()
);
match Backend::Kvm.ensure_available() {
Ok(()) => assert!(
kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_none(),
"KVM reported available without a usable /dev/kvm",
),
Err(kvm_error) => {
let message = kvm_error.to_string();
assert!(
message.contains("/dev/kvm"),
"unexpected KVM availability error: {message}",
);
assert!(!message.contains("requires root privileges"));
}
}
}
#[test]
fn public_backend_dispatch_rejects_unprepared_e9patch() {
let error = ensure_backend_dispatch(Backend::E9patch).unwrap_err();
assert!(
error.to_string().contains("requires CLI preprocessing"),
"unexpected error: {error}"
);
}
#[test]
#[cfg(feature = "dbt")]
fn dbt_retries_only_the_pre_guest_bootstrap_failure() {
use std::os::unix::process::ExitStatusExt as _;
let failure = std::process::ExitStatus::from_raw(
reverie_dbt::CLIENT_THREAD_START_FAILURE_EXIT_CODE << 8,
);
assert!(super::dbt_client_thread_start_failed(&failure));
assert!(!super::dbt_client_thread_start_failed(
&std::process::ExitStatus::from_raw(1 << 8)
));
}
#[test]
#[cfg(feature = "dbt")]
fn dbt_public_dispatch_requires_sequentialized_threads() {
let command = super::Command::new("/bin/true");
let config = super::DetConfig {
sequentialize_threads: false,
..Default::default()
};
let error = super::run_with_output_backend(command, config, false, &None, Backend::Dbt)
.expect_err("DBT must reject non-sequentialized execution");
assert!(
error
.to_string()
.contains("dbt backend requires sequentialized threads"),
"unexpected error: {error}"
);
}
#[test]
#[cfg(feature = "dbt")]
fn dbt_public_dispatch_runs_echo_through_detcore() {
use clap::Parser;
if Backend::Dbt.ensure_available().is_err() {
return;
}
const CHILD: &str = "HERMIT_TEST_DBT_LIBRARY_DIAGNOSTICS_CHILD";
if std::env::var_os(CHILD).is_none() {
let output = std::process::Command::new(std::env::current_exe().unwrap())
.args([
"--exact",
"tests::dbt_public_dispatch_runs_echo_through_detcore",
"--nocapture",
])
.env(CHILD, "1")
.output()
.expect("run isolated DBT library output checks");
let diagnostics = String::from_utf8_lossy(&output.stderr);
assert!(output.status.success(), "{output:?}");
assert!(
diagnostics
.lines()
.filter(|line| line.starts_with("reverie-dbt: tool=Detcore "))
.count()
>= 2,
"DBT native summaries did not prove both Detcore dispatches: {diagnostics}"
);
assert!(!diagnostics.contains("guest-stderr"), "{diagnostics}");
return;
}
let mut command = super::Command::new("/bin/echo");
command.arg("hello");
let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
config.sequentialize_threads = true;
config.validate();
let output = super::run_with_output_backend(command, config, true, &None, Backend::Dbt)
.expect("run /bin/echo through DbtGuest<Detcore>");
assert_eq!(
output.status,
super::ExitStatus::Exited(0),
"guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
String::from_utf8_lossy(&output.stderr),
String::from_utf8_lossy(&output.stdout),
);
assert_eq!(output.stdout, b"hello\n");
assert_eq!(output.stderr, b"");
let mut command = super::Command::new("/bin/sh");
command.args(["-c", "printf 'guest-stderr\\n' >&2"]);
let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
config.sequentialize_threads = true;
config.validate();
let output = super::run_with_output_backend(command, config, true, &None, Backend::Dbt)
.expect("capture nonempty guest stderr through DbtGuest<Detcore>");
assert_eq!(output.status, super::ExitStatus::Exited(0), "{output:?}");
assert_eq!(output.stdout, b"");
assert_eq!(output.stderr, b"guest-stderr\n");
}
#[test]
#[cfg(feature = "dbt")]
fn dbt_public_status_dispatch_runs_true_through_detcore() {
use clap::Parser;
if Backend::Dbt.ensure_available().is_err() {
return;
}
let command = super::Command::new("/bin/true");
let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
config.sequentialize_threads = true;
config.validate();
let status = super::run_with_backend(command, config, true, &None, Backend::Dbt)
.expect("run /bin/true through DbtGuest<Detcore>");
assert_eq!(status, super::ExitStatus::Exited(0));
}
#[test]
fn kvm_runs_dynamic_echo_through_detcore() {
use clap::Parser;
if kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_some() {
return;
}
let mut command = super::Command::new("/bin/echo");
command.arg("hello");
let mut config = super::DetConfig::parse_from(["hermit-kvm-test"]);
config.validate();
let output = super::run_with_output_backend(command, config, false, &None, Backend::Kvm)
.expect("run dynamic /bin/echo through KvmGuest<Detcore>");
assert_eq!(
output.status,
super::ExitStatus::Exited(0),
"guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
String::from_utf8_lossy(&output.stderr),
String::from_utf8_lossy(&output.stdout),
);
assert_eq!(output.stdout, b"hello\n");
assert!(output.stderr.is_empty());
}
#[test]
fn detcore_drives_kvm_guest_for_synthetic_syscall() {
use clap::Parser;
const MEMORY_SIZE: usize = 0x10_000;
const ENTRY_POINT: u64 = 0x1000;
const FRAME_ADDRESS: u64 = 0x2000;
let mut backend = match reverie_kvm::KvmBackend::new(MEMORY_SIZE) {
Ok(backend) => backend,
Err(error) => {
eprintln!("skipping KVM Detcore experiment: cannot init VM: {error}");
return;
}
};
backend
.install_syscall(
ENTRY_POINT,
FRAME_ADDRESS,
reverie_kvm::SyscallRequest::new(libc::SYS_getpid as u64, [0; 6]),
)
.expect("install synthetic getpid guest");
let mut config =
super::DetConfig::parse_from(["hermit-kvm-test", "--max-timeslice=disabled"]);
config.validate();
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("build tokio runtime");
let outcome = runtime.block_on(async {
backend
.run_with_tool::<super::Detcore, _>(
config,
|request: &reverie_kvm::SyscallRequest, _memory: &reverie_kvm::GuestMemory| {
unsafe {
libc::syscall(
request.number() as libc::c_long,
request.args()[0],
request.args()[1],
request.args()[2],
request.args()[3],
request.args()[4],
request.args()[5],
) as i64
}
},
)
.await
});
outcome.expect("Detcore drove the synthetic KVM guest to completion");
}
const FAKE_ELF: &[u8] = b"\x7fELF\x02\x01\x01\x00 fake elf body";
fn shebang_tmpdir(tag: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!(
"hermit-shebang-test-{}-{}",
std::process::id(),
tag
));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
dir
}
#[test]
fn resolve_shebang_plain_elf_is_unchanged() {
let dir = shebang_tmpdir("plain");
let prog = dir.join("prog");
fs::write(&prog, FAKE_ELF).unwrap();
let argv = vec!["prog".to_owned(), "-a".to_owned()];
let (path, out_argv, image) = resolve_kvm_shebang(&prog, argv).unwrap();
assert_eq!(path, prog);
assert_eq!(out_argv, vec!["prog".to_owned(), "-a".to_owned()]);
assert_eq!(image, FAKE_ELF);
fs::remove_dir_all(&dir).unwrap();
}
#[test]
fn resolve_shebang_single_level_kernel_order() {
let dir = shebang_tmpdir("single");
let interp = dir.join("fakebash");
fs::write(&interp, FAKE_ELF).unwrap();
let script = dir.join("script");
fs::write(&script, format!("#!{} -x\necho hi\n", interp.display())).unwrap();
let argv = vec!["script".to_owned(), "arg1".to_owned()];
let (path, out_argv, image) = resolve_kvm_shebang(&script, argv).unwrap();
assert_eq!(path, interp);
assert_eq!(
out_argv,
vec![
interp.to_string_lossy().into_owned(),
"-x".to_owned(),
script.to_string_lossy().into_owned(),
"arg1".to_owned(),
]
);
assert_eq!(image, FAKE_ELF);
fs::remove_dir_all(&dir).unwrap();
}
#[test]
fn resolve_shebang_nested_accumulates_like_binfmt_script() {
let dir = shebang_tmpdir("nested");
let interp = dir.join("fakebash");
fs::write(&interp, FAKE_ELF).unwrap();
let mid = dir.join("mid"); fs::write(&mid, format!("#!{}\n", interp.display())).unwrap();
let script = dir.join("script");
fs::write(&script, format!("#!{} -e\n", mid.display())).unwrap();
let argv = vec!["script".to_owned(), "arg1".to_owned()];
let (path, out_argv, image) = resolve_kvm_shebang(&script, argv).unwrap();
assert_eq!(path, interp);
assert_eq!(
out_argv,
vec![
interp.to_string_lossy().into_owned(),
mid.to_string_lossy().into_owned(),
"-e".to_owned(),
script.to_string_lossy().into_owned(),
"arg1".to_owned(),
]
);
assert_eq!(image, FAKE_ELF);
fs::remove_dir_all(&dir).unwrap();
}
#[test]
fn resolve_shebang_rejects_infinite_recursion() {
let dir = shebang_tmpdir("loop");
let a = dir.join("a");
let b = dir.join("b");
fs::write(&a, format!("#!{}\n", b.display())).unwrap();
fs::write(&b, format!("#!{}\n", a.display())).unwrap();
let argv = vec!["a".to_owned()];
assert!(resolve_kvm_shebang(&a, argv).is_err());
fs::remove_dir_all(&dir).unwrap();
}
mod reverie_pin_reader {
include!("../reverie_pin.rs");
const A: &str = "1111111111111111111111111111111111111111";
const B: &str = "2222222222222222222222222222222222222222";
fn dep(rev: &str) -> String {
format!(
"reverie = {{ git = \"https://github.com/rrnewton/reverie.git\", rev = \"{rev}\" }}\n"
)
}
#[test]
fn a_single_revision_is_read() {
assert_eq!(parse_reverie_pin(&dep(A)).as_deref(), Some(A));
}
#[test]
fn agreeing_revisions_are_read_once() {
let text = format!("{}{}", dep(A), dep(A));
assert_eq!(parse_reverie_pin(&text).as_deref(), Some(A));
}
#[test]
fn disagreeing_revisions_are_refused() {
let text = format!("{}{}", dep(A), dep(B));
assert_eq!(parse_reverie_pin(&text), None);
}
#[test]
fn a_commented_out_dependency_is_not_the_pin() {
let text = format!("# {}{}", dep(B), dep(A));
assert_eq!(
parse_reverie_pin(&text).as_deref(),
Some(A),
"a commented-out revision must not win"
);
}
#[test]
fn a_manifest_naming_no_revision_yields_none() {
assert_eq!(parse_reverie_pin("[dependencies]\nlibc = \"0.2\"\n"), None);
}
#[test]
fn an_unparseable_revision_is_ambiguous() {
let text = format!(
"{}reverie-x = {{ git = \"https://github.com/rrnewton/reverie.git\", rev = \"beef\" }}\n",
dep(A)
);
assert_eq!(parse_reverie_pin(&text), None);
}
}
#[cfg(feature = "sabre")]
#[test]
fn sabre_detlog_forwarding_answers_each_target_as_the_cli_filter_does() {
use detcore::detlog::ForwardPolicy;
use detcore::detlog::info_enabled_for_target;
use tracing::level_filters::LevelFilter;
use tracing_subscriber::layer::SubscriberExt;
use crate::liteinst_bootstrap::EffectiveFilter;
let targets = [
"",
"detcore",
"detcore::random",
"detcore::randomness",
"detcore::tool_local",
"detcore::scheduler",
"detcore::scheduler::runqueue",
"detcore::syscalls::files",
"hermit",
"warn",
];
let policy_under = |raw: &str, level: LevelFilter| {
let subscriber = tracing_subscriber::registry()
.with(EffectiveFilter::from_directives_lossy(raw, level).into_filter());
tracing::subscriber::with_default(subscriber, || {
let policy = ForwardPolicy::from_current_subscriber(raw);
let subscriber_says: Vec<bool> = targets
.iter()
.map(|target| info_enabled_for_target(target))
.collect();
(policy, subscriber_says)
})
};
for (raw, level) in [
("warn,detcore::random=info", LevelFilter::WARN),
("detcore::random=info", LevelFilter::WARN),
("detcore::random=warn", LevelFilter::INFO),
(
"warn,detcore=info,detcore::scheduler=off",
LevelFilter::WARN,
),
(
"warn,detcore[work]=info,detcore::random=info",
LevelFilter::WARN,
),
("", LevelFilter::INFO),
("", LevelFilter::WARN),
] {
let (policy, subscriber_says) = policy_under(raw, level);
for (target, enabled) in targets.iter().zip(subscriber_says) {
assert_eq!(
policy.forwards(target),
enabled,
"RUST_LOG={raw:?} --log={level}: policy {policy:?} disagrees on {target:?}"
);
}
}
let (scoped, subscriber_says) =
policy_under("warn,detcore::random=info", LevelFilter::WARN);
assert!(!subscriber_says[1], "the generic detcore target is off");
assert!(scoped.forwards_any());
assert!(scoped.forwards("detcore::random"));
assert!(!scoped.forwards("detcore::tool_local"));
assert_eq!(policy_under("", LevelFilter::INFO).0, ForwardPolicy::all());
assert!(!policy_under("", LevelFilter::WARN).0.forwards_any());
}
#[cfg(feature = "liteinst")]
#[test]
fn liteinst_launch_hands_the_guest_its_per_target_policy() {
use std::os::fd::AsRawFd;
use detcore::detlog::ForwardPolicy;
use detcore::in_guest_launch::InGuestLaunch;
use reverie::process::Command;
use super::LITEINST_DETLOG_FORWARD_ENV;
use super::LITEINST_DETLOG_FORWARD_POLICY_ENV;
use super::forward_in_guest_detlogs_to;
use super::in_guest_liteinst_launch;
let (sink, _peer) = std::os::unix::net::UnixDatagram::pair().unwrap();
forward_in_guest_detlogs_to(sink.into());
let removed = |command: &Command| {
[
LITEINST_DETLOG_FORWARD_ENV,
LITEINST_DETLOG_FORWARD_POLICY_ENV,
detcore::LITEINST_CONFIG_FINGERPRINT_ENV,
]
.into_iter()
.all(|key| {
command
.get_envs()
.any(|(name, value)| name == std::ffi::OsStr::new(key) && value.is_none())
})
};
let scoped = ForwardPolicy::decode("0,detcore::random=1").unwrap();
let mut command = Command::new("/bin/true");
let (launch, duplicate) = in_guest_liteinst_launch(&mut command, &scoped).unwrap();
let duplicate = duplicate.expect("a policy that forwards a target requests forwarding");
assert!(removed(&command));
let launch = InGuestLaunch::decode(&launch.encode()).unwrap();
let passed = launch.forward_request.expect("the descriptor is passed");
assert_eq!(
detcore::detlog::tool_output_env_target(&passed),
Some(duplicate.as_raw_fd()),
"{passed}"
);
let sent =
ForwardPolicy::decode(&launch.forward_policy.expect("the policy goes too")).unwrap();
assert_eq!(sent, scoped);
assert!(sent.forwards("detcore::random"));
assert!(!sent.forwards("detcore::tool_local"));
assert_eq!(
launch.coordinator_fingerprint,
Some(detcore::config_wire_fingerprint())
);
let nothing = ForwardPolicy::decode("0").unwrap();
let mut command = Command::new("/bin/true");
command
.env(LITEINST_DETLOG_FORWARD_ENV, "9")
.env(LITEINST_DETLOG_FORWARD_POLICY_ENV, "1")
.env(detcore::LITEINST_CONFIG_FINGERPRINT_ENV, "0000000000000000");
let (launch, duplicate) = in_guest_liteinst_launch(&mut command, ¬hing).unwrap();
assert!(duplicate.is_none());
assert!(removed(&command));
assert_eq!(launch.forward_request, None);
assert_eq!(launch.forward_policy, None);
}
#[test]
fn detlog_forward_policy_matches_real_detlog_emission_under_field_filters() {
use std::sync::Arc;
use std::sync::atomic::AtomicUsize;
use std::sync::atomic::Ordering;
use detcore::detlog::ForwardPolicy;
use tracing::level_filters::LevelFilter;
use tracing_subscriber::layer::SubscriberExt;
use crate::liteinst_bootstrap::EffectiveFilter;
struct Count(Arc<AtomicUsize>);
impl<S: tracing::Subscriber> tracing_subscriber::Layer<S> for Count {
fn on_event(
&self,
_event: &tracing::Event<'_>,
_context: tracing_subscriber::layer::Context<'_, S>,
) {
self.0.fetch_add(1, Ordering::Relaxed);
}
}
let module = module_path!();
for (raw, level) in [
(format!("info,{module}[{{unused}}]=warn"), LevelFilter::INFO),
(
format!("warn,{module}[{{unused}}]=trace"),
LevelFilter::WARN,
),
(
format!("info,{module}[{{message}}]=warn"),
LevelFilter::INFO,
),
(format!("info,{module}=warn"), LevelFilter::INFO),
(format!("warn,{module}=info"), LevelFilter::WARN),
("info".to_owned(), LevelFilter::INFO),
("warn".to_owned(), LevelFilter::WARN),
] {
let emitted = Arc::new(AtomicUsize::new(0));
let subscriber = tracing_subscriber::registry()
.with(EffectiveFilter::from_directives_lossy(&raw, level).into_filter())
.with(Count(emitted.clone()));
let forwards = tracing::subscriber::with_default(subscriber, || {
detcore::detlog!("probe record");
ForwardPolicy::from_current_subscriber(&raw).forwards(module)
});
assert_eq!(
forwards,
emitted.load(Ordering::Relaxed) == 1,
"RUST_LOG={raw:?} --log={level}: the policy and a real detlog! disagree"
);
}
}
}