# Classifier

> **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).

The classifier combines many signals about a submission (its email address, device headers, IP, location, text and more) into a score and a `GOOD`, `NEUTRAL`, or `BAD` verdict. It runs on every verified widget submission and on demand through `POST /v2/classifier`, so you can screen sign-ups, messages and API calls from your backend.

## How it works

The classifier runs in two places:

- **`POST /v2/verify`**, after a widget's solution verifies. It classifies the request itself (headers, client IP, the time zone the widget sends) and, when the widget sends them, the form's `fields`. The result is signed into `verificationData`. See [Verifying submissions](/docs/sentinel/v2/integrate/verification/).
- **`POST /v2/classifier`**, which your backend calls with a `restricted` or `full` key and whatever inputs it has. Every input is optional.

Each check is a *rule* that belongs to a *category*. A category runs only when its input is present:

| Category | Response field | Input |
| --- | --- | --- |
| Email | `email` | `email`, otherwise the email address found in `fields` |
| Device | `device` | HTTP headers: the body's `headers`; on `/v2/verify`, the request's own |
| IP | `ip` | `ip`; on `/v2/verify`, the client IP. Resolved with the [IP resolvers](/docs/sentinel/v2/configure/ip-resolvers/) and [threat intelligence](/docs/sentinel/v2/features/threat-intelligence/). |
| Location | `location` | The IP's country, otherwise the country of `timeZone` |
| Rate limit | `rateLimit` | `rateLimit` (`/v2/classifier` only) |
| Text | `text` | `text`, otherwise the text of `fields`. See [Spam, profanity & injection](/docs/sentinel/v2/features/text-analysis/). |
| Injection | `injection` | Each key and value of `fields`, plus `text` and `email` |
| Similarity | `similarity` | The text, compared with the account's training data. See [Similarity](/docs/sentinel/v2/features/similarity/). |
| HIS | `his` | The Human Interaction Signature (`/v2/verify` only). See [Human Interaction Signature](/docs/sentinel/v2/features/human-interaction-signature/). |
| AI | `ai` | The text, when the security group opts in. See [AI decider](/docs/sentinel/v2/features/ai-decider/). |

A category whose input is missing is `null` in the response. A rule that is disabled, or has nothing to check, scores `null`; a rule that ran and didn't trigger scores `0`.

### From rules to a verdict

A category's score is the sum of its rule scores. The overall `score` is the mean of the categories that ran, and the verdict follows from it: `GOOD` below `1`, `NEUTRAL` below `2`, `BAD` from `2`. Injection, similarity, rate limit and AI count toward the mean only when they score above `0`, so a clean check or a limit that wasn't exceeded doesn't dilute the others.

Because the score is a mean, one bad category can be outweighed by clean ones. *Floors* prevent that for unambiguous signals: any triggered injection rule, a phishing URL, a similarity match against a strongly weighted sample, a tampered HIS, or a confident AI answer raises the score to at least `2` (`BAD`) or `1` (`NEUTRAL`), whatever the other categories say. Floors never lower a score.

`triggeredRules` lists every rule that scored above `0`, highest first. On `/v2/verify` they become `reasons` in `verificationData`, and for API keys with request logging they are stored in the request log.

The formulas, every floor and every rule's score are in [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/). For how the score differs from risk and penalty, see [Scores, risk & penalty](/docs/sentinel/v2/concepts/scoring/).

## Enabling it

The classifier has no on/off switch: it runs whenever its inputs are present. Server configuration only tunes its DNS lookups and the lists behind some rules.

```toml
[classifier]
dns_timeout   = "500ms"   # per attempt, 2 attempts, for MX and _dmarc lookups
dns_cache_ttl = "1h"      # failed lookups are cached 30s at most

[classifier.free_providers]
enabled = false           # never download the list: FREE_PROVIDER always scores 0
```

