Crate iso_probe 

iso-probe

Runtime ISO discovery for a live rescue environment. Given a set of root paths (typically the AEGIS_ISOS partition mounted at /run/media/aegis-isos), finds every .iso, loop-mounts it once, extracts per-ISO boot metadata via iso-parser, and returns metadata records suitable for display in a TUI.

Part of the aegis-boot rescue environment — a signed-chain UEFI Secure Boot stick that boots any ISO.

Two-phase API

1. discover — scan roots, mount each ISO once, extract kernel/initrd/cmdline paths, unmount. Returns DiscoveredIso records — metadata only, no live mounts. Safe to display as a picker.
2. prepare — given a user-selected DiscoveredIso, re-mount the ISO and return a PreparedIso whose absolute paths can be fed to kexec-loader::load_and_exec. Mount persists until PreparedIso is dropped, or until kexec replaces the process on the success path.

Design

• Forbid unsafe. Mounting + loopback + path manipulation only. No raw syscalls.
• Sidecar verification. If <iso>.sha256 or <iso>.minisig is present next to the ISO, verifies before reporting. Uses minisign-verify for Ed25519 signatures and sha2 for digests.
• Sync-only API. Callers drive async elsewhere if they want; pollster is available for sync-over-async bridging.

Usage

// Illustrative shape only. Types and paths are consumer-specific;
// the real API is documented in the `discover` and `prepare` items
// below.
use iso_probe::{discover, prepare};

let discovered = discover(&["/run/media/aegis-isos"])?;
for iso in &discovered {
    println!("{} ({})", iso.label, iso.verification.display_summary());
}

// Operator picks one:
let prepared = prepare(&discovered[0])?;
kexec_loader::load_and_exec(&prepared.kernel, &prepared.initrd, &prepared.cmdline)?;

See the API docs for the full surface.

Status

Pre-1.0. API is settling through real-hardware validation on the parent project’s test fleet. Publishing to crates.io at 1.0. Until then, consume via the aegis-boot workspace.

License

Licensed under either of Apache-2.0 or MIT at your option.

---

Rust API — two-phase shape

Runtime ISO discovery on the live aegis-boot rescue environment.

Two-phase API:

1. discover — scan a set of root paths for .iso files, mount each once, extract per-ISO boot metadata (kernel + initrd + cmdline relative to the ISO root), unmount. Returns metadata-only DiscoveredIso records suitable for rendering in the TUI.
2. prepare — given a user-selected DiscoveredIso, re-mount the ISO and return a PreparedIso whose absolute paths can be handed to kexec-loader::load_and_exec. The mount is unmounted when the PreparedIso is dropped — but kexec replaces the process before that happens on the success path, so the live mount persists exactly as long as it needs to.

See ADR 0001.

Re-exports

pub use minisign::SignatureVerification;

pub use minisign::verify_iso_signature;

pub use sidecar::IsoSidecar;

pub use sidecar::SidecarError;

pub use sidecar::load_sidecar;

pub use sidecar::sidecar_path_for;

pub use sidecar::to_toml as sidecar_to_toml;

pub use sidecar::write_sidecar;

pub use signature::HashVerification;

pub use signature::compute_iso_sha256;

pub use signature::verify_iso_hash;

pub use signature::verify_iso_hash_with_progress;

Modules

minisign

Minisign detached signature verification.

sidecar

Operator-curated metadata that travels alongside an ISO.

signature

ISO hash verification against sibling checksum files.

Structs

BootEntry

Represents a discovered boot entry from an ISO

DiscoveredIso

Metadata for a single discovered ISO. Paths are relative to the (now unmounted) ISO root and become absolute once handed to prepare.

DiscoveryReport

Result of discover — every .iso file the scan found, split into the ones that parsed successfully and the ones that didn’t.

FailedIso

A .iso file found on disk that failed to parse. Paired with a human-readable reason and a structured FailureKind for downstream tier mapping.

PreparedIso

A live, loop-mounted ISO with absolute paths suitable for handoff to kexec-loader. Unmounts on drop.

ScanFailure

A single ISO file that failed to yield boot entries during a directory scan.

ScanReport

Result of a directory scan — successful boot entries plus any per-file failures that the caller should surface to the user.

Enums

Distribution

Supported distribution families.

FailureKind

Why an ISO failed to parse. 1-to-1 with ScanFailureKind from iso-parser — re-exposed here so consumers of iso-probe don’t need to depend on iso-parser directly.

IsoError

Errors that can occur during ISO parsing

ProbeError

Errors returned during probing.

Quirk

Compatibility quirks the TUI should surface to the user before invoking kexec. Populated by the per-distro matrix (issue #6).

ScanFailureKind

Structured classification of why an ISO failed to yield boot entries. A 1-to-1 map from the per-file variants of IsoError.

Functions

detect_installer

Heuristic: does this ISO filename indicate an installer image? See INSTALLER_MARKERS for the match list. (#131)

discover

Discover all bootable ISOs under the supplied root directories.

display_description

Optional one-line description for the menu’s second row, sourced from the operator-curated sidecar. Returns None when no sidecar is present or its description field is unset. (#246)

display_name

Preferred human label for display. Resolution order:

lookup_quirks

Look up quirks for a distribution family.

prepare

Re-mount the selected ISO and return absolute paths for kexec handoff.