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 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.

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.

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.

Connection lifecycle

heimdall run re-enters through systemd-run --user --scope when 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.