In this section
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.
The path at a glance
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.
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
heimdall runre-enters throughsystemd-run --user --scopewhen it needs an isolated delegated cgroup.- The CLI binds per-run relay and DNS listeners, then the authorized setup worker attaches eBPF and drops privilege.
- The child joins the cgroup only after setup succeeds, then executes the requested command.
- eBPF rewrites eligible TCP and UDP destinations to the local relay. DNS follows the selected fake or system mode.
- The relay recovers the original destination, evaluates ordered rules, and routes, connects directly, or rejects.
- The run writer records correlated fake-DNS exchanges, policy decisions, flow boundaries, parsed relay ClientHello, and explicit runtime/relay TLS observations.
- 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
| Layer | Decision | Default |
|---|---|---|
| Proxy | Whether and where a connection is relayed. | Policy required |
| Capture | Whether bounded bytes are retained as content-addressed blobs referenced by JSONL. | off |
| Decrypt | Whether 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
- Cluster or container orchestration integration.
- Host-wide routing rules for services.
- Workload labels, annotations, or admission hooks.
- A web UI or public HTTP API as the primary interface.