LogoDocsHub
Bot Detection

Known Threats

Checks the client IP against FireHOL threat intelligence feeds and anonymity network lists.

The known threats checker matches the client IP against compiled FireHOL threat intelligence feeds. FireHOL aggregates data from dozens of public sources covering active attackers, scanning infrastructure, abuse participants, and anonymity networks. A match in any feed adds a penalty weighted by that feed's severity level.

This checker runs in the cheap phase with no network I/O, all threat feeds are pre-compiled into MMDB databases loaded at startup.

How It Works

The middleware maintains five MMDB databases compiled from the FireHOL feed collection:

  • firehol_anonymous.mmdb: VPNs, open proxies, and Tor exit nodes not already in the Tor database. A match sets ctx.anon = true and applies the anonymiseNetwork penalty.
  • firehol_l1.mmdb: Confirmed active attack sources. FireHOL maintains this list with a strict no-false-positives policy.
  • firehol_l2.mmdb: Current abuse participants: scanners, brute-force sources, spam senders.
  • firehol_l3.mmdb: Broader web threat aggregation combining multiple exploit and scanning lists.
  • firehol_l4.mmdb: Extended watch list with relaxed inclusion criteria. Higher false-positive rate than levels 1–3.

Each level applies a separate penalty. Multiple levels can fire for the same IP if it appears across feeds.

Configuration

server.ts
await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    enableKnownThreatsDetections: {
      enable: true,
      penalties: {
        anonymiseNetwork: 20,
        threatLevels: {
          criticalLevel1: 40,
          currentAttacksLevel2: 30,
          threatLevel3: 20,
          threatLevel4: 10,
        },
      },
    },
  },
})

All weights live inside the penalties: {} sub-object. The four FireHOL level penalties live in the nested penalties.threatLevels object.

anonymiseNetwork
number
Penalty for IPs matched in the FireHOL anonymity feed (VPNs, open proxies). Default: 20.
threatLevels.criticalLevel1
number
Penalty for IPs in FireHOL Level 1 (confirmed active attack sources). Default: 40.
threatLevels.currentAttacksLevel2
number
Penalty for IPs in FireHOL Level 2 (current scanners, brute-force, spam). Default: 30.
threatLevels.threatLevel3
number
Penalty for IPs in FireHOL Level 3 (broader web threat aggregation). Default: 20.
threatLevels.threatLevel4
number
Penalty for IPs in FireHOL Level 4 (extended watch list, higher false-positive rate). Default: 10.

Reason Codes

CodeTrigger
ANONYMITY_NETWORKIP matched in the FireHOL anonymity feed.
FIREHOL_L1_THREATIP matched in FireHOL Level 1 (confirmed attackers).
FIREHOL_L2_THREATIP matched in FireHOL Level 2 (active abuse).
FIREHOL_L3_THREATIP matched in FireHOL Level 3 (web threats).
FIREHOL_L4_THREATIP matched in FireHOL Level 4 (watch list).
Run bot-detector init to download and compile the FireHOL feeds. The databases are written to _data-sources/ inside the package directory and reloaded automatically when the files change on disk. Re-run init periodically to keep the feeds current.
A Level 4 match on its own is a weak signal. Many residential IPs occasionally appear in Level 4 due to its relaxed inclusion criteria. Consider combining threatLevel4 with other signals rather than raising it to banScore in isolation.

Locale Map

ASN Classification

Logo