Skip to main content
ALTCHA®

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 isWho creates it
Threat sourceA 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 entryOne 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" }
FieldDescription
sourcemanual or auto for an entry, otherwise the source's name.
kindWhat the IP is known for (see below), or null.
actionallow, block, or null when the match only labels the IP.
threatScore0–10, or null when the source or entry has none.
matchThe 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

KindMeaning
maliciousAttacks, abuse, spam. Also the kind of auto entries from failed authentication and rate limits.
botAutomated clients, such as spam bots.
probeScanners. Also the kind of auto entries from honeypot hits.
proxyOpen, VPN or residential proxies.
torTor exit nodes.
crawlerSearch engines, SEO tools, link previews, archives and similar crawlers.
ai_trainingCrawlers that collect content for AI model training.
ai_searchCrawlers that index content for AI search and assistants.
user_fetchAgents 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:

  1. If any entry match has an action, the entry with the most specific CIDR decides (a /32 beats a /24).
  2. Otherwise, any source with allow gives allow.
  3. Otherwise, any source with block gives block.
  4. Otherwise the verdict is null (none in 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 NAT 100.64.0.0/10 (also used by Tailscale and some Kubernetes pod networks), 192.0.0.0/24, the documentation ranges 192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24, the benchmarking range 198.18.0.0/15, multicast and 240.0.0.0/4.
  • IPv6: 2001:db8::/32 and 3fff::/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 threat and threatVerdict conditions, 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, TOR and THREAT_SCORE in POST /v2/verify, POST /v2/classifier and GET /v2/inspect, and the signal and risk rule conditions.
  • Backend lookups: POST /v2/threat, and the threats and action fields of POST /v2/ip.
  • Request logs: each logged request's context.threats (matched source names) and context.threatAction (the verdict). See Request logs & analytics.

Who manages what

TaskCredential
Create, edit and delete threat sources and entries; refresh a listRoot 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 dataAccount 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 hits

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

FieldDescription
kind, action, threatScoreApplied to every IP in the list.
scheduleCron expression for update checks; default 0 */4 * * *.
maxEntries, maxSizeMbOnly the first maxEntries IPs are loaded; a larger download than maxSizeMb fails and the previous list stays in use.
headerRow, filterFor CSV lists with a header line: keep only the rows whose columns match, e.g. {"category": ["ai-training"]}.
enabledA 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/login and POST /v2/auth/ldap
  • POST /v2/auth/login/otp, POST /v2/auth/login/passkey/options and POST /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 is block. 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 allow entry 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's 100.64.0.0/10 addresses, only by a manual entry.
  • Sessions aren't affected. GET /v2/auth/challenge and 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

ConditionMatchesExample
threatAny match's source (manual, auto or a source name) or kind. Wildcards allowed. Ignores actions and the verdict.["tor", "firehol_*"]
threatVerdictThe 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

RuleTriggers when
MALICIOUSA match has kind malicious.
BOTA match has kind bot, crawler, ai_training, ai_search or user_fetch.
PROXY, TORThe IP is a proxy or Tor exit, from the IP resolvers or a proxy or tor match.
THREAT_SCOREThe 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 /v2 response with INVALID_CREDENTIALS, INCORRECT_OTP, INVALID_OTP_TOKEN, OTP_ATTEMPTS_EXCEEDED, PASSKEY_VERIFICATION_FAILED, API_KEY_REQUIRED, API_KEY_NOT_FOUND or RATE_LIMITED. A second-factor attempt on a locked otpJwt (OTP_ATTEMPTS_EXCEEDED) counts too, so retrying a locked login keeps counting. RATE_LIMITED counts for the global [rate_limit] and the audio code limit, but not for security-group rateLimit.limits. UNAUTHORIZED (expired sessions), ACCESS_DENIED (rule denials, threat blocks included), IP_BLOCKED (refused logins) and HEADER_ENTROPY don'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.php

    The honeypot answers 404 with 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" }'
FieldDescription
ipRequired. One IPv4 or IPv6 address.
limitRequired. 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.
kindOptional. A kind; default none.
actionOmit for block; null creates a label-only entry. Reports can't create allow entries.
expireOptional. The entry's lifetime, 1m to 30d. Default: the [threats.signals] expire for malicious and probe, 48h otherwise.
reasonOptional. Up to 1000 characters, stored in the entry's description.

Three reports in a row with "limit": "2/1m":

ReportResponse 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": true to a new threat or threatVerdict rule and watch its activity, or call GET /v2/inspect with the key: its network field lists the client IP's threats, action and IP rules. See Writing security rules.
  • Label first, block later. Keep lists with single, often dynamic addresses (such as firehol_abusers_30d and botscout_30d) as label-only. They still trigger MALICIOUS and BOT, which escalate to a code challenge in the Recommended preset, without denying everyone behind a shared address.
  • Adjust the signals. Raise [threats.signals] malicious if busy NATs trip it, or set enabled = false to 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_ip on.
  • A rule that denies by threat data also applies to your backend's own calls to /v2/threat and /v2/ip with a key of that group.

Start typing to search...

↑ ↓ Navigate ↵ Select