In this section
System / data path

Architecture

Heimdall has one product path: wrap a command and proxy that command's outbound connections. The control plane selects a policy; the data plane enforces it only for that command scope.

Heimdall Bifröst mark
The mark is a guarded crossing.The navy arch is the boundary; the spectrum path is Bifröst; a command crosses only inside its attached policy scope.

The path at a glance

heimdall run -- commandone foreground-owned cgroup
01 / CLIcommand scopeRuns the command and keeps descendants together.
02 / KERNELcgroup eBPFPer-run map and link FDs.
03 / RELAYrelay + policyRecovers destination identity.
04 / OUTBOUNDroute / direct / rejectApplies the first match.

Boundaries

The foreground CLI is the session owner. It selects a policy, creates a child cgroup, binds per-run relay and DNS listeners, executes the command, waits for every descendant, and closes all resources.

The platform-neutral relay_transport core resolves outbound credentials once and owns SOCKS5 TCP CONNECT, UDP ASSOCIATE, destination encoding, response validation, and setup timeouts. Linux owns cgroup interception, original-destination correlation, its TCP/UDP listeners, UDP identity, capture, and TLS. Apple-silicon macos-explicit uses only the shared TCP CONNECT path behind its own per-run cooperative listener.

A root setup worker validates one cgroup, attaches fresh unpinned maps and FD-owned eBPF links, transfers those FDs, and drops to the invoking user before the workload starts. Every run keeps that helper as a parent-death guard; runtime TLS also uses it to retain probe state. Unmarked owner exit kills and removes only that command cgroup. It never reads proxy credentials, captures bytes, or keeps a listener.

Runtime TLS pre-attaches supported OpenSSL images found in active mappings, standard library directories, and /etc/ld.so.conf. A loader-known image may map after child exec because the probe already owns its inode. Private images outside those paths remain opaque; the setup helper does not retain privilege to monitor the workload.

No persistent daemon. Relay and fake-DNS ports are kernel-assigned per run on IPv4/IPv6 loopback. The session helper has no listener and exits with its foreground invocation.

Reduced macOS path

heimdall run --backend macos-explicit -- command
  → 127.0.0.1:<kernel-assigned> SOCKS5 CONNECT
  → shared TCP policy
  → SOCKS5 / direct / reject

The child receives only ALL_PROXY and all_proxy. A client may ignore them, so this is cooperative rather than transparent. Preflight requires system DNS, rejected UDP, capture off, and decrypt off. JSONL uses source={backend:"macos-explicit", scope:"cooperative_environment"} and records no payload, DNS, TLS, or process-attribution evidence. The source build starts no daemon or Network Extension; official macOS packages remain pending.

The planned macos-interpose fallback is separate and narrower: compatible dynamic socket/resolver calls only, with Hardened Runtime, SIP, static code, alternate APIs, and unproven descendants outside the claim. The macos-transparent Network Extension prototype is deferred source research, reports release_included=false, and is excluded from release artifacts. Read the macOS decision →

For a plain hosts: files dns NSS path, the cgroup hooks redirect resolver port-53 traffic directly, including a systemd-resolved loopback stub. No user or mount namespace is needed. NSS modules or caches that bypass port 53 retain the private resolver-mount fallback; pinned Debian 13 exercises that path with its stock files myhostname resolve [!UNAVAIL=return] dns chain. Setup fails before command execution if the required scoped namespace is unavailable.

The read-only agent preflight uses the same classifier. decision.resolver reports its strategy, reason, hosts sources, nscd socket, AppArmor/userns settings, private-mount status, readiness, and stable error. A known system-wide disablement withholds actions.execute_prefix; an AppArmor restriction remains a runtime policy check because an exact-path profile may permit only Heimdall.

Connection lifecycle

  1. heimdall run re-enters through systemd-run --user --scope when it needs an isolated delegated cgroup.
  2. The CLI binds per-run relay and DNS listeners, then the authorized setup worker attaches eBPF and drops privilege.
  3. The child joins the cgroup only after setup succeeds, then executes the requested command.
  4. eBPF rewrites eligible TCP and UDP destinations to the local relay. DNS follows the selected fake or system mode.
  5. The relay recovers the original destination, evaluates ordered rules, and routes, connects directly, or rejects.
  6. The run writer records correlated fake-DNS exchanges, policy decisions, flow boundaries, parsed relay ClientHello, and explicit runtime/relay TLS observations.
  7. After the immediate child exits, the foreground owner keeps interception alive until the complete descendant tree leaves the cgroup, then closes links, maps, listeners, and logs.

Three independent data boundaries

LayerDecisionDefault
ProxyWhether and where a connection is relayed.Policy required
CaptureWhether bounded bytes are retained as content-addressed blobs referenced by JSONL.off
DecryptWhether retained TLS bytes are runtime-probed or relay-terminated.off

Heimdall never infers plaintext from a port or filename. Read the running capability evidence from heimdall agent before consuming capture data.

Non-goals