LogoDocsHub
Bot Detection

Known Bad IPs

Catches previously banned visitors and high-risk IPs on return visits using compiled MMDB databases.

The known bad IPs checker is the fast path for repeat offenders. It checks the client IP against two locally compiled databases built from your own visitor history. Previously banned IPs are rejected immediately. High-risk IPs (those that accumulated a suspicious score without reaching a ban) receive a proportional penalty in the cheap phase.

This checker avoids re-running the full 17-checker pipeline for visitors that are already known threats. The cheap-phase lookup takes microseconds.

How It Works

The checker performs two lookups:

banned.mmdb: compiled from all rows in the banned table with a non-null IP. If the client IP matches, the checker attaches PREVIOUSLY_BANNED_IP and BAD_BOT_DETECTED. The BAD_BOT_DETECTED code causes the pipeline to stop and the visitor to be banned immediately.

highRisk.mmdb: compiled from rows in the visitors table where suspicious_activity_score is at or above generator.scoreThreshold (default 70). If the client IP matches, the checker applies highRiskPenalty. The penalty is applied once and adds to the cheap-phase total alongside other checkers.

Both databases are optional. If either file is missing (for example, on a fresh installation before bot-detector generate has been run), the corresponding lookup is skipped silently.

These databases do not update automatically. Run bot-detector generate (or call runGeneration()) after bulk ban operations and on a regular schedule to keep the MMDB files current. See the CLI page for the full command reference.

Configuration

server.ts
await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    enableKnownBadIpsCheck: {
      enable: true,
      highRiskPenalty: 30,
    },
  },
})
enable
boolean
Enables or disables this checker. Default: true.
highRiskPenalty
number
Score applied when the client IP is found in highRisk.mmdb. Default: 30.

Reason Codes

CodeTrigger
PREVIOUSLY_BANNED_IPIP matched in banned.mmdb. Applied alongside BAD_BOT_DETECTED.
BAD_BOT_DETECTEDTriggers immediate ban when a previously banned IP is detected.
PREVIOUSLY_HIGH_RISK_IPIP matched in highRisk.mmdb. Applies highRiskPenalty to the score.

Keeping Databases Current

The bot-detector generate command compiles both databases from your current visitor and ban records. Run it after any bulk operation that adds records to the database, and schedule it periodically to incorporate new bans from ongoing traffic.

Terminal
npx bot-detector generate

You can also trigger generation programmatically at runtime:

server.ts
import { runGeneration } from '@riavzon/bot-detector';

await runGeneration();
Schedule bot-detector generate as a nightly cron job. This ensures that IPs banned during the day are caught by the cheap-phase lookup on their next visit without running the full pipeline.

Honeypot

Behavior Rate

Logo