Diátaxis quadrant: How-to. Audience: Red-team and Blue detection developers extending the detection engine or local defensive catalog.

This page is a router: it points you at your next reads and nothing else.

Start here: Developer (Red/Blue)

A developer works two loopback surfaces. On the Blue side you extend Core’s seven-stage detection pipeline and its one ordered enforcement-rule table. On the Red side you extend the local defensive profile catalog and measure your own detector. Gate reuses the scorer but currently supplies a smaller evidence set, so keep Core and Gate results separate.

Before you pick a path, read Which piece am I using? so you do not confuse the three surfaces: the standalone detection engine (:8443), the Detection Observatory (dev-gated page on that engine), and the Gate reverse proxy (edge :8444 + admin :8445).

The two surfaces you work, both self-target-only on your own 127.0.0.1:

flowchart TD
  D["Developer on 127.0.0.1"] --> BL["Blue — understand and extend detection"]
  D --> RD["Red — understand and extend the test catalog"]
  BL --> BE["Detection engine on :8443: signals, scoring, enforcement rules, score trace"]
  RD --> ROE["Rules of engagement first — defensive, local-only, self-target-only"]
  ROE --> OBS["Dev-gated Observatory: launch profiles, watch the live scored feed"]

Blue path — understand & extend detection

  1. Which piece am I using? — tell the three surfaces apart before you touch code.
  2. Run the detection engine — build the WASM detector and the server, run it on 127.0.0.1:8443, and score a request.
  3. Detection engine internals — signals, the scoring math (dedup → per-stage cap → noisy-OR), the enforcement-rule table, and the ScoreTrace you can observe.
  4. Extend detection — add a signal or an enforcement rule and confirm it in the trace.

Important: There is a cross-plane contract on the Pass solve path. When HMN_TOKEN_KEY is set, handlePassSolve in cmd/server/pass_handler.go mints a session-bound step-up receipt into the solve response JSON (stepUpReceipt), which the Gate redeems at POST /__hmn/stepup to issue the hmn_su proof the attested preset’s attestation floor requires. If you change the Pass solve flow — the response shape, the session binding, or when the receipt is minted — you can break attested-route redemption downstream even though the engine and its tests stay green. See Configure attested routes for the redemption path.

Red path — understand & extend the test catalog

Read the rules of engagement first — before running or writing anything.

  1. Red-team rules of engagement — the defensive, local-only, self-target-only boundaries. Read this first.
  2. Self-validation with the Red catalog — run the catalog against your own engine and read the results.
  3. Detection Observatory + Observatory tour — launch profiles from the dev-gated Observatory and watch the live scored feed and per-session trace.
  4. Red-team catalog — the profiles, their labels, and the enforcement rule each is expected to exercise.
  5. Red catalog architecture — the profile contract, the runner, and how a profile reaches the engine.
  6. Write a Red profile — add a profile and register it at the three points a new profile needs.

Note: Everything here is defensive, local-only, and self-target-only, on your own 127.0.0.1 engine — for understanding and extending your own detector and its test catalog, never third-party evasion. This is a reference implementation, and every measured number is reference-measured on your machine, not a guarantee.