LogoDocsHub
Bot Detection

IP Validation

Detects malformed or invalid client IP addresses before any other checker runs.

The IP validation checker is the first checker in the cheap phase. It validates the resolved client IP address using Node's built-in isIP() function. A valid IP must be a well-formed IPv4 or IPv6 address. Requests with a missing or malformed IP address fail this check immediately.

Bots and automated scripts that manipulate the X-Forwarded-For header often inject invalid values such as empty strings, hostnames, or garbage characters. Catching this early avoids passing a broken IP to every downstream lookup.

How It Works

The checker calls isIP(ctx.ipAddress). If the result is 0 (neither IPv4 nor IPv6), it applies the penalty and attaches IP_INVALID to the reason list. No network calls or database lookups are required.

Configuration

server.ts
await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    enableIpChecks: {
      enable: true,
      penalties: 10,
    },
  },
})
enable
boolean
Enables or disables this checker. Set to false to skip IP validation entirely. Default: true.
penalties
number
Score added when the client IP is missing or malformed. Default: 10.

Reason Codes

CodeTrigger
IP_INVALIDThe resolved client IP address is not a valid IPv4 or IPv6 address.
This checker runs in the cheap phase. If IP validation fails, the score still accumulates with other cheap checkers before a ban decision is made, unless the total already reaches banScore.

Checkers

Good / Bad Bot Verification

Logo