Stay organized with collections Save and categorize content based on your preferences.

Geolocation enrichment from an IP address

Incoming log data can include external IP addresses without corresponding location information. This is common when an event is logging information about device activity that is not in an enterprise network. For example, a login event to a cloud service would contain a source or client IP address based on the external IP address of a device returned by the carrier NAT.

Chronicle provides geolocation data enrichment (GeoIP data) for external IP addresses to enable more powerful rule detections and greater context for investigations. For example, Chronicle could associate an IP address to a country (country_or_region), such as the United States, and to a specific state, such as Alaska, as well as information about the network the IP address is in, such as ASN and carrier name.

Chronicle uses location data supplied by Google to provide an approximate geographic location and network information for an IP address. You can write Detection Engine rules against these fields in the events. The enriched event data is also exported to BigQuery where it can be used for visualization through Dashboards.

The following IP addresses are not enriched:

  • RFC 1918 private IP address spaces because they are internal to the enterprise network.
  • RFC 5771 multicast IP address space because multicast addresses do not belong to a single location.
  • IPv6 Unique Local addresses.
  • Google Cloud service IP addresses. Exceptions are Google Cloud Compute Engine
    external IP addresses, which are enriched.

Chronicle enriches the following UDM fields with GeoIP data:

  • Principal
  • Target
  • Src
  • Observer
GeoIP data UDM Path
Location (for example, United States) ( principal | target | src | observer ).ip_geo_artifact.location.country_or_region
State (for example, New York) ( principal | target | src | observer ).ip_geo_artifact.location.state
Longitude ( principal | target | src | observer ).ip_geo_artifact.location.region_longitude
Latitude ( principal | target | src | observer ).ip_geo_artifact.location.region_latitude
ASN (autonomous system number) ( principal | target | src | observer )
Carrier name (for example, Verizon) ( principal | target | src | observer )
DNS domain ( principal | target | src | observer )
Organization name ( principal | target | src | observer )

The following example shows the type of geographic information that would be added to a UDM event with an IP address tagged to the Netherlands:

UDM field UDM value
src.ip_geo_artifact.location.country_or_region Netherlands
src.ip_geo_artifact.location.region_latitude 52.132633
src.ip_geo_artifact.location.region_longitude 5.291266 8455 schuberg philis

Using Geolocation enriched fields in rules

GeoIP-enriched UDM can be used in Chronicle's Detection Engine. The following example illustrates how to detect if a user entity is authenticating from multiple distinct states.

rule geoip_user_login_multiple_states_within_1d {

    author = "demo"
    description = "Detect multiple authentication attempts from multiple distinct locations using Chronicle GeoIP enriched UDM."
    severity = "INFORMATIONAL"

    $geoip.metadata.event_type = "USER_LOGIN"
      $geoip.metadata.vendor_name = "Google Workspace" or
      $geoip.metadata.vendor_name = "Google Cloud Platform"
    /* optionally, detect distinct locations at a country */
      $geoip.principal.ip_geo_artifact.location.country_or_region != "" and
      $geoip.principal.ip_geo_artifact.location.country_or_region = $country
      $geoip.principal.ip_geo_artifact.location.state != "" and
      $geoip.principal.ip_geo_artifact.location.state = $state
    $ = $user

    $user over 1d

    $geoip and #state > 1


Google's proprietary IP geolocation technology uses a combination of networking data and other inputs and methods to provide IP address location and network resolution for our users. Other organizations may use different signals or methods, which might occasionally lead to different results.

If cases arise in which you experience an inconsistency in IP geolocation results that Google provides, please open a customer support case, so that we can investigate and, if appropriate, correct our records moving forward.