IP Geolocation¶

This is an optional feature that can be selectively enabled. Enabling it will determine IP Geolocation information for each request. The geolocation information can then be used to be passed downstream to your application and for rule building.

Downstream Headers¶

When enabled, the following headers will be added to downstream requests:

X-Rescaled-Geo-Country: DE
X-Rescaled-Geo-Country-Name: Germany
X-Rescaled-Geo-City: Frankfurt am Main
X-Rescaled-Geo-Timezone: Europe/Berlin
X-Rescaled-Geo-Postal-Code: 60313
X-Rescaled-Geo-Subdivision: Hesse
X-Rescaled-Geo-Continent: EU
X-Rescaled-Geo-Latitude: 50.116900
X-Rescaled-Geo-Longitude: 8.683700

In case the information could not be determined, the headers will be either empty or missing entirely. You can use this information in your downstream application for further threat intelligence purposes (or disregard them, if not relevant for you).

In order to enable this sub-feature, you need to adjust your configuration accordingly.

[...]
features:
  geoip:
    enabled: true
    downstream_headers:
      enabled: true

Rule Building¶

If enabled, you can use the same request metadata during rule building. This allows you to craft powerful rules to either prevent whole countries or continents from accessing the protected website or application or to aggressively challenge users if they visit from countries known to be a risk for you.

You should however keep in mind, that there's no such thing as a 100% reliable geolocation for an IP address. That's not how the internet works, and it's not something you, or we can control. Take the location information with a grain of salt. Too strict rules based on geolocation can also lead to false positives and to a bad user experience.

In order to enable this sub-feature, you need to adjust your configuration accordingly.

If not enabled, you can't use any geolocation metadata in your rules. Doing so will result into a rule compilation error upon startup.

[...]
features:
  geoip:
    enabled: true
    policy_usage:
      enabled: true

Direct Expression¶

You can address the country code within rules using the geoip field. It can either be a single country code as string or a list of country codes as array.

- name: block-china
  action: DENY
  geoip: CN

- name: block-germany-and-france
  action: DENY
  geoip:
    - DE
    - FR

CEL Expressions¶

You can also use CEL expressions to address the geolocation request metadata. This allows you to access more information than just the country code, but it should be used carefully.

Using a CEL expression allows you to combine multiple conditions into a single rule.

- name: block-bots-from-north-america
  action: DENY
  expression:
    all:
      - 'geoContinent == "NA"' 
      - '"bot" in userAgent'

IP Source¶

If needed, you can adjust the header that is used to obtain the IP address to determine the geolocation information from.

[...]
features:
  geoip:
    enabled: true
    client_ip_header: "cf-connecting-ip"

Database¶

You need to provide a MMDB database file for the feature to work. You can either define the path to a file on disk or provide a URL for the database to be downloaded from. When using the latter, you can also provide a refresh interval to automatically re-download the database in a given interval to be sure to always use the latest database version.

[...]
features:
  geoip:
    enabled: true
    database:
      source: "file" # or `url`
      path: "/path/to/GeoLite2-City.mmdb"
      # url: "https://example.com/GeoLite2-City.mmdb"
      refresh_interval: "0"

rescaled can also provide you with an appropriate database. You don't need to obtain the database yourself.