Core concepts

Introduction

A short glossary of the ideas the rest of the documentation builds on.

Canonical Request Model

The single, in-memory representation of a request that every analysis stage reads. It holds the method, version, path, host, headers, framing, detected anomalies, and a flat list of parameters — and it is where all the decoding and normalization lands. Detection never touches raw bytes directly; it reads the canonical model. See Normalization and Internals.

Params and Source

Every input Heimdall can find in a request — a query value, a form field, a JSON leaf, a header, a cookie, a multipart part, a JWT claim, a GraphQL variable, an XML/SOAP node — is flattened into a Param: {Source, Name, Raw, Norm}. The Source tag records where it came from (Query, Form, JSON, Header, Cookie, JWT, GraphQL, XML, SOAP, WebSocket, …). The set of Params is the detection surface: engines iterate Params, not the raw request. Raw is the decoded-but-original bytes; Norm is the canonical form.

Detection engine and Finding

A detection engine is a specialized analyzer for one class of attack. It implements a fixed contract — Analyze(request, out) — and, crucially, never blocks. When it sees something, it appends a Finding:

Finding { Engine, Category, Risk, Confidence, Evidence{ Param, Offset, Length, Rule } }

Risk is how dangerous, Confidence is how sure, and Evidence points at the exact canonical span that triggered it (so the Attack Explorer can highlight it). Engines are pure and side-effect-free; deciding what to do is someone else's job. See Detection engines.

Risk and Decision

The risk engine aggregates all findings plus protocol anomalies into one saturating score, weighting each finding by a per-engine weight and its own confidence. The decision engine maps that score to an Action through a threshold ladder:

Allow → Monitor → Throttle → Challenge → Block → Drop

See Risk & decision.

Shadow vs enforce

Two operating modes:

• Shadow (monitor) — the default. Every request is inspected and scored, but any action stronger than Monitor is clamped down to Monitor, so traffic is never blocked. The decision still records the action enforcement would have taken (surfaced as would in telemetry).
• Enforce — decisions are applied: Challenge issues a proof-of-work, Block/Drop returns a graceful 403, Throttle tarpits the connection.

Mode is set per policy, so you can enforce one site while shadowing another.

Anomalies

Framing- and protocol-level problems the HTTP engine detects while parsing the request head — conflicting Content-Length/Transfer-Encoding, duplicate headers, obsolete line folding, bare CR, a duplicate Host. These are not findings from an engine; they are flags on the canonical model, and the risk engine weights them directly. They are how request smuggling is caught.

Plugins

Out-of-process programs that contribute additional findings and reputation over a gRPC contract. The engine hands each plugin a connection context (IP, TLS fingerprint, header order) once per connection and a request view per request; the plugin returns an Enrichment (findings, reputation, tags) that flows through the same risk → decision → telemetry path as the built-in engines. Plugin findings are reserved to engine IDs ≥ 128 and can never impersonate a core engine. See Intelligence plugins.

Policy and sites

A policy is the JSON contract the control plane writes and the data plane reads: enforce flag, decision thresholds, which engines are enabled, access control, custom rules, and edge behavior. A sites file maps Host headers to per-site origin + policy, so one engine instance protects many sites with different rules. See Policy & sites.