Bot Detection

Honeypot

Bans any visitor that requests a configured trap path that no legitimate user would ever visit.

The honeypot checker compares the request path against a list of configured trap URLs. These paths are never linked from your application and serve no legitimate purpose. Real users never visit them. Any request that hits one of these paths must have come from an automated scanner, a bot enumerating common vulnerability paths, or a script that constructed the URL directly.

This checker runs in the cheap phase and requires no databases or external data.

How It Works

The checker compares req.path against each path in honeypot.paths using a case-insensitive match. When any path matches, the checker attaches HONEYPOT_PATH_HIT and BAD_BOT_DETECTED to the reason list. BAD_BOT_DETECTED causes the pipeline to stop immediately and the visitor to be banned, regardless of the accumulated score.

The checker does not apply a numeric score. It relies entirely on the immediate-ban behavior of BAD_BOT_DETECTED.

Configuration

Define your trap paths in honeypot.paths. Good candidates include:

Paths to common CMS login panels you do not use (e.g., /wp-login.php, /wp-admin)
Common environment and configuration file paths (e.g., /.env, /.git/config)
Paths to known vulnerable endpoints in third-party software you do not run
Fake API endpoints that real clients would never call

server.ts

await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    honeypot: {
      enable: true,
      paths: [
        '/.env',
        '/wp-login.php',
        '/wp-admin',
        '/.git/config',
        '/admin/config.php',
        '/phpmyadmin',
        '/xmlrpc.php',
      ],
    },
  },
})

enable

boolean

Enables or disables this checker. Default: true.

paths

string[]

List of path strings that trigger an immediate ban when matched. Path matching is case-insensitive. Default: [] (no trap paths configured).

Reason Codes

Code	Trigger
`HONEYPOT_PATH_HIT`	The request path matched one of the configured trap paths.
`BAD_BOT_DETECTED`	Applied alongside `HONEYPOT_PATH_HIT`. Triggers immediate ban.

The honeypot checker has no effect until you configure at least one path. With an empty paths array, the checker is enabled but never fires. Add paths that are specific to your environment and that real users would never access.

Rotate honeypot paths occasionally. Sophisticated scrapers maintain lists of known honeypot paths and avoid them. Adding application-specific fake paths that look plausible (e.g., /api/v1/internal/debug) makes detection harder to evade.

Timezone Consistency

Known Bad IPs