Product contract

Heimdall runs one CLI command and its descendants through an explicit TCP/UDP egress policy, with optional transparent TLS inspection. This page is the normative summary; detailed docs must agree with it.

One binary, one foreground lifecycle

Linux installs one heimdall executable with the eBPF object embedded.
Every run owns isolated listeners, cgroup, maps, links, logs, and policy state.
No persistent Heimdall service is installed or required for proxying, capture, or TLS inspection.
The setup worker drops privilege before exec and remains only as a session parent-death guard.
Normal exit leaves no process, listener, cgroup, BPF link, or map behind.

Command-scoped network contract

Only the wrapped command cgroup is intercepted.
Policies select named SOCKS5, direct, or reject actions independently for TCP and UDP.
Fake DNS preserves hostnames; system DNS is an explicit choice.
Unsupported or ambiguous shapes fail closed and never fall back to unproxied egress.

Independent capture and TLS boundaries

Mode	Contract
`off`	Proxy TLS as opaque transport.
`runtime`	Observe supported startup-discovered OpenSSL APIs without changing trust.
`relay`	Terminate TLS in the per-run relay with explicit private CA material.
Capture	Write bounded private SHA-256 blobs referenced by `heimdall.event/v1` with an explicit byte boundary.

Selecting a TLS mode is not proof of plaintext. Agents must read the reported capability and event boundary. When a complete bounded HTTP/1 header is present in explicit plaintext capture, Heimdall may emit a derived record linked to its source sequences; common credential headers are masked and bodies are not copied into JSONL.

Agent evidence is file-first

heimdall agent emits one read-only heimdall.agent/v8 document with argv-safe actions.
Each run writes one heimdall.run/v1 manifest and ordered heimdall.event/v1 JSONL.
Fake-DNS exchanges, policy decisions, flow boundaries, and TLS observations are explicit records.
Derived HTTP/1 records point to the exact plaintext event sequences used to parse them.
jq, rg, sed, sort, wc, and heimdall logs are supported analysis paths.
Heimdall owns active-file rotation; schemas and integrity verification work offline.

Optional viewer

A future Web UI is explicitly started, unprivileged, and read-only. It reads the same files directly and has no authority over policy, TLS, capture, or the data plane. Its lifecycle cannot affect a run.

Platform and acceptance scope

Linux cgroup v2 plus eBPF is available. macOS remains planned as separately measured wrapper and NETransparentProxyProvider paths. A capability becomes available only with a machine contract, documented failure behavior, and relevant unit or disposable real-eBPF VM acceptance.