Classifier
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'sfields. The result is signed intoverificationData. See Verifying submissions.POST /v2/classifier, which your backend calls with arestrictedorfullkey 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, 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 and 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. |
| 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. |
| HIS | his | The Human Interaction Signature (/v2/verify only). See Human Interaction Signature. |
| AI | ai | The text, when the security group opts in. See 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. For how the score differs from risk and penalty, see Scores, risk & penalty.
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.
[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 0MX 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 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], Classifier lists and [classifier.ai].
Security-group settings
Each API key's security group tunes the classifier with set rules. These apply to both /v2/verify and /v2/classifier:
[
{
"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. |
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. Because set rules accumulate, you can tune the classifier per form or per country with conditions. See 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.
| Category | Rules |
|---|---|
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. |
| Injection | SQL_INJECTION, HTML_INJECTION, EMAIL_HEADER_INJECTION, TEMPLATE_INJECTION, NOSQL_INJECTION. See Spam, profanity & injection. |
| Similarity | SIMILARITY, NEAR_DUPLICATE, CAMPAIGN. See Similarity. |
| HIS | HIS_AUTOMATION, HIS_INTEGRITY, HIS_NO_INTERACTION, HIS_REPLAY. See Human Interaction Signature. |
| AI | AI_SPAM, AI_SCAM, AI_ABUSE, AI_GIBBERISH, AI_OFF_TOPIC, AI_CUSTOM. See 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.
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.
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!"
}
}'{
"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 for the full schema and Error codes for the rest.
Tuning
- Pick your own threshold.
classificationis a fixed mapping ofscore. In your backend, usescoredirectly for a finer cut, for example holdNEUTRALsubmissions for review and reject onlyBAD. See 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 disableFREE_PROVIDERandPRIVACY_RELAY(the Form fields (consumer sign-ups) template does this). See Request logs. - Tune per form, not per account. Put
classifier.*settings insetrules with conditions (headers,origin,country), or give each form its own key and security group. - Remember the order of
setrules. A laterclassifier.disableRulesreplaces 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/versiontoken and addnametoclassifier.trustedApps. - Reproduce a result. Send the same inputs to
POST /v2/classifierwith 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/verifyclassifies only verified solutions. Withoutclassifier.fields(orfields=1on the challenge), it sees no email or text./v2/classifiercan't verify Web Bot Auth signatures forwarded inheaders, so the deviceBOTrule never triggers there. It has no HIS input.LOCATION_DISTANCEandrateLimitare available only on/v2/classifier.- Without an IP resolver, the IP has no country or network flags:
HOSTING,PROXYandTORrely 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
MXandDMARC. - List-based rules score
0until their list has downloaded, and when the list is disabled.