HCAD Early Threat Detection

Overview

HCAD early threat detection runs before controllers or @Protectable methods are reached by having HCADFilterConfigurer insert HCADFilter before Spring Security's AuthorizationFilter. The current configurer order is SecurityConfigurer.HIGHEST_PRECEDENCE + 115, followed by AuthenticatedPendingAnomalyTriggerFilter at HIGHEST_PRECEDENCE + 116. HCAD is not a final risk decision engine. It is an early gate that decides whether an authenticated request is worth sending to the LLM analysis path before a protected resource is reached.

From request arrival to decision

When analysis begins

Without HCAD early detection, AI analysis begins only when a protected resource is reached. With HCAD enabled, requests that already carry strong anomaly signals get their analysis scheduled at the filter stage — before any controller code runs.

Trusted fast context projection

HCAD scoring is now based on TrustedHcadContextProjection, created by TrustedHcadContextProjectionFactory. Only fields with TRUSTED_SERVER, BRIDGE_VERIFIED, or STORE_DERIVED provenance can influence pre-trigger scoring. Client-provided simulation headers, official-inspection override slots, RAG/vector/MCP data, and external threat-pack inputs are excluded from the hot-path decision.

Signal weight model

Signals fall into two classes. Anchor signals are heavy enough that a single anchor can push the request into the early-analysis path. Corroborating signals carry meaning only when several accumulate. The final rule is "at least one anchor AND total ≥ 70".

Anchor signals

Corroborating signals

Risk score bands

The aggregated score on a 0–100 scale is classified into four bands. Early analysis kicks in once the request enters the RED band and an anchor signal is present.

Assessment record structure

The scorer output is stored in an immutable record — HcadPreProtectablePromotionAssessment — and attached to HTTP request attributes for the pending-anomaly trigger chain. Candidate, trigger, duplicate, and LLM-outcome state is persisted separately in hcad_detection_evaluation. The runtime audit log keeps only summary trace data; monitoring statistics are computed from the dedicated evaluation table.

Trusted projection assessment and evaluation persistence

Example code illustrating the current hot-path shape before a request reaches the protected controller:

// Simplified from HCADFilter.
// 1. Build a canonical fast projection from trusted sources only
TrustedHcadContextProjection projection =
        trustedProjectionFactory.project(request, authentication);

// 2. Score only trusted fields; ignoredInputs are kept for explanation, not scoring
HcadPreProtectablePromotionAssessment assessment =
        hcadPreProtectablePromotionScorer.score(projection);

// 3. Attach the assessment to request attributes for the trigger chain
HcadPreProtectablePromotionRequestProjector.project(
        request,
        assessment,
        hcadProperties.getPreTrigger().effectiveMode());

// 4. The orchestrator persists hcad_detection_evaluation and coordinates LLM dedup
if (assessment.eligible()) {
    pendingAnomalyTriggerOrchestrator.maybeTrigger(request, authentication);
}

Early-analysis trigger chain

Placed right after the HCAD filter, AuthenticatedPendingAnomalyTriggerFilter publishes an event only when a request passes the sequential gates below. Any gate can stop the flow independently — the original request path is never affected. HCAD and @Protectable triggers share an idempotency key so the same request does not produce duplicate LLM analysis.

Normal-behaviour baseline learning

Before HCAD can decide what is abnormal for a user, it has to learn what is normal. BaselineLearningService observes high-trust requests and incrementally updates two baselines — one per user, one per cohort — across IP ranges, access hours, paths, User-Agents, operating systems, and authentication methods.

Learning mechanics

Event payload fields

Requests that clear all five gates are published as PRE_PROTECTABLE_REDLINE events and then consumed by the existing asynchronous LLM pipeline and audit system. The payload contract carries every judgement input, so the same structure can later be reused by external verifier scenarios.

Infrastructure modes & wiring

HCAD's session metadata, request counters, and device records live in a storage layer that swaps implementations based on the infrastructure mode. Both implementations satisfy the same HCADDataStore contract, so application code is unaffected.

Wiring points

Shadow monitoring and qualification

HCAD pre-trigger evaluation is observable through the IAM admin page /contexa/admin/security-monitor/hcad. The page reads from hcad_detection_evaluation and provides day, week, month, and year windows for candidate count, LLM trigger count, precision, false positives, observable false negatives, unknown ratio, average LLM latency, duplicate suppression, signal performance, resource performance, user/session repeats, and estimated wasted cost.

Related documentation