Bot Detection

Proxy / ISP / Cookie

Detects proxy IPs, datacenter hosting networks, missing canary cookies, and unknown ISP or organization data.

The proxy/ISP/cookie checker evaluates several related signals that together paint a picture of the visitor's network identity. A missing canary cookie suggests the visitor does not persist cookies (common in bots). A proxy IP means the traffic is being routed through an anonymization service. A hosting network IP suggests the request comes from a cloud VM rather than a real user's device. Unknown ISP or organization fields are a secondary indicator of incomplete or obscured network identity.

This checker runs in the heavy phase.

How It Works

Cookie presence: The canary_id cookie is set by detectBots() on the first visit. When a subsequent request arrives without the cookie, the visitor either cleared cookies or never stored them. Most bots discard cookies between requests. A missing cookie on a non-first request applies cookieMissing.

The checker determines whether a request is a "first visit" using internal context. If the visitor truly has no prior record, the missing cookie is expected and is not penalized.

Proxy detection: The checker looks up the client IP in proxy.mmdb, which aggregates known proxy and anonymizer IPs from multiple public sources. A match applies proxyDetected. The proxy database record includes a comment field listing the source feeds that flagged the IP. When the IP appears in two or three sources, a multiSourceBonus2to3 penalty adds on top of proxyDetected. Four or more sources add multiSourceBonus4plus instead.

Hosting detection: The geolocation lookup populates ctx.geoData.hosting. When this flag is true, the IP belongs to a hosting or CDN network. The hostingDetected penalty applies.

Unknown ISP or organization: The geolocation record includes isp and org fields. Legitimate residential and business ISPs always populate these. Proxy services, VPNs, and some datacenter providers leave them null. When either field is absent, the corresponding penalty applies.

Configuration

server.ts

await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    enableProxyIspCookiesChecks: {
      enable: true,
      penalties: {
        cookieMissing: 80,
        proxyDetected: 40,
        multiSourceBonus2to3: 10,
        multiSourceBonus4plus: 20,
        hostingDetected: 50,
        ispUnknown: 10,
        orgUnknown: 10,
      },
    },
  },
})

All weights live inside the penalties: {} sub-object.

cookieMissing

number

Penalty when a returning visitor's request does not carry the canary_id cookie. Default: 80.

proxyDetected

number

Penalty when the client IP is found in proxy.mmdb. Default: 40.

multiSourceBonus2to3

number

Additional penalty when the proxy IP appears in two or three source feeds. Default: 10.

multiSourceBonus4plus

number

Additional penalty when the proxy IP appears in four or more source feeds. Replaces multiSourceBonus2to3. Default: 20.

hostingDetected

number

Penalty when the geolocation data identifies the IP as belonging to a hosting or CDN network. Default: 50.

ispUnknown

number

Penalty when the geolocation ISP field is null or absent. Default: 10.

orgUnknown

number

Penalty when the geolocation organization field is null or absent. Default: 10.

Reason Codes

Code	Trigger
`COOKIE_MISSING`	A returning visitor's request has no `canary_id` cookie.
`PROXY_DETECTED`	The client IP matched a known proxy or anonymizer in `proxy.mmdb`.
`HOSTING_DETECTED`	The geolocation data identifies the IP as a hosting or CDN network.
`ISP_UNKNOWN`	The ISP field in the geolocation record is null or absent.
`ORG_UNKNOWN`	The organization field in the geolocation record is null or absent.

This checker requires cookie-parser to be mounted before detectBots() in the Express middleware stack. Without it, req.cookies is undefined and cookie presence cannot be evaluated. See the Security page for setup details.

The cookieMissing penalty defaults to 80, close to the default banScore of 100. A single missing cookie combined with any other weak signal (unknown ISP, hosting IP) will reach banScore. If your application serves a significant number of legitimate users who disable cookies, reduce this penalty and rely on the combination with other signals.

Behavior Rate

Session Coherence