Threat detection
Some traffic is bad because of where it comes from, not what it submits: botnets, scanners, credential-stuffing sources, anonymizing networks and AI crawlers. This page combines Sentinel's IP reputation (threat lists and entries) with the per-request risk and the per-client penalty, to deny or challenge such traffic on every widget key, check IPs from your backend, and feed what your application detects back into the lists.
Prerequisites: a running Sentinel with an active license. Managing threat sources and entries needs a root user; everything else needs an admin user who can edit security groups and API keys.
What you're defending against
| Threat | Signal |
|---|---|
| IPs on public blocklists (botnets, abusers, spam sources) | Threat sources such as FireHOL level 1 and Spamhaus DROP, downloaded on a schedule. Their verdict block feeds the threatVerdict condition. |
| Scanners probing for weak spots | Honeypot paths on Sentinel's listeners, and your own reports, create automatic block entries. |
| Repeated failed authentication and rate-limit hits | Automatic malicious entries from Sentinel's own signals. |
| Tor exits, proxies and data centers | The network condition, threat kinds tor and proxy, and the IP rules TOR, PROXY and HOSTING. |
| Bots and AI crawlers | Crawler and bot lists, Web Bot Auth signatures, and the agent condition. |
| Clients whose behavior gets worse over time | The penalty, which grows with failed verifications, rate-limit pressure and header rotation. |
How the three numbers differ is explained in Scores, risk & penalty.
Recommended configuration
Server configuration
Threat intelligence is on by default, and the first start creates 15 threat sources. Make sure Sentinel sees the real client IP before you rely on it:
[server]
trusted_proxies = ["10.0.0.0/8"] # your load balancer or CDN, so client IPs are resolved
[threats.signals]
enabled = true # default
malicious = { limit = "10/5m", expire = "48h" } # failed authentication and rate limits
probe = { limit = "2/5m", expire = "48h" } # honeypot hitsConfigure an IP resolver as well, for example MaxMind's Anonymous-IP database for network flags and its City or Country database for countries. Without one, the country condition never matches, hosting is unknown, and the proxy and tor flags come only from the proxy and tor threat lists. See Threat intelligence and [threats].
Widget security groups
Every widget base preset (Recommended, Strict, …) starts with a threats rule that denies IPs with the verdict block, except on /v2/verify. Recommended also escalates on risk, penalty and the MALICIOUS, BOT, PROXY and TOR signals. Apply it to each public group, and add:
| Add-on | Why |
|---|---|
| Trusted networks | Exempts your office and monitoring networks from everything after it. |
| Block AI agents | Denies AI training crawlers and user-driven AI fetchers, and requests whose Web Bot Auth signature doesn't verify. |
Then add a rule after the base preset that gives IPs with a softer reputation a code challenge instead of denying them: Tor exits, IPs that Sentinel or your reports listed automatically, and IPs on the label-only lists:
{
"name": "suspicious-challenge",
"action": "set",
"conditions": [
{ "field": "threat", "operator": "=", "value": ["tor", "auto", "firehol_abusers_30d", "botscout_30d"] }
],
"set": [
{ "field": "codeChallenge.enabled", "value": "true" },
{ "field": "pow.counter", "value": "1-30000" }
]
}A threat condition matches any source name or kind, whatever its action. An auto entry with action block is already denied by the threats rule; this rule catches the ones whose action is null or allow. The group then runs:
preset:trusted:accept
preset:block-ai:signed
preset:block-ai:lists
preset:recommended:threats
preset:recommended:base
preset:recommended:elevated
preset:recommended:high
suspicious-challengeYour own networks
As a root user, create a manual allow entry for each IP of your backends, office NAT and monitoring under Threat Intelligence → Entries → Create entry. An entry for the exact IP stops Sentinel from listing it automatically, for example after a misconfigured API key keeps failing. An allow entry for a wider CIDR doesn't. See Threat intelligence: Tuning.
Integration steps
Step 1 — Check IPs from your backend
Before a sensitive action, such as a sign-up, a payment or a password reset, check the client IP with POST /v2/threat and a restricted key. It reads only Sentinel's own lists and entries, so it never waits on an IP resolver:
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": "firehol_level1", "kind": "malicious", "action": "block", "threatScore": null, "match": "81.2.69.0/24" }
],
"action": "block",
"time": 0.14
}
}Refuse on action: "block". On null, look at threats if your policy cares about a kind such as tor or proxy. When you also need the country or network type, call POST /v2/ip, which returns the same threats and action plus the resolver data. See Check an IP and Lookups & inspect.
Step 2 — Report what your application detects
Report IPs that your application catches doing something no legitimate client does, such as requesting paths your application never serves. This Express middleware reports hits on a few honeypot paths of your own:
import type { NextFunction, Request, Response } from 'express';
const HONEYPOTS = new Set(['/wp-login.php', '/.env', '/phpmyadmin/', '/admin/config.php']);
const SENTINEL_AUTH =
'Basic ' + Buffer.from(`key_…:${process.env.SENTINEL_API_KEY_SECRET}`).toString('base64');
export function honeypot(req: Request, res: Response, next: NextFunction) {
if (!HONEYPOTS.has(req.path)) return next();
// Fire and forget: the scanner gets the same 404 as for any unknown path.
fetch('https://sentinel.example.com/v2/threat/_report', {
method: 'POST',
headers: { Authorization: SENTINEL_AUTH, 'Content-Type': 'application/json' },
body: JSON.stringify({ ip: req.ip, limit: '2/5m', kind: 'probe', reason: `Honeypot ${req.path}` }),
}).catch(() => {});
res.status(404).end();
}limit. The report that reaches it gives the IP an automatic entry, with actionblockby default. There is one counter per IP and kind, shared with Sentinel's ownprobesignals and with every account.expire. Entries from reports last48hformaliciousandprobeby default (the[threats.signals]values); setexpirein the report for another lifetime, from1mto30d.- Label without blocking. Send
"action": nullwith a kind to label an IP for the classifier and thethreatcondition, without a verdict.
Use the same call for failed logins and confirmed spam, as in Protecting login & authentication and Protecting user registration. See Report abuse.
Step 3 — Add your own lists
A root user can add any IP list you trust as a threat source under Threat Intelligence → Sources, or with POST /v2/threat-sources: FireHOL .netset, plain IP or CIDR lists, Spamhaus-style ip ; comment lines, or CSV. Give it "action": "block" to deny through the threats rule, or no action to label only. Start new lists as label-only and watch what they match before you block. See Threat sources.
Step 4 — Respond to an attack
During an ongoing attack on one form or site:
- Switch that group's base preset to Lockdown: every visitor gets a code challenge, strict HIS and a heavy proof-of-work, and hosting, proxy and Tor networks are denied. Switch back when the attack ends.
- Block the attacking ranges for a limited time with manual entries:
curl -X POST https://sentinel.example.com/v2/threat-entries \
-H 'Authorization: Bearer <jwt>' \
-H 'Content-Type: application/json' \
-d '{"ip": "203.0.113.0/24", "kind": "malicious", "action": "block", "expiresAt": "2026-11-21T12:00:00Z", "description": "Credential stuffing, ticket 4711"}'The call needs a root session. A second entry for the same CIDR returns 409 THREAT_ENTRY_EXISTS. Entries apply to every account; other replicas pick them up at once with Redis, otherwise within [threats] sync_interval (default 5m). See Manual entries.
Monitoring & tuning
- Test new rules in monitor mode. Add
"monitor": trueto a newthreatorthreatVerdictrule and watch its Activity before it acts.GET /v2/inspectwith the group's key shows the calling IP'sthreats,action,riskandpenalty. See How to test a rule. - Follow denials. The
altcha_sentinel_requests_blocked_totalmetric counts refused requests byreason:rule_deny(rules, threat blocks included),rate_limit_global,rate_limit_rule,header_entropy,hisandip_blocked. In request logs, filter by Security rulepreset:recommended:threatsto see which requests the threat rule denied. See Monitoring & metrics. - Keep lists current. Each source shows its download status under Remote Files, and the
download_failuresalert reports a list that keeps failing. A failed download keeps the previous list in use. - Review automatic entries. Under Threat Intelligence → Entries, filter automatic entries to see what signals and reports listed. Set a false positive's action to
allowrather than deleting it: a later signal refreshes an automatic entry but keeps its action. - Mind shared IPs. Mobile carriers, corporate NATs and VPN exits carry the reputation of everyone behind them. Prefer challenges (
setrules) over denials for label-only lists and automatic entries.