Architecture overview

Architecture

Heimdall Shield has two planes joined by files and a plugin socket: a data plane that sees every request, and a control plane that configures it and shows you what happened.

The data plane

The security-engine binary is the heart. HAProxy terminates TLS and splices the raw byte stream to the engine over a TCP-mode inline backend (see Traffic capture and ADR-0001); the engine owns all HTTP parsing, normalization, analysis and proxying to the origin. Internally it is a pipeline:

The control plane

The hs-api binary stores and distributes policy, tails the telemetry stream, and serves the Svelte GUI (it is embedded in the binary). Its flagship view is the Attack Explorer: for any request it shows the raw → canonical trace, the findings each engine produced, the risk breakdown, and the final decision — the why behind every verdict. Policy changes are written as versioned JSON and hot-reloaded by the data plane without dropping a connection. See Control plane & GUI.

The plugin boundary

Learned and at-scale intelligence lives in separate, out-of-process programs that attach over a gRPC contract. The engine spawns them from the -plugins flag, hands them connection and request context, and folds their findings into the same risk pipeline as the built-in engines. This keeps the open-source core decoupled from the commercial intelligence and lets either side crash without taking the other down. See Intelligence plugins.

What is built, and what is planned

The deterministic protection path is complete and runs live; the learned tier is the frontier.

Every page repeats the status marker for its own subsystem, so the distinction between the original plan and how it works today is always explicit.