MX and DMARC lookups use the host's resolver (`/etc/resolv.conf`); there is no setting to point them elsewhere. The six lists (`disposable`, `free_providers`, `trusted_providers`, `privacy_relays`, `user_agents`, `phishing`) are [remote files](/docs/sentinel/v2/configure/remote-files/) downloaded from the ALTCHA directory. Until a list loads, its rule scores `0`. The AI category also needs a provider under `[classifier.ai]`. See [`[classifier]`](/docs/sentinel/v2/reference/configuration/#classifier), [Classifier lists](/docs/sentinel/v2/reference/configuration/#classifier-lists) and [`[classifier.ai]`](/docs/sentinel/v2/reference/configuration/#classifierai).

### Security-group settings

Each API key's security group tunes the classifier with `set` rules. These apply to both `/v2/verify` and `/v2/classifier`:

```json
[
{
"name": "classifier",
"action": "set",
"set": [
  { "field": "classifier.fields", "value": "true" },
  { "field": "classifier.disableRules", "value": "FREE_PROVIDER PRIVACY_RELAY" },
  { "field": "classifier.highRiskCountries", "value": "high_risk cn" }
]
}
]
```

| Field | What it does |
| --- | --- |
| `classifier.fields` | Makes the widget send the form's fields to `/v2/verify`, so the email, text, injection and similarity categories run there. The **Form fields** template writes this rule. See [Widget integration](/docs/sentinel/v2/integrate/widget/). |
| `classifier.disableRules`, `classifier.enableRules` | Choose which rules run (below). |
| `classifier.highRiskCountries` | Countries that trigger `HIGH_RISK_COUNTRY`; default the built-in `high_risk` list. |
| `classifier.trustedApps` | User-Agent product tokens exempt from `USER_AGENT_HEADER_UNCOMMON`, `CLI` and `LIBRARY`; default the ALTCHA native widgets. |
| `classifier.similarityGroups` | Training groups the text is compared with; default `*` (all). |
| `classifier.ai` | Turns on the AI category, with `classifier.aiPurpose`, `classifier.aiInstructions` and `classifier.aiSignals`. |

