Geolocation

The geolocation checker evaluates the richness of the client IP's geolocation data and optionally enforces a country blocklist. Legitimate residential and business IPs resolve to complete geolocation records with all geographic fields populated. IPs from proxies, VPNs, and certain datacenter allocations often return records with many null fields.

This checker runs in the heavy phase. It reads geolocation data already resolved from the MMDB database.

How It Works

Country blocklist: When bannedCountries is non-empty, the checker compares the resolved ISO 3166-1 alpha-2 country code against the list. A match applies the full banScore to the visitor's total, triggering an immediate ban. This check runs first before any field validation.

Missing geo fields: The checker validates nine geolocation fields independently. Each missing or null field applies its own penalty. The fields are: country, region, latitude/longitude, district, city, timezone, subregion, phone code, and continent. A residential IP in a well-covered region typically has all fields populated. An IP behind a VPN or in a poorly covered allocation may be missing several.

Configuration

await defineConfiguration({
  store: { main: { driver: 'sqlite', name: './bot-detector.db' } },
  checkers: {
    enableGeoChecks: {
      enable: true,
      bannedCountries: ['KP', 'CU'],  // ISO 3166-1 alpha-2 codes
      penalties: {
        countryUnknown: 10,
        regionUnknown: 10,
        latLonUnknown: 10,
        districtUnknown: 10,
        cityUnknown: 10,
        timezoneUnknown: 10,
        subregionUnknown: 10,
        phoneUnknown: 10,
        continentUnknown: 10,
      },
    },
  },
})

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

Reason Codes