Threat intelligence
Threat intelligence matches client IP addresses against remote threat lists and against entries that you or Sentinel add. Use it to deny widget requests from listed IPs, to refuse admin logins from blocked IPs, to check an IP from your backend before you accept a sign-up or payment, and to report abusive IPs your application detects.
How it works
Sentinel keeps two kinds of IP data:
| What it is | Who creates it | |
|---|---|---|
| Threat source | A remote IP list, such as FireHOL level 1 or Spamhaus DROP, downloaded on a schedule. Every IP in it gets the source's kind, action and threatScore. | Root users. 15 default sources are created on first start. |
| Threat entry | One IP or CIDR stored in the database, with an optional kind, action, threatScore and expiry. | Root users (manual entries), or Sentinel (auto entries from reports, failed authentication, rate limits and honeypot hits). |
Looking up an IP returns every entry and every loaded source that contains it. Each one is a match:
{ "source": "firehol_level1", "kind": "malicious", "action": "block", "threatScore": null, "match": "81.2.69.0/24" }| Field | Description |
|---|---|
source | manual or auto for an entry, otherwise the source's name. |
kind | What the IP is known for (see below), or null. |
action | allow, block, or null when the match only labels the IP. |
threatScore | 0–10, or null when the source or entry has none. |
match | The CIDR that contains the IP, in canonical form, e.g. 81.2.69.142/32. |
Entry matches come first, then source matches sorted by name. A source matches at most once per lookup.
Kinds
| Kind | Meaning |
|---|---|
malicious | Attacks, abuse, spam. Also the kind of auto entries from failed authentication and rate limits. |
bot | Automated clients, such as spam bots. |
probe | Scanners. Also the kind of auto entries from honeypot hits. |
proxy | Open, VPN or residential proxies. |
tor | Tor exit nodes. |
crawler | Search engines, SEO tools, link previews, archives and similar crawlers. |
ai_training | Crawlers that collect content for AI model training. |
ai_search | Crawlers that index content for AI search and assistants. |
user_fetch | Agents that fetch a page on a user's request, such as an AI assistant opening a link. |
A proxy or tor match also sets the IP's proxy or tor flag (and so the network rule condition and the PROXY and TOR classifier rules) when no IP resolver provider has already given a value. The last four kinds are covered in Bots & AI agents.
Actions and the verdict
An IP's verdict combines the actions of its matches:
- If any entry match has an action, the entry with the most specific CIDR decides (a
/32beats a/24). - Otherwise, any source with
allowgivesallow. - Otherwise, any source with
blockgivesblock. - Otherwise the verdict is
null(nonein rule conditions).
So entries always override sources: an allow entry exempts an IP from every block list, and a block entry blocks it even if an allow source lists it. Matches with action null never decide.
A verdict has no effect on API-key requests on its own: a block verdict denies them only through a security-group rule with a threatVerdict condition. Logins are different: with [auth] block_threats on (the default), a block verdict from entries refuses them without any rule. See Blocking logins. The action doesn't affect scoring: every match's threatScore and kind feed the classifier, whatever its action.
Private and non-routable IPs
Private, loopback and link-local addresses never match. Their lookups return no matches and no verdict, and reports and signals about them are ignored.
Other addresses that never appear as client IPs on the public internet match only manual entries:
- IPv4:
0.0.0.0/8, carrier-grade NAT100.64.0.0/10(also used by Tailscale and some Kubernetes pod networks),192.0.0.0/24, the documentation ranges192.0.2.0/24,198.51.100.0/24and203.0.113.0/24, the benchmarking range198.18.0.0/15, multicast and240.0.0.0/4. - IPv6:
2001:db8::/32and3fff::/20(documentation),2001:2::/48(benchmarking),100::/64(discard) and multicast.
Threat sources and automatic entries don't apply to them, and reports and signals about them are ignored. Lists such as firehol_level1 include these reserved ranges, and a Sentinel that sees such a client IP is reached from an internal network, for example over Tailscale. A manual entry still blocks or allows them.
To try threat matching, use a public IP: a documentation address such as 203.0.113.9 returns no source matches.
Where threat data is used
- Security-group rules: the
threatandthreatVerdictconditions, on every API-key request. Sentinel looks up the client IP only for groups whose rules need it. - Login steps: password, LDAP, second-factor and OAuth logins from an IP whose entries decide
block, with[auth] block_threats. Sources don't count here. See Blocking logins. - The classifier: the IP rules
MALICIOUS,BOT,PROXY,TORandTHREAT_SCOREinPOST /v2/verify,POST /v2/classifierandGET /v2/inspect, and thesignalandriskrule conditions. - Backend lookups:
POST /v2/threat, and thethreatsandactionfields ofPOST /v2/ip. - Request logs: each logged request's
context.threats(matched source names) andcontext.threatAction(the verdict). See Request logs & analytics.
Who manages what
| Task | Credential |
|---|---|
| Create, edit and delete threat sources and entries; refresh a list | Root user session (403 ROOT_PRIVILEGES_REQUIRED otherwise) |
Look up an IP (POST /v2/threat), report an IP (POST /v2/threat/_report) | restricted or full API key, from any account |
| Deny requests by threat data | Account users who can edit security groups, through threat and threatVerdict rules |
Sources and entries are global: they apply to every account. A public key gets 403 NON_PUBLIC_API_KEY_REQUIRED on the threat endpoints, so the widget can't look up or report IPs. See API keys & access levels.
Replicas
The database is the source of truth. Changes to entries, auto entries included, apply right away on the replica that made them. With an external KV store ([redis]), other replicas apply them on a pub/sub notice. Every replica also re-reads all sources and entries every [threats] sync_interval (5m by default), which catches missed notices and deletes expired entries.
Each replica downloads and indexes source lists itself, on each source's own schedule, so a source's load status can differ briefly between replicas. See Clustering & high availability.
Enabling it
Threat intelligence is on by default. The server keys, with their defaults:
[threats]
store = "file" # "memory": indexes in RAM, rebuilt at startup
sync_interval = "5m" # 10s to 1h
seed_defaults = true # create the default sources on first start
[threats.signals]
enabled = true # false: no auto entries from signals (reports still work)
malicious = { limit = "10/5m", expire = "48h" } # failed authentication and rate limits
probe = { limit = "2/5m", expire = "48h" } # honeypot hitsA signal's limit window must be 1s to 24h, and its expire 1m to 30d. Give both limit and expire when you set malicious or probe. See [threats] and [threats.signals].
On first start, when no threat source exists, Sentinel creates 15 sources from the ALTCHA directory: FireHOL, Spamhaus DROP, blocklist.de, Tor exits, BotScout and four crawler categories. Only firehol_level1, spamhaus_drop and spamhaus_drop_v6 have the action block; the others only label IPs. See Default threat sources.
Then add a rule to each security group that should deny listed IPs. The Recommended preset includes this one:
{
"name": "threat-block",
"action": "deny",
"message": "Blocked by threat intelligence.",
"conditions": [
{ "field": "threatVerdict", "operator": "=", "value": ["block"] },
{ "field": "path", "operator": "!=", "value": ["/v2/verify"] }
]
}The path condition lets a visitor who already got a challenge still submit it. A blocked request gets the rule's message:
{ "code": "ACCESS_DENIED", "error": "Blocked by threat intelligence.", "statusCode": 403 }Threat sources
Root users manage sources under Threat Intelligence → Sources in the admin UI, or with /v2/threat-sources. A source needs a name (lowercase letters, digits, _ and -; not manual, auto or a kind name) and an http:// or https:// url. The fields that matter most:
| Field | Description |
|---|---|
kind, action, threatScore | Applied to every IP in the list. |
schedule | Cron expression for update checks; default 0 */4 * * *. |
maxEntries, maxSizeMb | Only the first maxEntries IPs are loaded; a larger download than maxSizeMb fails and the previous list stays in use. |
headerRow, filter | For CSV lists with a header line: keep only the rows whose columns match, e.g. {"category": ["ai-training"]}. |
enabled | A disabled source doesn't match and isn't updated. |
Sentinel detects the list format from its content: FireHOL .netset, plain IP or CIDR lists, ip ; comment lines (Spamhaus DROP), CSV, and ALTCHA directory lists, also inside a gzip, zip or tar archive with a single file. JSON lists aren't supported. Downloads go through remote files, where you see each source's download and load status. Every field is in the threat sources API reference.
Manual entries
Root users add single IPs or CIDRs under Threat Intelligence → Entries → Create entry, or with POST /v2/threat-entries. The IP is stored as a canonical CIDR (198.51.100.8 becomes 198.51.100.8/32) and can't be changed later; a second entry for the same CIDR returns 409 THREAT_ENTRY_EXISTS. expiresAt must be in the future, and null never expires. See the threat entries API reference.
Blocking logins
With [auth] block_threats = true, the default, Sentinel refuses login attempts from a client IP that a manual or automatic threat entry blocks. No rule is needed. These steps answer 403 IP_BLOCKED before the login ALTCHA or any credential is checked, so a blocked IP costs no password hash or LDAP bind:
POST /v2/auth/loginandPOST /v2/auth/ldapPOST /v2/auth/login/otp,POST /v2/auth/login/passkey/optionsandPOST /v2/auth/login/passkey
The OAuth routes redirect to /login?error=IP_BLOCKED instead: the start route without contacting the provider, the callback without starting a session. The admin UI shows "Login from your IP address is blocked. Contact your administrator."
{ "code": "IP_BLOCKED", "error": "Login from this IP address is blocked.", "statusCode": 403 }What decides:
- Only manual and automatic entries count, not threat sources. The IPs that root users add under Threat Intelligence → Entries and the ones Sentinel lists from signals and reports can refuse a login. IPs that are only in a downloaded list, such as
firehol_level1, can't, even when the source's action isblock. Those lists include whole networks, some as wide as a/8, and could lock out legitimate admins. - The verdict rules apply as usual, among those entries: the most specific CIDR decides, so an
allowentry for the exact IP, or for a narrower CIDR than the blocking entry, lets the IP log in. Private and loopback IPs are never refused; other non-routable IPs, such as Tailscale's100.64.0.0/10addresses, only by a manual entry. - Sessions aren't affected.
GET /v2/auth/challengeand every request with a session token still work, so an admin who's already signed in keeps their session.
Refused attempts are written to the audit log as failed logins with code IP_BLOCKED, so they count toward the [alerts.brute_force] login alerts. The exceptions are …/passkey/options and the OAuth start route, which aren't audited. The 403 refusals appear in altcha_sentinel_requests_blocked_total with reason ip_blocked; OAuth redirects don't. Refusals don't count as threat signals, so a blocked IP that keeps trying doesn't extend its entry; it expires on schedule.
If you lock yourself out, log in from another IP and set the entry's action to allow or delete it under Threat Intelligence → Entries. A connection from a private, loopback or carrier-grade NAT address, for example through an SSH tunnel to the server or over Tailscale, is never refused by an automatic entry. As a last resort, set [auth] block_threats = false and restart.
Rules & signals
Rule conditions
| Condition | Matches | Example |
|---|---|---|
threat | Any match's source (manual, auto or a source name) or kind. Wildcards allowed. Ignores actions and the verdict. | ["tor", "firehol_*"] |
threatVerdict | The IP's verdict: allow, block, or none. No wildcards. | ["block"] |
Use threatVerdict when entries should be able to override lists. A threat rule on malicious also denies an IP that a manual allow entry exempts. A threat condition is useful for a softer response, such as a code challenge for Tor exits and auto-listed IPs:
{
"name": "suspicious-challenge",
"action": "set",
"conditions": [{ "field": "threat", "operator": "=", "value": ["tor", "auto"] }],
"set": [{ "field": "codeChallenge.enabled", "value": "true" }]
}!= holds when no match has any of the values, so threat != ["*"] holds for IPs on no list. See Condition fields.
Classifier rules
| Rule | Triggers when |
|---|---|
MALICIOUS | A match has kind malicious. |
BOT | A match has kind bot, crawler, ai_training, ai_search or user_fetch. |
PROXY, TOR | The IP is a proxy or Tor exit, from the IP resolvers or a proxy or tor match. |
THREAT_SCORE | The highest threatScore of the IP's matches, scored as is. |
These rules use every match, whatever its action: a malicious match triggers MALICIOUS even when an allow entry makes the verdict allow. Scores are in Classifier rules & scores. The same rules are available as signal conditions, which the Recommended preset uses to escalate to a code challenge.
Automatic entries
Sentinel creates auto entries with action block from two signals, counted per client IP:
Failed authentication and rate limits (kind
malicious): a/v2response withINVALID_CREDENTIALS,INCORRECT_OTP,INVALID_OTP_TOKEN,OTP_ATTEMPTS_EXCEEDED,PASSKEY_VERIFICATION_FAILED,API_KEY_REQUIRED,API_KEY_NOT_FOUNDorRATE_LIMITED. A second-factor attempt on a lockedotpJwt(OTP_ATTEMPTS_EXCEEDED) counts too, so retrying a locked login keeps counting.RATE_LIMITEDcounts for the global[rate_limit]and the audio code limit, but not for security-grouprateLimit.limits.UNAUTHORIZED(expired sessions),ACCESS_DENIED(rule denials, threat blocks included),IP_BLOCKED(refused logins) andHEADER_ENTROPYdon't count. By default, 10 within 5 minutes list the IP for 48 hours.Honeypot hits (kind
probe): a request with any method to one of these 19 paths, which only scanners request. By default, 2 within 5 minutes list the IP for 48 hours./.env,/.htaccess,/.git/config,/.svn/entries,/php.ini,/backup.sql,/dump.sql,/admin.php,/install.php,/upgrade.php,/wp-admin,/wp-login.php,/shell.php,/cmd.php,/c99.php,/phpinfo.php,/x.php,/test.php,/xmlrpc.phpThe honeypot answers
404with an empty body, like any unknown path, on the main and public widget listeners, whatever the host.
Reports from your backend (see Report abuse) create auto entries the same way. The description of an auto entry says what created it:
{
"id": "thl_…",
"ip": "89.160.20.130/32",
"kind": "probe",
"action": "block",
"threatScore": null,
"description": "== Abuse Detected ==\nDate: 2026-11-19T02:40:45Z\nReason: honeypot\nLimit: 2/5m\nPath: /wp-login.php\nUser-Agent: Mozilla/5.0 (compatible; scanner)",
"auto": true,
"expiresAt": "2026-11-21T02:40:45.903Z",
…
}A later signal or report for an IP with an auto entry refreshes its description, kind and expiry, but keeps its action, so an auto entry that you changed to allow stays allow. An IP with a manual entry for that exact IP is never auto-listed, and neither is a non-routable IP.
An auto entry blocks the IP's API-key requests only through a threatVerdict rule, but it refuses the IP's logins right away while [auth] block_threats is on. See Blocking logins.
Using the API
Check an IP
From your backend, send the IP to POST /v2/threat with a restricted or full key:
curl -X POST https://sentinel.example.com/v2/threat \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{ "ip": "81.2.69.142" }'{
"data": {
"threats": [
{ "source": "auto", "kind": "bot", "action": "block", "threatScore": null, "match": "81.2.69.142/32" },
{ "source": "firehol_level1", "kind": "malicious", "action": "block", "threatScore": null, "match": "81.2.69.0/24" }
],
"action": "block",
"time": 0.14
}
}threats lists the matches ([] when there are none), action is the verdict (null when no match decides), and time is the lookup duration in milliseconds. Reject or challenge on block; on null, use threats if your policy cares about a kind such as tor. ip must be one IPv4 or IPv6 address; anything else, a CIDR included, returns 400 VALIDATION_ERROR.
/v2/threat reads only Sentinel's own lists and entries, so it never waits on an IP resolver provider. When you also need the country or network type, call POST /v2/ip, which returns the same threats and action. The key's security-group rules run against your backend's IP, not the looked-up one. See the API reference.
Report abuse
When your application detects abuse from an IP, such as spam or credential stuffing, report it. The report that reaches your limit gives the IP an auto entry:
curl -X POST https://sentinel.example.com/v2/threat/_report \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{ "ip": "81.2.69.142", "limit": "2/1m", "kind": "bot", "reason": "Spam comment" }'| Field | Description |
|---|---|
ip | Required. One IPv4 or IPv6 address. |
limit | Required. N/duration, window 1s to 24h: the Nth report of this kind for this IP within the window creates the entry. 1/1m lists the IP on the first report. |
kind | Optional. A kind; default none. |
action | Omit for block; null creates a label-only entry. Reports can't create allow entries. |
expire | Optional. The entry's lifetime, 1m to 30d. Default: the [threats.signals] expire for malicious and probe, 48h otherwise. |
reason | Optional. Up to 1000 characters, stored in the entry's description. |
Three reports in a row with "limit": "2/1m":
| Report | Response data |
|---|---|
| 1st | {"action": "block", "limitExceeded": false, "entryExists": false} |
| 2nd | {"action": "block", "limitExceeded": true, "entryExists": true} |
| 3rd | {"action": "block", "limitExceeded": false, "entryExists": true} |
action is the IP's verdict after the report. It is already block on the first report here because firehol_level1 lists the IP. limitExceeded is true only for the report that created or refreshed the entry, and entryExists is true when the IP has an unexpired entry for that exact IP. Private IPs return {"action": null, "limitExceeded": false, "entryExists": false} and aren't recorded. Other non-routable IPs aren't recorded either: limitExceeded is false, and action and entryExists reflect only their manual entries.
There is one counter per IP and kind, shared by every API key, every account, and the automatic signals of the same kind. The window starts with the first report and doesn't slide. See the API reference.
See the score in the classifier
An entry with a threatScore and no action raises the classifier score without blocking. With a manual entry {"ip": "81.2.69.136/29", "kind": "proxy", "action": null, "threatScore": 6}, POST /v2/classifier with {"ip": "81.2.69.137"} returns:
{
"data": {
"ip": {
"threats": [
{ "source": "manual", "kind": "proxy", "action": null, "threatScore": 6, "match": "81.2.69.136/29" },
{ "source": "firehol_level1", "kind": "malicious", "action": "block", "threatScore": null, "match": "81.2.69.0/24" }
],
"action": "block",
"threatScore": 6,
"proxy": true,
"triggeredRules": ["THREAT_SCORE", "MALICIOUS", "PROXY"],
…
},
"classification": "BAD",
…
}
}Tuning
- Test before you block. Add
"monitor": trueto a newthreatorthreatVerdictrule and watch its activity, or callGET /v2/inspectwith the key: itsnetworkfield lists the client IP'sthreats,actionand IP rules. See Writing security rules. - Label first, block later. Keep lists with single, often dynamic addresses (such as
firehol_abusers_30dandbotscout_30d) as label-only. They still triggerMALICIOUSandBOT, which escalate to a code challenge in the Recommended preset, without denying everyone behind a shared address. - Adjust the signals. Raise
[threats.signals] maliciousif busy NATs trip it, or setenabled = falseto keep only reports. Remember that the resulting auto entries also refuse logins.
An allow entry for a wider CIDR doesn't stop signals from creating a /32 auto entry inside it, and the more specific /32 then decides the verdict. If an auto entry already exists, change its action to allow or delete it.
Limitations
- Threat data is per IP. Shared addresses (mobile carriers, corporate NAT, VPN exits) carry the reputation of everyone behind them.
- Lists are as current as their last download, every 4 hours for the default sources. A failed download keeps the previous list.
- Default sources are created only on first start. Sources added to the defaults in later versions aren't added to existing installations; create them yourself.
- Threat entries store full IP addresses, even with
[privacy] anonymize_ipon. - A rule that denies by threat data also applies to your backend's own calls to
/v2/threatand/v2/ipwith a key of that group.
Related
- Bots & AI agents
- Rules reference: condition fields
- Classifier rules & scores: IP
- Presets
- Remote files & data sources
[threats]and[auth] block_threatsin the Configuration reference- Threat, threat sources and threat entries API reference