# Threat Intelligence

Threat Intelligence gives Sentinel real-time awareness of IP addresses already known to be malicious — combining open-source threat feeds with its own detection of abusive behavior in live traffic — and factors that reputation into the risk score for every request. Configuring it requires Root privileges (see [Users & Accounts](/docs/sentinel/configure/users-accounts/)).

## Why it matters

Some abuse doesn't need interaction analysis to catch: known Tor exit nodes, open proxies, IPs actively participating in credential-stuffing campaigns, or ranges flagged by the broader threat-intel community are strong signals on their own. Checking reputation up front lets Sentinel respond immediately, without waiting for other signals to accumulate.

## Data sources

By default, Sentinel pulls from FireHOL's open-source blocklists:

| List | What it covers |
|---|---|
| `firehol_level1` | General-purpose blocklist — broad protection, minimal false positives. |
| `firehol_abusers_30d` | IPs with recent abusive activity. |
| `firehol_proxies` | Known open proxies. |
| `botscout_30d` | Automated bot registration/spam sources. |
| `spamhaus_drop` | High-confidence cybercriminal ranges. |
| `tor_exits_30d` | Current Tor exit nodes. |

You can also add your own **custom blocklists** from any remote HTTP server, in `.csv`, `.txt`, `.ipset`, or `.netset` format (one IP or CIDR per line). Sentinel re-fetches a source automatically when it changes, using `ETag`/`Last-Modified` headers — the source server should support at least one of these. Basic auth is supported, either as an `Authorization` header or embedded in the URL.

## Threat kinds and actions

Every entry is a **kind** — `bot`, `malicious`, `probe`, `proxy`, or `tor` — matched to one of three **actions**:

- **`block`** — deny access outright.
- **`allow`** — explicitly permit, overriding a blocklist match.
- **`penalize`** — allow the request through, but add to its threat score. (Some sources, like `firehol_proxies`, ship with no action set by default — detection without automatic blocking.)

These kinds line up directly with the `bot`, `malicious`, `proxy`, and `tor` [Security Group condition fields](/docs/sentinel/configure/security-groups/#schema), so you can write rules against them the same way as any other condition.

## Live-traffic detection

Beyond static feeds, Sentinel detects abuse directly from what it observes:

- Repeated invalid login attempts / credential stuffing.
- Continued requests after a rate limit has already been exceeded.
- Vulnerability scanning — probing sensitive paths like `/.env`, `/.git/config`, or `/backup.sql`.

To test it yourself: repeatedly hit a sensitive path like `/.env`, or repeatedly use an invalid API key — your IP should show up in the internal threat list once the relevant threshold is crossed.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `THREATS_ENABLED` | `1` | Set to `0` to disable the feature entirely. |
| `THREATS_MALICIOUS_LIMIT` | `10/5m(expire=48h)` | Blocks after 10 invalid logins / rate-limit violations within 5 minutes; the block expires after 48h. |
| `THREATS_PROBE_LIMIT` | `2/5m(expire=48h)` | Blocks after 2 requests to sensitive/scanning-pattern paths within 5 minutes. |
| `THREATS_BOT_LIMIT` / `THREATS_PROXY_LIMIT` / `THREATS_TOR_LIMIT` | *(empty)* | Same rate-limit syntax, for the `bot`/`proxy`/`tor` kinds specifically. |
| `THREATS_INDEX_STORE` | `auto` | `auto` picks in-memory or SQLite based on available RAM; set explicitly to force one. |

Enable enforcement in a Security Group by setting `threats=true` in a rule, or simply turn on [Autopilot](/docs/sentinel/features/autopilot/). A blocked IP gets an HTTP `403` from `POST /v1/verify`.

## Threats API

Query an IP's current status:

```
POST /v1/threat
Authorization: Bearer {API_KEY}
Content-Type: application/json

{ "ip": "1.2.3.4" }
```

Report abuse (adds toward the given limit, rather than blocking immediately):

```
POST /v1/threat/report
Authorization: Bearer {API_KEY}

{ "action": "block", "ip": "1.2.3.4", "limit": "10/5m", "kind": "malicious", "reason": "API abuse" }
```

For an immediate block instead of a threshold-based one, use `POST /v1/threat-list`.

## Classifier integration

When [Classifier](/docs/sentinel/features/classifier/) is active, a blocklist match also triggers the corresponding classification rule (`MALICIOUS`, `PROXY`, `TOR`) and adjusts the request's overall score accordingly.

## Related

- [Adaptive Captcha](/docs/sentinel/features/adaptive-captcha/)
- [Autopilot](/docs/sentinel/features/autopilot/) — enables Threat Intelligence enforcement automatically.
- [Rate Limiters](/docs/sentinel/features/rate-limiters/)
- [IP Resolvers](/docs/sentinel/integrations/ip-resolvers/) — accuracy here depends on Sentinel seeing the real client IP; see [Reverse Proxy](/docs/sentinel/operations/reverse-proxy/) if you're behind a load balancer or CDN.