Scores, risk & penalty
Sentinel produces three numbers that are easy to confuse: the classification score (with its verdict), risk, and penalty. They come from different inputs and are used in different places, so a rule written against the wrong one won't do what you expect. Read this page before you write security rules or act on verificationData in your backend.
How it works
Classification score and verdict
The classifier scores a submission: its email address, device headers, IP, location, text, and more. Each check is a rule that belongs to a category (email, device, ip, location, text, injection, similarity, rateLimit, his, ai). A category's score is the sum of its rule scores.
The overall score is the mean of the categories that ran, rounded down to 2 decimals. Some strong signals then raise it to a floor, for example any triggered injection rule makes it at least 2. The verdict (classification) follows from the score:
| Score | Verdict |
|---|---|
< 1 | GOOD |
< 2 | NEUTRAL |
≥ 2 | BAD |
Because the score is a mean, one bad category is diluted by clean ones. The floors exist so that a few unambiguous signals decide on their own. The per-rule scores, which categories count, and every floor are listed in Classifier rules & scores.
The classifier runs in POST /v2/verify (for a valid solution, with the result signed in verificationData) and in POST /v2/classifier. Security groups tune it with classifier.* settings. See Classifier.
Risk
Risk is a stateless 0–10 score of the request itself, before any submission exists. It's the sum of the device, IP, and location category scores, capped at 10. It keeps no state: the same request always gets the same risk.
GET /v2/inspectreturns it asrisk, with the rules that fed it intriggeredRules. Its optionaltimeZoneparameter can addTIMEZONE_MISMATCH.- The
riskrule condition uses the same sum, without a time zone. It's computed with theclassifier.*settings of thesetrules before that rule, so rule order matters.
Penalty
The penalty is a stateful 0–10 score of how a client has misbehaved recently. Sentinel keeps it in the KV store per account and client IP, so every API key of the account shares it, and a client that rotates headers keeps adding to the same value. It expires [penalty] ttl (default 30m) after its last increase.
| Source | Adds |
|---|---|
| A new distinct header set beyond the first in a header-entropy window | headerEntropy.penalty (default 1) |
Pressure on a rateLimit.limits limit keyed by edk or ip: every 20% of its points | 1 |
A failed POST /v2/verify (wrong solution, bad signature, reused challenge, wrong code, too fast, …) | 1 |
| A Human Interaction Signature block or penalty | his.penalty (default 1) |
A matching penalty.add rule on an allowed request | its value, from -10 to 10 |
An expired challenge and a successful verification add nothing. Requests denied by a security-group rule (403 ACCESS_DENIED) add nothing either; a Human Interaction Signature block (403 HIS_BLOCKED) adds his.penalty as listed above.
- The
penaltyrule condition reads the value from before the current request. GET /v2/inspectreturns it aspenalty, including this request's increments.
The penalty fails open: when the KV store is unavailable, it reads as 0 and increases are skipped.
[penalty]
ttl = "30m" # a penalty expires this long after its last increaseSee the Configuration reference and the penalty.add setting.
Key terms
| Classification score / verdict | Risk | Penalty | |
|---|---|---|---|
| Range | 0 and up; verdict GOOD / NEUTRAL / BAD | 0–10, one decimal | 0–10, one decimal |
| State | Per submission | None: computed per request | Kept per account + client IP until [penalty] ttl |
| Inputs | Email, device, IP, location, text, injection, similarity, rate limit, HIS, AI | Device, IP, and location rules | Failed verifications, rate-limit pressure, header entropy, HIS, penalty.add |
| Returned by | POST /v2/verify (verificationData), POST /v2/classifier | GET /v2/inspect (risk) | GET /v2/inspect (penalty) |
| Used in rules by | — | risk condition | penalty condition, changed by penalty.add |
Risk and penalty are independent: the penalty doesn't add to risk. Rules can act on either.
Examples
Inspecting a request. A curl request to GET /v2/inspect with a restricted key whose security group adds 1.5 penalty per call. The device rules give a risk of 3, and the second call shows the penalty accumulating:
curl -s 'https://sentinel.example.com/v2/inspect' -u 'key_…:sec_…'{
"data": {
"device": { "score": 3.0, "triggeredRules": ["ACCEPT_LANGUAGE_HEADER_MISSING", "USER_AGENT_HEADER_UNCOMMON", "CLI"], "…": "…" },
"network": { "score": 0.0, "…": "…" },
"location": null,
"risk": 3.0,
"triggeredRules": ["ACCEPT_LANGUAGE_HEADER_MISSING", "USER_AGENT_HEADER_UNCOMMON", "CLI"],
"penalty": 3.0,
"…": "…"
}
}See the /v2/inspect API reference.
A score that is a mean. POST /v2/classifier with a disposable email address, curl headers, and a time zone. The device category scores 4, email scores 2, and location scores 0. The injection scan found nothing, so it doesn't count. The mean is (4 + 2 + 0) / 3 = 2, which is BAD:
{
"data": {
"classification": "BAD",
"score": 2.0,
"triggeredRules": ["ACCEPT_HEADER_MISSING", "ACCEPT_LANGUAGE_HEADER_MISSING", "USER_AGENT_HEADER_UNCOMMON", "CLI", "DISPOSABLE", "FREE_PROVIDER"],
"…": "…"
}
}See the /v2/classifier API reference.
Risk and penalty in rules. Deny risky requests outright, and require a code challenge from clients that have been failing:
[
{ "action": "deny", "message": "Request blocked.", "conditions": [{ "field": "risk", "operator": ">=", "value": ["5"] }] },
{ "action": "set", "conditions": [{ "field": "penalty", "operator": ">=", "value": ["3"] }], "set": [{ "field": "codeChallenge.enabled", "value": "true" }] }
]See Security groups & rules and the Rules reference.