Bot Detection

Browser & Device Fingerprint

Detects CLI tools, impossible browser/OS combinations, Internet Explorer, and missing User-Agent attributes.

The browser and device checker parses the User-Agent header with ua-parser-js and validates the resulting browser and device attributes. Bots and automated tools produce User-Agents that fail real-world plausibility checks: they identify as CLI libraries, declare impossible OS/browser combinations, or omit fields that every real browser populates.

This checker runs entirely in memory. It reads no databases and performs no network calls.

How It Works

After parsing the User-Agent, the checker evaluates a set of independent conditions. Each condition adds its own penalty if it matches. Multiple conditions can fire on the same request.

CLI or library tools: User-Agents containing keywords like curl, python-requests, go-http-client, axios, or similar library identifiers receive the cliOrLibrary penalty. These strings never appear in browser requests.

Internet Explorer: IE is a deprecated browser with known security vulnerabilities. Requests claiming to use IE receive the internetExplorer penalty. Legitimate modern users no longer run IE.

Linux OS on a desktop: Server-side scripts and headless browsers commonly run on Linux and produce User-Agents that declare a Linux desktop. The linuxOs penalty applies a low-weight signal to desktop Linux claims.

Impossible browser/OS combinations: Certain combinations are physically impossible: macOS does not run on non-Apple hardware in standard deployments, Safari does not run on Windows, and desktop browsers do not report mobile device attributes. When the parsed UA produces one of these contradictions, the impossibleBrowserCombinations penalty fires.

Missing browser fields: Every real browser populates its browser name, browser type, browser version, and engine. Automated tools often omit some of these fields. The checker applies individual penalties for each missing field: browserTypeUnknown, browserNameUnknown, browserVersionUnknown.

Missing device fields: Desktop browsers typically identify their OS but not a specific device vendor or model. Mobile browsers identify all three. When a User-Agent reports a desktop without any OS, or a device type that implies vendor/model data but those fields are absent, the checker applies desktopWithoutOS, deviceVendorUnknown, and deviceModelUnknown.

Configuration

server.ts

await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    enableBrowserAndDeviceChecks: {
      enable: true,
      penalties: {
        cliOrLibrary: 100,
        internetExplorer: 100,
        linuxOs: 10,
        impossibleBrowserCombinations: 30,
        browserTypeUnknown: 10,
        browserNameUnknown: 10,
        desktopWithoutOS: 10,
        deviceVendorUnknown: 10,
        browserVersionUnknown: 10,
        deviceModelUnknown: 5,
      },
    },
  },
})

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

cliOrLibrary

number

Penalty for User-Agents that identify as a CLI tool or HTTP library (curl, python-requests, etc.). Default: 100.

internetExplorer

number

Penalty for User-Agents claiming Internet Explorer. Default: 100.

linuxOs

number

Penalty for desktop User-Agents declaring Linux as the operating system. Default: 10.

impossibleBrowserCombinations

number

Penalty for contradictory browser and OS or device pairs that cannot exist in real browsers. Default: 30.

browserTypeUnknown

number

Penalty when the parsed browser type is missing or unrecognized. Default: 10.

browserNameUnknown

number

Penalty when the parsed browser name is missing or unrecognized. Default: 10.

desktopWithoutOS

number

Penalty for desktop device type with no recognized operating system. Default: 10.

deviceVendorUnknown

number

Penalty for a non-desktop device type with no recognized device vendor. Default: 10.

browserVersionUnknown

number

Penalty when the browser version is absent. Default: 10.

deviceModelUnknown

number

Penalty for a non-desktop device type with no recognized device model. Default: 5.

Reason Codes

Code	Trigger
`CLI_OR_LIBRARY`	User-Agent identified as a CLI tool or HTTP library.
`INTERNET_EXPLORER`	User-Agent claims Internet Explorer.
`LINUX_OS`	User-Agent declares Linux as the operating system.
`IMPOSSIBLE_BROWSER_COMBINATION`	Browser, OS, or device attributes form a physically impossible combination.
`BROWSER_TYPE_UNKNOWN`	Browser type field is absent or unrecognized after parsing.
`BROWSER_NAME_UNKNOWN`	Browser name field is absent or unrecognized after parsing.
`DESKTOP_WITHOUT_OS`	Device type is desktop but no OS is present in the User-Agent.
`DEVICE_VENDOR_UNKNOWN`	Device type implies a vendor but the vendor field is absent.
`BROWSER_VERSION_UNKNOWN`	Browser version field is absent after parsing.
`NO_MODEL`	Device type implies a model but the model field is absent.

The cliOrLibrary and internetExplorer penalties default to 100, matching banScore. A single match from either condition immediately bans the visitor without accumulating other scores. Lower these values if your application intentionally serves programmatic clients.

Good / Bad Bot Verification

Locale Map