# Scores, risk & penalty

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](/docs/sentinel/v2/reference/classifier-rules/#score-computation).

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](/docs/sentinel/v2/features/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.

| 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 `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.

```toml
[penalty]
ttl = "30m"   # a penalty expires this long after its last increase
```

See the [Configuration reference](/docs/sentinel/v2/reference/configuration/#penalty) and the [`penalty.add` setting](/docs/sentinel/v2/reference/rules/#penalty).

## 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:

```bash
curl -s 'https://sentinel.example.com/v2/inspect' -u 'key_…:sec_…'
```

```json
{
"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](/sentinel-api-docs-v2.html#tag/inspect/GET/v2/inspect).

**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`:

```json
{
"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](/sentinel-api-docs-v2.html#tag/classifier/POST/v2/classifier).

**Risk and penalty in rules.** Deny risky requests outright, and require a code challenge from clients that have been failing:

```json
[
{ "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](/docs/sentinel/v2/concepts/security-groups/) and the [Rules reference](/docs/sentinel/v2/reference/rules/#condition-fields).

## Related

- [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/)
- [Classifier](/docs/sentinel/v2/features/classifier/)
- [Writing security rules](/docs/sentinel/v2/policies/security-rules/)
- [Verifying submissions](/docs/sentinel/v2/integrate/verification/)
