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 ).ip_geo_artifact.network.asn
Carrier name (for example, Verizon)	( principal | target | src | observer ).ip_geo_artifact.network.carrier_name
DNS domain	( principal | target | src | observer ).ip_geo_artifact.network.dns_domain
Organization name	( principal | target | src | observer ).ip_geo_artifact.network.organization_name

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
src.ip_geo_artifact.network.asn	8455
src.ip_geo_artifact.network.carrier_name	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 {

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

  events:
    $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
    )
    
    $geoip.target.user.email_addresses = $user

  match:
    $user over 1d

  condition:
    $geoip and #state > 1
}

Inconsistencies

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.