Skip to main content
ALTCHA®

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:

ScoreVerdict
< 1GOOD
< 2NEUTRAL
≥ 2BAD

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/inspect returns it as risk, with the rules that fed it in triggeredRules. Its optional timeZone parameter can add TIMEZONE_MISMATCH.
  • The risk rule condition uses the same sum, without a time zone. It's computed with the classifier.* settings of the set rules 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.

SourceAdds
A new distinct header set beyond the first in a header-entropy windowheaderEntropy.penalty (default 1)
Pressure on a rateLimit.limits limit keyed by edk or ip: every 20% of its points1
A failed POST /v2/verify (wrong solution, bad signature, reused challenge, wrong code, too fast, …)1
A Human Interaction Signature block or penaltyhis.penalty (default 1)
A matching penalty.add rule on an allowed requestits 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 penalty rule condition reads the value from before the current request.
  • GET /v2/inspect returns it as penalty, 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 increase

See the Configuration reference and the penalty.add setting.

Key terms

Classification score / verdictRiskPenalty
Range0 and up; verdict GOOD / NEUTRAL / BAD0–10, one decimal0–10, one decimal
StatePer submissionNone: computed per requestKept per account + client IP until [penalty] ttl
InputsEmail, device, IP, location, text, injection, similarity, rate limit, HIS, AIDevice, IP, and location rulesFailed verifications, rate-limit pressure, header entropy, HIS, penalty.add
Returned byPOST /v2/verify (verificationData), POST /v2/classifierGET /v2/inspect (risk)GET /v2/inspect (penalty)
Used in rules by—risk conditionpenalty 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.

Start typing to search...

↑ ↓ Navigate ↵ Select