Behavior Rate

The behavior rate checker tracks how many requests a visitor makes within a configurable sliding time window. Bots typically send requests much faster than humans. A scanner probing an entire site, a credential-stuffing script cycling through login combinations, or a price-scraper crawling product pages will all exceed a normal human browsing rate within seconds.

This checker runs in the heavy phase. It reads and writes to the cache layer configured in storage.

How It Works

The checker stores a request counter and a window start timestamp for each canary cookie in the cache. On every request:

1. If no cache entry exists, the checker initializes a new entry and records the first request.
2. If an entry exists and the current time is still within the window, the counter increments.
3. When the counter exceeds behavioral_threshold, the checker applies the penalty and attaches BEHAVIOR_TOO_FAST.
4. When the window expires (elapsed time exceeds behavioral_window), the counter resets and the window restarts.

The canary cookie links requests from the same browser session across multiple requests. Without a cookie (first-time visitors or bots that discard cookies), rate tracking does not apply.

Configuration

await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    enableBehaviorRateCheck: {
      enable: true,
      behavioral_window: 60_000,   // 1 minute in milliseconds
      behavioral_threshold: 30,    // max requests per window
      penalties: 60,
    },
  },
})

Reason Codes