Helix whitepaper — traffic DNA firewall

Thesis

Classic stack asks “is this packet weird?” Helix asks “is this still the certified app?” Canon: trust nothing until certified; DNA from traffic, not hope; change guilty until promoted. Buyer sentence: “We don’t allow app shape we didn’t certify.”

Real traffic → learn → draft DNA → promote → certified DNA
                                              ↓
                         scoreRequest / scoreResponse → match allow · mismatch hole

Before: NGFW + WAF + hope
After:  NGFW + WAF + Helix DNA certificate on the app hop

Implementation packages

Package	Role
`helix-proxy`	`createHelixProxy` — learn/shadow/enforce; default port 4080; panel at `/__helix/`
`dna-core`	Learn, score, promote, sign, path templates, fingerprints
`helix-cli`	`helix learn\|promote\|seed-cwl\|cutover\|…`
`cwl-bridge`	Optional seed/compare against CWL surface
`helix-agent`	Mode A soft host intercept
`helix-bridge`	Mode B / L2 transparent placement

Env: MODE, DNA, OBSERVE, SHADOW_LOG, SIEM_LOG, HELIX_DNA_KEY, HELIX_DNA_REQUIRE, HELIX_MAX_BODY_BYTES, PLACEMENT=proxy|bridge|agent.

Artifact: `app-dna-v1`

Required root: schema, app_id, created_at, mode (draft|certified), routes. additionalProperties: false.

Route field	Constraint
`method`, `path_template`, `host`	Required — identity with content_class
`content_class`	`json` \| `html` \| `other`
`status_classes`	integer[]
`response_key_fingerprint`	string \\| null — sorted JSON key paths depth ≤ 2
`request_key_fingerprint`	string \\| null
`query_key_fingerprint`	names only; `""` = none learned; null = do not enforce (legacy)
`holes[]`	`{ code, reason, observed_at? }`
`signature`	optional `hmac-sha256` \| `ed25519`

Fingerprints (`dna-core`)

Function	Behavior
`pathTemplate`	Strip query; UUID/hex/digits → `/:id`; static assets → `/*/.js` etc.
`contentClass`	From Content-Type → json/html/other
`responseKeyFingerprint`	Sorted key paths; arrays/scalars as leaves; maxDepth 2
`queryKeyFingerprint`	Sorted unique query names (values ignored)
`routeKey`	`${host} ${METHOD} ${path_template}`
`scoreRequest` / `scoreResponse`	Runtime checks before/after upstream

HTML body hashes deliberately not in DNA v0 (CMS churn → false positives).

Enforce hole codes

Code	When
`HX-NO-DNA`	No certified DNA (fail-closed)
`HX-ROUTE-UNKNOWN`	Route not in DNA
`HX-QUERY-SCHEMA-DRIFT`	Query names ≠ learned
`HX-REQUEST-SCHEMA-DRIFT`	Request JSON keys ≠ learned
`HX-STATUS-DRIFT`	Status class not learned
`HX-CONTENT-CLASS-DRIFT`	Content class mismatch
`HX-SCHEMA-DRIFT`	Response JSON keys fail-closed
`HX-DNA-UNSIGNED` / `HX-DNA-BAD-SIG`	Signature policy failures
`HX-BODY-TOO-LARGE`	Over `HELIX_MAX_BODY_BYTES` → 413

Enforce: hole → 403 + x-helix-hole. Shadow: allow + alert / x-helix-shadow-hole.

Modes

learn → promote → shadow → enforce → reload

Mode	Traffic	Security
learn	Pass	Append observations NDJSON
shadow	Pass	Score; alert only
enforce	Pass iff DNA match	Block holes (403)

Promote without downtime: write DNA → POST /__helix/reload (or SIGHUP/SIGUSR2). Ops: /__helix/, /__helix/healthz, /__helix/status, /__helix/api/snapshot.

Placement / NGFW

Mode	Role	Code
A — host intercept	Product target; NGFW NAT unchanged	`helix-agent`
B — L2 transparent	Segment-wide	`helix-bridge`
C — reverse proxy	Lab / simple hop	`helix-proxy` day-one path

D1: no NGFW TLS dependency. D4: augment without NAT homework. No FortiOS blade / Snort inspector SDK — SIEM via SIEM_LOG NDJSON.

Signed DNA

signDna / verifyDna: HMAC-SHA256 (default) or Ed25519. HELIX_DNA_REQUIRE=1 refuses unsigned. Smoke: SIGN_SMOKE_OK. Promote must stripBridgeEnvelope so CWL annotations never enter certified routeKey.

CLI surface

helix learn      --in observations.ndjson --out dna.json
helix promote    --in draft.json --out certified.json [--alg] [--key]
helix verify     --in certified.json [--require]
helix seed-cwl   --in routes.cwl --out draft.json [--deploy-profile] [--strip-bridge]
helix cutover    --cwl routes.cwl --dna certified.json [--deploy-profile]
helix ready      --in dna.json --target shadow|enforce
helix diff       --a a.json --b b.json

Optional CWL bridge

Protect stays DNA-only (D5). Cutover default: CWL surface ⊆ certified DNA. Consumes @agenticop-io/cwl/dna-seed (SoR in CWL pillar). Tokens: CWL_BRIDGE_SMOKE_OK, CUTOVER_SMOKE_OK, CUTOVER_MULTIHOST_OK, LIVE_MATCH_OK. CWL side: smoke:ut-spine → UT_SPINE_OK.

Non-goals and residual

Replace WAF / UEBA / SQLi signature packs.
Helix DSL instead of traffic DNA; forking CWL grammar into Helix.
Requiring Convert monorepo to enforce.
Inventing soak traffic — lab preflight ≠ customer soak.

See Traffic decides.

Helix — traffic DNA firewall