In this section
Product / normative requirements

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

Command-scoped network contract

For the selected policy, decision.resolver reports system DNS, direct port-53 interception, or a private resolver mount with its NSS/nscd and user-namespace evidence. A deterministically disabled required namespace makes preflight not ready and withholds command execution argv.

Independent capture and TLS boundaries

ModeContract
offProxy TLS as opaque transport.
runtimeObserve supported OpenSSL APIs pre-attached from active mappings and system loader paths without changing trust; loader-known images may map after exec.
relayTerminate TLS in the per-run relay with explicit private CA material.
CaptureWrite 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.

Relay readiness uses the runtime's certificate/key, permission, signing-usage, and key-match validation. Invalid CA material makes agent readiness false before command execution.

Agent evidence is file-first

actions.resolver_inspect contains independent shell-safe argv arrays for the files behind that resolver decision. They are read-only inspection actions and never authorize a host security change.

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 the complete transparent backend and the only backend in published packages. Apple silicon can run source-built macos-explicit: one foreground loopback SOCKS5 CONNECT listener for cooperative TCP clients, shared route/direct/reject policy, and truthful metadata evidence. It sets only child ALL_PROXY/all_proxy and never changes system settings. Native package mechanics cover Mach-O hygiene, checksum, install, upgrade, rollback, and uninstall; a published claim still requires a versioned Developer ID-signed/notarized asset and fresh-download acceptance. Explicit mode has no strict scope, UDP, fake DNS, capture, TLS inspection, QUIC, process attribution, or fail-closed claim. macos-interpose is an unavailable proxychains-style research backend for compatible dynamic TCP and resolver calls. Hardened Runtime, SIP-protected and static code, alternate APIs, direct syscalls, complete descendants, UDP, strict scope, and TLS remain outside its claim. Proxyman-style child-only adapters may be evaluated, but Heimdall does not change the system proxy or keychain. macos-transparent is deferred NETransparentProxyProvider source research, excluded from releases with release_included=false. Its optional sourceAppAuditToken attribution and NEAppProxyProvider alternatives require a future roadmap decision and native evidence. No current macOS path requires a persistent user-managed Heimdall daemon. Read the macOS design.

A capability becomes available only with a machine contract, documented failure behavior, and relevant native acceptance. Compilation alone is not acceptance.