Decisions & thresholds
A model produces an anomaly score. The thresholds in your release turn it into a clear action.
This page describes endpoint forests and native Nginx headers. The separate behavior service returns application decisions with shadow-mode recommendations and sequence evidence; forest thresholds are not sequence-model scores.
The three outcomes
| Action | Nginx behavior | Your backend |
|---|---|---|
allow | Forwards to the usual upstream with trusted risk headers. | Handles the request normally. |
check | Forwards to the usual upstream with trusted risk headers. | Decides whether and how to verify it. |
block | Stops the request with HTTP 403. | Does not receive the request. |
The release requires 0 <= check < block <= 1. A score equal to a threshold takes the higher action: score >= block blocks; otherwise score >= check checks. Lower scores allow.
Read the score correctly
PragmaChange uses -IsolationForest.score_samples. A higher score means the vector looks more unusual to this trained forest. It is not an attack probability, a confidence percentage, or an explanation of the cause. Unlabeled holdout percentiles can suggest starting thresholds, but they do not establish detection accuracy. If suggestions are equal, adjust them before creating a release.
Use request replay to inspect the exact partition hash, windows, feature vector, score, and decision for examples you understand. Replay uses fresh state and does not affect production Nginx windows.
What check requires
check is a signal, not a built-in challenge. Your backend receives the request and decides whether to require extra verification, log it, slow it, or continue normally. PragmaChange v1 does not include a JavaScript challenge or external verification callback.
Warm-up and some errors also return check, but without a score. Treat a missing score as unknown rather than as zero. The HTTP API represents missing scores as null; the forwarded score header is empty.
Trusted request headers
For forwarded matching requests, the module sets:
X-PragmaChange-Action
X-PragmaChange-Score
X-PragmaChange-Reason
X-PragmaChange-Pipeline
X-PragmaChange-Model
Incoming client headers with the X-PragmaChange- prefix are removed in protected locations, including unmatched routes. Your backend should accept PragmaChange risk headers only from its trusted proxy. Unmatched routes are forwarded without risk headers.
When there is no complete vector
The longest feature window must warm up for each partition. A missing or invalid required field, malformed or oversized JSON body, incomplete history, or a capacity problem can prevent normal scoring. The specific reason travels with check. A body buffered to disk is forwarded unchanged and also produces check when inspection cannot read it.