Values, limits and defaults are in [Set fields: Classifier](/docs/sentinel/v2/reference/rules/#classifier). Because `set` rules accumulate, you can tune the classifier per form or per country with conditions. See [Classify each form differently](/docs/sentinel/v2/policies/security-rules/#classify-each-form-differently).

### Choosing rules

`classifier.disableRules` and `classifier.enableRules` take rule names from any category, case-insensitive, separated by `,`, `;` or whitespace:

- With a disable list, every rule except those runs, and any enable list is ignored.
- Otherwise, with an enable list, only those rules run.
- Otherwise, every rule runs.

`BOT` switches both the device and the IP rule of that name. On `/v2/classifier`, the body's `disableRules` and `enableRules` arrays replace the group's lists of the same name. A body `enableRules` therefore has no effect while the group sets `classifier.disableRules`; send `disableRules` in the body as well to replace it. An unknown rule name returns `400 VALIDATION_ERROR` with the list of known names.

## Rules & signals

The classifier has 53 rules in ten categories. The text, injection, similarity, HIS and AI rules have their own pages; scores and exact triggers for all of them are in [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/).

| Category | Rules |
| --- | --- |
| Email | `DISPOSABLE` (disposable-email domain), `DMARC` (no DMARC record), `FREE_PROVIDER` (free-email domain), `MX` (no MX record), `PRIVACY_RELAY` (alias service such as Hide My Email) |
| Device | `BOT` (verified Web Bot Auth agent), `ACCEPT_HEADER_MISSING`, `ACCEPT_LANGUAGE_HEADER_MISSING`, `USER_AGENT_HEADER_MISSING`, `USER_AGENT_HEADER_UNCOMMON` (not on the common User-Agent list), `CLI` (command-line client such as `curl`), `LIBRARY` (HTTP library such as `python-requests`) |
| IP | `BOT` (on a bot or crawler list), `HOSTING` (data center), `MALICIOUS` (on a malicious-IP list), `PROXY`, `TOR`, `THREAT_SCORE` (the IP's threat score) |
| Location | `HIGH_RISK_COUNTRY`, `LOCATION_DISTANCE` (far from `lastKnownLocation`), `TIMEZONE_MISMATCH` (time zone and IP in different countries) |
| Rate limit | `RATE_LIMIT` (the body's `rateLimit` was exceeded) |
| Text | `SPAM_WORDS`, `PROFANITY`, `URL`, `URL_PHISHING`, `LINK_MARKUP`, `CURRENCY`, `EXCLAMATION`, `REPEATED_CHARS`, `INVISIBLE_CHARS`, `MIXED_SCRIPT`, `RANDOM_CHARS`, `EMOJI`, `OBFUSCATION`, `CAPITALIZATION`. See [Spam, profanity & injection](/docs/sentinel/v2/features/text-analysis/). |
| Injection | `SQL_INJECTION`, `HTML_INJECTION`, `EMAIL_HEADER_INJECTION`, `TEMPLATE_INJECTION`, `NOSQL_INJECTION`. See [Spam, profanity & injection](/docs/sentinel/v2/features/text-analysis/). |
| Similarity | `SIMILARITY`, `NEAR_DUPLICATE`, `CAMPAIGN`. See [Similarity](/docs/sentinel/v2/features/similarity/). |
| HIS | `HIS_AUTOMATION`, `HIS_INTEGRITY`, `HIS_NO_INTERACTION`, `HIS_REPLAY`. See [Human Interaction Signature](/docs/sentinel/v2/features/human-interaction-signature/). |
| AI | `AI_SPAM`, `AI_SCAM`, `AI_ABUSE`, `AI_GIBBERISH`, `AI_OFF_TOPIC`, `AI_CUSTOM`. See [AI decider](/docs/sentinel/v2/features/ai-decider/). |

The device and IP rules also feed the `risk` and `signal` conditions of security-group rules, so you can act on them before a challenge is issued. See [Condition fields](/docs/sentinel/v2/reference/rules/#condition-fields).

## Using the API

Call `POST /v2/classifier` with Basic auth and a `restricted` or `full` key. This request classifies a contact-form submission as your backend received it: the visitor's IP, time zone and headers, and the form fields.

```bash
curl -X POST 'https://sentinel.example.com/v2/classifier' \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{
"ip": "81.2.69.34",
"timeZone": "Europe/Berlin",
"headers": {
  "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
  "accept": "text/html,application/xhtml+xml",
  "accept-language": "de-DE,de;q=0.9,en;q=0.8"
},
"fields": {
  "email": "jan.novak@gmail.com",
  "name": "Jan Novak",
  "message": "Hallo, kann ich die Bestellung 4711 noch ändern? Danke!"
}
}'
```

```json
{
"data": {
"classification": "NEUTRAL",
"score": 1.1,
"triggeredRules": ["MALICIOUS", "FREE_PROVIDER"],
"device": {
  "browser": "Chrome",
  "os": "Windows",
  "type": "desktop",
  "languages": ["de", "en"],
  "rules": { "BOT": { "score": 0.0 }, "CLI": { "score": 0.0 }, … },
  "score": 0.0,
  "triggeredRules": [],
  …
},
"email": {
  "rules": { "FREE_PROVIDER": { "score": 0.5 }, "MX": { "score": 0.0 }, … },
  "score": 0.5,
  "triggeredRules": ["FREE_PROVIDER"],
  …
},
"ip": {
  "countryCode": null,
  "threats": [
    { "source": "firehol_level1", "kind": "malicious", "action": "block", "threatScore": null, "match": "81.2.69.0/24" }
  ],
  "rules": { "MALICIOUS": { "score": 5.0 }, "HOSTING": { "score": 0.0 }, … },
  "score": 5.0,
  "triggeredRules": ["MALICIOUS"],
  …
},
"location": {
  "countryCode": "de",
  "name": "Germany",
  "rules": { "HIGH_RISK_COUNTRY": { "score": 0.0 }, "TIMEZONE_MISMATCH": { "score": null }, … },
  "score": 0.0,
  "timeZone": "Europe/Berlin",
  …
},
"rateLimit": null,
"text": { "language": "de", "terms": [], "score": 0.0, "triggeredRules": [], … },
"injection": { "matches": [], "score": 0.0, "triggeredRules": [], … },
"similarity": { "matches": [], "score": 0.0, "triggeredRules": [], … },
"his": null,
"ai": null,
"timeZone": { "countryCode": "de", "city": "Berlin", "lat": 52.510885, "lon": 13.3989367, "region": null }
}
}
```

The IP is on a malicious-IP threat list, so the IP category scores `5`. Device, email, IP, location and text ran, so the score is their mean: (0 + 0.5 + 5 + 0 + 0) / 5 = `1.1`, `NEUTRAL`. Injection and similarity scored `0` and don't count. The location comes from the time zone because no IP resolver knows the IP's country, and `TIMEZONE_MISMATCH` is `null` for the same reason. `rateLimit` is `null` because the body has no `rateLimit`; `his` is always `null` here.

Other inputs: `text` (classified instead of the text of `fields`), `languages` (candidate languages for the text rules), `lastKnownLocation` (`{"lat": …, "lon": …}` for `LOCATION_DISTANCE`), `rateLimit` (`{"limit": "10/1m", "customKey": "user-42"}` for `RATE_LIMIT`), `similarityGroups`, and `enableRules` / `disableRules`. Limits: `email` and `timeZone` up to 200 characters, `text` up to 16000, up to 200 `fields` and 100 `headers`. An invalid input returns `400 VALIDATION_ERROR`. See the [`POST /v2/classifier` API reference](/sentinel-api-docs-v2.html#tag/classifier/POST/v2/classifier) for the full schema and [Error codes](/docs/sentinel/v2/reference/errors/) for the rest.

## Tuning

- **Pick your own threshold.** `classification` is a fixed mapping of `score`. In your backend, use `score` directly for a finer cut, for example hold `NEUTRAL` submissions for review and reject only `BAD`. See [Decide from the classification](/docs/sentinel/v2/integrate/verification/#decide-from-the-classification).
- **Find false positives in `triggeredRules`.** Request logs store each request's triggered rules for API keys with request logging on. A rule that fires on legitimate traffic is the one to disable for that group. Consumer sign-ups, for example, often disable `FREE_PROVIDER` and `PRIVACY_RELAY` (the **Form fields (consumer sign-ups)** template does this). See [Request logs](/docs/sentinel/v2/operations/request-logs/).
- **Tune per form, not per account.** Put `classifier.*` settings in `set` rules with conditions (`headers`, `origin`, `country`), or give each form its own key and security group.
- **Remember the order of `set` rules.** A later `classifier.disableRules` replaces an earlier one, so repeat names you disabled earlier.
- **Native apps.** If your app uses a stock HTTP library User-Agent, append your own `name/version` token and add `name` to `classifier.trustedApps`.
- **Reproduce a result.** Send the same inputs to `POST /v2/classifier` with the same group's key to see each rule's score.

## Limitations

- The score is a mean. A single signal that isn't covered by a floor can be outweighed by clean categories, and a known, non-high-risk location lowers the mean of the others.
- `/v2/verify` classifies only verified solutions. Without `classifier.fields` (or `fields=1` on the challenge), it sees no email or text.
- `/v2/classifier` can't verify Web Bot Auth signatures forwarded in `headers`, so the device `BOT` rule never triggers there. It has no HIS input.
- `LOCATION_DISTANCE` and `rateLimit` are available only on `/v2/classifier`.
- Without an IP resolver, the IP has no country or network flags: `HOSTING`, `PROXY` and `TOR` rely on threat lists only, and the location falls back to the time zone.
- DNS-based rules depend on the host's resolver. A failed lookup counts as "no record", so an unreachable resolver triggers `MX` and `DMARC`.
- List-based rules score `0` until their list has downloaded, and when the list is disabled.

## Related

- [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/)
- [Scores, risk & penalty](/docs/sentinel/v2/concepts/scoring/)
- [Spam, profanity & injection](/docs/sentinel/v2/features/text-analysis/)
- [Similarity](/docs/sentinel/v2/features/similarity/)
- [AI decider](/docs/sentinel/v2/features/ai-decider/)
- [Verifying submissions](/docs/sentinel/v2/integrate/verification/)
- [Rules reference: Classifier set fields](/docs/sentinel/v2/reference/rules/#classifier)
- [Configuration reference: `[classifier]`](/docs/sentinel/v2/reference/configuration/#classifier)
