nordisk/heimdall

The heimdall command line

Heimdall is a defensive sandbox. Milestone 1 runs wasm jobs only.

heimdall run --job wasm --module <guest.wasm> --trust-root <root.der>... --in <dir> --out <dir>
             [--policy <file>] [--pin-out <file>] [--pin-blake3 <hex>]
             [--decoder <decoder.wasm> [--decoder-pin-blake3 <hex>]]
             [--job-id <32 hex>] [--nonce <64 hex>] [--param key=value]...
             [--seccomp generated|none] [--seccomp-sha256 sha256:<hex>]
heimdall verify-result <out>/result.signed --key <key file | key record>
             [--files <dir>] [--job-id <32 hex> --nonce <64 hex>]
heimdall profile probe|gen|check <workload> [--profiles <dir>] [--libc glibc|musl]
             [--binary <file>] [--only <run>]...

• --job native prints not in milestone 1 and exits 2.
• --module names the guest; its signature <guest>.wasm.p7s and hash pin <guest>.wasm.blake3 sit beside it and are verified against the --trust-root certificates before load. There is no unsigned mode: without a trust root the job does not start.
• --decoder makes the job a split guest (GATLING-WASM.md): --module is then the verifier and --decoder its decoder module, signed and pinned exactly like the guest (<decoder>.wasm.p7s, .wasm.blake3, and --decoder-pin-blake3 as the caller pin). The decoder is loaded first; any refusal of it says decoder refused: ... and exits 3 before anything runs. The policy key decoders sets how many decoder instances run at once. Verdicts, outputs and verify-result are the same as for the single-instance guest.
• --in, --out and --policy follow RUN.md and POLICY.md.
• --job-id and --nonce let the caller bind the result to its own request; both are random when absent and printed either way.
• --seccomp generated (the default of a release build) runs the guest in a worker process under the checked-in, generated heimdall-wasm-host seccomp profile for this build's arch and libc (unknown call = kill); the parent holds the key, re-checks the worker's outputs and signs. The result says Generated { profile_digest } (sha256: of the profile's .oci.json). A worker killed by the filter gives a signed Refused heimdall-seccomp-1, no outputs, exit 4. --seccomp none (the default of a debug build: the profiles are generated from the release build) runs it in-process with no filter (Protection::None). HEIMDALL_SECCOMP=generated|none sets the default; the flag wins. --seccomp-sha256 demands that digest: another one exits 3 before anything runs. No profile for this arch/libc with generated: exit 3. The worker gets only PATH=/usr/bin:/bin and RUST_BACKTRACE=0 as its environment (the probe's), none of the caller's.
• run prints pinned-key:, seccomp:, job-id:, nonce:, result: and verdict: lines on stdout. --pin-out also writes the pinned key record to a new file.
• verify-result checks the format, the pinned key id and boot id, the Ed25519 signature and the result's well-formedness; with --job-id and --nonce, that the result is for that job; and that the files in --files (default: files/ beside the result file, when it exists) are exactly the listed outputs with matching sha256 and length.

heimdall profile (spec §3)

The syscall profile of a workload is probed, generated and checked from profiles/<workload>/workload.toml (the binary per libc and the probe corpus; format in heimdall_probe::workload). See SECCOMP.md.

• probe runs every corpus run in learning mode (seccomp USER_NOTIF, log and allow) and writes <arch>-<libc>.probe.json: every distinct call with the tests that made it.
• gen reads the probe file and writes <arch>-<libc>.rs (a const table), .json (the same profile plus the review: near-miss calls, W|X mappings left out, bare allows) and .oci.json. A person reviews the diff before it is committed.
• check probes again and exits 1 when a call is outside the checked-in .json, printing new call <call> (kill_process), made by test <run>, or when .rs/.oci.json do not match .json.

Exit codes: 0 done / check passed, 1 check failed, 2 usage error, 3 the workload, binary or a probe run failed (a run that times out or ends with another exit code than its expect_exit fails the probe, naming the run).

heimdall trace (dynamic-trace jobs)

heimdall trace run --layout <dir> --image <sha256:..> [--tracer <heimdall-trace>] --in <dir> --out <dir>
                   --result <file> [--work <dir>] [--pin-out <file>] [--wall-secs 120] [--memory-mib 1024]
                   [--pids 256] [--max-bytes 4194304] [--env K=V]... [--writable <dir>]... -- <command>...
heimdall trace verify <result> --key <pinned key> --files <out dir> [--max-bytes <n>]
heimdall trace diff <baseline.json> <trace.json> [--max-bytes <n>]

run traces the command in a HeimdallRunner job with no network (heimdall-container, its shim found as for every HeimdallRunner) and prints the outcome as one JSON line ({"outcome":"traced",...} or {"outcome":"unknown","reason":...}); --tracer first adds the static tracer to the image as one more layer. verify checks a trace job's signed result and trace.json. diff prints what the trace does beyond the baseline (JSON). Exit codes: 0 traced / clean diff, 1 Unknown / new behaviour or a trace not complete, 2 usage, 3 a file, the key or the runner could not be read or started. See API.md.

Exit codes