use std::collections::hash_map::DefaultHasher;
use std::ffi::OsStr;
use std::fmt;
use std::fs;
use std::fs::File;
use std::fs::OpenOptions;
use std::hash::Hash;
use std::hash::Hasher;
use std::io::Read;
use std::io::Write;
use std::num::NonZeroU64;
use std::os::unix::ffi::OsStrExt;
use std::os::unix::fs::PermissionsExt;
use std::path::Path;
use std::path::PathBuf;
use std::str::FromStr;
use std::sync::LazyLock;
use std::time::Duration;
use std::time::SystemTime;
use clap::Parser;
use colored::Colorize;
use detcore_model::backend_engagement::BackendEngagement;
use detcore_model::backend_engagement::BackendEngagementReport;
use detcore_model::happens_before::HappensBeforeProgram;
use detcore_model::happens_before::Strength;
use detcore_model::summary::RunSummary;
use hermit::Backend;
use hermit::Context;
use hermit::DetConfig;
use hermit::Error;
use hermit::LITEINST_IN_GUEST_ENV;
use hermit::LiteinstRuntime;
use hermit::Shebang;
use hermit::SkidOvershootError;
use hermit::happens_before::DebugInfoResolver;
use hermit::happens_before::describe_anchor;
use hermit::happens_before::load_program;
use hermit::happens_before::resolve_program;
use hermit::run_evidence::GuestRunDeterminism;
use reverie::Errno;
use reverie::process::Bind;
use reverie::process::Command;
use reverie::process::Container;
use reverie::process::ExitStatus;
use reverie::process::Mount;
use reverie::process::MountFlags;
use reverie::process::Namespace;
use reverie::process::Output;
use super::container::IdentityGuard;
use super::container::PolicyRefusal;
use super::container::apply_affinity;
use super::container::default_container;
use super::container::identity_hardening_mounts;
use super::container::image_container;
use super::global_opts::GlobalOpts;
use super::guest_capture::GuestRunCapturePaths;
use super::guest_capture::GuestRunCaptureSession;
use super::record_envelope::RecordEnvelope;
use super::tracing::BoundedWriter;
use super::tracing::init_sync_file_tracing;
use super::tracing::log_max_bytes;
use super::verify::ComparedRun;
use super::verify::ComparisonOptions;
use super::verify::LogCompareStrictness;
use super::verify::NoResultReason;
use super::verify::SecondRun;
use super::verify::VerificationReport;
use super::verify::VerificationRun;
use super::verify::VerificationRuntime;
use super::verify::announce_verification_outcome;
use super::verify::compare_two_runs;
use super::verify::default_failed_verify_log_retention;
use super::verify::emit_compared_guest_output;
use super::verify::retain_logs_after_verification_error;
use super::verify::retain_verification_error;
use super::verify::retain_verification_logs;
use super::verify::run_verification_execution;
use super::verify::temp_log_files_in;
use super::verify::validate_log_level;
use super::verify::verification_log_level;
use super::verify::verification_runtime_from_summaries;
use super::verify::write_pending_verification_json;
use super::verify::write_report_json;
use super::verify::write_skid_overshoot_verification_json;
use super::verify::write_skid_overshoot_without_comparison_json;
use super::verify::write_verification_json;
const TMP_DIR: &str = "/tmp";
const FAIL_CLOSED_ENV: &str = "HERMIT_FAIL_CLOSED";
const NORMALIZED_SABRE_DETLOG_TIMESTAMP: &str = "1970-01-01T00:00:00.000000Z";
fn contains_bytes(haystack: &[u8], needle: &[u8]) -> bool {
haystack
.windows(needle.len())
.any(|window| window == needle)
}
fn read_verify_summary(path: &Path) -> Option<RunSummary> {
match fs::read(path)
.with_context(|| format!("reading verification run summary {}", path.display()))
.and_then(|bytes| {
serde_json::from_slice(&bytes)
.with_context(|| format!("parsing verification run summary {}", path.display()))
}) {
Ok(summary) => Some(summary),
Err(error) => {
eprintln!("WARNING: verification runtime statistics unavailable: {error:#}");
None
}
}
}
fn first_run_rejected_report(
output: &Output,
runtime: Option<VerificationRuntime>,
) -> VerificationReport {
let mut report = VerificationReport::no_result();
report.no_result_reason = Some(NoResultReason::FirstRunRejected {
exit_code: output.status.code(),
signal: output.status.signal(),
stdout_bytes: u64::try_from(output.stdout.len()).expect("guest stdout length fits u64"),
stderr_bytes: u64::try_from(output.stderr.len()).expect("guest stderr length fits u64"),
});
report.guest_exit_code = output.status.code();
report.guest_signal = output.status.signal();
report.runtime = runtime;
report
}
fn private_summary_dir() -> Result<PathBuf, Error> {
summary_dir_under(&std::env::current_dir()?)
}
fn disposable_dir_is_ignored(root: &Path) -> bool {
let Ok(text) = std::fs::read_to_string(root.join(".gitignore")) else {
return false;
};
text.lines()
.map(|line| line.split('#').next().unwrap_or_default().trim())
.any(|rule| matches!(rule, "ignored/" | "/ignored/" | "ignored" | "/ignored"))
}
fn summary_dir_under(start: &Path) -> Result<PathBuf, Error> {
let mut root = start;
loop {
if root.join(".git").exists() && disposable_dir_is_ignored(root) {
let disposable = root.join("ignored");
std::fs::create_dir_all(&disposable).with_context(|| {
format!(
"creating the disposable run-summary directory {}; refusing to fall back to \
the work tree, where this file would be counted as prepared source",
disposable.display()
)
})?;
return Ok(disposable);
}
match root.parent() {
Some(parent) => root = parent,
None => break,
}
}
Ok(start.to_path_buf())
}
fn private_summary_descriptor_path(file: &tempfile::NamedTempFile) -> PathBuf {
use std::os::fd::AsRawFd;
PathBuf::from(format!("/proc/self/fd/{}", file.as_file().as_raw_fd()))
}
fn private_verify_summary() -> Result<tempfile::NamedTempFile, Error> {
tempfile::Builder::new()
.prefix(".hermit-verify-summary-")
.tempfile_in(private_summary_dir()?)
.context("creating private verification run summary")
}
fn private_backend_engagement_summary() -> Result<tempfile::NamedTempFile, Error> {
tempfile::Builder::new()
.prefix(".hermit-backend-engagement-summary-")
.tempfile_in(private_summary_dir()?)
.context("creating private backend-engagement run summary")
}
fn clear_machine_record(path: &Path, description: &str) -> Result<(), Error> {
match fs::remove_file(path) {
Ok(()) => Ok(()),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
Err(error) => Err(error)
.with_context(|| format!("clearing stale {description} record {}", path.display())),
}
}
fn write_backend_engagement(path: &Path, engagement: BackendEngagement) -> Result<(), Error> {
let report = BackendEngagementReport::new(engagement);
report.validate().map_err(Error::msg)?;
let mut bytes = serde_json::to_vec(&report)?;
bytes.push(b'\n');
fs::write(path, bytes)
.with_context(|| format!("writing backend engagement record {}", path.display()))
}
fn take_verify_summary_before_next_run(path: &Path) -> Result<Option<RunSummary>, Error> {
let summary = read_verify_summary(path);
fs::write(path, b"").with_context(|| {
format!(
"resetting private verification run summary {} before run 2",
path.display()
)
})?;
Ok(summary)
}
fn extract_sabre_detlogs(path: &Path, stderr: &mut Vec<u8>) -> Result<usize, Error> {
let mut log = OpenOptions::new().append(true).open(path)?;
let mut guest_stderr = Vec::with_capacity(stderr.len());
let mut syscall_records = 0;
for line in stderr.split_inclusive(|byte| *byte == b'\n') {
let start = line
.iter()
.position(|byte| !byte.is_ascii_whitespace())
.unwrap_or(line.len());
let payload = line[start..].strip_suffix(b"\n").unwrap_or(&line[start..]);
let payload = payload.strip_suffix(b"\r").unwrap_or(payload);
if payload.starts_with(b"INFO detcore") && contains_bytes(payload, b" DETLOG ") {
log.write_all(NORMALIZED_SABRE_DETLOG_TIMESTAMP.as_bytes())?;
log.write_all(b" ")?;
log.write_all(payload)?;
log.write_all(b"\n")?;
syscall_records += usize::from(contains_bytes(payload, b"DETLOG [syscall]"));
} else {
guest_stderr.extend_from_slice(line);
}
}
*stderr = guest_stderr;
Ok(syscall_records)
}
struct PreparedMounts {
mounts: Vec<Mount>,
identity_sources: IdentityGuard,
}
#[derive(Debug, Clone)]
struct E9patchOverlay {
source: PathBuf,
target: PathBuf,
}
#[derive(Debug, Clone, Eq, PartialEq)]
enum GuestPathMapping {
Mapped(PathBuf),
Hidden,
Unchanged,
}
#[derive(Debug, Parser, Clone)]
pub(crate) struct DetOptions {
#[clap(flatten)]
pub det_config: DetConfig,
}
#[derive(Debug, Parser, Clone)]
pub struct RunOpts {
#[clap(skip)]
backend: Option<Backend>,
#[clap(value_name = "PROGRAM")]
program: PathBuf,
#[clap(value_name = "ARGS")]
args: Vec<String>,
#[clap(long, value_name = "filepath")]
happens_before: Option<PathBuf>,
#[clap(long, requires = "happens_before")]
hb_list_events: bool,
#[clap(skip)]
resolved_happens_before: Option<HappensBeforeProgram>,
#[clap(skip)]
epoch_captured_from_host: bool,
#[clap(skip)]
epoch_omitted: bool,
#[clap(skip)]
epoch_from_recording: bool,
#[clap(flatten)]
pub(crate) det_opts: DetOptions,
#[clap(
long,
conflicts_with_all = ["no_sequentialize_threads", "no_deterministic_io", "strace_only"]
)]
strict: bool,
#[clap(
long,
conflicts_with_all = ["strict", "panic_on_unsupported_syscalls"]
)]
allow_unsupported_syscalls: bool,
#[clap(long, value_name = "SECONDS")]
timeout: Option<NonZeroU64>,
#[clap(long)]
pub(crate) no_sequentialize_threads: bool,
#[clap(long)]
no_deterministic_io: bool,
#[clap(long)]
pin_threads: bool,
#[clap(long, value_name = "RCBS")]
skid_margin: Option<u64>,
#[clap(long, value_name = "path")]
mount: Vec<Mount>,
#[clap(long, value_name = "path")]
pub(crate) bind: Vec<Bind>,
#[clap(
long,
alias = "net",
value_name = "local|host",
default_value = "local"
)]
network: NetworkingMode,
#[clap(
long,
alias = "lite",
conflicts_with = "chaos",
conflicts_with = "verify"
)]
namespace_only: bool,
#[clap(
long,
visible_alias = "core-only",
conflicts_with_all = [
"mount",
"bind",
"network",
"tmp",
"namespace_only",
"analyze_networking",
"replay_schedule_from",
"replay_preemptions_from"
]
)]
no_namespace: bool,
#[clap(
long,
conflicts_with = "chaos",
conflicts_with = "namespace_only",
conflicts_with = "seed",
conflicts_with = "seed_from",
conflicts_with = "analyze_networking"
)]
strace_only: bool,
#[clap(long, value_name = "dirpath")]
tmp: Option<PathBuf>,
#[clap(long, value_name = "OCI-REFERENCE")]
image: Option<String>,
#[clap(long, value_name = "'Args'|'SystemRandom'")]
seed_from: Option<SeedFrom>,
#[clap(long)]
verify: bool,
#[clap(long, requires = "verify")]
verify_verbose: bool,
#[clap(long, requires = "verify")]
verify_strict: bool,
#[clap(long, value_name = "success|failure|both", default_value = "success")]
verify_allow: VerifyAllow,
#[clap(long = "print-verify-logs", alias = "verify-logs", requires = "verify")]
print_verify_logs: bool,
#[clap(long, requires = "verify")]
keep_logs: bool,
#[clap(long, value_name = "DIRECTORY", requires = "keep_logs")]
verify_log_dir: Option<PathBuf>,
#[clap(long, requires = "verify", value_name = "PATH")]
verify_json: Option<PathBuf>,
#[clap(long, short = 'u')]
pub(crate) summary: bool,
#[clap(long)]
pub(crate) summary_json: Option<PathBuf>,
#[clap(
long,
conflicts_with_all = ["verify", "namespace_only"],
value_name = "PATH"
)]
backend_engagement_json: Option<PathBuf>,
#[clap(
long,
conflicts_with_all = ["verify", "namespace_only"],
value_name = "NEW_PATH"
)]
run_evidence_dir: Option<PathBuf>,
#[clap(
long,
value_name = "NEW_PATH",
requires_all = ["guest_stdout", "guest_stderr", "run_evidence_dir"],
conflicts_with_all = ["verify", "namespace_only"]
)]
run_result_json: Option<PathBuf>,
#[clap(
long,
value_name = "NEW_PATH",
requires_all = ["run_result_json", "guest_stderr", "run_evidence_dir"],
conflicts_with_all = ["verify", "namespace_only"]
)]
guest_stdout: Option<PathBuf>,
#[clap(
long,
value_name = "NEW_PATH",
requires_all = ["run_result_json", "guest_stdout", "run_evidence_dir"],
conflicts_with_all = ["verify", "namespace_only"]
)]
guest_stderr: Option<PathBuf>,
#[clap(long)]
analyze_networking: bool,
#[clap(long, default_value = "host", value_name = "str")]
base_env: BaseEnv,
#[clap(short = 'e', long, value_parser = parse_assignment, value_name="name[=val]")]
env: Vec<(String, Option<String>)>,
#[clap(long, value_name = "path")]
workdir: Option<String>,
#[clap(long, value_name = "path")]
pub save_config: Option<PathBuf>,
#[clap(skip)]
e9patch_overlay: Option<E9patchOverlay>,
#[clap(skip)]
e9patch_program: Option<PathBuf>,
#[clap(skip)]
e9patch_engagement: Option<BackendEngagement>,
#[clap(skip)]
e9patch_sites: Option<reverie::SiteCounters>,
}
pub(super) fn parse_assignment(src: &str) -> Result<(String, Option<String>), Error> {
static ENV_RE: LazyLock<regex::Regex> = LazyLock::new(||
regex::Regex::new("^([\x07-<>-~]+)=([\x07-~]*)$").unwrap());
static VAR_RE: LazyLock<regex::Regex> =
LazyLock::new(|| regex::Regex::new("^([\x07-<>-~]+)$").unwrap());
if let Some(capture) = ENV_RE.captures(src) {
if let (Some(name), Some(value)) = (capture.get(1), capture.get(2)) {
Ok((name.as_str().to_owned(), Some(value.as_str().to_owned())))
} else {
anyhow::bail!("unable to parse name=value from '{}'", src)
}
} else if VAR_RE.is_match(src) {
let var: String = src.to_owned();
Ok((var, None))
} else {
anyhow::bail!("unable to parse env var name or name=value from '{}'", src)
}
}
fn apply_base_and_explicit_environment(
command: &mut Command,
base_env: &BaseEnv,
env: &[(String, Option<String>)],
) -> Result<(), Error> {
match base_env {
BaseEnv::Empty => {
command.env_clear();
}
BaseEnv::Minimal => {
command.env_clear();
command.env("HOSTNAME", "hermetic-container.local");
command.env(
"PATH",
"/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
);
command.env("HOME", "/root");
}
BaseEnv::Host => {}
}
for (name, value) in env {
if let Some(value) = value {
command.env(name, value);
} else if let Ok(value) = std::env::var(name) {
command.env(name, value);
} else {
anyhow::bail!(
"Attempt to pass through env var {}, but it is not set in the host environment",
name
);
}
}
Ok(())
}
fn disable_sanitizer_leak_detection(command: &mut Command) {
command.env("ASAN_OPTIONS", "detect_leaks=0");
command.env("LSAN_OPTIONS", "detect_leaks=0");
}
pub(super) fn apply_base_environment(
command: &mut Command,
base_env: &BaseEnv,
env: &[(String, Option<String>)],
) -> Result<(), Error> {
apply_base_and_explicit_environment(command, base_env, env)?;
disable_sanitizer_leak_detection(command);
Ok(())
}
#[derive(Debug, Default, Clone, Copy, Parser, Eq, PartialEq)]
pub enum NetworkingMode {
#[default]
Local,
Host,
}
impl NetworkingMode {
pub(crate) fn configure(self, container: &mut Container, analyze_networking: bool) {
match self {
NetworkingMode::Local => {
container.local_networking_only();
}
NetworkingMode::Host if analyze_networking => {
container.local_networking_only();
}
NetworkingMode::Host => {}
}
}
}
impl fmt::Display for NetworkingMode {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let s = match &self {
NetworkingMode::Local => "local",
NetworkingMode::Host => "host",
};
write!(f, "{}", s)
}
}
impl FromStr for NetworkingMode {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s.to_lowercase().as_str() {
"local" => Ok(NetworkingMode::Local),
"host" => Ok(NetworkingMode::Host),
_ => Err(format!("Could not parse: {:?}", s)),
}
}
}
#[derive(Debug, Clone, Copy, Parser, Eq, PartialEq)]
pub enum VerifyAllow {
Success,
Failure,
Both,
}
impl FromStr for VerifyAllow {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s.to_lowercase().as_str() {
"success" => Ok(VerifyAllow::Success),
"failure" => Ok(VerifyAllow::Failure),
"both" => Ok(VerifyAllow::Both),
_ => Err(format!("Could not parse: {:?}", s)),
}
}
}
impl VerifyAllow {
pub(crate) fn satisfies(&self, status: ExitStatus) -> bool {
match self {
VerifyAllow::Success => status == ExitStatus::SUCCESS,
VerifyAllow::Failure => status != ExitStatus::SUCCESS,
VerifyAllow::Both => true,
}
}
}
fn describe_exit_status(status: ExitStatus) -> String {
match status {
ExitStatus::Exited(code) => format!("exited with code {code}"),
ExitStatus::Signaled(signal, core_dumped) => {
let core = if core_dumped { " (core dumped)" } else { "" };
format!("terminated by signal {} ({signal:?}){core}", signal as i32)
}
}
}
#[derive(Debug, Clone, Eq, PartialEq)]
pub(super) enum BaseEnv {
Empty,
Minimal,
Host,
}
impl FromStr for BaseEnv {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s.to_lowercase().as_str() {
"empty" => Ok(BaseEnv::Empty),
"minimal" => Ok(BaseEnv::Minimal),
"host" => Ok(BaseEnv::Host),
_ => Err(format!(
"Expected Empty | Minimal | Host, could not parse: {:?}",
s
)),
}
}
}
#[derive(Debug, Clone)]
pub enum SeedFrom {
Args,
SystemRandom,
}
#[derive(Debug, Clone)]
pub struct ParseSeedFromError {
details: String,
}
impl fmt::Display for ParseSeedFromError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "{}", self.details)
}
}
impl std::error::Error for ParseSeedFromError {
fn description(&self) -> &str {
&self.details
}
}
impl FromStr for SeedFrom {
type Err = ParseSeedFromError;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s.to_lowercase().as_str() {
"args" => Ok(SeedFrom::Args),
"systemrandom" => Ok(SeedFrom::SystemRandom),
_ => Err(ParseSeedFromError {
details: format!("Expected Args | SystemRandom, could not parse: {:?}", s),
}),
}
}
}
impl fmt::Display for RunOpts {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
let mut dop = self.det_opts.det_config.clone();
dop.panic_on_unsupported_syscalls = false;
if let Some(skid_margin) = self.skid_margin {
write!(f, " --skid-margin={skid_margin}")?;
}
if self.no_sequentialize_threads {
write!(f, " --no-sequentialize-threads")?;
}
if self.no_deterministic_io {
write!(f, " --no-deterministic-io")?;
assert!(!dop.deterministic_io)
} else {
assert!(dop.deterministic_io)
}
if self.allow_unsupported_syscalls {
write!(f, " --allow-unsupported-syscalls")?;
}
if self.network != Default::default() {
write!(f, " --network={}", self.network)?;
}
if self.namespace_only {
write!(f, " --namespace-only")?;
}
if self.no_namespace {
write!(f, " --no-namespace")?;
}
if self.summary {
write!(f, " --summary")?;
}
if let Some(p) = &self.summary_json {
let s = p.to_str().expect("valid unicode path");
write!(f, " --summary-json={}", shell_words::quote(s))?;
}
if let Some(p) = &self.backend_engagement_json {
let s = p.to_str().expect("valid unicode path");
write!(f, " --backend-engagement-json={}", shell_words::quote(s))?;
}
if let Some(p) = &self.run_evidence_dir {
let s = p.to_str().expect("valid unicode path");
write!(f, " --run-evidence-dir={}", shell_words::quote(s))?;
}
for (name, path) in [
("run-result-json", self.run_result_json.as_ref()),
("guest-stdout", self.guest_stdout.as_ref()),
("guest-stderr", self.guest_stderr.as_ref()),
] {
if let Some(path) = path {
write!(
f,
" --{name}={}",
shell_words::quote(&path.to_string_lossy())
)?;
}
}
if self.analyze_networking {
write!(f, " --analyze-networking")?;
}
if self.verify {
write!(f, " --verify")?;
}
if self.verify_verbose {
write!(f, " --verify-verbose")?;
}
if self.verify_strict {
write!(f, " --verify-strict")?;
}
if self.print_verify_logs {
write!(f, " --print-verify-logs")?;
}
if self.keep_logs {
write!(f, " --keep-logs")?;
}
if let Some(p) = &self.verify_log_dir {
let s = p.to_str().expect("valid unicode path");
write!(f, " --verify-log-dir={}", shell_words::quote(s))?;
}
if let Some(p) = &self.verify_json {
let s = p.to_str().expect("valid unicode path");
write!(f, " --verify-json={}", shell_words::quote(s))?;
}
if let Some(p) = &self.tmp {
let s = p.to_str().expect("valid unicode path");
write!(f, " --tmp={}", shell_words::quote(s))?;
}
if let Some(image) = &self.image {
write!(f, " --image={}", shell_words::quote(image))?;
}
match &self.verify_allow {
VerifyAllow::Success => {} VerifyAllow::Failure => {
write!(f, " --verify-allow=failure")?;
}
VerifyAllow::Both => {
write!(f, " --verify-allow=both")?;
}
}
match &self.base_env {
BaseEnv::Empty => {
write!(f, " --base-env=empty")?;
}
BaseEnv::Minimal => {
write!(f, " --base-env=minimal")?;
}
BaseEnv::Host => {} }
for (key, m_val) in &self.env {
if let Some(val) = m_val {
write!(f, " --env={}={}", key, shell_words::quote(val))?;
} else {
write!(f, " --env={}", key)?;
}
}
if let Some(p) = &self.workdir {
write!(f, " --workdir={}", shell_words::quote(p))?;
}
if let Some(p) = &self.save_config {
let s = p.to_str().expect("valid string provided to --save-config");
write!(f, " --save-config={}", shell_words::quote(s))?;
}
if let Some(p) = &self.happens_before {
let s = p
.to_str()
.expect("valid string provided to --happens-before");
write!(f, " --happens-before={}", shell_words::quote(s))?;
}
if self.hb_list_events {
write!(f, " --hb-list-events")?;
}
for mount in &self.mount {
let mut acc = Vec::new();
if let Some(s) = &mount.get_source() {
acc.push(format!("source={}", s.display()));
}
acc.push(format!("target={}", mount.get_target().display()));
write!(f, "--mount={}", shell_words::quote(&acc.join(",")),)?;
}
for bind in &self.bind {
let src = bind.source.to_str().expect("valid unicode bind source");
let tar = bind.target.to_str().expect("valid unicode target");
if bind.source == bind.target {
write!(f, " --bind={}", shell_words::quote(src))?;
} else {
write!(
f,
" --bind={}:{}",
shell_words::quote(src),
shell_words::quote(tar)
)?;
}
}
write!(f, "{}", dop)?;
if dop.has_default_epoch() {
write!(f, " --epoch={}", dop.epoch.to_rfc3339())?;
}
write!(
f,
" -- {}",
shell_words::quote(self.program.to_str().expect("valid unicode path"))
)?;
if !self.args.is_empty() {
write!(f, " {}", shell_words::join(&self.args))?;
}
Ok(())
}
}
fn is_vmm_program(program: &Path) -> bool {
program
.file_name()
.and_then(|name| name.to_str())
.is_some_and(|name| name.starts_with("qemu-system-"))
}
fn emulator_uses_instruction_count_clock(args: &[String]) -> bool {
args.iter()
.any(|arg| arg == "-icount" || arg.starts_with("-icount="))
}
fn vmm_time_virtualization_warning(
program: &Path,
args: &[String],
virtualize_time: bool,
) -> Option<String> {
if virtualize_time && is_vmm_program(program) && !emulator_uses_instruction_count_clock(args) {
Some(format!(
"WARNING: {} looks like a hardware emulator (VMM). Hermit's host-time \
virtualization exposes mutually inconsistent clock sources (a synthetic RDTSC \
versus a virtualized clock_gettime) to the emulated guest, which can corrupt its \
clock calibration (for example \"Unable to calibrate against PIT\", TSC marked \
unstable, or \"No current clocksource\") and stall boot. Two routes were measured \
to reach a booted guest: give the emulator a single instruction-derived clock \
(for QEMU: -icount shift=0,sleep=off), or pass no_timer_check on the nested \
guest's kernel command line. Note that -icount forecloses multi-threaded TCG, \
which QEMU refuses to combine with it. See docs/QEMU_BOOT.md.",
program.display()
))
} else {
None
}
}
#[test]
fn vmm_time_warning_fires_for_qemu_with_virtual_time() {
for program in [
"qemu-system-x86_64",
"/usr/bin/qemu-system-x86_64",
"qemu-system-aarch64",
] {
let warning = vmm_time_virtualization_warning(Path::new(program), &[], true);
let message = warning
.unwrap_or_else(|| panic!("expected a warning for {program} under virtual time"));
assert!(message.contains("-icount"));
assert!(message.contains("no_timer_check"));
}
}
#[test]
fn vmm_time_warning_does_not_recommend_disabling_virtual_time() {
let message = vmm_time_virtualization_warning(Path::new("qemu-system-x86_64"), &[], true)
.expect("expected a warning under virtual time");
assert!(
!message.contains("--no-virtualize-time"),
"the advisory must not recommend --no-virtualize-time: measured 2026-08-21, it leaves \
the guest panicking in timer setup with a byte-identical console, and combined with \
--strict it aborts the run before the guest starts. Message was: {message}"
);
assert!(
!message.contains("--no-virtualize-metadata"),
"same: --no-virtualize-metadata is half of a route that does not work. Message was: \
{message}"
);
}
#[test]
fn vmm_time_warning_silent_when_the_emulator_already_uses_icount() {
for args in [
vec!["-icount".to_string(), "shift=0,sleep=off".to_string()],
vec!["-icount=shift=0,sleep=off".to_string()],
vec![
"-nographic".to_string(),
"-icount".to_string(),
"shift=auto".to_string(),
],
] {
assert!(
vmm_time_virtualization_warning(Path::new("qemu-system-x86_64"), &args, true).is_none(),
"the emulator already uses the instruction-derived clock this advisory \
recommends, so there is nothing left to act on: {args:?}"
);
}
}
#[test]
fn vmm_time_warning_still_fires_for_arguments_that_only_resemble_icount() {
for args in [
vec!["-no-icount".to_string()],
vec!["--icount".to_string()],
vec!["-append".to_string(), "icount=1".to_string()],
vec!["-drive".to_string(), "file=icount.qcow2".to_string()],
] {
assert!(
vmm_time_virtualization_warning(Path::new("qemu-system-x86_64"), &args, true).is_some(),
"these do not enable QEMU's instruction-derived clock, so the advisory still \
applies: {args:?}"
);
}
}
#[test]
fn vmm_time_warning_silent_without_virtual_time() {
assert!(
vmm_time_virtualization_warning(Path::new("qemu-system-x86_64"), &[], false).is_none(),
"no warning is expected once virtual time is disabled"
);
}
#[test]
fn vmm_time_warning_silent_for_non_vmm_programs() {
for program in ["ls", "/bin/echo", "qemu-img", "my-qemu-wrapper"] {
assert!(
vmm_time_virtualization_warning(Path::new(program), &[], true).is_none(),
"unexpected VMM warning for {program}"
);
}
}
#[cfg(test)]
fn run_opts_for(argv: &[&str]) -> RunOpts {
let args = crate::Args::try_parse_from(argv)
.unwrap_or_else(|error| panic!("{argv:?} should parse: {error}"));
let crate::Subcommand::Run(mut run) = args.command else {
panic!("{argv:?} is not a `run` command");
};
run.backend = args.global.backend;
*run
}
#[test]
fn display_runopts1() {
let vec: Vec<&str> = vec!["fakehermit", "fakeprog", "arg1", "arg2"];
let mut ro = RunOpts::parse_from(vec.iter());
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(
format!("{}", ro),
" --epoch=2026-01-01T00:00:00+00:00 -- fakeprog arg1 arg2"
);
}
#[test]
fn backend_defaults_to_ptrace() {
let mut ro = RunOpts::parse_from(["fakehermit", "fakeprog"]);
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(ro.backend, None);
assert_eq!(ro.selected_backend(), Backend::Ptrace);
assert_eq!(
format!("{}", ro),
" --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
#[test]
fn backend_values_parse_and_round_trip() {
for (value, expected) in [
("ptrace", Backend::Ptrace),
("dbt", Backend::Dbt),
("liteinst", Backend::Liteinst),
("sabre", Backend::Sabre),
("kvm", Backend::Kvm),
("e9patch", Backend::E9patch),
] {
let mut ro = run_opts_for(&["hermit", "--backend", value, "run", "fakeprog"]);
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(ro.backend, Some(expected));
assert_eq!(ro.selected_backend(), expected);
assert_eq!(ro.global_backend_arg(), format!(" --backend={value}"));
assert_eq!(
format!("{}", ro),
" --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
}
#[test]
fn comparator_choice_does_not_depend_on_the_backend() {
for (value, backend) in [
("ptrace", Backend::Ptrace),
("dbt", Backend::Dbt),
("liteinst", Backend::Liteinst),
("sabre", Backend::Sabre),
("kvm", Backend::Kvm),
("e9patch", Backend::E9patch),
] {
let plain = run_opts_for(&["hermit", "--backend", value, "run", "--verify", "fakeprog"]);
assert_eq!(plain.selected_backend(), backend);
assert_eq!(
plain.verification_strictness(),
LogCompareStrictness::Stripped,
"plain --verify on {value} must stay on the lossy comparator, so it \
cannot claim canonical bitwise parity"
);
for flag in ["--verify-strict", "--verify-verbose"] {
let canonical = run_opts_for(&[
"hermit",
"--backend",
value,
"run",
"--verify",
flag,
"fakeprog",
]);
assert_eq!(
canonical.verification_strictness(),
LogCompareStrictness::Canonical,
"{flag} on {value} must reach the canonical comparator; KVM \
bypassing it unconditionally was the hermit#2217 defect"
);
}
}
}
#[test]
fn verification_always_compares_retained_logs() {
for backend in ["ptrace", "dbt", "liteinst", "sabre", "kvm", "e9patch"] {
let run = run_opts_for(&[
"hermit",
"--backend",
backend,
"run",
"--verify",
"fakeprog",
]);
assert!(
run.verification_comparison_options().compare_logs,
"--verify on {backend} must compare both retained logs"
);
}
}
#[test]
fn every_backend_keeps_io_buffer_checking_on_by_default() {
for backend in ["ptrace", "dbt", "liteinst", "sabre", "kvm", "e9patch"] {
let run = run_opts_for(&[
"hermit",
"--backend",
backend,
"run",
"--verify",
"--verify-strict",
"fakeprog",
]);
let prepared =
hermit::prepare_backend_config(run.effective_det_config(), run.runtime_backend());
assert!(
prepared.detlog_io_buffers,
"{backend} disabled syscall output-buffer checking while the ordinary strict-verify \
request left it enabled"
);
if run.selected_backend() != Backend::Dbt {
assert_eq!(
run.verification_comparison_options().compare_io_buffers,
prepared.detlog_io_buffers,
"{backend} reported an io-buffer comparison state different from the \
configuration that backend actually receives"
);
}
let opted_out = run_opts_for(&[
"hermit",
"--backend",
backend,
"run",
"--verify",
"--verify-strict",
"--no-detlog-io-buffers",
"fakeprog",
]);
let prepared_opt_out = hermit::prepare_backend_config(
opted_out.effective_det_config(),
opted_out.runtime_backend(),
);
assert!(
!prepared_opt_out.detlog_io_buffers,
"{backend} ignored the explicit --no-detlog-io-buffers relaxation"
);
if opted_out.selected_backend() != Backend::Dbt {
assert_eq!(
opted_out
.verification_comparison_options()
.compare_io_buffers,
prepared_opt_out.detlog_io_buffers,
"{backend} reported an io-buffer comparison state different from its explicit \
opt-out"
);
}
}
}
#[test]
fn e9patch_preserves_executable_identity_and_uses_ptrace_runtime() {
let mut ro = run_opts_for(&[
"hermit",
"--backend",
"e9patch",
"run",
"/bin/echo",
"hello",
]);
ro.e9patch_overlay = Some(E9patchOverlay {
source: PathBuf::from("/cache/patched-echo"),
target: PathBuf::from("/bin/echo"),
});
let command = ro.guest_command().unwrap();
assert_eq!(command.get_program(), "/bin/echo");
assert_eq!(command.get_arg0(), "/bin/echo");
assert_eq!(ro.runtime_backend(), Backend::Ptrace);
let tmpfs = tempfile::tempdir().unwrap();
let mounts = ro.mounts(tmpfs.path()).unwrap();
let overlay = mounts
.mounts
.iter()
.find(|mount| mount.get_source() == Some(Path::new("/cache/patched-echo")))
.unwrap();
assert_eq!(overlay.get_target(), Path::new("/bin/echo"));
}
#[test]
fn mapped_guest_path_is_resolved_before_host_validation() {
let tmp = tempfile::tempdir().unwrap();
let tool = tmp.path().join("tool");
fs::write(&tool, b"fixture").unwrap();
let mut permissions = fs::metadata(&tool).unwrap().permissions();
permissions.set_mode(0o755);
fs::set_permissions(&tool, permissions).unwrap();
let tmp_arg = format!("--tmp={}", tmp.path().display());
let mut ro = run_opts_for(&[
"hermit",
"--backend",
"e9patch",
"run",
&tmp_arg,
"-e",
"PATH=/tmp",
"tool",
]);
assert_eq!(ro.tmp.as_deref(), Some(tmp.path()));
assert_eq!(
ro.guest_command()
.unwrap()
.get_captured_envs()
.get(OsStr::new("PATH")),
Some(&OsStr::new("/tmp").to_os_string())
);
assert_eq!(
ro.mapped_host_program(Path::new("/tmp/tool")),
GuestPathMapping::Mapped(tool.clone())
);
let (guest, host) = ro.resolve_guest_and_host_program().unwrap();
assert_eq!(guest, Path::new("/tmp/tool"));
assert_eq!(host, tool);
ro.e9patch_program = Some(guest);
let command = ro.guest_command().unwrap();
assert_eq!(command.get_program(), "/tmp/tool");
assert_eq!(command.get_arg0(), "tool");
}
#[test]
fn non_e9patch_validation_preserves_parent_component_paths() {
let ro = run_opts_for(&["hermit", "--backend", "ptrace", "run", "/bin/../bin/echo"]);
ro.validate_program().unwrap();
}
#[test]
fn guest_env_disables_sanitizer_leak_detection_on_every_backend() {
let asan = OsStr::new("ASAN_OPTIONS");
let lsan = OsStr::new("LSAN_OPTIONS");
let expected = OsStr::new("detect_leaks=0").to_os_string();
for backend in ["ptrace", "kvm", "sabre", "dbt"] {
let ro = run_opts_for(&["hermit", "--backend", backend, "run", "/bin/echo", "hi"]);
let envs = ro.guest_command().unwrap().get_captured_envs();
assert_eq!(
envs.get(asan),
Some(&expected),
"ASAN_OPTIONS not set for backend {backend}"
);
assert_eq!(
envs.get(lsan),
Some(&expected),
"LSAN_OPTIONS not set for backend {backend}"
);
}
}
#[test]
fn namespace_only_guest_command_applies_process_options_once() {
let ro = RunOpts::parse_from([
"fakehermit",
"--namespace-only",
"--base-env=minimal",
"--env=NAMESPACE_ONLY_EXPLICIT=present",
"--workdir=/test",
"/bin/echo",
"first",
"second",
]);
let command = ro.namespace_only_guest_command().unwrap();
assert_eq!(command.get_program(), OsStr::new("/bin/echo"));
assert_eq!(
command.get_args().collect::<Vec<_>>(),
&[OsStr::new("first"), OsStr::new("second")]
);
assert_eq!(command.get_current_dir(), Some(Path::new("/test")));
let envs = command.get_captured_envs();
assert_eq!(
envs.len(),
4,
"unexpected namespace-only environment: {envs:?}"
);
assert_eq!(
envs.get(OsStr::new("HOME")).map(|value| value.as_os_str()),
Some(OsStr::new("/root"))
);
assert_eq!(
envs.get(OsStr::new("HOSTNAME"))
.map(|value| value.as_os_str()),
Some(OsStr::new("hermetic-container.local"))
);
assert_eq!(
envs.get(OsStr::new("PATH")).map(|value| value.as_os_str()),
Some(OsStr::new(
"/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
))
);
assert_eq!(
envs.get(OsStr::new("NAMESPACE_ONLY_EXPLICIT"))
.map(|value| value.as_os_str()),
Some(OsStr::new("present"))
);
}
#[test]
fn namespace_only_guest_command_preserves_sanitizer_environment() {
let ro = RunOpts::parse_from(["fakehermit", "--namespace-only", "/bin/true"]);
let command = ro.namespace_only_guest_command().unwrap();
let sanitizer_overrides: Vec<_> = command
.get_envs()
.filter(|(name, _)| {
*name == OsStr::new("ASAN_OPTIONS") || *name == OsStr::new("LSAN_OPTIONS")
})
.map(|(name, value)| (name.to_owned(), value.map(OsStr::to_owned)))
.collect();
assert!(
sanitizer_overrides.is_empty(),
"namespace-only added explicit sanitizer overrides: {sanitizer_overrides:?}"
);
let missing = format!("HERMIT_NAMESPACE_ONLY_MISSING_ENV_{}", std::process::id());
assert!(std::env::var_os(&missing).is_none());
let option = format!("--env={missing}");
let ro = RunOpts::parse_from(["fakehermit", "--namespace-only", &option, "/bin/true"]);
let error = match ro.namespace_only_guest_command() {
Ok(_) => panic!("namespace-only accepted a missing pass-through environment variable"),
Err(error) => error.to_string(),
};
assert!(error.contains(&missing), "unexpected error: {error}");
assert!(error.contains("not set in the host environment"), "{error}");
}
#[test]
fn dbt_rejects_mount_and_bind_but_accepts_workdir() {
let mut with_mount = run_opts_for(&[
"hermit",
"--backend",
"dbt",
"run",
"--mount=type=tmpfs,target=/test",
"/bin/true",
]);
let error = with_mount
.validate_args_with_perf_support(true)
.unwrap_err()
.to_string();
assert!(error.contains("dbt backend cannot apply --mount"));
let mut with_bind = run_opts_for(&[
"hermit",
"--backend",
"dbt",
"run",
"--bind=/tmp:/test",
"/bin/true",
]);
let error = with_bind
.validate_args_with_perf_support(true)
.unwrap_err()
.to_string();
assert!(error.contains("dbt backend cannot apply --mount"));
let mut with_workdir = run_opts_for(&[
"hermit",
"--backend",
"dbt",
"run",
"--workdir",
"/test",
"/bin/true",
]);
with_workdir.validate_args_with_perf_support(true).unwrap();
assert_eq!(
with_workdir.guest_command().unwrap().get_current_dir(),
Some(Path::new("/test"))
);
}
#[test]
fn guest_path_normalization_rejects_parent_components() {
let error = normalize_guest_path(Path::new("/mnt/../tool")).unwrap_err();
assert!(error.to_string().contains("parent components"));
}
#[test]
fn e9patch_mount_target_rejects_parent_components() {
let ro = run_opts_for(&[
"hermit",
"--backend",
"e9patch",
"run",
"--mount=type=tmpfs,target=/tmp/../bin",
"/bin/echo",
]);
let error = ro.validate_e9patch_mount_targets().unwrap_err().to_string();
assert!(error.contains("mount target cannot contain parent components"));
}
#[test]
fn e9patch_mount_target_rejects_symlink_components() {
let directory = tempfile::tempdir().unwrap();
let link = directory.path().join("link");
std::os::unix::fs::symlink("/tmp", &link).unwrap();
let mount = format!(
"--mount=type=tmpfs,target={}",
link.join("target").display()
);
let ro = run_opts_for(&["hermit", "--backend", "e9patch", "run", &mount, "/bin/echo"]);
let error = ro.validate_e9patch_mount_targets().unwrap_err();
assert!(error.to_string().contains("mount target traverses symlink"));
}
#[test]
fn source_less_mount_hides_program_from_resolution() {
let ro = RunOpts::parse_from(["fakehermit", "--mount=type=tmpfs,target=/bin", "/bin/echo"]);
assert_eq!(
ro.mapped_host_program(Path::new("/bin/echo")),
GuestPathMapping::Hidden
);
let error = ro.resolve_guest_and_host_program().unwrap_err().to_string();
assert!(error.contains("not visible through the configured guest mounts"));
}
#[test]
fn non_elf_entrypoints_skip_e9patch_preprocessing() {
let directory = tempfile::tempdir().unwrap();
let script = directory.path().join("script");
fs::write(&script, b"#!/bin/sh\nexit 0\n").unwrap();
let mut permissions = fs::metadata(&script).unwrap().permissions();
permissions.set_mode(0o755);
fs::set_permissions(&script, permissions).unwrap();
assert!(!is_elf_file(&script).unwrap());
assert!(is_elf_file(Path::new("/bin/sh")).unwrap());
let mount_link = directory.path().join("mount-link");
std::os::unix::fs::symlink("/var/run", &mount_link).unwrap();
let unrelated_mount = format!(
"--mount=type=tmpfs,target={}",
mount_link.join("target").display()
);
let tmp = format!("--tmp={}", directory.path().display());
let mut ro = run_opts_for(&[
"hermit",
"--backend",
"e9patch",
"run",
&unrelated_mount,
&tmp,
"/tmp/script",
]);
ro.prepare_e9patch_program().unwrap();
assert!(ro.e9patch_overlay.is_none());
}
#[test]
fn e9patch_overlay_uses_canonical_target_without_custom_mounts() {
let ro = run_opts_for(&["hermit", "--backend", "e9patch", "run", "/bin/echo"]);
assert_eq!(
ro.resolve_e9patch_overlay_target(Path::new("/bin/echo"), Path::new("/bin/echo"))
.unwrap(),
fs::canonicalize("/bin/echo").unwrap()
);
}
#[test]
fn e9patch_rejects_symlinked_executables_through_custom_mounts() {
let directory = tempfile::tempdir().unwrap();
let executable = directory.path().join("executable");
let link = directory.path().join("link");
fs::write(&executable, b"fixture").unwrap();
std::os::unix::fs::symlink(&executable, &link).unwrap();
let mount = format!(
"--mount=type=bind,source={},target=/e9patch-test",
directory.path().display()
);
let ro = run_opts_for(&[
"hermit",
"--backend",
"e9patch",
"run",
&mount,
"/e9patch-test/link",
]);
let error = ro
.resolve_e9patch_overlay_target(Path::new("/e9patch-test/link"), &link)
.unwrap_err();
assert!(error.to_string().contains("symlinked executable"));
}
#[test]
fn e9patch_rejects_mounts_that_change_a_symlink_target() {
let directory = tempfile::tempdir().unwrap();
let mount = format!(
"--mount=type=bind,source={},target=/usr",
directory.path().display()
);
let ro = run_opts_for(&["hermit", "--backend", "e9patch", "run", &mount, "/bin/echo"]);
let error = ro
.resolve_e9patch_overlay_target(Path::new("/bin/echo"), Path::new("/bin/echo"))
.unwrap_err();
assert!(error.to_string().contains("symlinked executable"));
}
#[test]
fn detects_symlink_resolution_through_implicit_mounts() {
use std::os::fd::AsRawFd;
let temp_root = std::env::temp_dir();
let file = tempfile::NamedTempFile::new().unwrap();
let proc_fd = PathBuf::from(format!("/proc/self/fd/{}", file.as_raw_fd()));
assert!(path_resolution_visits_prefix(&proc_fd, &temp_root).unwrap());
assert!(path_resolution_visits_prefix(&proc_fd, Path::new("/proc")).unwrap());
assert!(!path_resolution_visits_prefix(Path::new("/bin/echo"), &temp_root).unwrap());
}
#[test]
fn display_runopts2() {
let vec: Vec<&str> = vec![
"fakehermit",
"--sequentialize-threads",
"fakeprog",
"arg1",
"arg2",
];
let mut ro = RunOpts::parse_from(vec.iter());
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(
format!("{}", ro),
" --epoch=2026-01-01T00:00:00+00:00 -- fakeprog arg1 arg2"
);
}
#[test]
fn display_runopts3() {
let vec: Vec<&str> = vec![
"fakehermit",
"--no-sequentialize-threads",
"--no-virtualize-metadata",
"--epoch=2000-12-31T23:59:59+00:00",
"fakeprog",
"arg1",
"arg2",
];
let mut ro = RunOpts::parse_from(vec.iter());
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(
format!("{}", ro),
" --no-sequentialize-threads --no-virtualize-metadata --epoch=2000-12-31T23:59:59+00:00 -- fakeprog arg1 arg2"
);
}
#[test]
fn display_runopts4() {
let vec: Vec<&str> = vec!["fakehermit", "--sequentialize-threads", "fakeprog", "arg1"];
let mut ro = RunOpts::parse_from(vec.iter());
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(
format!("{}", ro),
" --epoch=2026-01-01T00:00:00+00:00 -- fakeprog arg1"
);
}
#[test]
fn unsupported_syscalls_fail_closed_by_default_with_explicit_opt_out() {
let mut normal = RunOpts::parse_from(["fakehermit", "fakeprog"]);
normal.validate_args_with_perf_support(true).unwrap();
assert!(normal.det_opts.det_config.panic_on_unsupported_syscalls);
assert!(!normal.det_opts.det_config.passthru_opt);
assert_eq!(
format!("{}", normal),
" --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
let mut strict = RunOpts::parse_from(["fakehermit", "--strict", "fakeprog"]);
strict.validate_args_with_perf_support(true).unwrap();
assert!(strict.det_opts.det_config.sequentialize_threads);
assert!(strict.det_opts.det_config.deterministic_io);
assert!(!strict.det_opts.det_config.passthru_opt);
assert!(strict.det_opts.det_config.panic_on_unsupported_syscalls);
assert_eq!(
format!("{}", strict),
" --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
let mut compatibility =
RunOpts::parse_from(["fakehermit", "--allow-unsupported-syscalls", "fakeprog"]);
compatibility.validate_args_with_perf_support(true).unwrap();
assert!(
!compatibility
.det_opts
.det_config
.panic_on_unsupported_syscalls
);
assert_eq!(
format!("{}", compatibility),
" --allow-unsupported-syscalls --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
#[test]
fn panic_on_rbc_overshoot_flag_wires_to_detcore_config() {
let default = RunOpts::parse_from(["fakehermit", "fakeprog"]);
assert!(!default.det_opts.det_config.panic_on_rcb_overshoot);
let mut opts = RunOpts::parse_from(["fakehermit", "--panic-on-rbc-overshoot", "fakeprog"]);
opts.validate_args_with_perf_support(true).unwrap();
assert!(opts.det_opts.det_config.panic_on_rcb_overshoot);
assert_eq!(
format!("{}", opts),
" --panic-on-rbc-overshoot --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
#[test]
fn passthru_optimization_requires_explicit_compatibility_opt_out() {
let mut ro = RunOpts::parse_from([
"fakehermit",
"--allow-unsupported-syscalls",
"--passthru-opt",
"fakeprog",
]);
ro.validate_args_with_perf_support(true).unwrap();
assert!(ro.det_opts.det_config.passthru_opt);
assert_eq!(
format!("{}", ro),
" --allow-unsupported-syscalls --passthru-opt --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
#[test]
fn passthru_optimization_rejects_fail_closed_modes() {
for arguments in [
vec!["fakehermit", "--passthru-opt", "fakeprog"],
vec!["fakehermit", "--passthru-opt", "--strict", "fakeprog"],
vec![
"fakehermit",
"--passthru-opt",
"--panic-on-unsupported-syscalls",
"fakeprog",
],
] {
let mut opts = RunOpts::parse_from(arguments);
let error = opts.validate_args_with_perf_support(true).unwrap_err();
let message = error.to_string();
assert!(
message.contains("--passthru-opt"),
"unexpected error: {message}"
);
assert!(
message.contains("fail-closed"),
"unexpected error: {message}"
);
assert!(
message.contains("--allow-unsupported-syscalls"),
"unexpected error: {message}"
);
}
}
#[test]
fn timeslice_flags_parse_and_round_trip() {
let mut ro = RunOpts::parse_from([
"fakehermit",
"--max-timeslice=100000",
"--target-timeslice=20000",
"fakeprog",
]);
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(
ro.det_opts.det_config.max_timeslice,
std::num::NonZeroU64::new(100_000)
);
assert_eq!(
ro.det_opts.det_config.target_timeslice,
std::num::NonZeroU64::new(20_000)
);
let rendered = format!("{}", ro);
assert_eq!(
rendered,
" --max-timeslice=100000 --target-timeslice=20000 --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
let mut reparsed_args = vec!["fakehermit".to_owned()];
reparsed_args.extend(shell_words::split(&rendered).unwrap());
let mut reparsed = RunOpts::parse_from(reparsed_args);
reparsed.validate_args_with_perf_support(true).unwrap();
assert_eq!(
reparsed.det_opts.det_config.max_timeslice,
ro.det_opts.det_config.max_timeslice
);
assert_eq!(
reparsed.det_opts.det_config.target_timeslice,
ro.det_opts.det_config.target_timeslice
);
}
#[test]
fn skid_margin_override_parses_and_round_trips() {
let mut opts = RunOpts::parse_from(["fakehermit", "--skid-margin=500", "fakeprog"]);
opts.validate_args_with_perf_support(true).unwrap();
assert_eq!(opts.skid_margin, Some(500));
assert_eq!(
format!("{opts}"),
" --skid-margin=500 --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
#[test]
fn skid_margin_override_rejects_non_ptrace_backed_backends() {
for backend in ["dbt", "kvm", "sabre"] {
let mut opts = run_opts_for(&[
"hermit",
&format!("--backend={backend}"),
"run",
"--skid-margin=500",
"fakeprog",
]);
let error = opts.validate_args_with_perf_support(true).unwrap_err();
assert!(
error
.to_string()
.contains("requires a ptrace-backed backend"),
"unexpected {backend} error: {error}"
);
}
}
#[test]
fn skid_margin_override_is_available_to_liteinst_host_hybrid() {
let mut opts = run_opts_for(&[
"hermit",
"--backend=liteinst",
"run",
"--skid-margin=500",
"fakeprog",
]);
opts.validate_args_with_perf_support(true).unwrap();
assert_eq!(opts.skid_margin, Some(500));
assert_eq!(opts.global_backend_arg(), " --backend=liteinst");
assert_eq!(
format!("{opts}"),
" --skid-margin=500 --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
#[cfg(test)]
fn liteinst_in_guest_refusal(
runtime: LiteinstRuntime,
options: &[&str],
) -> Result<(), anyhow::Error> {
let mut argv = vec!["hermit", "--backend=liteinst", "run"];
argv.extend_from_slice(options);
argv.push("fakeprog");
run_opts_for(&argv).refuse_unqualified_liteinst_in_guest_options(runtime)
}
#[test]
fn liteinst_in_guest_refuses_options_it_cannot_honour() {
let error = liteinst_in_guest_refusal(LiteinstRuntime::InGuest, &[]).unwrap_err();
assert!(error.downcast_ref::<PolicyRefusal>().is_some(), "{error:#}");
assert!(
error.to_string().contains("pass --max-timeslice=disabled"),
"{error:#}"
);
for (option, reason) in [
("--verify", "--verify compares Detcore's internal logs"),
(
"--run-evidence-dir=/unused/new-path",
"--run-evidence-dir has not been qualified",
),
("--timeout=3", "--timeout has not been qualified"),
("--skid-margin=500", "--skid-margin configures"),
("--gdbserver", "--gdbserver needs the ptrace tracer"),
] {
let error = liteinst_in_guest_refusal(
LiteinstRuntime::InGuest,
&["--max-timeslice=disabled", option],
)
.unwrap_err();
assert!(
error.downcast_ref::<PolicyRefusal>().is_some(),
"{option}: {error:#}"
);
assert!(error.to_string().contains(reason), "{option}: {error:#}");
}
liteinst_in_guest_refusal(LiteinstRuntime::InGuest, &["--max-timeslice=disabled"]).unwrap();
}
#[test]
fn liteinst_host_hybrid_is_not_subject_to_the_in_guest_refusals() {
liteinst_in_guest_refusal(
LiteinstRuntime::HostHybrid,
&[
"--verify",
"--timeout=3",
"--skid-margin=500",
"--gdbserver",
],
)
.unwrap();
}
#[test]
fn deprecated_preemption_timeout_alias_round_trips_canonically() {
let mut ro = RunOpts::parse_from(["fakehermit", "--preemption-timeout=100000", "fakeprog"]);
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(
ro.det_opts.det_config.max_timeslice,
std::num::NonZeroU64::new(100_000)
);
assert_eq!(
format!("{}", ro),
" --max-timeslice=100000 --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
#[test]
fn deprecated_preemption_timeout_disabled_values_round_trip_canonically() {
for value in ["disabled", "0"] {
let flag = format!("--preemption-timeout={value}");
let mut ro = RunOpts::parse_from(["fakehermit", &flag, "fakeprog"]);
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(ro.det_opts.det_config.max_timeslice, None);
assert_eq!(
format!("{}", ro),
" --max-timeslice=disabled --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
}
#[test]
fn max_timeslice_rejects_less_than_one_rcb() {
let error =
RunOpts::try_parse_from(["fakehermit", "--max-timeslice=9", "fakeprog"]).unwrap_err();
assert_eq!(error.kind(), clap::error::ErrorKind::ValueValidation);
assert!(error.to_string().contains("at least one RCB"));
let mut ro = RunOpts::parse_from(["fakehermit", "--max-timeslice=10", "fakeprog"]);
ro.validate_args_with_perf_support(true).unwrap();
assert_eq!(
ro.det_opts.det_config.max_timeslice,
std::num::NonZeroU64::new(10)
);
let mut scaled = RunOpts::parse_from([
"fakehermit",
"--max-timeslice=10",
"--clock-multiplier=2",
"fakeprog",
]);
let error = scaled.validate_args_with_perf_support(true).unwrap_err();
assert!(error.to_string().contains("at least one RCB"));
let mut zero = RunOpts::parse_from(["fakehermit", "--clock-multiplier=0", "fakeprog"]);
assert!(
zero.validate_args_with_perf_support(true)
.unwrap_err()
.to_string()
.contains("finite and positive")
);
}
#[test]
fn strict_flag_rejects_determinism_opt_outs() {
for opt_out in ["--no-sequentialize-threads", "--no-deterministic-io"] {
let error =
RunOpts::try_parse_from(["fakehermit", "--strict", opt_out, "fakeprog"]).unwrap_err();
assert_eq!(error.kind(), clap::error::ErrorKind::ArgumentConflict);
let message = error.to_string();
assert!(message.contains("--strict"));
assert!(message.contains(opt_out));
}
}
#[test]
fn strict_rejects_strace_only() {
let error = RunOpts::try_parse_from(["fakehermit", "--strict", "--strace-only", "fakeprog"])
.unwrap_err();
assert_eq!(error.kind(), clap::error::ErrorKind::ArgumentConflict);
let message = error.to_string();
assert!(message.contains("--strict"));
assert!(message.contains("--strace-only"));
}
#[test]
fn strict_rejects_every_route_to_host_networking() {
for (args, expected_cause) in [
(vec!["--strict", "--network=host"], "--network=host"),
(vec!["--strict", "--no-namespace"], "--no-namespace"),
(vec!["--strict", "--gdbserver"], "--gdbserver"),
] {
let mut argv = vec!["fakehermit"];
argv.extend(args.iter().copied());
argv.push("fakeprog");
let mut opts = match RunOpts::try_parse_from(&argv) {
Ok(opts) => opts,
Err(error) => {
assert_eq!(error.kind(), clap::error::ErrorKind::ArgumentConflict);
continue;
}
};
let error = opts
.validate_args_with_perf_support(true)
.expect_err(&format!("{argv:?} must be refused under --strict"));
let message = error.to_string();
assert!(
message.contains("--strict"),
"{argv:?}: message must name --strict: {message}"
);
assert!(
message.contains(expected_cause),
"{argv:?}: message must name the cause {expected_cause}: {message}"
);
}
}
#[test]
fn non_strict_runs_still_allow_host_networking() {
let mut opts = RunOpts::parse_from(["fakehermit", "--network=host", "fakeprog"]);
opts.validate_args_with_perf_support(true)
.expect("host networking without --strict must remain allowed");
assert_eq!(opts.network, NetworkingMode::Host);
}
#[test]
fn gdbserver_forces_host_networking() {
let mut plain = RunOpts::parse_from(["fakehermit", "fakeprog"]);
plain.validate_args_with_perf_support(true).unwrap();
assert_eq!(plain.network, NetworkingMode::Local);
let mut opts = RunOpts::parse_from(["fakehermit", "--gdbserver", "fakeprog"]);
assert_eq!(opts.network, NetworkingMode::Local);
opts.validate_args_with_perf_support(true).unwrap();
assert!(opts.det_opts.det_config.gdbserver);
assert_eq!(opts.network, NetworkingMode::Host);
}
#[test]
fn gdbserver_respects_explicit_host_networking() {
let mut opts = RunOpts::parse_from(["fakehermit", "--gdbserver", "--network=host", "fakeprog"]);
opts.validate_args_with_perf_support(true).unwrap();
assert_eq!(opts.network, NetworkingMode::Host);
}
#[test]
fn gdbserver_conflicts_with_analyze_networking() {
let mut opts = RunOpts::parse_from([
"fakehermit",
"--gdbserver",
"--analyze-networking",
"fakeprog",
]);
let error = opts.validate_args_with_perf_support(true).unwrap_err();
let message = error.to_string();
assert!(message.contains("--gdbserver"), "message: {message}");
assert!(
message.contains("--analyze-networking"),
"message: {message}"
);
}
#[test]
fn no_namespace_uses_host_resources_and_disables_uts_assumption() {
let mut opts = RunOpts::parse_from(["fakehermit", "--core-only", "fakeprog"]);
opts.validate_args_with_perf_support(true).unwrap();
assert!(opts.no_namespace);
assert_eq!(opts.network, NetworkingMode::Host);
assert_eq!(opts.tmp.as_deref(), Some(Path::new(TMP_DIR)));
assert!(!opts.det_opts.det_config.has_uts_namespace);
assert!(opts.pin_threads);
assert_eq!(
format!("{}", opts),
" --network=host --no-namespace --tmp=/tmp --epoch=2026-01-01T00:00:00+00:00 -- fakeprog"
);
}
#[test]
fn dbt_backend_disables_uts_assumption() {
let mut opts = run_opts_for(&["hermit", "--backend=dbt", "run", "fakeprog"]);
opts.validate_args_with_perf_support(true).unwrap();
assert_eq!(opts.selected_backend(), Backend::Dbt);
assert!(!opts.no_namespace);
assert!(!opts.det_opts.det_config.has_uts_namespace);
}
#[test]
fn ptrace_backend_keeps_uts_assumption_with_namespaces() {
let mut opts = RunOpts::parse_from(["fakehermit", "fakeprog"]);
opts.validate_args_with_perf_support(true).unwrap();
assert_eq!(opts.selected_backend(), Backend::Ptrace);
assert!(!opts.no_namespace);
assert!(opts.det_opts.det_config.has_uts_namespace);
}
#[test]
fn image_conflicts_with_no_namespace_with_explanatory_error() {
let mut opts = RunOpts::parse_from([
"fakehermit",
"--image=docker.io/library/busybox@sha256:deadbeef",
"--no-namespace",
"/bin/sh",
]);
let message = opts
.validate_args_with_perf_support(true)
.unwrap_err()
.to_string();
assert!(message.contains("--image"), "message: {message}");
assert!(message.contains("--no-namespace"), "message: {message}");
assert!(message.contains("chroot"), "message: {message}");
}
#[test]
fn image_rejects_unqualified_backend_and_namespace_paths() {
let mut backend = run_opts_for(&[
"hermit",
"--backend=dbt",
"run",
"--image=busybox@sha256:deadbeef",
"/bin/sh",
]);
let message = backend
.validate_args_with_perf_support(true)
.unwrap_err()
.to_string();
assert!(
message.contains("only the ptrace backend"),
"message: {message}"
);
let mut namespace_only = RunOpts::parse_from([
"fakehermit",
"--image=busybox@sha256:deadbeef",
"--namespace-only",
"/bin/sh",
]);
let message = namespace_only
.validate_args_with_perf_support(true)
.unwrap_err()
.to_string();
assert!(message.contains("--namespace-only"), "message: {message}");
}
#[test]
fn image_script_validation_resolves_interpreter_inside_rootfs() {
let tmp = tempfile::TempDir::new().unwrap();
let rootfs = tmp.path();
let script = rootfs.join("bin/image-script");
let interpreter = rootfs.join("image-only-interpreter");
std::fs::create_dir_all(script.parent().unwrap()).unwrap();
std::fs::write(&script, b"#!/image-only-interpreter\nexit 0\n").unwrap();
std::fs::write(&interpreter, b"image interpreter fixture\n").unwrap();
std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
std::fs::set_permissions(&interpreter, std::fs::Permissions::from_mode(0o755)).unwrap();
validate_executable(&script, Path::new("/bin/image-script"), Some(rootfs)).unwrap();
std::fs::write(&script, b"#!/missing-image-interpreter\nexit 0\n").unwrap();
let error = validate_executable(&script, Path::new("/bin/image-script"), Some(rootfs))
.expect_err("a missing guest interpreter must be rejected");
assert!(
error.to_string().contains("/missing-image-interpreter"),
"unexpected error: {error:#}"
);
}
#[test]
fn validate_executable_rejects_empty_shebang_interpreter() {
let tmp = tempfile::TempDir::new().unwrap();
let script = tmp.path().join("empty-shebang");
let requested = Path::new("/bin/empty-shebang");
for contents in [b"#!".as_slice(), b"#! \t", b"#!\n"] {
std::fs::write(&script, contents).unwrap();
std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
for guest_root in [None, Some(tmp.path())] {
let error = match validate_executable(&script, requested, guest_root) {
Ok(()) => panic!(
"preflight accepted an executable whose contents are {contents:?} \
(guest_root: {guest_root:?}); it must be rejected"
),
Err(error) => error,
};
assert!(
error.to_string().contains("empty shebang interpreter"),
"contents {contents:?} (guest_root: {guest_root:?}): unexpected error: {error:#}"
);
}
}
}
#[test]
fn image_guest_program_resolution_matches_execve_pathname_rules() {
assert_eq!(
resolve_image_guest_program(Path::new("/bin/sh"), Path::new("/")).unwrap(),
PathBuf::from("/bin/sh")
);
assert_eq!(
resolve_image_guest_program(Path::new("bin/busybox"), Path::new("/opt/app")).unwrap(),
PathBuf::from("/opt/app/bin/busybox")
);
assert_eq!(
resolve_image_guest_program(Path::new("./run.sh"), Path::new("/srv")).unwrap(),
PathBuf::from("/srv/run.sh")
);
assert_eq!(
resolve_image_guest_program(Path::new("./bin/sh"), Path::new("/")).unwrap(),
PathBuf::from("/bin/sh")
);
let bare = resolve_image_guest_program(Path::new("sh"), Path::new("/"))
.unwrap_err()
.to_string();
assert!(bare.contains("PATH search"), "message: {bare}");
assert!(bare.contains("bin/sh"), "message: {bare}");
assert!(resolve_image_guest_program(Path::new("../etc/x"), Path::new("/app")).is_err());
}
#[test]
fn strict_help_describes_compatibility_and_opt_outs() {
use clap::CommandFactory;
let help = RunOpts::command().render_long_help().to_string();
for expected in [
"--strict",
"Require Hermit's deterministic defaults",
"already fail closed in ordinary runs",
"--no-sequentialize-threads",
"Disable deterministic sequential thread execution",
"--no-deterministic-io",
"Disable deterministic I/O behavior",
"--passthru-opt",
"optimized partial syscall subscription set",
"--allow-unsupported-syscalls",
"This weakens determinism",
"--panic-on-rbc-overshoot",
"--max-timeslice",
"--preemption-timeout",
"--target-timeslice",
"syscall boundaries",
] {
assert!(
help.contains(expected),
"missing {expected:?} in run help:\n{help}"
);
}
assert!(
!help.contains("--backend <BACKEND>"),
"run help still offers a subcommand-level --backend:\n{help}"
);
let top_level = crate::Args::command().render_long_help().to_string();
for expected in [
"--backend <BACKEND>",
"Select the process instrumentation backend",
"This is a global option",
"ptrace",
"dbt",
"kvm",
] {
assert!(
top_level.contains(expected),
"missing {expected:?} in top-level help:\n{top_level}"
);
}
}
#[test]
fn only_instrumented_ptrace_family_runs_depend_on_host_perf() {
let default = RunOpts::parse_from(["fakehermit", "fakeprog"]);
assert!(default.arms_reverie_ptrace_pmu_timer());
let namespace_only = RunOpts::parse_from(["fakehermit", "--namespace-only", "fakeprog"]);
assert_eq!(namespace_only.selected_backend(), Backend::Ptrace);
assert!(!namespace_only.arms_reverie_ptrace_pmu_timer());
let kvm = run_opts_for(&["hermit", "--backend=kvm", "run", "fakeprog"]);
assert!(!kvm.arms_reverie_ptrace_pmu_timer());
}
#[test]
fn display_runopts_without_perf_support() {
let mut ro = RunOpts::parse_from(["fakehermit", "fakeprog", "arg1"]);
ro.validate_args_with_perf_support(false).unwrap();
assert_eq!(
format!("{}", ro),
" --max-timeslice=disabled --epoch=2026-01-01T00:00:00+00:00 -- fakeprog arg1"
);
}
fn shebang_interpreter(path: &Path) -> Option<PathBuf> {
let mut file = File::open(path).ok()?;
let mut bytes = [0_u8; 256];
let count = file.read(&mut bytes).ok()?;
Shebang::interpreter_from_buf(&bytes[..count])
}
pub(super) fn is_elf_file(path: &Path) -> Result<bool, Error> {
let mut file = File::open(path)
.with_context(|| format!("failed to open executable {}", path.display()))?;
let mut magic = [0_u8; 4];
match file.read_exact(&mut magic) {
Ok(()) => Ok(magic == *b"\x7fELF"),
Err(error) if error.kind() == std::io::ErrorKind::UnexpectedEof => Ok(false),
Err(error) => Err(error)
.with_context(|| format!("failed to inspect executable format for {}", path.display())),
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GuestProgramFault {
NotFound,
NotExecutable,
}
impl GuestProgramFault {
pub fn exit_code(self) -> i32 {
match self {
Self::NotFound => hermit::GUEST_PROGRAM_NOT_FOUND_EXIT,
Self::NotExecutable => hermit::GUEST_PROGRAM_NOT_EXECUTABLE_EXIT,
}
}
pub fn class(self) -> &'static str {
match self {
Self::NotFound => "guest-program-not-found",
Self::NotExecutable => "guest-program-not-executable",
}
}
}
impl std::fmt::Display for GuestProgramFault {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(match self {
Self::NotFound => "guest program not found",
Self::NotExecutable => "guest program not executable",
})
}
}
impl std::error::Error for GuestProgramFault {}
fn validate_executable(
path: &Path,
requested: &Path,
guest_root: Option<&Path>,
) -> Result<(), Error> {
let metadata = fs::metadata(path)
.with_context(|| {
format!(
"Program {} does not exist or is not accessible. Check the path and any --mount \
or --bind target.",
requested.display()
)
})
.map_err(|error| error.context(GuestProgramFault::NotFound))?;
if metadata.is_dir() {
return Err(anyhow::anyhow!(
"Program {} is a directory; provide the path to an executable file",
requested.display()
)
.context(GuestProgramFault::NotExecutable));
}
if !metadata.is_file() {
return Err(anyhow::anyhow!(
"Program {} is not a regular executable file",
requested.display()
)
.context(GuestProgramFault::NotExecutable));
}
if metadata.permissions().mode() & 0o111 == 0 {
return Err(anyhow::anyhow!(
"Program {} is not executable. Add execute permission (for example, `chmod +x {}`) \
or select another file.",
requested.display(),
requested.display()
)
.context(GuestProgramFault::NotExecutable));
}
if let Some(interpreter) = shebang_interpreter(path) {
if interpreter.as_os_str().is_empty() {
anyhow::bail!(
"Program {} has an empty shebang interpreter",
requested.display()
);
}
let interpreter_host = guest_root
.map(|root| crate::image::resolve_in_rootfs(root, &interpreter))
.unwrap_or_else(|| interpreter.clone());
let interpreter_metadata = fs::metadata(&interpreter_host).with_context(|| {
format!(
"Program {} uses shebang interpreter {}, but that interpreter does not exist in \
the selected guest filesystem. Install it or update the script's #! line.",
requested.display(),
interpreter.display()
)
})?;
if !interpreter_metadata.is_file() || interpreter_metadata.permissions().mode() & 0o111 == 0
{
anyhow::bail!(
"Program {} uses shebang interpreter {}, but it is not an executable file",
requested.display(),
interpreter.display()
);
}
}
Ok(())
}
fn mapped_path(path: &Path, source: &Path, target: &Path) -> Option<PathBuf> {
path.strip_prefix(target)
.ok()
.map(|suffix| source.join(suffix))
}
fn normalize_guest_path(path: &Path) -> Result<PathBuf, Error> {
if !path.is_absolute() {
anyhow::bail!("guest path must be absolute: {}", path.display());
}
let mut normalized = PathBuf::from("/");
for component in path.components() {
match component {
std::path::Component::RootDir | std::path::Component::CurDir => {}
std::path::Component::ParentDir => {
anyhow::bail!(
"guest path cannot contain parent components: {}",
path.display()
);
}
std::path::Component::Normal(part) => normalized.push(part),
std::path::Component::Prefix(_) => unreachable!("Unix guest path has a prefix"),
}
}
Ok(normalized)
}
fn resolve_image_guest_program(requested: &Path, guest_cwd: &Path) -> Result<PathBuf, Error> {
if requested.is_absolute() {
Ok(requested.to_path_buf())
} else if requested.to_string_lossy().contains('/') {
normalize_guest_path(&guest_cwd.join(requested))
} else {
anyhow::bail!(
"With --image, a bare program name ({:?}) would require a PATH search inside the \
image, which is not yet supported; use a path containing '/' (absolute like \
`/bin/sh`, or relative to the working directory like `./bin/sh`).",
requested
)
}
}
pub(super) fn path_resolution_visits_prefix(path: &Path, prefix: &Path) -> Result<bool, Error> {
let mut candidate = std::path::absolute(path)?;
for _ in 0..40 {
let components = candidate
.components()
.map(|component| component.as_os_str().to_os_string())
.collect::<Vec<_>>();
let mut current = PathBuf::from("/");
let mut followed_symlink = false;
for (index, component) in components.iter().enumerate() {
if component == OsStr::new("/") || component == OsStr::new(".") {
continue;
}
if component == OsStr::new("..") {
current.pop();
} else {
current.push(component);
}
if current.starts_with(prefix) {
return Ok(true);
}
let metadata = match fs::symlink_metadata(¤t) {
Ok(metadata) => metadata,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
Err(error) => return Err(error.into()),
};
if !metadata.file_type().is_symlink() {
continue;
}
let target = fs::read_link(¤t)?;
let mut next = if target.is_absolute() {
target
} else {
current
.parent()
.ok_or_else(|| Error::msg("symlink has no parent"))?
.join(target)
};
for remaining in &components[index + 1..] {
next.push(remaining);
}
candidate = next;
followed_symlink = true;
break;
}
if !followed_symlink {
return Ok(false);
}
}
anyhow::bail!("executable path exceeded Linux's symlink traversal limit")
}
fn validate_e9patch_mount_target(path: &Path) -> Result<(), Error> {
if !path.is_absolute() {
anyhow::bail!("e9patch mount target must be absolute: {}", path.display());
}
if path
.components()
.any(|component| matches!(component, std::path::Component::ParentDir))
{
anyhow::bail!(
"e9patch mount target cannot contain parent components: {}",
path.display()
);
}
let mut current = PathBuf::from("/");
for component in path.components() {
let std::path::Component::Normal(part) = component else {
continue;
};
current.push(part);
match fs::symlink_metadata(¤t) {
Ok(metadata) if metadata.file_type().is_symlink() => {
anyhow::bail!(
"e9patch mount target traverses symlink {}",
current.display()
);
}
Ok(_) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => break,
Err(error) => return Err(error.into()),
}
}
Ok(())
}
const VERIFY_RESTORED_FDS: [libc::c_int; 3] =
[libc::STDIN_FILENO, libc::STDOUT_FILENO, libc::STDERR_FILENO];
fn fd_status_flags(fd: libc::c_int) -> Option<libc::c_int> {
let flags = unsafe { libc::fcntl(fd, libc::F_GETFL) };
if flags < 0 { None } else { Some(flags) }
}
fn standard_fd_status_flags() -> [Option<libc::c_int>; VERIFY_RESTORED_FDS.len()] {
VERIFY_RESTORED_FDS.map(fd_status_flags)
}
fn restore_standard_fd_status_flags(before: [Option<libc::c_int>; VERIFY_RESTORED_FDS.len()]) {
for (fd, before) in VERIFY_RESTORED_FDS.iter().copied().zip(before) {
let Some(before) = before else {
continue;
};
let Some(now) = fd_status_flags(fd) else {
continue;
};
if now == before {
continue;
}
unsafe {
libc::fcntl(fd, libc::F_SETFL, before);
}
}
}
impl RunOpts {
pub(crate) fn capture_default_epoch(&mut self, capture_now: impl FnOnce() -> SystemTime) {
self.epoch_omitted = true;
if self.uses_virtual_time_determinization() {
self.det_opts
.det_config
.capture_epoch_from_host_time(capture_now());
self.epoch_captured_from_host = true;
}
}
#[cfg(test)]
pub(crate) fn epoch_capture_for_test(&self) -> (String, bool) {
(
self.det_opts.det_config.epoch.to_rfc3339(),
self.epoch_captured_from_host,
)
}
#[cfg(test)]
pub(crate) fn reports_virtual_epoch_for_test(&self) -> bool {
self.uses_virtual_time_determinization()
}
fn uses_virtual_time_determinization(&self) -> bool {
self.det_opts.det_config.virtualize_time
&& !self.namespace_only
&& !self.strace_only
&& !self.hb_list_events
}
fn epoch_rfc3339(&self) -> String {
self.det_opts.det_config.epoch.to_rfc3339()
}
fn adopt_replayed_schedule_epoch(&mut self) -> Result<(), Error> {
if self.namespace_only {
return Ok(());
}
let config = &self.det_opts.det_config;
let Some(path) = config
.replay_preemptions_from
.as_ref()
.or(config.replay_schedule_from.as_ref())
else {
return Ok(());
};
let Some(recorded) = detcore::preemptions::read_recorded_epoch(path).map_err(Error::msg)?
else {
return Ok(());
};
if self.epoch_omitted {
self.det_opts.det_config.epoch = recorded;
self.epoch_captured_from_host = false;
self.epoch_from_recording = true;
return Ok(());
}
if config.epoch != recorded {
let recorded = recorded.to_rfc3339();
return Err(Error::new(PolicyRefusal).context(format!(
"the explicit virtual-time epoch {} (from --epoch or HERMIT_EPOCH) differs from \
the epoch {recorded} that {} was recorded under. The recording's timeslice \
ends are absolute virtual times measured from its own epoch, so replaying \
them from another epoch cannot reproduce the run. Omit --epoch to replay \
from the recorded epoch, or pass --epoch={recorded}.",
config.epoch.to_rfc3339(),
path.display(),
)));
}
Ok(())
}
pub(crate) fn set_image(&mut self, image: String) {
self.image = Some(image);
}
pub(crate) fn image(&self) -> Option<&str> {
self.image.as_deref()
}
pub(crate) fn run_evidence_request(
&self,
global_backend: Option<Backend>,
) -> Option<(&Path, Backend)> {
self.run_evidence_dir
.as_deref()
.map(|directory| (directory, global_backend.unwrap_or_default()))
}
fn guest_run_capture_paths(&self) -> Result<Option<GuestRunCapturePaths>, Error> {
match (
self.run_result_json.as_ref(),
self.guest_stdout.as_ref(),
self.guest_stderr.as_ref(),
) {
(None, None, None) => Ok(None),
(Some(result), Some(stdout), Some(stderr)) => Ok(Some(GuestRunCapturePaths::new(
result.clone(),
stdout.clone(),
stderr.clone(),
))),
_ => Err(Error::msg(
"--run-result-json, --guest-stdout, and --guest-stderr must be supplied together",
)),
}
}
fn check_capture_companions(&self, paths: &GuestRunCapturePaths) -> Result<(), Error> {
paths.require_distinct_from(
self.backend_engagement_json.as_deref(),
"--backend-engagement-json",
)?;
paths.check_host_summary(self.summary_json.as_deref())
}
fn selected_backend(&self) -> Backend {
self.backend.unwrap_or_default()
}
pub(crate) fn set_backend(&mut self, backend: Option<Backend>) {
self.backend = backend;
}
pub(crate) fn global_backend_arg(&self) -> String {
self.backend
.map(|backend| format!(" --backend={}", backend.as_str()))
.unwrap_or_default()
}
fn runtime_backend(&self) -> Backend {
if self.selected_backend() == Backend::E9patch {
Backend::Ptrace
} else {
self.selected_backend()
}
}
fn liteinst_runtime(&self) -> Result<LiteinstRuntime, Error> {
if self.namespace_only || self.selected_backend() != Backend::Liteinst {
return Ok(LiteinstRuntime::HostHybrid);
}
LiteinstRuntime::from_env()
}
fn refuse_unqualified_liteinst_in_guest_options(
&self,
runtime: LiteinstRuntime,
) -> Result<(), Error> {
if runtime != LiteinstRuntime::InGuest {
return Ok(());
}
let config = &self.det_opts.det_config;
let reason = if config.max_timeslice.is_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"
} else if self.verify {
"--verify compares Detcore's internal logs, and the in-guest Tool does not forward \
its records to Hermit yet"
} else if self.run_evidence_dir.is_some() {
"--run-evidence-dir has not been qualified for the in-guest runtime"
} else if self.timeout.is_some() {
"--timeout has not been qualified for the in-guest runtime, whose run future does \
not kill the guest when it is dropped"
} else if self.skid_margin.is_some() {
"--skid-margin configures the Reverie ptrace PMU timer, which the in-guest runtime \
does not arm"
} else if config.gdbserver {
"--gdbserver needs the ptrace tracer, which the in-guest runtime does not attach"
} else {
return Ok(());
};
Err(Error::new(PolicyRefusal).context(format!(
"{LITEINST_IN_GUEST_ENV}=1 (in-guest LiteInst) refuses this run: {reason}"
)))
}
fn verification_strictness(&self) -> LogCompareStrictness {
if self.verify_verbose || self.verify_strict {
LogCompareStrictness::Canonical
} else {
LogCompareStrictness::Stripped
}
}
fn verification_comparison_options(&self) -> ComparisonOptions {
let config =
hermit::prepare_backend_config(self.effective_det_config(), self.runtime_backend());
ComparisonOptions {
verbose: self.verify_verbose,
strictness: self.verification_strictness(),
compare_logs: true,
diagnostic_full_trace: self.verify_verbose,
compare_io_buffers: config.detlog_io_buffers,
keep_logs: self.keep_logs,
match_overridden: false,
failed_log_retention: (!self.keep_logs).then(default_failed_verify_log_retention),
record_envelope: RecordEnvelope::all_records_v1(),
virtualize_time: config.virtualize_time,
}
}
fn verify_liteinst_activation(&self) -> Result<(), Error> {
let executable = std::env::current_exe().context("locate Hermit LiteInst probe")?;
let mut command = Command::new(executable);
command
.env_clear()
.env(super::LITEINST_ACTIVATION_PROBE_ENV, "1");
let output = hermit::run_with_output_backend(
command,
self.effective_det_config(),
false,
&None,
Backend::Liteinst,
)?;
let expected = b"hermit-liteinst-activation calls=32 traps=1 hooks=31\n";
if output.status != ExitStatus::Exited(0) || output.stdout != expected {
anyhow::bail!(
"LiteInst activation probe failed closed: status={:?}, stdout={:?}, stderr={:?}",
output.status,
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr),
);
}
Ok(())
}
pub(crate) fn verify_json_path(&self) -> Option<&Path> {
self.verify.then_some(self.verify_json.as_deref()).flatten()
}
fn retained_verify_log_dir(&self) -> Result<Option<PathBuf>, Error> {
if !self.keep_logs {
return Ok(None);
}
let directory = match &self.verify_log_dir {
Some(directory) => directory.clone(),
None => dirs::state_dir()
.ok_or_else(|| {
Error::msg(
"--keep-logs needs --verify-log-dir because no user state directory is available",
)
})?
.join("hermit")
.join("verify-logs"),
};
fs::create_dir_all(&directory).with_context(|| {
format!(
"could not create verification log directory {}",
directory.display()
)
})?;
Ok(Some(fs::canonicalize(&directory).with_context(|| {
format!(
"could not resolve verification log directory {}",
directory.display()
)
})?))
}
pub fn main(&mut self, global: &GlobalOpts) -> Result<ExitStatus, Error> {
self.backend = global.backend;
let guest_capture_paths = self.guest_run_capture_paths()?;
if let Some(paths) = &guest_capture_paths {
self.check_capture_companions(paths)?;
}
if let Some(path) = &self.backend_engagement_json {
clear_machine_record(path, "backend engagement")?;
}
self.refuse_unqualified_liteinst_in_guest_options(self.liteinst_runtime()?)?;
if self.verify {
validate_log_level(global)?;
}
let dbt_verification_stdin = if self.verify && self.selected_backend() == Backend::Dbt {
super::startup_stdin()?
} else if self.verify {
hermit::reserve_output_stdin_snapshot(super::startup_stdin()?)?;
None
} else if self.selected_backend() == Backend::Kvm {
hermit::reserve_kvm_stdin(super::startup_stdin()?)?;
None
} else {
None
};
self.validate_args()?;
self.adopt_replayed_schedule_epoch()?;
if self.uses_virtual_time_determinization() {
let epoch = self.epoch_rfc3339();
let source = if self.epoch_captured_from_host {
"host-now"
} else if self.epoch_from_recording {
"recording"
} else {
"explicit"
};
global.write_controller_diagnostic(format_args!(
"hermit: virtual-time epoch={epoch} source={source}; reproduce with --epoch={epoch}"
))?;
}
if self.allow_unsupported_syscalls {
eprintln!(
"WARNING: --allow-unsupported-syscalls permits unmodeled syscalls to reach the \
host; a successful exit does not establish complete deterministic execution."
);
}
let backend = self.selected_backend();
if backend == Backend::E9patch && self.no_namespace {
anyhow::bail!(
"--backend=e9patch requires mount namespaces to overlay the rewritten ELF at its \
original guest path"
);
}
if self.namespace_only
&& let Some(explicit_backend) = self.backend
{
anyhow::bail!(
"--backend={} cannot be used with --namespace-only because namespace-only mode \
bypasses instrumentation",
explicit_backend.as_str()
);
}
self.ensure_timeout_supported()?;
if !self.namespace_only && backend != Backend::Kvm {
backend.ensure_available()?;
}
self.install_pmu_config()?;
self.validate_mount_sources()?;
self.validate_program()?;
if self.hb_list_events {
return self.list_happens_before_events();
}
self.validate_summary_json_visibility()?;
if self.happens_before.is_some() {
self.resolved_happens_before = Some(self.load_and_resolve_happens_before()?);
}
if backend == Backend::E9patch {
self.prepare_e9patch_program()?;
}
let mut guest_capture = guest_capture_paths
.map(|paths| {
let evidence = self.run_evidence_dir.as_deref().ok_or_else(|| {
Error::msg("harness guest capture requires --run-evidence-dir")
})?;
GuestRunCaptureSession::create(&paths, evidence)
})
.transpose()?;
let private_engagement_summary = if self.backend_engagement_json.is_some()
&& backend == Backend::Ptrace
&& self.summary_json.is_none()
{
let file = private_backend_engagement_summary()?;
self.summary_json = Some(if guest_capture.is_some() {
file.path().to_owned()
} else {
private_summary_descriptor_path(&file)
});
Some(file)
} else {
None
};
match backend {
Backend::Ptrace
| Backend::Liteinst
| Backend::Sabre
| Backend::Kvm
| Backend::E9patch => {}
Backend::Dbt => {
let environment = self.guest_command()?.get_captured_envs();
let config = hermit::prepare_backend_config(self.effective_det_config(), backend);
let retained_log_dir = self.retained_verify_log_dir()?;
return super::backends::run_dbt(
&self.program,
&self.args,
self.verify,
self.verify_verbose,
self.verify_allow,
self.print_verify_logs,
self.keep_logs,
retained_log_dir.as_deref(),
self.verify_json.as_deref(),
self.summary,
self.backend_engagement_json.as_deref(),
global.log,
global.log_file.as_deref(),
&config,
environment,
self.workdir.as_deref().map(Path::new),
dbt_verification_stdin,
);
}
}
if backend == Backend::Liteinst {
match self.liteinst_runtime()? {
LiteinstRuntime::HostHybrid => {
self.verify_liteinst_activation()?;
eprintln!(
"hermit: [liteinst host hybrid] activation verified (traps=1, hooks=31); Detcore Tool active in ptrace host"
);
}
LiteinstRuntime::InGuest => eprintln!(
"hermit: [liteinst in-guest] selected: the guest preload is to host the Detcore Tool; the host-hybrid activation probe does not apply"
),
}
}
if self.no_namespace {
eprintln!(
"WARNING: --no-namespace is not a sandbox; run trusted guests only. The guest \
inherits the caller UID/GID/capabilities and shares host /proc, filesystem, /tmp, \
localhost/network, ports, Unix sockets, and mutable state between runs. Unsupported \
syscalls can mutate host state; --verify may be less deterministic due to shared state."
);
}
if self.namespace_only {
self.run_with_namespace_only(global)
} else if self.verify {
self.verify(global)
} else {
let (status, _) = self.run_with_guest_capture(global, false, guest_capture.as_ref())?;
if let Some(capture) = &mut guest_capture {
let config = hermit::prepare_backend_config(
self.effective_det_config(),
self.runtime_backend(),
);
capture.finish(
self.selected_backend(),
status,
GuestRunDeterminism {
detlog_io_buffers: config.detlog_io_buffers,
virtualize_time: config.virtualize_time,
},
)?;
}
self.write_backend_engagement_after_run(guest_capture.as_ref())?;
drop(private_engagement_summary);
Ok(status)
}
}
pub fn validate_args(&mut self) -> Result<(), Error> {
let liteinst_runtime = self.liteinst_runtime()?;
let perf_supported = !self.arms_reverie_ptrace_pmu_timer()
|| liteinst_runtime == LiteinstRuntime::InGuest
|| reverie_ptrace::is_perf_supported();
self.validate_args_with_perf_support(perf_supported)?;
self.refuse_unqualified_liteinst_in_guest_options(liteinst_runtime)
}
fn arms_reverie_ptrace_pmu_timer(&self) -> bool {
!self.namespace_only
&& match self.selected_backend() {
Backend::Ptrace | Backend::Liteinst | Backend::E9patch => true,
Backend::Dbt | Backend::Sabre | Backend::Kvm => false,
}
}
fn validate_args_with_perf_support(&mut self, perf_supported: bool) -> Result<(), Error> {
let backend = self.selected_backend();
if self.run_evidence_dir.is_some() {
let limitation = match backend {
Backend::Ptrace | Backend::Liteinst | Backend::Kvm => None,
Backend::Dbt => Some(
"authenticated DBT evidence currently implies an isolated process group, \
which can change guest setsid/setpgid results",
),
Backend::Sabre => Some(
"the SaBRe plugin currently emits DETLOG only on shared stderr, which is not \
an authoritative private evidence channel",
),
Backend::E9patch => Some(
"e9patch preprocessing has not been qualified for this evidence contract; \
request the ptrace backend directly",
),
};
if let Some(limitation) = limitation {
return Err(Error::new(PolicyRefusal).context(format!(
"--run-evidence-dir is unavailable for backend `{}`: {limitation}",
backend.as_str()
)));
}
}
if self.skid_margin.is_some()
&& (self.namespace_only
|| !matches!(
backend,
Backend::Ptrace | Backend::Liteinst | Backend::E9patch
))
{
anyhow::bail!(
"--skid-margin configures the Reverie ptrace PMU timer and requires a ptrace-backed backend"
);
}
if self.image.is_some() && self.no_namespace {
anyhow::bail!(
"--image chroots the guest into a materialized OCI rootfs, which requires mount \
and PID namespaces; it is incompatible with --no-namespace"
);
}
if self.image.is_some() && backend != Backend::Ptrace {
anyhow::bail!(
"--image currently supports only the ptrace backend; backend `{}` has separate \
launcher/runtime-file requirements that have not been qualified inside the OCI rootfs",
backend.as_str()
);
}
if backend == Backend::Dbt && (!self.mount.is_empty() || !self.bind.is_empty()) {
anyhow::bail!(
"the dbt backend cannot apply --mount or --bind because its DynamoRIO adapter \
does not enter the guest mount namespace"
);
}
if self.backend_engagement_json.is_some()
&& !matches!(backend, Backend::Ptrace | Backend::E9patch | Backend::Dbt)
{
anyhow::bail!(
"--backend-engagement-json is not available for backend `{}`; SaBRe publishes \
HERMIT_SABRE_PATH_EVIDENCE, and liteinst/KVM expose no engagement value",
backend.as_str()
);
}
if self.image.is_some() && self.namespace_only {
anyhow::bail!("--image cannot be combined with --namespace-only");
}
if self.image.is_some() && (!self.mount.is_empty() || !self.bind.is_empty()) {
anyhow::bail!(
"--image does not yet compose with custom --mount/--bind targets inside the OCI rootfs"
);
}
let config = &mut self.det_opts.det_config;
let backend_applies_uts_hostname = !matches!(backend, Backend::Dbt);
config.has_uts_namespace = !self.no_namespace && backend_applies_uts_hostname;
if self.no_namespace {
self.network = NetworkingMode::Host;
self.tmp = Some(PathBuf::from(TMP_DIR));
}
if self.analyze_networking {
config.warn_non_zero_binds = true;
}
config.sequentialize_threads = self.strict || !self.no_sequentialize_threads;
config.deterministic_io = self.strict || !self.no_deterministic_io;
config.panic_on_unsupported_syscalls = !self.allow_unsupported_syscalls;
if config.passthru_opt && config.panic_on_unsupported_syscalls {
anyhow::bail!(
"--passthru-opt cannot be combined with fail-closed unsupported-syscall handling \
(the default; pass --allow-unsupported-syscalls to opt out)"
);
}
config.shutdown_on_unsupported_syscall = config.panic_on_unsupported_syscalls;
if config.virtualize_metadata && !config.virtualize_time {
anyhow::bail!(
"--no-virtualize-time also requires --no-virtualize-metadata; metadata timestamps \
cannot be virtualized without virtual time"
);
}
if !(0.0..=1.0).contains(&config.sched_sticky_random_param) {
anyhow::bail!(
"--sched-sticky-random-param must be between 0 and 1 inclusive (received {})",
config.sched_sticky_random_param
);
}
if let Some(multiplier) = config.clock_multiplier
&& (!multiplier.is_finite() || multiplier <= 0.0)
{
anyhow::bail!(
"--clock-multiplier must be finite and positive (received {})",
multiplier
);
}
let minimum_max_timeslice = config.minimum_max_timeslice_nanos();
if let Some(max_timeslice) = config.max_timeslice
&& u64::from(max_timeslice) < minimum_max_timeslice
{
anyhow::bail!(
"--max-timeslice must be at least one RCB ({} virtual nanoseconds at this clock multiplier)",
minimum_max_timeslice
);
}
config.validate();
if config.max_timeslice.is_some() && !perf_supported {
let mut stderr = detcore::util::RetryingStderr;
let _ = writeln!(
stderr,
"WARNING: --max-timeslice requires user-space perf counters, but \
perf_event_open is unavailable; continuing with \
--max-timeslice=disabled. Check the host perf_event_paranoid value and \
container seccomp policy."
);
config.max_timeslice = None;
}
if let Some(sf) = &self.seed_from {
let seed = match sf {
SeedFrom::Args => {
let mut hasher = DefaultHasher::new();
self.args.hash(&mut hasher);
self.program.hash(&mut hasher);
hasher.finish()
}
SeedFrom::SystemRandom => rand::random::<u64>(),
};
eprintln!(
"[hermit] auto setting --seed {0:?} --sched-seed {0:?}",
seed
);
config.seed = seed;
}
if config.max_timeslice.is_some() && config.sequentialize_threads {
self.pin_threads = true;
}
if self.strace_only {
config.virtualize_cpuid = false;
config.virtualize_metadata = false;
config.virtualize_time = false;
config.deterministic_io = false;
self.network = NetworkingMode::Host;
config.sequentialize_threads = false;
config.no_rcb_time = true;
if self.tmp.is_none() {
self.tmp = Some(PathBuf::from("/tmp"));
}
}
if self.happens_before.is_some() && !config.sequentialize_threads {
anyhow::bail!(
"--happens-before requires deterministic sequential thread execution; remove \
--no-sequentialize-threads (and --strace-only) so the scheduler can enforce \
ordering edges"
);
}
if self.det_opts.det_config.gdbserver && self.network == NetworkingMode::Local {
if self.analyze_networking {
anyhow::bail!(
"--gdbserver requires host networking so a host gdb client can reach the \
gdbserver port, but --analyze-networking forces an isolated network \
namespace. Run these two modes separately."
);
}
eprintln!(
"WARNING: --gdbserver requires host networking so a host gdb client can reach \
the gdbserver port; overriding --network=local with --network=host for this \
debug session. Network isolation and deterministic networking are disabled \
while the gdbserver is attached."
);
self.network = NetworkingMode::Host;
}
if self.strict && self.network == NetworkingMode::Host {
let cause = if self.no_namespace {
"--no-namespace, which forces host networking"
} else if self.det_opts.det_config.gdbserver {
"--gdbserver, which forces host networking"
} else {
"--network=host"
};
anyhow::bail!(
"--strict is fail-closed deterministic mode and cannot be combined with {}: \
host networking exposes the guest to external traffic that hermit does not \
determinize. Re-run without --strict to allow it deliberately.",
cause
);
}
let virtualize_time = self.det_opts.det_config.virtualize_time;
if let Some(warning) =
vmm_time_virtualization_warning(&self.program, &self.args, virtualize_time)
{
eprintln!("{warning}");
}
Ok(())
}
fn install_pmu_config(&self) -> Result<(), Error> {
let Some(skid_margin) = self.skid_margin else {
return Ok(());
};
let config = reverie_ptrace::PmuConfig::new().with_skid_margin_override(skid_margin);
reverie_ptrace::set_pmu_config(config).map_err(|_| {
anyhow::anyhow!(
"Reverie PMU configuration was initialized before --skid-margin could be applied"
)
})
}
fn validate_mount_sources(&self) -> Result<(), Error> {
for bind in &self.bind {
let source = Path::new(OsStr::from_bytes(bind.source.to_bytes()));
if !source.exists() {
anyhow::bail!(
"--bind source {} does not exist. Create it or correct the source path before \
starting Hermit.",
source.display()
);
}
}
for mount in &self.mount {
if let Some(source) = mount.get_source()
&& !source.exists()
{
anyhow::bail!(
"--mount source {} does not exist. Create it or correct the source path \
before starting Hermit.",
source.display()
);
}
}
Ok(())
}
fn validate_e9patch_mount_targets(&self) -> Result<(), Error> {
for bind in &self.bind {
let target = Path::new(OsStr::from_bytes(bind.target.to_bytes()));
validate_e9patch_mount_target(target)?;
}
for mount in &self.mount {
validate_e9patch_mount_target(mount.get_target())?;
}
Ok(())
}
fn resolve_e9patch_overlay_target(&self, guest: &Path, host: &Path) -> Result<PathBuf, Error> {
let canonical = fs::canonicalize(host)
.with_context(|| format!("failed to resolve executable {}", host.display()))?;
match self.mapped_host_program(guest) {
GuestPathMapping::Mapped(mapped) => {
let mapped = std::path::absolute(mapped)?;
if canonical != mapped {
anyhow::bail!(
"e9patch cannot safely overlay symlinked executable {} through a custom \
guest mount; use the resolved executable path or remove the mount",
guest.display()
);
}
Ok(guest.to_path_buf())
}
GuestPathMapping::Unchanged => {
let host = std::path::absolute(host)?;
let symlinked = canonical != host;
let tmp_is_remapped =
self.tmp.as_deref() != Some(Path::new(TMP_DIR)) || !self.bind.is_empty();
let crosses_implicit_mount = symlinked
&& ((tmp_is_remapped
&& path_resolution_visits_prefix(&host, Path::new(TMP_DIR))?)
|| path_resolution_visits_prefix(&host, Path::new("/proc"))?);
if symlinked && (!self.mount.is_empty() || crosses_implicit_mount) {
anyhow::bail!(
"e9patch cannot safely resolve symlinked executable {} across guest \
mounts; use its resolved guest path or remove the relevant mounts",
guest.display()
);
}
let canonical_guest = normalize_guest_path(&canonical)?;
match self.mapped_host_program(&canonical_guest) {
GuestPathMapping::Mapped(mapped)
if std::path::absolute(&mapped)? != canonical =>
{
anyhow::bail!(
"e9patch cannot safely resolve executable {} because a custom guest \
mount changes its canonical target {}; use the resolved guest path",
guest.display(),
canonical_guest.display()
);
}
GuestPathMapping::Hidden => anyhow::bail!(
"Program {} is hidden by a mount after resolving symlinks",
guest.display()
),
GuestPathMapping::Mapped(_) | GuestPathMapping::Unchanged => {}
}
Ok(canonical_guest)
}
GuestPathMapping::Hidden => anyhow::bail!(
"Program {} is not visible through the configured guest mounts",
guest.display()
),
}
}
fn mapped_host_program(&self, program: &Path) -> GuestPathMapping {
for bind in self.bind.iter().rev() {
let source = Path::new(OsStr::from_bytes(bind.source.to_bytes()));
let target = Path::new(OsStr::from_bytes(bind.target.to_bytes()));
if !target.starts_with(TMP_DIR) {
continue;
}
if let Some(path) = mapped_path(program, source, target) {
return GuestPathMapping::Mapped(path);
}
}
for mount in self.mount.iter().rev() {
let target = mount.get_target();
if let Ok(suffix) = program.strip_prefix(target) {
return match mount.get_source() {
Some(source) => GuestPathMapping::Mapped(source.join(suffix)),
None => GuestPathMapping::Hidden,
};
}
}
if let Ok(suffix) = program.strip_prefix(TMP_DIR) {
return self
.tmp
.as_ref()
.map(|tmp| GuestPathMapping::Mapped(tmp.join(suffix)))
.unwrap_or(GuestPathMapping::Hidden);
}
GuestPathMapping::Unchanged
}
fn guest_current_dir(&self, command: &Command) -> Result<PathBuf, Error> {
let directory = command
.get_current_dir()
.map(Path::to_path_buf)
.unwrap_or(std::env::current_dir()?);
let absolute = if directory.is_absolute() {
directory
} else {
std::path::absolute(directory)?
};
normalize_guest_path(&absolute)
}
fn mapped_or_visible_host_program(&self, guest: &Path) -> Option<PathBuf> {
match self.mapped_host_program(guest) {
GuestPathMapping::Mapped(host) => Some(host),
GuestPathMapping::Hidden => None,
GuestPathMapping::Unchanged => Some(guest.to_path_buf()),
}
}
fn load_and_resolve_happens_before(&self) -> Result<HappensBeforeProgram, Error> {
let spec_path = self
.happens_before
.as_ref()
.expect("load_and_resolve_happens_before requires --happens-before");
let mut program = load_program(spec_path)?;
let (_, host) = self.resolve_guest_and_host_program()?;
match DebugInfoResolver::open(&host) {
Ok(resolver) if !resolver.is_empty() => {
let unresolved = resolve_program(&mut program, &resolver);
if !unresolved.is_empty() {
eprintln!(
"hermit: {} happens-before anchor(s) with unresolved code locations \
(they will never fire): {}",
unresolved.len(),
unresolved.join(", ")
);
}
}
Ok(_) => {
let unresolved: Vec<String> = program
.unresolved_locations()
.map(|a| a.name.clone())
.collect();
if !unresolved.is_empty() {
eprintln!(
"hermit: {} has no usable symbol/debug info; {} code-location anchor(s) \
will never fire: {}",
host.display(),
unresolved.len(),
unresolved.join(", ")
);
}
}
Err(err) => {
eprintln!(
"hermit: could not read debug info from {}: {:#}; code-location anchors will \
never fire",
host.display(),
err
);
}
}
Ok(program)
}
fn list_happens_before_events(&self) -> Result<ExitStatus, Error> {
let spec_path = self
.happens_before
.as_ref()
.expect("--hb-list-events requires --happens-before");
let mut program = load_program(spec_path)?;
let (_, host) = self.resolve_guest_and_host_program()?;
let resolver = match DebugInfoResolver::open(&host) {
Ok(r) if !r.is_empty() => Some(r),
Ok(_) => {
eprintln!(
"hermit: {} has no usable symbol/debug info; code-location anchors will not \
resolve",
host.display()
);
None
}
Err(err) => {
eprintln!(
"hermit: could not read debug info from {}: {:#}",
host.display(),
err
);
None
}
};
let unresolved = match &resolver {
Some(r) => resolve_program(&mut program, r),
None => program
.unresolved_locations()
.map(|a| a.name.clone())
.collect(),
};
println!(
"happens-before program: {} anchor(s), {} edge(s)",
program.anchors.len(),
program.edges.len()
);
println!("anchors:");
for (name, anchor) in &program.anchors {
println!(
" {} = {}",
name,
describe_anchor(anchor, resolver.as_ref())
);
}
println!("edges:");
for edge in &program.edges {
let op = match edge.strength {
Strength::Hard => "<",
Strength::Soft => "<~",
};
println!(" {} {} {}", edge.before, op, edge.after);
}
if !unresolved.is_empty() {
eprintln!(
"hermit: {} anchor(s) with unresolved code locations: {}",
unresolved.len(),
unresolved.join(", ")
);
}
Ok(ExitStatus::SUCCESS)
}
fn resolve_guest_and_host_program(&self) -> Result<(PathBuf, PathBuf), Error> {
let command = self.guest_command()?;
let requested = Path::new(command.get_program());
if requested.is_absolute() {
let requested = normalize_guest_path(requested)?;
if let Some(host) = self.mapped_or_visible_host_program(&requested) {
return Ok((requested, host));
}
if requested.starts_with(TMP_DIR) && requested.exists() {
anyhow::bail!(
"Program {} is under host /tmp, but Hermit replaces guest /tmp with an \
isolated directory. Pass --tmp=/tmp to expose host /tmp or bind the program \
to a guest path under /tmp.",
requested.display()
);
}
anyhow::bail!(
"Program {} is not visible through the configured guest mounts",
requested.display()
);
}
let current_dir = self.guest_current_dir(&command)?;
if requested.components().count() > 1 {
let guest = normalize_guest_path(¤t_dir.join(requested))?;
let host = self.mapped_or_visible_host_program(&guest).ok_or_else(|| {
Error::msg(format!(
"Program {} is not visible through the configured guest mounts",
requested.display()
))
})?;
return Ok((guest, host));
}
let environment = command.get_captured_envs();
let path = environment
.get(OsStr::new("PATH"))
.cloned()
.unwrap_or_default();
for directory in path
.as_bytes()
.split(|byte| *byte == b':')
.map(|bytes| Path::new(OsStr::from_bytes(bytes)))
{
let candidate = if directory.is_absolute() {
directory.join(requested)
} else {
current_dir.join(directory).join(requested)
};
let guest = normalize_guest_path(&candidate)?;
let Some(host) = self.mapped_or_visible_host_program(&guest) else {
continue;
};
if fs::metadata(&host).is_ok_and(|metadata| {
metadata.is_file() && metadata.permissions().mode() & 0o111 != 0
}) {
return Ok((guest, host));
}
}
anyhow::bail!(
"Could not resolve program {:?} in the guest PATH. Check PATH or use an absolute \
executable path.",
requested
)
}
fn validate_summary_json_visibility(&self) -> Result<(), Error> {
let Some(path) = self.summary_json.as_deref() else {
return Ok(());
};
if self.no_namespace
|| self.namespace_only
|| self.image.is_some()
|| self.selected_backend() == Backend::Dbt
|| !path.is_absolute()
{
return Ok(());
}
let hidden = match self.mapped_host_program(path) {
GuestPathMapping::Hidden => true,
GuestPathMapping::Mapped(host) => self.tmp.as_deref().is_some_and(|tmp| {
tmp != Path::new(TMP_DIR)
&& path
.strip_prefix(TMP_DIR)
.is_ok_and(|suffix| host == tmp.join(suffix))
}),
GuestPathMapping::Unchanged => false,
};
if hidden {
let (cause, remedy) = if path.starts_with(TMP_DIR) {
(
"it is under host /tmp, but Hermit replaces guest /tmp with an isolated \
directory (or the --tmp directory)",
"Write it outside /tmp, or pass --tmp=/tmp to expose host /tmp.",
)
} else {
(
"a --mount without a source hides it",
"Write it outside that mount.",
)
};
anyhow::bail!(
"--summary-json {} is not visible inside the run container: {cause}. The summary \
is written from inside the container, so it would be lost. {remedy}",
path.display()
);
}
Ok(())
}
fn validate_program(&self) -> Result<(), Error> {
if let Some(image) = &self.image {
let rootfs = crate::image::materialize_rootfs(image)?;
let command = self.guest_command()?;
let requested = Path::new(command.get_program());
let guest_cwd = command
.get_current_dir()
.map(Path::to_path_buf)
.unwrap_or_else(|| PathBuf::from("/"));
let guest_abs = resolve_image_guest_program(requested, &guest_cwd)?;
let in_rootfs = crate::image::resolve_in_rootfs(&rootfs, &guest_abs);
return validate_executable(&in_rootfs, &guest_abs, Some(&rootfs));
}
if self.selected_backend() == Backend::E9patch {
let (_, host) = self.resolve_guest_and_host_program()?;
return validate_executable(&host, &self.program, None);
}
let command = self.guest_command()?;
let requested = Path::new(command.get_program());
if requested.is_absolute() {
if let GuestPathMapping::Mapped(host) = self.mapped_host_program(requested) {
return validate_executable(&host, requested, None);
}
if requested.starts_with(TMP_DIR) && self.tmp.is_none() && requested.exists() {
anyhow::bail!(
"Program {} is under host /tmp, but Hermit replaces guest /tmp with an \
isolated directory. Pass --tmp=/tmp to expose host /tmp or bind the program \
into guest /tmp.",
requested.display()
);
}
return validate_executable(requested, requested, None);
}
let resolved = command
.find_program()
.with_context(|| {
format!(
"Could not resolve program {:?} in the guest PATH. Check PATH or use an absolute \
executable path.",
requested
)
})
.map_err(|error| error.context(GuestProgramFault::NotFound))?;
validate_executable(&resolved, requested, None)
}
fn validate_e9patch_source_visibility(&self, source: &Path) -> Result<(), Error> {
for mount in &self.mount {
let target = mount.get_target();
if !target.starts_with(TMP_DIR) && source.starts_with(target) {
anyhow::bail!(
"--mount target {} would hide the cached e9patch artifact {}; choose a more \
specific mount target or a different instruction-map cache directory",
target.display(),
source.display()
);
}
}
Ok(())
}
fn prepare_e9patch_program(&mut self) -> Result<(), Error> {
let (guest, host) = self.resolve_guest_and_host_program()?;
self.e9patch_program = Some(guest.clone());
let overlay_target = self.resolve_e9patch_overlay_target(&guest, &host)?;
if !is_elf_file(&host)? {
self.e9patch_engagement = Some(BackendEngagement::E9patch {
candidate_sites: 0,
mapped_sites: 0,
b0_sites: 0,
});
self.e9patch_sites = Some(reverie::SiteCounters::default());
eprintln!(
":: Backend: e9patch preprocessing + ptrace runtime; mapped_sites=0; \
main_executable=non-ELF; preprocessing=not-applicable"
);
return Ok(());
}
if let Some(reason) = hermit::e9patch::unavailable_reason() {
anyhow::bail!("backend `e9patch` is unavailable: {reason}");
}
let prepared = hermit::e9patch::prepare(&host)?;
self.e9patch_engagement = Some(BackendEngagement::E9patch {
candidate_sites: u64::try_from(prepared.candidate_sites)
.map_err(|_| Error::msg("e9patch candidate-site count does not fit u64"))?,
mapped_sites: u64::try_from(prepared.patched_sites)
.map_err(|_| Error::msg("e9patch mapped-site count does not fit u64"))?,
b0_sites: u64::try_from(prepared.b0_sites)
.map_err(|_| Error::msg("e9patch B0-site count does not fit u64"))?,
});
self.e9patch_sites = Some(reverie::SiteCounters::from_rewrite(
prepared.candidate_sites as u64,
prepared.patched_sites as u64,
));
if prepared.patched_sites != 0 {
self.validate_e9patch_mount_targets()?;
self.validate_e9patch_source_visibility(&prepared.binary)?;
self.e9patch_overlay = Some(E9patchOverlay {
source: prepared.binary,
target: overlay_target,
});
}
let rewrite_cache = if prepared.patched_sites == 0 {
"not-applicable"
} else if prepared.rewrite_cache_hit {
"hit"
} else {
"miss"
};
eprintln!(
":: Backend: e9patch preprocessing + ptrace runtime; candidate_sites={}; \
mapped_sites={}; b0_sites={}; \
instruction_map_cache={:?}; rewrite_cache={}; artifact_sha256={}; \
preprocess_us={}",
prepared.candidate_sites,
prepared.patched_sites,
prepared.b0_sites,
prepared.instruction_map_cache_status,
rewrite_cache,
prepared.artifact_sha256.as_deref().unwrap_or("none"),
prepared.preprocess_micros,
);
if let Some(shape) = &prepared.patch_shape {
eprintln!(
":: e9patch patch-shape stats (selected=e9patch, runtime=ptrace, \
scope=root-image): {shape}"
);
}
Ok(())
}
fn write_backend_engagement_after_run(
&self,
guest_capture: Option<&GuestRunCaptureSession>,
) -> Result<(), Error> {
let Some(path) = &self.backend_engagement_json else {
return Ok(());
};
let engagement = match self.selected_backend() {
Backend::Ptrace => {
let summary_path = self.summary_json.as_deref().ok_or_else(|| {
Error::msg("ptrace backend engagement requires a typed run summary")
})?;
let summary = fs::read(summary_path)
.with_context(|| {
format!(
"reading ptrace backend engagement from {}",
summary_path.display()
)
})
.and_then(|bytes| {
serde_json::from_slice::<RunSummary>(&bytes).with_context(|| {
format!(
"parsing ptrace backend engagement from {}",
summary_path.display()
)
})
})?;
BackendEngagement::Ptrace {
scheduler_turns: summary.sched_turns,
}
}
Backend::E9patch => self.e9patch_engagement.clone().ok_or_else(|| {
Error::msg("e9patch backend engagement was not recorded during preparation")
})?,
Backend::Dbt => unreachable!("the DBT adapter writes its own engagement record"),
Backend::Liteinst | Backend::Sabre | Backend::Kvm => {
return Err(Error::msg(format!(
"backend `{}` does not expose an engagement value",
self.selected_backend().as_str()
)));
}
};
if let Some(capture) = guest_capture {
capture.require_distinct_from(path, "--backend-engagement-json")?;
}
write_backend_engagement(path, engagement)
}
fn tmpfs(&self) -> Result<Tmpfs, Error> {
match self.tmp.as_ref() {
Some(path) => {
let path = path.as_path();
fs::create_dir_all(path)?;
Ok(Tmpfs::Path(path.to_path_buf()))
}
None => Ok(Tmpfs::Temp(tempfile::TempDir::new()?)),
}
}
pub fn run(
&self,
global: &GlobalOpts,
capture_output: bool,
) -> Result<(ExitStatus, Option<Output>), Error> {
self.run_with_guest_capture(global, capture_output, None)
}
fn run_with_guest_capture(
&self,
global: &GlobalOpts,
capture_output: bool,
guest_capture: Option<&GuestRunCaptureSession>,
) -> Result<(ExitStatus, Option<Output>), Error> {
let summary_output = if guest_capture.is_some() && self.summary_json.is_some() {
Some(super::staged_summary::private_output(
&private_summary_dir()?,
)?)
} else {
None
};
let options = self.clone();
let global = global.clone();
let guest_capture = guest_capture
.map(GuestRunCaptureSession::try_clone_for_child)
.transpose()?;
let timeout = self.run_timeout();
if self.no_namespace {
let mut process = Container::new();
apply_affinity(&mut process, self.pin_threads);
return super::owned_container::run(
&mut process,
summary_output,
"held summary/output descriptors; no PID namespace".into(),
false,
"with_container",
timeout,
move |summary| {
options.run_in_container(
&global,
capture_output,
guest_capture.as_ref(),
summary.as_ref(),
None,
)
},
)
.map(|(value, _guards)| value);
}
let tmpfs = self.tmpfs()?;
let (mut container, identity) = self.container(tmpfs.path())?;
let resources = format!(
"private tmp {}, identity mounts and summary/output descriptors",
tmpfs.path().display()
);
super::owned_container::run(
&mut container,
(tmpfs, identity, summary_output),
resources,
true,
"with_container",
timeout,
move |(_, identity, summary)| {
options.run_in_container(
&global,
capture_output,
guest_capture.as_ref(),
summary.as_ref(),
Some(identity),
)
},
)
.map(|(value, _guards)| value)
}
fn run_with_namespace_only(&self, global: &GlobalOpts) -> Result<ExitStatus, Error> {
let _guard = global.init_tracing_for_backend(self.runtime_backend());
let tmpfs = self.tmpfs()?;
let PreparedMounts {
mounts,
identity_sources: _identity_sources,
} = self.mounts(tmpfs.path())?;
let mut command = self.namespace_only_guest_command()?;
unsafe {
command.pre_exec(|| {
if libc::prctl(libc::PR_SET_PDEATHSIG, libc::SIGKILL) == -1 {
return Err(Errno::last());
}
hermit::proc_mount::warn_if_readonly_proc();
Ok(())
});
}
command
.unshare(Namespace::PID)
.map_root()
.hostname("hermetic-container.local")
.domainname("local")
.mount(Mount::proc().allow_readonly_fallback())
.mounts(mounts);
match &self.network {
NetworkingMode::Local => {
command.local_networking_only();
}
NetworkingMode::Host => {}
}
let mut child = command.spawn()?;
let exit_status = child.wait_blocking()?;
Ok(exit_status)
}
fn verify(&self, global: &GlobalOpts) -> Result<ExitStatus, Error> {
if let Some(path) = &self.verify_json {
write_pending_verification_json(path)?;
}
let retained_log_dir = self.retained_verify_log_dir()?;
let (log1, log2) = temp_log_files_in("run1", "run2", retained_log_dir.as_deref())
.context("Failed to create verification log files")?;
let (log1_file, log1_path) = log1.into_parts();
let (log2_file, log2_path) = log2.into_parts();
let summary1_file = private_verify_summary()?;
let summary1_path = private_summary_descriptor_path(&summary1_file);
let summary2_path = self.summary_json.as_deref().unwrap_or(&summary1_path);
let mut run1_options = self.clone();
run1_options.summary_json = Some(summary1_path.clone());
let mut run2_options = self.clone();
run2_options.summary_json = Some(summary2_path.to_owned());
let fd_flags_before_run1 = standard_fd_status_flags();
eprintln!(":: {}", "Run1...".yellow().bold());
let (mut out1, skid_overshoots_run1) = match run_verification_execution(
self.verify_json.as_deref(),
VerificationRun::Run1,
|| run1_options.run_verify(log1_file, global),
) {
Ok(result) => result,
Err(mut error) => {
if let Some(overshoot) = error.downcast_ref::<SkidOvershootError>()
&& let Some(path) = &self.verify_json
{
let summary1 = read_verify_summary(&summary1_path);
if let Err(report_error) = write_skid_overshoot_without_comparison_json(
path,
overshoot.count(),
verification_runtime_from_summaries(summary1.as_ref(), None),
None,
) {
error = retain_verification_error(
error,
"publishing skid overshoot",
report_error,
);
}
}
if self.keep_logs {
error = retain_logs_after_verification_error(error, [("run 1", log1_path)]);
}
return Err(error);
}
};
let sabre_syscalls1 = match (self.selected_backend() == Backend::Sabre)
.then(|| extract_sabre_detlogs(&log1_path, &mut out1.stderr))
.transpose()
{
Ok(count) => count,
Err(error) => {
if self.keep_logs {
retain_verification_logs([("run 1", log1_path)])?;
}
return Err(error);
}
};
if self.print_verify_logs {
match fs::read(&log1_path) {
Ok(bytes) => std::io::stderr().write_all(&bytes)?,
Err(err) => eprintln!(
"WARNING: --print-verify-logs could not read first-run log {}: {}",
log1_path.display(),
err
),
}
}
if !self.verify_allow.satisfies(out1.status) {
if skid_overshoots_run1 > 0 {
if let Some(path) = &self.verify_json {
let summary1 = read_verify_summary(&summary1_path);
write_skid_overshoot_without_comparison_json(
path,
skid_overshoots_run1,
verification_runtime_from_summaries(summary1.as_ref(), None),
Some(out1.status),
)?;
}
if self.keep_logs {
retain_verification_logs([("run 1", log1_path)])?;
}
return Err(Error::new(SkidOvershootError::new(skid_overshoots_run1)));
}
let status = describe_exit_status(out1.status);
eprintln!(
"First run errored during --verify, not continuing to a second.\nExit status: {status}\nStdout:\n{}\nStderr:\n{}",
String::from_utf8_lossy(&out1.stdout),
String::from_utf8_lossy(&out1.stderr),
);
if let Some(path) = &self.verify_json {
let summary1 = read_verify_summary(&summary1_path);
let report = first_run_rejected_report(
&out1,
verification_runtime_from_summaries(summary1.as_ref(), None),
);
if let Err(error) = write_report_json(path, &report) {
eprintln!(
"WARNING: could not record the rejected first run in {}: {}",
path.display(),
error
);
}
}
if self.keep_logs {
retain_verification_logs([("run 1", log1_path)])?;
}
return Err(Error::msg(format!("First run during --verify {status}")));
}
let summary1 = take_verify_summary_before_next_run(&summary1_path)?;
if skid_overshoots_run1 > 0
&& let Some(path) = &self.verify_json
{
write_skid_overshoot_without_comparison_json(
path,
skid_overshoots_run1,
verification_runtime_from_summaries(summary1.as_ref(), None),
Some(out1.status),
)?;
}
restore_standard_fd_status_flags(fd_flags_before_run1);
eprintln!(":: {}", "Run2...".yellow().bold());
let (mut out2, skid_overshoots_run2) = match run_verification_execution(
self.verify_json.as_deref(),
VerificationRun::Run2,
|| run2_options.run_verify(log2_file, global),
) {
Ok(result) => result,
Err(mut error) => {
if let Some(overshoot) = error.downcast_ref::<SkidOvershootError>()
&& let Some(path) = &self.verify_json
{
let summary2 = read_verify_summary(summary2_path);
let count = skid_overshoots_run1.saturating_add(overshoot.count());
if let Err(report_error) = write_skid_overshoot_without_comparison_json(
path,
count,
verification_runtime_from_summaries(summary1.as_ref(), summary2.as_ref()),
Some(out1.status),
) {
error = retain_verification_error(
error,
"publishing skid overshoot",
report_error,
);
}
}
if self.keep_logs {
error = retain_logs_after_verification_error(
error,
[("run 1", log1_path), ("run 2", log2_path)],
);
}
return Err(error);
}
};
if let Some(sabre_syscalls1) = sabre_syscalls1 {
let sabre_syscalls2 = match extract_sabre_detlogs(&log2_path, &mut out2.stderr) {
Ok(count) => count,
Err(error) => {
if self.keep_logs {
retain_verification_logs([("run 1", log1_path), ("run 2", log2_path)])?;
}
return Err(error);
}
};
if sabre_syscalls1 == 0 || sabre_syscalls2 == 0 {
if self.keep_logs {
retain_verification_logs([("run 1", log1_path), ("run 2", log2_path)])?;
}
return Err(Error::msg(format!(
"SaBRe verification captured no syscall DETLOG records: run1={sabre_syscalls1}, run2={sabre_syscalls2}"
)));
}
eprintln!(
":: SaBRe syscall DETLOG records included: run1={sabre_syscalls1}, run2={sabre_syscalls2}"
);
}
let mut comparison_options = self.verification_comparison_options();
let success_message = if !comparison_options.compare_io_buffers {
"Success: deterministic. Determinism verified. NOTE: syscall \
output-buffer CONTENT was not compared because \
--no-detlog-io-buffers was given, so a divergence confined to a \
buffer whose length is stable would not have been seen; drop that \
flag to include it."
} else {
"Success: deterministic. Determinism verified."
};
let failure_message = "Failure: nondeterministic.";
let summary2 = read_verify_summary(summary2_path);
let skid_overshoots = skid_overshoots_run1.saturating_add(skid_overshoots_run2);
if skid_overshoots > 0
&& let Some(path) = &self.verify_json
{
write_skid_overshoot_without_comparison_json(
path,
skid_overshoots,
verification_runtime_from_summaries(summary1.as_ref(), summary2.as_ref()),
Some(out1.status),
)?;
}
comparison_options.match_overridden = skid_overshoots > 0;
let mut outcome = compare_two_runs(
ComparedRun {
output: &out1,
log: log1_path,
label: "run 1",
},
ComparedRun {
output: &out2,
log: log2_path,
label: "run 2",
},
comparison_options,
)?;
outcome.runtime = verification_runtime_from_summaries(summary1.as_ref(), summary2.as_ref());
if let Some(path) = &self.verify_json {
if skid_overshoots > 0 {
write_skid_overshoot_verification_json(path, &outcome, skid_overshoots)?;
} else {
write_verification_json(path, &outcome)?;
}
}
if skid_overshoots > 0 {
return Err(Error::new(SkidOvershootError::new(skid_overshoots)));
}
announce_verification_outcome(&outcome, SecondRun::Rerun, success_message, failure_message);
if !outcome.verified() {
emit_compared_guest_output(false, &out1, &out2)?;
return outcome.into_exit_status();
}
let status = outcome.guest_status;
let backend_banner = match self.selected_backend() {
Backend::Kvm => Some("KVM (reverie-kvm KvmGuest<Detcore>)"),
Backend::Liteinst => {
Some("LiteInst host hybrid (reverie-liteinst patch runtime + ptrace Detcore Tool)")
}
Backend::Ptrace | Backend::Dbt | Backend::Sabre | Backend::E9patch => None,
};
if let Some(backend_banner) = backend_banner {
eprintln!(":: Backend: {backend_banner}");
}
emit_compared_guest_output(true, &out1, &out2)?;
Ok(status)
}
fn mounts(&self, tmpfs: &Path) -> Result<PreparedMounts, Error> {
let (mut identity_mounts, identity_sources) = identity_hardening_mounts()?;
let mut identity_sources = identity_sources;
let mut explicit_tmp_mount = false;
let mut user_mounts = Vec::with_capacity(self.mount.len() + self.bind.len());
for mount in &self.mount {
let user_target = mount.get_target();
identity_sources.discard_mounts_shadowed_by(&mut identity_mounts, user_target);
if let Ok(path) = mount.get_target().strip_prefix(TMP_DIR) {
explicit_tmp_mount |= path.as_os_str().is_empty();
user_mounts.push(mount.clone().target(tmpfs.join(path)).touch_target());
} else {
user_mounts.push(mount.clone());
}
}
for bind in &self.bind {
let mount = Mount::from(bind.clone()).rshared();
if let Ok(relative_path) = mount.get_target().strip_prefix(TMP_DIR) {
explicit_tmp_mount |= relative_path.as_os_str().is_empty();
identity_sources
.discard_mounts_shadowed_by(&mut identity_mounts, mount.get_target());
let target = tmpfs.join(relative_path);
user_mounts.push(mount.target(target).touch_target());
} else {
eprintln!(
"WARNING: --bind target {} is outside guest /tmp, so this option has no \
effect; files outside /tmp are already visible unless another mount hides them",
bind.target.to_string_lossy()
);
}
}
if self.tmp.is_none() {
if explicit_tmp_mount {
identity_sources.add_translated_tmp_mountpoint(tmpfs);
} else {
identity_sources.add_private_tmp(tmpfs)?;
}
}
let mut mounts = identity_mounts;
mounts.extend(user_mounts);
if let Some(overlay) = &self.e9patch_overlay {
let target = if let Ok(relative_path) = overlay.target.strip_prefix(TMP_DIR) {
tmpfs.join(relative_path)
} else {
overlay.target.clone()
};
mounts.push(
Mount::bind(&overlay.source, &target)
.readonly()
.touch_target(),
);
mounts.push(
Mount::new(target)
.flags(MountFlags::MS_BIND | MountFlags::MS_REMOUNT | MountFlags::MS_RDONLY),
);
}
mounts.push(Mount::bind(tmpfs, TMP_DIR).rshared());
Ok(PreparedMounts {
mounts,
identity_sources,
})
}
fn container(&self, tmpfs: &Path) -> Result<(Container, IdentityGuard), Error> {
if let Some(image) = &self.image {
let rootfs = crate::image::materialize_rootfs(image)?;
let (mut container, identity_sources) =
image_container(&rootfs, tmpfs, self.pin_threads, self.tmp.is_none())?;
self.network
.configure(&mut container, self.analyze_networking);
return Ok((container, identity_sources));
}
let mut container = default_container(self.pin_threads);
self.network
.configure(&mut container, self.analyze_networking);
let PreparedMounts {
mounts,
identity_sources,
} = self.mounts(tmpfs)?;
container.mounts(mounts);
Ok((container, identity_sources))
}
pub fn run_verify(
&self,
log_file: fs::File,
global: &GlobalOpts,
) -> Result<(Output, u64), Error> {
let options = self.clone();
let global = global.clone();
if self.no_namespace {
let mut process = Container::new();
apply_affinity(&mut process, self.pin_threads);
return super::owned_container::run(
&mut process,
Some(log_file),
"verification log descriptor; no PID namespace".into(),
false,
"with_container",
None,
move |log| options.run_verify_in_container(log, &global, None),
)
.map(|(value, _guards)| value);
}
let tmpfs = self.tmpfs()?;
let (mut container, identity) = self.container(tmpfs.path())?;
let resources = format!(
"private tmp {}, identity mounts and verification log",
tmpfs.path().display()
);
super::owned_container::run(
&mut container,
(tmpfs, identity, Some(log_file)),
resources,
true,
"with_container",
None,
move |(_, identity, log)| options.run_verify_in_container(log, &global, Some(identity)),
)
.map(|(value, _guards)| value)
}
fn merge_from_env_settings(&self, command: &mut Command) -> anyhow::Result<()> {
for (var, m_val) in &self.env {
if let Some(val) = m_val {
command.env(var, val);
} else if let Ok(value) = std::env::var(var) {
command.env(var, &value);
} else {
anyhow::bail!(
"Attempt to pass through env var {}, but it is not set in the host environment",
var
)
}
}
Ok(())
}
fn guest_command(&self) -> Result<Command, Error> {
self.build_guest_command(true)
}
fn namespace_only_guest_command(&self) -> Result<Command, Error> {
self.build_guest_command(false)
}
fn build_guest_command(
&self,
disable_sanitizer_leak_detection_for_guest: bool,
) -> Result<Command, Error> {
let program = self.e9patch_program.as_ref().unwrap_or(&self.program);
let mut command = Command::new(program);
command.args(&self.args);
if self.e9patch_program.is_some() {
command.arg0(&self.program);
}
if let Some(current_dir) = &self.workdir {
command.current_dir(current_dir);
} else if let Some(image) = &self.image {
let cfg = crate::image::read_image_config(image)?;
command.current_dir(cfg.workdir.as_deref().unwrap_or("/"));
}
if let Some(image) = &self.image {
command.env_clear();
let cfg = crate::image::read_image_config(image)?;
let declares_path = cfg.env.iter().any(|(k, _)| k == "PATH");
let declares_home = cfg.env.iter().any(|(k, _)| k == "HOME");
command.env("HOSTNAME", "hermetic-container.local");
if !declares_path {
command.env(
"PATH",
"/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
);
}
if !declares_home {
command.env("HOME", "/root");
}
for (key, value) in &cfg.env {
command.env(key, value);
}
self.merge_from_env_settings(&mut command)?;
return Ok(command);
}
apply_base_and_explicit_environment(&mut command, &self.base_env, &self.env)?;
if disable_sanitizer_leak_detection_for_guest {
disable_sanitizer_leak_detection(&mut command);
}
Ok(command)
}
fn save_config_to_disk(&self) -> Result<(), Error> {
if let Some(path) = &self.save_config {
let mut file = File::create(path)?;
file.write_all(format!("{:#?}\n", self).as_bytes())?;
}
Ok(())
}
fn effective_det_config(&self) -> DetConfig {
let mut config = self.det_opts.det_config.clone();
if !self.allow_unsupported_syscalls
&& std::env::var(FAIL_CLOSED_ENV).is_ok_and(|value| value == "1")
{
config.panic_on_unsupported_syscalls = true;
}
config.shutdown_on_unsupported_syscall = config.panic_on_unsupported_syscalls;
config.happens_before = self.resolved_happens_before.clone();
config
}
fn run_timeout(&self) -> Option<Duration> {
self.timeout
.map(|seconds| Duration::from_secs(seconds.get()))
}
fn ensure_timeout_supported(&self) -> Result<(), Error> {
if self.timeout.is_none() {
return Ok(());
}
let backend = self.runtime_backend();
if matches!(backend, Backend::Ptrace | Backend::Liteinst) {
return Ok(());
}
Err(Error::new(PolicyRefusal).context(format!(
"--timeout is not qualified on the `{backend:?}` backend and hermit will not \
accept a bound it cannot enforce. Measured 2026-08-26 with `--timeout 3` on a \
guest that never exits: ptrace and liteinst stopped at 3s and reported \
`class=run-timeout`; kvm stopped only via the hard fallback at 13s; sabre and \
dbt did not stop the run at all. Use an outer bound (the cell's \
`timeout_seconds`, or `bin/safehermit --sh-deadline`) on this backend, and see \
docs/TIMEOUT_LADDER.md."
)))
}
fn run_in_container(
&self,
global: &GlobalOpts,
capture_output: bool,
guest_capture: Option<&GuestRunCaptureSession>,
summary_output: Option<&File>,
identity_sources: Option<&IdentityGuard>,
) -> Result<(ExitStatus, Option<Output>), Error> {
let _guard = global.init_tracing_for_backend(self.runtime_backend());
hermit::proc_mount::warn_if_readonly_proc();
if capture_output && guest_capture.is_some() {
anyhow::bail!("internal output capture cannot be combined with harness guest capture");
}
if let (Some(capture), Some(summary)) = (guest_capture, self.summary_json.as_deref()) {
capture.require_distinct_from(summary, "--summary-json")?;
}
let backend = self.runtime_backend();
let mut command = self.guest_command()?;
if let Some(capture) = guest_capture.filter(|_| backend != Backend::Kvm) {
let stderr_fd = capture.stderr_fd_for_guest();
command.stdout(capture.stdout_for_guest()?);
unsafe {
command.pre_exec(move || {
if libc::dup2(stderr_fd, libc::STDERR_FILENO) == -1 {
return Err(Errno::last());
}
Ok(())
});
}
}
let mut config = self.effective_det_config();
config.mountinfo_root_rewrites = identity_sources
.map(IdentityGuard::mountinfo_root_rewrites)
.transpose()?
.unwrap_or_default();
let mountinfo_order = identity_sources
.map(IdentityGuard::mountinfo_identity_order)
.transpose()?
.unwrap_or_default();
config.mountinfo_mount_ids = mountinfo_order;
config.mountinfo_mount_ids_captured = identity_sources.is_some();
config.fdinfo_unlisted_mount_ids.clear();
self.save_config_to_disk()?;
let timeout = self.run_timeout();
super::staged_summary::with_published_summary(
summary_output,
self.summary_json.as_deref(),
guest_capture,
|summary_json| {
let result =
if capture_output || (guest_capture.is_some() && backend == Backend::Kvm) {
let out = hermit::run_with_output_backend_timeout(
command,
config,
self.summary,
summary_json,
backend,
timeout,
)?;
if let Some(capture) = guest_capture {
capture.write_kvm_virtual_console(&out.stdout, &out.stderr)?;
(out.status, None)
} else {
(out.status, Some(out))
}
} else {
let status = hermit::run_with_backend_timeout(
command,
config,
self.summary,
summary_json,
backend,
timeout,
)?;
(status, None)
};
self.relabel_e9patch_dispatch_stats(summary_json)?;
Ok(result)
},
)
}
fn relabel_e9patch_dispatch_stats(&self, summary_json: &Option<PathBuf>) -> Result<(), Error> {
let (Some(path), Some(sites)) = (summary_json, self.e9patch_sites) else {
return Ok(());
};
let mut summary: RunSummary = serde_json::from_slice(
&fs::read(path)
.with_context(|| format!("reading the e9patch run summary {}", path.display()))?,
)
.with_context(|| format!("parsing the e9patch run summary {}", path.display()))?;
let Some(record) = summary.dispatch_stats.as_mut() else {
return Ok(());
};
record.backend = Backend::E9patch.as_str().to_owned();
record.sites = sites;
fs::write(path, serde_json::to_string_pretty(&summary)? + "\n")
.with_context(|| format!("writing the e9patch run summary {}", path.display()))
}
fn run_verify_in_container(
&self,
log_file: &mut Option<fs::File>,
global: &GlobalOpts,
identity_sources: Option<&IdentityGuard>,
) -> Result<(Output, u64), Error> {
hermit::proc_mount::warn_if_readonly_proc();
let log_file = log_file.take().unwrap();
let strictness = self.verification_strictness();
let level = verification_log_level(global.log, strictness, self.verify_verbose);
let limit = log_max_bytes().map_err(Error::msg)?;
let _guard = init_sync_file_tracing(
Some(level),
BoundedWriter::new(log_file, limit),
self.runtime_backend(),
);
let command = self.guest_command()?;
let mut config = self.effective_det_config();
config.mountinfo_root_rewrites = identity_sources
.map(IdentityGuard::mountinfo_root_rewrites)
.transpose()?
.unwrap_or_default();
let mountinfo_order = identity_sources
.map(IdentityGuard::mountinfo_identity_order)
.transpose()?
.unwrap_or_default();
config.mountinfo_mount_ids = mountinfo_order;
config.mountinfo_mount_ids_captured = identity_sources.is_some();
config.fdinfo_unlisted_mount_ids.clear();
self.save_config_to_disk()?;
let result = hermit::run_with_output_backend_timeout_and_skid_overshoots(
command,
config,
self.summary,
&self.summary_json,
self.runtime_backend(),
None,
)?;
self.relabel_e9patch_dispatch_stats(&self.summary_json)?;
Ok(result)
}
}
enum Tmpfs {
Path(PathBuf),
Temp(tempfile::TempDir),
}
impl Tmpfs {
pub fn path(&self) -> &Path {
match self {
Self::Path(path) => path,
Self::Temp(temp) => temp.path(),
}
}
}
#[cfg(test)]
mod tests {
use clap::CommandFactory;
use super::*;
#[test]
fn real_returned_guest_disposition_still_uses_first_run_rejected() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("verify.json");
write_pending_verification_json(&path).unwrap();
let output = run_verification_execution(Some(&path), VerificationRun::Run1, || {
super::super::container::classify_container_result(Container::new().run(|| {
Ok::<_, hermit::SerializableError>(Output {
status: ExitStatus::Signaled(reverie::process::Signal::SIGALRM, false),
stdout: b"returned guest output".to_vec(),
stderr: Vec::new(),
})
}))
})
.unwrap();
let options = RunOpts::parse_from(["run", "--", "/bin/true"]);
assert!(!options.verify_allow.satisfies(output.status));
let report = first_run_rejected_report(&output, None);
write_report_json(&path, &report).unwrap();
let parsed = VerificationReport::from_current_json_slice(&fs::read(path).unwrap()).unwrap();
assert!(matches!(
parsed.no_result_reason,
Some(NoResultReason::FirstRunRejected {
signal: Some(libc::SIGALRM),
..
})
));
assert_eq!(parsed.guest_signal, Some(libc::SIGALRM));
assert!(parsed.comparison.is_none());
}
#[test]
fn first_run_rejected_report_keeps_available_guest_exit_code() {
let output = Output {
status: ExitStatus::Exited(23),
stdout: b"out".to_vec(),
stderr: b"error".to_vec(),
};
let report = first_run_rejected_report(&output, None);
let directory = tempfile::tempdir().unwrap();
let path = directory.path().join("verification.json");
write_report_json(&path, &report).unwrap();
let persisted = VerificationReport::from_current_json_value(
serde_json::from_slice(&fs::read(path).unwrap()).unwrap(),
)
.unwrap();
assert_eq!(persisted.guest_exit_code, Some(23));
assert_eq!(persisted.guest_signal, None);
assert_eq!(
persisted.no_result_reason,
Some(NoResultReason::FirstRunRejected {
exit_code: Some(23),
signal: None,
stdout_bytes: 3,
stderr_bytes: 5,
})
);
}
#[test]
fn run_one_summary_is_empty_again_before_run_two() -> Result<(), Error> {
let file = tempfile::NamedTempFile::new().unwrap();
let summary = RunSummary {
sched_turns: 12,
virttime_elapsed: 34,
syscalls: Some(5),
..Default::default()
};
fs::write(
file.path(),
serde_json::to_vec(&summary).expect("summary fixture serializes"),
)
.unwrap();
let captured = take_verify_summary_before_next_run(file.path())?
.expect("run one summary remains readable");
assert_eq!(captured.sched_turns, 12);
assert_eq!(captured.virttime_elapsed, 34);
assert_eq!(captured.syscalls, Some(5));
assert_eq!(fs::read(file.path()).unwrap(), b"");
Ok::<(), Error>(())
}
#[test]
fn ptrace_engagement_record_reads_the_typed_run_summary() {
let summary_file = tempfile::NamedTempFile::new().unwrap();
let engagement_file = tempfile::NamedTempFile::new().unwrap();
let mut options = run_opts_for(&["hermit", "--backend=ptrace", "run", "/bin/true"]);
options.summary_json = Some(summary_file.path().to_owned());
options.backend_engagement_json = Some(engagement_file.path().to_owned());
for scheduler_turns in [12, 13] {
let summary = RunSummary {
sched_turns: scheduler_turns,
..Default::default()
};
fs::write(summary_file.path(), serde_json::to_vec(&summary).unwrap()).unwrap();
options.write_backend_engagement_after_run(None).unwrap();
let report: BackendEngagementReport =
serde_json::from_slice(&fs::read(engagement_file.path()).unwrap()).unwrap();
assert_eq!(
report.engagement,
BackendEngagement::Ptrace { scheduler_turns }
);
}
}
#[test]
fn e9patch_engagement_record_follows_the_preparation_value() {
let engagement_file = tempfile::NamedTempFile::new().unwrap();
let mut options = run_opts_for(&["hermit", "--backend=e9patch", "run", "/bin/true"]);
options.backend_engagement_json = Some(engagement_file.path().to_owned());
for (candidate_sites, mapped_sites, b0_sites) in [(0, 0, 0), (2, 2, 0)] {
options.e9patch_engagement = Some(BackendEngagement::E9patch {
candidate_sites,
mapped_sites,
b0_sites,
});
options.write_backend_engagement_after_run(None).unwrap();
let report: BackendEngagementReport =
serde_json::from_slice(&fs::read(engagement_file.path()).unwrap()).unwrap();
assert_eq!(
report.engagement,
BackendEngagement::E9patch {
candidate_sites,
mapped_sites,
b0_sites,
}
);
}
}
#[test]
fn exit_status_diagnostic_reports_guest_exit_code_and_signal() {
assert_eq!(
describe_exit_status(ExitStatus::Exited(23)),
"exited with code 23"
);
assert_eq!(
describe_exit_status(ExitStatus::Signaled(
reverie::process::Signal::SIGTERM,
false,
)),
"terminated by signal 15 (SIGTERM)"
);
assert_eq!(
describe_exit_status(ExitStatus::Signaled(
reverie::process::Signal::SIGSEGV,
true,
)),
"terminated by signal 11 (SIGSEGV) (core dumped)"
);
}
#[test]
fn verification_report_is_published_before_success_is_announced() {
let source = include_str!("run.rs")
.split_once("#[cfg(test)]\nmod tests {")
.expect("test module")
.0;
let verification = source
.split_once("let mut outcome = compare_two_runs(")
.expect("verification comparison")
.1;
let publish = verification
.find("write_verification_json(path, &outcome)")
.expect("verification report publication");
let announce = verification
.find("announce_verification_outcome(&outcome")
.expect("verification announcement");
assert!(publish < announce);
let call = &verification[announce..];
let call = &call[..call.find(");").expect("end of announcement call")];
assert!(call.contains("SecondRun::Rerun"), "{call}");
}
#[test]
fn skid_overshoot_overrides_a_log_match_for_retention() {
let source = include_str!("run.rs");
let production = source
.split_once("\n#[cfg(test)]\nmod tests {")
.expect("run.rs has a test module")
.0;
let total =
"let skid_overshoots = skid_overshoots_run1.saturating_add(skid_overshoots_run2);";
let overridden = "comparison_options.match_overridden = skid_overshoots > 0;";
let compared = "let mut outcome = compare_two_runs(";
for statement in [total, overridden, compared] {
assert_eq!(
production.matches(statement).count(),
1,
"run.rs must contain `{statement}` exactly once"
);
}
let total_at = production.find(total).unwrap();
let overridden_at = production.find(overridden).unwrap();
let compared_at = production.find(compared).unwrap();
assert!(
total_at < overridden_at && overridden_at < compared_at,
"the skid total must mark the match overridden before the runs are compared"
);
assert!(
!production[overridden_at + overridden.len()..compared_at]
.contains("comparison_options"),
"nothing may replace the options between the override and the comparison"
);
let call = &production[compared_at..];
let call = &call[..call.find(")?;").expect("the comparison call ends")];
assert!(
call.trim_end().ends_with("comparison_options,"),
"the runs must be compared with the options that carry the override:\n{call}"
);
}
#[test]
fn verification_log_flags_are_discoverable_and_old_print_spelling_still_parses() {
let current = RunOpts::try_parse_from([
"run",
"--verify",
"--print-verify-logs",
"--keep-logs",
"--verify-log-dir",
"/tmp/logs",
"/bin/true",
])
.unwrap();
assert!(current.print_verify_logs);
assert!(current.keep_logs);
assert_eq!(current.verify_log_dir, Some(PathBuf::from("/tmp/logs")));
let compatible =
RunOpts::try_parse_from(["run", "--verify", "--verify-logs", "/bin/true"]).unwrap();
assert!(compatible.print_verify_logs);
let mut help = Vec::new();
RunOpts::command().write_long_help(&mut help).unwrap();
let help = String::from_utf8(help).unwrap();
assert!(help.contains("--print-verify-logs"));
assert!(help.contains("--keep-logs"));
assert!(help.contains("--verify-log-dir"));
assert!(!help.contains("--verify-logs"));
assert!(
RunOpts::try_parse_from([
"run",
"--verify",
"--verify-log-dir",
"/tmp/logs",
"/bin/true",
])
.is_err(),
"a retention directory without --keep-logs must be refused"
);
}
#[test]
fn user_selected_retention_directory_is_resolved_and_created() {
let parent = tempfile::tempdir().unwrap();
let requested = parent.path().join("retained");
let options = RunOpts::try_parse_from([
"run",
"--verify",
"--keep-logs",
"--verify-log-dir",
requested.to_str().unwrap(),
"/bin/true",
])
.unwrap();
assert_eq!(
options.retained_verify_log_dir().unwrap(),
Some(fs::canonicalize(requested).unwrap())
);
}
#[test]
fn run_evidence_backend_scope_matches_authoritative_private_sinks() {
for backend in [Backend::Ptrace, Backend::Liteinst, Backend::Kvm] {
let mut options = run_opts_for(&[
"hermit",
&format!("--backend={}", backend.as_str()),
"run",
"--run-evidence-dir=/unused/new-path",
"/bin/true",
]);
options
.validate_args_with_perf_support(true)
.unwrap_or_else(|error| panic!("{backend:?} should be supported: {error:#}"));
}
for (backend, limitation) in [
(Backend::Dbt, "isolated process group"),
(Backend::Sabre, "shared stderr"),
(Backend::E9patch, "not been qualified"),
] {
let mut options = run_opts_for(&[
"hermit",
&format!("--backend={}", backend.as_str()),
"run",
"--run-evidence-dir=/unused/new-path",
"/bin/true",
]);
let error = options.validate_args_with_perf_support(true).unwrap_err();
assert!(error.downcast_ref::<PolicyRefusal>().is_some());
assert!(error.to_string().contains(limitation), "{error:#}");
}
}
#[test]
fn run_evidence_is_only_an_ordinary_instrumented_run_option() {
for incompatible in ["--verify", "--namespace-only"] {
assert!(
RunOpts::try_parse_from([
"run",
"--run-evidence-dir=/unused/new-path",
incompatible,
"/bin/true",
])
.is_err(),
"{incompatible} must remain incompatible with one-run evidence"
);
}
}
#[test]
fn harness_guest_capture_requires_all_paths_and_supported_ordinary_backend() {
let flags = [
"--run-evidence-dir=/unused/evidence",
"--run-result-json=/unused/result.json",
"--guest-stdout=/unused/stdout",
"--guest-stderr=/unused/stderr",
];
let ordinary = RunOpts::parse_from(["run", "/bin/true"]);
assert!(ordinary.guest_run_capture_paths().unwrap().is_none());
for omitted in 0..flags.len() {
let mut args = vec!["run"];
args.extend(
flags
.iter()
.enumerate()
.filter_map(|(index, flag)| (index != omitted).then_some(*flag)),
);
args.push("/bin/true");
assert!(
RunOpts::try_parse_from(args).is_err(),
"accepted capture without {}",
flags[omitted]
);
}
for incompatible in ["--verify", "--namespace-only"] {
let mut args = vec!["run", incompatible];
args.extend(flags);
args.push("/bin/true");
assert!(RunOpts::try_parse_from(args).is_err());
}
for backend in [
Backend::Ptrace,
Backend::Liteinst,
Backend::Kvm,
Backend::Dbt,
Backend::Sabre,
Backend::E9patch,
] {
let backend_arg = format!("--backend={}", backend.as_str());
let mut args = vec!["hermit", backend_arg.as_str(), "run"];
args.extend(flags);
args.push("/bin/true");
let mut options = run_opts_for(&args);
let paths = options.guest_run_capture_paths().unwrap().unwrap();
assert_eq!(paths.result, PathBuf::from("/unused/result.json"));
assert_eq!(paths.stdout, PathBuf::from("/unused/stdout"));
assert_eq!(paths.stderr, PathBuf::from("/unused/stderr"));
let result = options.validate_args_with_perf_support(true);
if matches!(backend, Backend::Ptrace | Backend::Liteinst | Backend::Kvm) {
result.unwrap();
} else {
assert!(
result
.unwrap_err()
.downcast_ref::<PolicyRefusal>()
.is_some()
);
}
}
let paths = GuestRunCapturePaths::new(
PathBuf::from("/result"),
PathBuf::from("/stdout"),
PathBuf::from("/stderr"),
);
assert!(
paths
.require_distinct_from(Some(Path::new("/stdout")), "--summary-json")
.unwrap_err()
.to_string()
.contains("must not reuse the --summary-json path")
);
}
#[test]
fn capture_preflight_preserves_summary_and_engagement_collisions() {
use std::os::unix::fs::MetadataExt as _;
use std::os::unix::fs::symlink;
let global = GlobalOpts::parse_from(["hermit"]);
for option in ["--summary-json", "--backend-engagement-json"] {
for capture_name in ["result.json", "stdout", "stderr"] {
for alias in [false, true] {
let directory = tempfile::tempdir().unwrap();
let root = directory.path();
let target = root.join(capture_name);
fs::write(&target, b"preserve captured artifact").unwrap();
let before = fs::metadata(&target).unwrap();
let companion = if alias {
let alias = root.join("alias");
symlink(&target, &alias).unwrap();
alias
} else {
target.clone()
};
let engagement = root.join("engagement");
fs::write(&engagement, b"preserve engagement").unwrap();
let evidence = root.join("evidence");
fs::create_dir(&evidence).unwrap();
fs::write(evidence.join("already-claimed"), b"preserve evidence").unwrap();
let mut options =
RunOpts::parse_from(["run", "/nonexistent-capture-preflight-guest"]);
assert!(!options.program.exists());
options.run_evidence_dir = Some(evidence.clone());
options.run_result_json = Some(root.join("result.json"));
options.guest_stdout = Some(root.join("stdout"));
options.guest_stderr = Some(root.join("stderr"));
options.backend_engagement_json = Some(engagement.clone());
if option == "--summary-json" {
options.summary_json = Some(companion);
} else {
options.backend_engagement_json = Some(companion);
}
let error = options.main(&global).unwrap_err();
assert!(
error
.to_string()
.contains(&format!("must not reuse the {option} path")),
"{error:#}"
);
let after = fs::metadata(&target).unwrap();
assert_eq!((before.dev(), before.ino()), (after.dev(), after.ino()));
assert_eq!(fs::read(&target).unwrap(), b"preserve captured artifact");
assert_eq!(fs::read(&engagement).unwrap(), b"preserve engagement");
assert_eq!(
fs::read(evidence.join("already-claimed")).unwrap(),
b"preserve evidence"
);
for absent in ["result.json", "stdout", "stderr"]
.into_iter()
.filter(|name| *name != capture_name)
{
assert!(!root.join(absent).exists());
}
}
}
}
let directory = tempfile::tempdir().unwrap();
let root = directory.path();
let evidence = root.join("evidence");
fs::create_dir(&evidence).unwrap();
let paths = GuestRunCapturePaths::new(
root.join("result"),
root.join("stdout"),
root.join("stderr"),
);
let mut options = RunOpts::parse_from(["run", "/nonexistent-capture-preflight-guest"]);
options.summary_json = Some(root.join("summary"));
options.backend_engagement_json = Some(root.join("engagement"));
options.check_capture_companions(&paths).unwrap();
let mut capture = GuestRunCaptureSession::create(&paths, &evidence).unwrap();
capture
.finish(
Backend::Ptrace,
ExitStatus::Exited(0),
GuestRunDeterminism {
detlog_io_buffers: true,
virtualize_time: true,
},
)
.unwrap();
fs::write(
options.summary_json.as_ref().unwrap(),
serde_json::to_vec(&RunSummary {
sched_turns: 12,
..RunSummary::default()
})
.unwrap(),
)
.unwrap();
fs::hard_link(
&paths.result,
options.backend_engagement_json.as_ref().unwrap(),
)
.unwrap();
let result = fs::read(&paths.result).unwrap();
assert!(
options
.write_backend_engagement_after_run(Some(&capture))
.unwrap_err()
.to_string()
.contains("must not reuse the --backend-engagement-json path")
);
assert_eq!(fs::read(&paths.result).unwrap(), result);
fs::remove_file(options.backend_engagement_json.as_ref().unwrap()).unwrap();
options
.write_backend_engagement_after_run(Some(&capture))
.unwrap();
assert_eq!(fs::read(&paths.result).unwrap(), result);
assert!(
!fs::read(options.backend_engagement_json.as_ref().unwrap())
.unwrap()
.is_empty()
);
}
#[test]
fn extracts_sabre_detlogs_and_preserves_guest_stderr() {
let log = tempfile::NamedTempFile::new().unwrap();
std::fs::write(
log.path(),
"2026-08-02T00:00:00.000000Z INFO detcore: coordinator message\n",
)
.unwrap();
let mut stderr = b"guest stderr\n INFO detcore: inbound syscall: getpid() = ?\n\
INFO detcore: DETLOG scheduler event\n\
INFO detcore: DETLOG [syscall] finish syscall #1: getpid() = Ok(3)\n"
.to_vec();
let syscall_records = extract_sabre_detlogs(log.path(), &mut stderr).unwrap();
assert_eq!(syscall_records, 1);
assert_eq!(
stderr,
b"guest stderr\n INFO detcore: inbound syscall: getpid() = ?\n"
);
assert_eq!(
std::fs::read_to_string(log.path()).unwrap(),
"2026-08-02T00:00:00.000000Z INFO detcore: coordinator message\n\
1970-01-01T00:00:00.000000Z INFO detcore: DETLOG scheduler event\n\
1970-01-01T00:00:00.000000Z INFO detcore: DETLOG [syscall] finish syscall #1: getpid() = Ok(3)\n",
);
}
#[test]
fn summary_dir_is_the_work_tree_disposable_directory() {
let tmp = tempfile::tempdir().expect("fixture root");
let root = tmp.path();
std::fs::create_dir(root.join(".git")).expect("fixture work tree");
std::fs::write(root.join(".gitignore"), "/ignored/\n").expect("fixture ignore rule");
let chosen = summary_dir_under(root).expect("resolving from the work-tree root");
assert_eq!(chosen, root.join("ignored"));
assert!(chosen.is_dir(), "the disposable directory was not created");
let nested = root.join("hermit-cli").join("src");
std::fs::create_dir_all(&nested).expect("fixture subdirectory");
assert_eq!(
summary_dir_under(&nested).expect("resolving from a subdirectory"),
root.join("ignored"),
"a summary resolved relative to the subdirectory rather than the work tree"
);
}
#[test]
fn summary_dir_outside_a_work_tree_is_unchanged() {
let tmp = tempfile::tempdir().expect("fixture root");
let plain = tmp.path().join("not-a-checkout");
std::fs::create_dir(&plain).expect("fixture directory");
assert_eq!(
summary_dir_under(&plain).expect("resolving outside a work tree"),
plain,
"the previous behaviour must be kept where nothing enumerates source"
);
}
#[test]
fn a_stray_git_that_does_not_ignore_the_directory_is_not_a_work_tree() {
let tmp = tempfile::tempdir().expect("fixture root");
let stray = tmp.path();
std::fs::create_dir(stray.join(".git")).expect("fixture stray git");
let nested = stray.join("scratch");
std::fs::create_dir(&nested).expect("fixture directory");
assert_eq!(
summary_dir_under(&nested).expect("resolving under a stray git"),
nested,
"a stray .git without an ignore rule was mistaken for the work tree"
);
std::fs::write(stray.join(".gitignore"), "/ignored/\n").expect("fixture ignore rule");
assert_eq!(
summary_dir_under(&nested).expect("resolving under a real work tree"),
stray.join("ignored"),
"a work tree that does ignore the directory was rejected"
);
}
static CWD_GUARD: std::sync::Mutex<()> = std::sync::Mutex::new(());
#[test]
fn both_writers_put_their_summary_in_the_disposable_directory() {
let _guard = CWD_GUARD
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let tmp = tempfile::tempdir().expect("fixture root");
let root = tmp.path().canonicalize().expect("canonical fixture root");
std::fs::create_dir(root.join(".git")).expect("fixture work tree");
std::fs::write(root.join(".gitignore"), "/ignored/\n").expect("fixture ignore rule");
let previous = std::env::current_dir().expect("saving the working directory");
std::env::set_current_dir(&root).expect("entering the fixture work tree");
let produced = [
("verification", private_verify_summary()),
("backend engagement", private_backend_engagement_summary()),
];
std::env::set_current_dir(&previous).expect("restoring the working directory");
let expected = root.join("ignored");
for (what, result) in produced {
let file = result.unwrap_or_else(|error| panic!("{what} summary: {error:#}"));
let parent = file
.path()
.parent()
.expect("a summary has a parent")
.canonicalize()
.expect("canonical summary parent");
assert_eq!(
parent,
expected,
"the {what} summary was written to {} rather than the disposable \
directory, so it is counted as prepared source again",
parent.display()
);
}
}
#[test]
fn summary_dir_refuses_rather_than_falling_back_into_the_work_tree() {
let tmp = tempfile::tempdir().expect("fixture root");
let root = tmp.path();
std::fs::create_dir(root.join(".git")).expect("fixture work tree");
std::fs::write(root.join(".gitignore"), "/ignored/\n").expect("fixture ignore rule");
std::fs::write(root.join("ignored"), b"not a directory").expect("fixture file");
let error = summary_dir_under(root)
.expect_err("a work tree that cannot hold the disposable directory must refuse");
let rendered = format!("{error:#}");
assert!(
rendered.contains("refusing to fall back"),
"the refusal did not say why it refused: {rendered}"
);
}
}