Salta ai contenuti
ALTCHA ALTCHA ALTCHA

Questi contenuti non sono ancora disponibili nella tua lingua.

How to Use Threat Intelligence

The Threat Intelligence feature protects your apps and APIs by automatically blocking malicious IP addresses using real-time traffic analysis and dynamic blocklists like Firehol. This guide shows how to configure sources, manage threat lists, and test automatic detection.

Setup

  1. Ensure you have Sentinel installed.

The default Sentinel configuration includes recommended open-source IP intelligence with automatic updates. No additional setup is required.

Managing Sources

Open-source IP intelligence sources can be managed through the administration panel of the app. Threat Sources are IP blocklists that Sentinel downloads from remote locations and keeps updated automatically when changes are detected.

To manage sources:

  1. Go to the Admin section of the app.
  2. Select Threat Sources from the admin menu.

Supported Formats

Sentinel supports blocklists with one IP or CIDR per line. Supported formats include:

  • .csv
  • .txt
  • .ipset
  • .netset

Default Sources

By default, Sentinel includes several blocklists from Firehol, which provide free, frequently updated data on malicious IPs:

  • botscout_30d
    Detects automated bots that register on forums, spread spam, and abuse forms.
  • firehol_abusers_30d
    Tracks abusive IPs over the last 30 days.
  • firehol_level1
    A general-purpose blacklist offering maximum protection with minimal false positives.
  • firehol_proxies
    Tracks known open proxy IPs from multiple sources.
  • spamhaus_drop
    High-trust list of IP ranges associated with known cybercriminals.
  • tor_exits_30d
    Lists all current TOR exit nodes.

These blocklists collectively contain approximately 1.4 million entries used by the Threat Intelligence system.

Automatic Updates

Remote sources are updated automatically when a change is detected on the remote server. To enable this, a CRON schedule must be set for each source to specify how often updates should be checked.

The remote HTTP server should support ETag and/or Last-Modified headers to detect changes efficiently.

Managing the Internal List

While Sources are externally maintained blocklists, the internal list contains user-defined entries that can override those from remote sources. It also includes entries automatically added when threats are detected.

To manage the internal IP list:

  1. Go to the Admin section of the app.
  2. Select Threat List from the admin menu.

Actions

Each entry includes an action that determines how matched IPs are handled:

  • block – Fully blocks the IP address.
  • allow – Explicitly allows the IP, overriding any blocks.
  • penalize – Allows the IP but applies a threat score penalty.

Kinds

The kind of an entry describes the nature of the threat, helping the Threat Intelligence and Classifier systems determine appropriate responses:

  • bot
  • malicious
  • probe
  • proxy
  • tor

Automatic Threat Detection

Sentinel provides real-time protection by detecting malicious behavior on its interfaces. Detection includes:

  • Brute-force attempts using invalid credentials.
  • Continued API usage after exceeding the rate limit.
  • Vulnerability scanning attempts (e.g., accessing /.env, /.git/config, /backup.sql, etc.)

Blocking thresholds are defined via THREATS_*_LIMIT environment variables using rate-limit format.

Default values:

  • THREATS_MALICIOUS_LIMIT: 10/5m(expire=48h)
    Blocks clients after 10 invalid login or rate-limit violations in 5 minutes.
  • THREATS_PROBE_LIMIT: 2/5m(expire=48h)
    Blocks clients probing sensitive paths twice in 5 minutes.

Entries expire automatically based on the expire= parameter.

Detected threats are added to the internal list, where you can review or manually remove them.

Testing Detection

To verify your settings:

  • Attempt to access /.env, /.git/config, or /backup.sql multiple times.
  • Use an invalid API key on any endpoint repeatedly.

After triggering the limits, your IP should appear in the internal list. Remove your IP afterward to reset.

Using with Captcha Verification

Threat Intelligence can be enabled for Captchas — including both Simple PoW and Adaptive modes — through Security Groups by enabling either Autopilot or explicitly setting threats=true in a set rule.

Users blocked by Threat Intelligence will fail verification. The POST /v1/verify API endpoint will respond with HTTP 403 for blocked IPs.

Using with the Classifier

When using the Classifier, IP addresses flagged by Threat Intelligence will trigger rules such as MALICIOUS, PROXY, and TOR. If a Threat Score is set for a blocklisted entry, it will also adjust the overall IP score. No additional setup is required.

Using the Threats API

You can use the Threat Detection API to query the intelligence system from your services:

Terminal window
curl -X POST http://localhost:8080/v1/threat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "ip": "1.2.3.4"
  }'

For convenience, you can also use the alternative GET /v1/threat?ip= endpoint.

Reporting Abuse

While Threat Intelligence automatically monitors traffic and blocks malicious IPs, you can also report abuse manually from your own services, reverse proxies, or security systems.

You can report violations via:

Terminal window
curl -X POST http://localhost:8080/v1/threat/report \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}" \
  -d '{
    "action": "block",
    "ip": "1.2.3.4",
    "limit": "10/5m",
    "kind": "malicious",
    "reason": "API abuse"
  }'

Note: The IP will only be blocked after exceeding the specified limit. You should report each violation, and Sentinel will add the entry once the limit is reached.

If you want to block an IP immediately, use the POST /v1/threat-list endpoint instead.

Disabling Threat Intelligence

To completely disable the Threat Intelligence feature, set the environment variable THREATS_ENABLED to 0.