nordisk/heimdall

Kernel tooling read-through (2026-11-03)

Read-only review of the source as it is on the git server today. No code was changed. Purpose: say what exists, what is connected, what is not, and how it could fit together.

Commits read: edda main 3d8fe66, tunnr main 3953015, heimdall main d747087 (the no-pivot shim lands in 9ac44df..d747087; the shared clone on the build box still sits at f4b5002), holger main a76203a plus branch kern/appliance-lsm 390cb8c, dwarves main c5150d2, nornir main eed4eaf8. Line numbers refer to those commits. "Not verified" means I did not run it.

Status words used for every arrow:

• CONNECTED: code calls it, or a file is read by code (path:line given).
• MANUAL: only a shell script, an environment variable, a shell redirect or a person links it.
• MISSING: planned or implied by docs, but nothing links it.

0. Glossary (for an outside reader)

1. System map

                 BUILD BOX (podman, no KVM)                          KVM HOST                       NODE / APPLIANCE
 ┌──────────────────────────────────────────────────────┐   ┌─────────────────────────┐   ┌─────────────────────────────┐
 │ edda: nornir-build-thing (engine)                    │   │ scripts/kernel-suite.sh │   │ korp-start (PID-1 root of   │
 │  kernel.rs  rows→fragment→container build→pin        │   │  rusternetes-kvm.sh     │   │  trust) loads seccomp/*.oci │
 │  kernel_trim  what-if / candidates / coverage / veto │──►│  rusternetes-check.py   │   │ node PID-1 (supervise,      │
 │  syscall_join measured calls → CONFIG options        │ C │  memsave snapshots      │   │  landlock, filter)          │
 │  measure.rs   heimdall binary → .nornir/profiles     │   │ holger tools/           │   │ Rusternetes kubelet (youki) │
 └───────────▲────────────────────────▲─────────────────┘   │  kernel-suite.sh        │   │  ──► heimdall-k8s signer    │
             │ path dep (C)           │ path dep (C)        │  holuse-init.c          │   │ Heimdall shim+broker (jobs) │
 ┌───────────┴────────────┐  ┌────────┴─────────────────┐   └────────────▲────────────┘   └─────────────▲───────────────┘
 │ tunnr-build-thing      │  │ dwarves                  │                │ ScriptSuite (C)              │ medium (C)
 │  5 kernel rows, pins   │  │  buildthing (compose)    │                │                              │
 │  kernel-vetoes/*.list  │  │  kernel_ledger           │   ┌────────────┴────────────────┐            │
 │  door: kernel-probe,   │  │  tune probe/gen/check/   │   │ .nornir/kernel-coverage/    │            │
 │   kernel what-if…veto, │  │   approve/show/app       │   │   <row>/<sha12>.json   (C)  │            │
 │   measure syscalls/gate│  │  dwarves-tune-graph      │   │ .nornir/kernel-vetoes/<row>/│            │
 │  korp-installer (ISO)  │  │   (reads Graph JSON)     │   │   protect.list, receipts/   │            │
 │  payloads/rusternetes- │  └──────────┬───────────────┘   │ .nornir/profiles/<row>/     │            │
 │   node, xtask stage    │             │ runs the binary   │   measure.toml/json, *.json │            │
 └───────────┬────────────┘             ▼                   │   kernel-needs.json (MANUAL)│            │
             │ emit (C)      ┌──────────────────────────┐   └─────────────────────────────┘            │
             ▼               │ heimdall (AGPL binary)   │                                               │
 .nornir/build-variants.toml │  profile probe/gen/check │   ┌─────────────────────────────┐            │
 (installer.requires =n      │  probe-exec/-container   │   │ holger .nornir/kernel-usage/│            │
  from the veto list)   (C)  │  KernelReport (runtime)  │   │  needs.json, coverage.json, │            │
                             │  k8s signer, shim, broker│   │  heimdall-needs.fragment    │──MISSING──►│ Holger kernel rows
                             └──────────────────────────┘   │  (a REPORT; nothing reads   │  (rows exist only on branch
                                                            │   it back)                  │   kern/appliance-lsm)
 ┌──────────────────────────────────────────────────────┐   └─────────────────────────────┘
 │ Mímir (nornir): driver CALLS edges, binary symbols,  │
 │  boundary @syscall nodes (x86_64), libc map, BTF     │──MISSING (step 1: walk + Graph JSON)──► dwarves-tune-graph --graph
 └──────────────────────────────────────────────────────┘                                        ──MISSING──► syscall_join / veto

1.1 Pieces and where they run

1.2 Every arrow, with its status

2. Inventory

2.1 Build Thing kernel side (edda crates/nornir-build-thing)

2.2 tunnr (node OS, media, kernel rows, doors, suite)

2.3 Heimdall

No approve verb, no review UI, no "heimdall-tune" exists in Heimdall. Approval lives in dwarves (tune approve → approved.toml, tune app approve, RowApprover in dwarves-server) and edda measure (approval_status, approve).

2.4 Holger kernel usage report (.nornir/kernel-usage/holger-scan-worker/)

Finding 1 of that report (the shipped Holger kernel cannot run Heimdall strict) is addressed on holger branch kern/appliance-lsm by hand-typed requires rows, and in heimdall d747087 by the no-pivot shim. Nothing reads needs.json, coverage.json or the fragment back by code.

2.5 dwarves

2.6 Mímir (nornir) — the possible-syscalls engine

Missing (plan steps): 1 walk from entry points to SYSCALLS and export the Graph JSON dwarves-tune-graph reads; 2 unresolved edges for dyn Trait / fn pointers / Box<dyn Fn>; 3 dependency sources from Holger's crates.io mirror; 4 aarch64 table; 5 bench on rusternetes-node + tunnr-cni against their approved profiles.

Consumers of Mímir's output (who reads what, once step 1 exists):

Repo fit per plan step: 1, 2, 4 → nornir (mimir-room export verb writing the Graph JSON from @syscall nodes; the aarch64 table beside boundary/x86_64.rs); 3 → nornir mimir-ingest reading crate sources from Holger (a Holger door if one is missing); 5 → tunnr (.nornir/profiles/<row>/<program>/graph.json + the cross-check report committed beside the row), run through dwarves tune. The walk itself stays the owner's; lanes only add readers of the JSON.

3. Data flow today

 [[build.kernel]] row (tunnr kernel.rs)                 measure.toml (hand-written, per row)
        │ preset + profile + closure                             │
        ▼                                                        ▼
 requires (consumers, incl. veto list =n) ──► merged fragment    heimdall profile probe (external binary, privileged podman)
        │                                      (edda kernel.rs:1652)      │
        ▼                                                                 ▼
 kernel build in container ──► .kernel-out/<name>/ + kernel-pin.json   .nornir/profiles/<row>/{measure.json,<prog>/*.probe.json,*.json,*.oci.json}
        │                            │ ledger key                          │                          │
        ▼                            ▼                                     ▼                          ▼ (MISSING: not packed)
 korp-installer ISO (kernel_donor) dwarves kernel ledger            kernel needs (syscall_join)   korp-start seccomp/<entry>.oci.json
        │                                                                   │ stdout only          (hand-written 361-call file today)
        ▼                                                                   ▼ MANUAL redirect
 kernel-suite.sh (KVM): boot, stages, memsave  ◄── kernel coverage        kernel-needs.json ──► dwarves tune show
        │                                                                   
        ▼                                                                   
 .nornir/kernel-coverage/<row>/<sha12>.json ──► kernel candidates ──► kernel veto ──► <row>.list + receipt JSON
        ▲ protect.list                                   ▲ what-if (+ measured-call refusal)        │
        │                                                │                                           ▼
        └── PROBE_ALTERED always protected               └── syscall_join::vetoes_for               include_str! → recipe → emit → build-variants.toml

 Holger: tools/kernel-suite.sh ──► tunnr-build-thing kernel-probe --repo <holger> --fragment-extra heimdall-needs.fragment
         ──► needs.json, coverage.json, candidates.txt, heimdall-needs.fragment  (a REPORT; nothing consumes it)
         ──MISSING──► Holger [[build.installer.requires]] (hand-typed on branch kern/appliance-lsm)

 Mímir: driver CALLS + binary symbols + @syscall boundary ──MISSING step 1──► graph.json ──► dwarves-tune-graph (reader exists)
                                                                                       └──MISSING──► syscall_join possible set

4. Overlaps, duplicates, gaps and sharp edges (seen in code)

5. Dead or orphaned

6. How it could work together

The boundary that already holds in code and licence: Build Thing (MIT) never links Heimdall (AGPL); it runs the binary and reads JSON by field name. The owner's engine (Mímir) writes a Graph JSON; lanes only read it. Every option below keeps both.

Homes

Interface = files in the row directory, with schemas (no code coupling)

.nornir/profiles/<row>/
  measure.toml, measure.json, approved.toml            Heimdall tooling (exists)
  <program>/<arch>-<libc>.{probe.json,json,oci.json}   Heimdall tooling (exists)
  <program>/graph.json                                 Mímir  (MISSING: plan step 1)
  kernel-needs.json      nornir.kernel-needs/1         Build Thing join  (MISSING writer)
  kernel-requires.toml   generated requires rows       Build Thing from heimdall needs (MISSING)
.nornir/kernel-coverage/<row>/<sha>.json               Build Thing (exists)
.nornir/kernel-vetoes/<row>/{protect.list,receipts/}   Build Thing (exists); the .list should live here too

Option A — keep the three homes, close the missing writers (smallest)

• kernel needs <row> --save writes kernel-needs.json beside the row (closes arrow 12).
• heimdall kernel needs --json emits the kconfig lines strict mode requires (from missing_for_strict), and Build Thing turns them into [[build.installer.requires]] rows with Heimdall's reasons (closes arrows 13, 14; the Holger branch rows become generated).
• The veto list moves beside its receipts (.nornir/kernel-vetoes/<row>/<row>.list); <repo>-build-thing reads it from there and refuses a line with no applied receipt on the current fragment (closes S5, S6, S7).
• Mímir step 1 writes graph.json; syscall_join reads it as a possible set (arrows 22, 23).
• Trade-off: the join stays in edda although it is "runtime need"; acceptable because it reads the kernel tree. Least motion; each step is one small PR.

Option B — a shared MIT crate nordisk-kernel-evidence

• Move syscall_join, the coverage/veto report types and dwarves-tune-graph's Graph/Seen types into one crate used by edda, dwarves and <repo>-build-thing; Heimdall stays out (AGPL) and only emits JSON.
• Pro: one definition of every evidence file; the three .probe.json readers become one. Con: a crate split out of an 8k-line module and a new release line; pays off only after A.

Option C — Heimdall owns the "needs" end to end

• Heimdall emits a signed kernel-needs statement per program (strict-mode features + the measured calls' options), and Build Thing only verifies and consumes.
• Pro: the runtime is the authority. Con: Heimdall would need the syscall→CONFIG map, which lives in the kernel tree the build has; it would duplicate syscall_join under AGPL. Not recommended.

7. Recommendation

Option A now, B later. The pieces exist and each file already has a schema; what is missing is four writers and one reader. Keep Mímir's walk the owner's; lanes add only the graph.json reader in syscall_join and the tune show lookup.

Smallest first step: kernel needs <row> --json --save writes .nornir/profiles/<row>/kernel-needs.json (edda kernel_trim.rs verb + tunnr main.rs usage), and the Holger report's needs.json is copied there as the first real file. One PR, one test, and dwarves tune show starts showing the kernel join for a real row.

8. Fix list (smallest first)