nordisk/heimdall

crates/heimdall-trace/src/lib.rs

// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (C) 2026 Ignalina ApS and Vetra Automation AB

//! heimdall-trace: the dynamic-trace job. **Heimdall is a defensive
//! sandbox.** A package's install or import (`pip install --no-index` of a
//! wheel or sdist from `/in`, `npm install` of a tarball with its scripts on,
//! `python3 -c 'import x'`) runs inside a HeimdallRunner container job with
//! no network, under heimdall-probe's learning filter (seccomp USER_NOTIF),
//! and the job's one output is a canonical trace document of what it did:
//! every exec with its argv, every connect/bind/send-to-an-address (refused),
//! every file call with its path and flags (writes outside `/tmp` flagged and
//! refused), and the syscall set per program. The trace is signed the
//! ordinary way: it is listed with its SHA-256 in the job's
//! [`heimdall_core::SignedResult`].
//!
//! - [`doc`]: the trace document (`heimdall.trace.v1`), canonical JSON.
//! - [`tracer`]: the in-job tracer (the `heimdall-trace` binary, PID 1 of
//!   the job).
//! - [`job`]: [`TraceJob`] (the job to run), [`verify_trace`] and
//!   [`run_trace`] (the caller's side, failing closed to
//!   [`TraceOutcome::Unknown`]).
//! - [`diff`]: a trace against a baseline (a clean package's trace).
//! - [`image`]: a trace image (a worker image plus the tracer layer).
//!
//! The trace job is a plain `JobKind::Native` job: no new job kind or policy
//! flag, so every runner and the signed wire stay as they are. See
//! docs/API.md, "Dynamic-trace jobs".

pub mod classify;
pub mod diff;
pub mod doc;
pub mod image;
pub mod job;
pub mod record;
pub mod tracer;

pub use diff::{diff, TraceDiff};
pub use doc::{
    DocError, ExecEvent, FileEvent, NetEvent, Status, SyscallFact, Trace, FORMAT, TRACE_FILE,
};
pub use job::{run_trace, verify_trace, TraceJob, TraceOutcome, TRACER_PATH};