In this section
Runbook
Build eBPF before userspace, install one binary, authorize only its setup worker, and verify the foreground contract rather than trusting a successful compile.
Build
The single binary embeds the versioned eBPF ELF, so refresh it first. Enter the pinned development environment before running project commands.
nix develop -c just sync-ebpf
nix develop -c just verify
nix develop -c just check-macos
# On a native Apple-silicon Mac:
just test-macos-native
just test-macos-interpose-feasibility
# Deferred source research; not a package or release gate:
just test-macos-companion-native
scripts/build-macos-release-assets --unsigned /tmp/heimdall-dist
# From the Linux release host:
HEIMDALL_MACOS_BUILD_HOST=<ssh-alias> just test-package-macos
check-macos type-checks the target-selected CLI and portable unit-test targets for pinned aarch64-apple-darwin. It proves Linux-only aya/cgroup code does not leak into shared config/init, RunEvidence, relay_transport, the JSONL store and offline log CLI, or the reduced explicit-agent contract. It also compiles the internal heimdall.macos.control/v1 HMAC, fixed-vector, replay, framing, concurrent-run, and owner-EOF tests. It does not link a native binary or connect that protocol to a provider.
test-macos-native builds and runs the release CLI on Apple silicon. It routes curl through the macos-explicit loopback SOCKS5 CONNECT listener and a fixture upstream, then verifies domain preservation, shared policy routing, cooperative JSONL, integrity, listener teardown, exit passthrough, and fail-closed backend selection. Its unit phase reruns the control protocol but does not supply Apple flow metadata, so it does not accept strict scope, UDP, fake DNS, capture, TLS inspection, Network Extension behavior, or official packaging.
test-macos-interpose-feasibility is a no-network research gate. It proves an ordinary dynamic fixture loads the injected constructor while Hardened Runtime and SIP-protected targets do not. It does not implement or accept socket routing, DNS, descendants, capture, or TLS.
test-macos-companion-native runs the native Swift control-codec tests and builds one containing app with one embedded NETransparentProxyProvider system extension, both unsigned arm64 macOS 11 products. It never signs, installs, activates, approves, or configures the extension. The app does not submit activation; provider startup fails and an unexpected flow is closed instead of returned to the normal route. This is deferred source and bundle-shape evidence, excluded from package and release construction.
test-package-macos sends only git archive HEAD through a stable SSH alias and returns only an archive/checksum. Its --unsigned path proves CLI Mach-O hygiene, macOS 11 deployment, deterministic tar metadata, checksum, install, simulated upgrade, rollback, and uninstall. It neither builds nor includes the deferred companion. The default path requires Developer ID, Hardened Runtime, timestamp, a warning-free accepted notarytool log, and Gatekeeper assessment.
Run the current and Linux 6.6 LTS disposable NixOS real-eBPF VMs when changing cgroups, DNS, relay correlation, routing, or kernel programs. Both execute the same static binary and full daemonless acceptance suite. Run both pinned distro gates to prove the release archive on non-NixOS systems:
nix develop -c just test-vm
# On an x86_64 Linux KVM host:
just test-vm-ubuntu
just test-vm-debian
# On an aarch64 Linux execution host:
nix develop .#acceptance -c just test-vm-native-aarch64
The Ubuntu 24.04 guest uses QEMU user-mode networking, grants only the exact setup-worker sudo rule, rejects copied-binary authorization, and verifies fake DNS through SOCKS5 while AppArmor's default user-namespace restriction remains enabled, direct TCP/UDP, descendants, all four owner signals, concurrent sessions, parent-death recovery, runtime and relay TLS, JSONL integrity, exit propagation, and daemonless process/listener/cgroup/BPF-pin cleanup. It rejects host link, route, or rule changes. It is focused distribution coverage, not a replacement for the broader NixOS protocol/stress matrix or native aarch64 execution.
The Debian 13 guest runs the same archive and lifecycle suite against its stock files myhostname resolve [!UNAVAIL=return] dns chain. It proves the private resolver mount without changing host NSS state or requiring a session D-Bus service, and its Python 3.13/OpenSSL client validates Heimdall's generated relay CA and leaf extensions.
Install
For a tagged static release, verify the checksum and use the bundled atomic installer. See Install and upgrade for download and rollback commands. For a source build:
sudo install -Dm755 target/release/heimdall /usr/local/bin/heimdall
heimdall init
# Add with visudo after replacing USERNAME:
# USERNAME ALL=(root) NOPASSWD: /usr/local/bin/heimdall __setup-worker
sudo chmod 0440 /etc/sudoers.d/heimdall
sudo visudo -cf /etc/sudoers.d/heimdall
Replace USERNAME. The worker receives one strict request over stdin, transfers map/link FDs, and drops privilege before the command starts. Runtime TLS retains that unprivileged helper only for the run lifetime. No service is required.
Smoke test
heimdall agent | jq .
heimdall config validate
heimdall run -- curl -fsS https://example.com
Acceptance coverage
The NixOS VMs exercise real eBPF attachment, fake/system DNS, SOCKS5 TCP/UDP, QUIC, descendants, signals, concurrent isolated runs, runtime and relay TLS, provenance-linked HTTP/1 header evidence and credential masking, log rotation, orphan recovery, exact preview/apply retention, fail-closed errors, parent-death cgroup cleanup, and link cleanup. Ubuntu independently proves namespace-free fake DNS under its default user-namespace restriction; Debian proves the private-mount fallback through its stock nss-resolve chain. Both install the archive and cover exact authorization, direct TCP/UDP, descendants, all owner signals, concurrent isolation, parent-death recovery, both TLS modes, logs, and normal cleanup outside NixOS. The native-aarch64 recipe rejects a non-aarch64 host and asserts the guest architecture; qemu-user CLI execution does not satisfy that gate.
Local release verification is authoritative. From a clean main checkout that exactly matches origin/main, set HEIMDALL_MACOS_BUILD_HOST=<ssh-alias> and run just release-github. It validates curated highlights, the structured version changelog and known limitations before running source verification, the current and Linux 6.6 LTS NixOS real-eBPF guests, the pinned Ubuntu 24.04 and Debian 13 compatibility guests, all package checks, and the signed/notarized Mac build sequentially. Only then does it create the tag and publish the generated release notes, archives, and checksums. GitHub Pages or Actions status is not release evidence.
The same local transaction builds and checksums the npm tarball, x86_64/aarch64 PyPI wheels, and Cargo CLI source package. Publishing the GitHub Release triggers thin npm, PyPI, and crates.io OIDC workflows that upload only those immutable assets; Actions does not rebuild Heimdall and routine publication needs no registry login, write token, 2FA link, or second dispatch.
| Evidence | What it proves |
|---|---|
just verify | Build, format, lint, dependency, unit, Darwin type-check, deferred companion source-contract, and userspace gates. |
just check-macos | The Darwin entry and portable protocol tests exclude Linux-only dependencies; this is a compile boundary, not native acceptance. |
just test-macos-native | The reduced cooperative TCP backend on native Apple silicon, including routing, metadata evidence, integrity, cleanup, exit status, and explicit selection. |
just test-macos-interpose-feasibility | Only the DYLD loader boundary: ordinary dynamic target accepted, Hardened Runtime and SIP-protected targets blocked. |
just test-macos-companion-native | Deferred Swift control-codec and unsigned app/system-extension source shape; no release inclusion, signing, install, activation, routing, or attribution. |
just test-package-macos | Native non-publishable arm64 CLI package mechanics: Mach-O/deployment/path hygiene, archive/checksum, install, upgrade, rollback, and uninstall; no companion. |
just test-package | x86_64/aarch64 static linkage, architecture, checksum, source-path and debug-section hygiene, BTF preservation, aarch64 emulated CLI, and x86_64 install/upgrade/rollback/uninstall. |
just test-vm | The x86_64 static release binary on the current/LTS NixOS real-kernel daemonless data path. |
just test-vm-ubuntu | The installed x86_64 archive on Ubuntu 24.04 with exact authorization, restricted-userns fake DNS, direct TCP/UDP, descendant/signal/concurrent/parent-death lifecycle, runtime and relay TLS, logs, cleanup, and host isolation. |
just test-vm-debian | The same archive on Debian 13 with private-mount fake DNS through stock nss-resolve, strict OpenSSL relay verification, the complete distro lifecycle, cleanup, and host isolation. |
just test-vm-native-aarch64 | The aarch64 static CLI on the same current/LTS real-eBPF suite; it must execute from an aarch64 Linux host. |
heimdall agent | Config, execution ownership, capabilities, and repair actions. |
heimdall logs schema --summary v1 | The strict offline contract for the low-cardinality run-health document. |
heimdall logs summary | Run health, sequence loss, active flows, failures, and protocol counters. |
heimdall logs schema --flow v1 | The strict offline contract for one bounded flow explanation. |
heimdall logs flow | Route/result, capture boundaries, actual plaintext, protocol counters, errors, and argv-safe next actions without payload disclosure. |
heimdall logs verify | Per-run JSONL sequence, schema, segment, and blob integrity. |
The Ubuntu gate also asserts that heimdall agent --policy fake selects port53_intercept, reports the still-enabled AppArmor restriction, and needs no private resolver mount.
The Debian gate asserts private_mount for its nss-resolve status-action chain and completes without a session D-Bus service or host resolver edits.
Performance baseline
nix develop -c just benchmark-vm
just benchmark-vm-ubuntu
just benchmark-vm-debian
The current/Linux 6.6 LTS NixOS guests and pinned Ubuntu 24.04 and Debian 13 guests each emit one heimdall.benchmark/v1 document after measuring cold start, direct TCP, proxied TCP/UDP, relay TLS, maximum RSS, 1/10/50 concurrent starts, event integrity, and sustained direct/proxied TCP, proxied UDP, transport-capture, and relay-plaintext-capture throughput. Each throughput record includes bytes, elapsed time, bytes per second, and its capture/decrypt boundary. Event integrity requires zero incomplete runs, sequence gaps, out-of-order records, active or failed flows, and error events. NixOS uses GNU time accounting; Ubuntu and Debian use SOCKS5 routing, procfs RSS sampling, and 8 GiB guests. The Ubuntu baseline does not weaken its AppArmor user-namespace restriction. These explicit performance checks are not part of release-check. Results are specific to the reported distribution, architecture, kernel, CPU count, memory, and RSS source; they are environment baselines, not universal performance claims.
Diagnose failures
- Run
heimdall agentand preserve its JSON even when it exits 1. - Follow
actions.validateand everyactions.resolver_inspect[]item as independent argv arrays. - Check the exact sudoers path if foreground setup is denied.
- Preview with
config explain, then reproduce with a minimal command and the same policy.
A plain hosts: files dns NSS path uses cgroup port-53 interception for fake DNS and needs no user namespace. Read decision.resolver first. fake_dns_user_namespace_disabled fails before run state or the workload exists; choose system DNS or use a compatible host. For apparmor_policy_check, grant userns, only to the exact installed Heimdall path when authorized. Never relax Ubuntu's system-wide restriction.
Before relay trust, require agent.config.decrypt.ca_material_ready and compare the DER SHA-256 in tls init-ca ca_cert_sha256 with agent.config.decrypt.ca_cert_sha256. Trust only that public certificate in the explicitly wrapped client; never expose the signing key. For relay_ca_material_invalid, generate replacement material in a new private directory, update command-scoped trust, and then change both config paths.
For relay TLS, tls_upstream_certificate_invalid means Heimdall rejected the remote peer and upstream verification must not be weakened. tls_upstream_client_auth_required means the verified upstream requires a client certificate relay mode cannot forward, so use runtime mode or disable decryption. tls_downstream_certificate_rejected is an explicit client certificate alert. tls_downstream_closed_without_close_notify is ambiguous; preserve the wrapped command's stderr and exit status before diagnosing trust.
Do not equate config validity with connectivity. A real acceptance check must exercise the selected policy through heimdall run.