In this section
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
heimdallexecutable 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.
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
| Mode | Contract |
|---|---|
off | Proxy TLS as opaque transport. |
runtime | Observe supported OpenSSL APIs pre-attached from active mappings and system loader paths without changing trust; loader-known images may map after exec. |
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.
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
heimdall agentemits one read-onlyheimdall.agent/v8document with argv-safe actions.- Each run writes one
heimdall.run/v1manifest and orderedheimdall.event/v1JSONL. - Strict
heimdall.logs.summary/v1andheimdall.logs.flow/v1documents provide bounded read-only aggregation; JSONL remains the source of truth andlogs verifyremains the integrity gate. - Fake-DNS exchanges, policy decisions, flow boundaries, and TLS observations are explicit records.
- Flow summaries copy no payload, derived header, or SNI and report plaintext only from explicit non-empty
tls_plaintext.*evidence. - Derived HTTP/1 records point to the exact plaintext event sequences used to parse them.
jq,rg,sed,sort,wc, andheimdall logsare supported analysis paths.- Heimdall owns active-file rotation; schemas and integrity verification work offline.
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.