ip-lookup

The ip-lookup operator retrieves geolocation data of IP addresses using MaxMind’s GeoIP2 and GeoLite2 or IPinfo’s IP address databases to enrich events with details such as city, continent, country, latitude, longitude, postal code, region, and time zone based on the provided IP address field. You can customize which fields to return, add prefixes, and their language.

You can display ip-lookup results in a Map Chart.

Prerequisites

​

The ip-lookup operator needs a .mmdb database file. You need to download the file from MaxMind or IPinfo and then create a lookup table with it. This file contains the geolocation data needed for IP address enrichment.

• MaxMind’s GeoIP2 City, GeoIP2 Country, and GeoLite2 are supported. The GeoIP2 databases are a more accurate version of the free GeoLite2 City database.

• To download the free GeoLite2 City database you need a free GeoLite2 account. For details, see MaxMind’s Accessing GeoLite2 Free Geolocation Data documentation.

• IPinfo’s IP Geolocation, IP to privacy detection, ASN, IP to Company, Abuse contact, and WHOIS databases are supported.

• IPinfo also provides the following free IP databases: IP to Country, IP to ASN, and IP to Country ASN.

Syntax

​

Arguments

​

• Scope: The events to search.
• OutputField: Field(s) to return from the lookup. By default, all available fields are returned.
  • city – for example, Georgetown
  • continent – for example, North America
  • continent_code – for example, NA
  • country – for example, United States
  • country_code – for example, US
  • lat – numeric latitude coordinate
  • lon – numeric longitude coordinate
  • postal – for example, 40324
  • region – for example, Kentucky
  • region_code – for example, KY
  • time_zone – for example, America/Los_Angeles
• Prefix: A prefix to add to the output fields. For example, if the prefix is set to ip_, output fields will be named ip_city ip_country, etc.
• Lang: Specifies the language for data retrieval. Defaults to en for English. Supports Brazilian Portuguese (pt-BR), English (en), French (fr), German (de), Japanese (ja), Russian (ru), Simplified Chinese (zh-CN), and Spanish (es).
• LookupTable: The lookup filename that contains the database. Do not add the .mmdb file extension. For example, a filename of GeoLite2-city.mmdb is entered as GeoLite2-city.
• IPField: The field name with an IP address. Defaults to ip.

Examples

​

The runnable examples below require you to first acquire and upload a compatible .mmdb file, as outlined above in Prerequisites.

• Lookup geolocation data on the dstaddr field:

  dataset="cribl_search_sample" dataSource=*vpc* | limit 1000  | ip-lookup geocity on dstaddr

  Copy Run in Cribl Search

• Lookup latitude and longitude data on the dstaddr field:

  dataset="cribl_search_sample" dataSource=*vpc* | limit 1000  | ip-lookup output=lat,lon geocity on dstaddr

  Copy Run in Cribl Search

• Lookup geolocation data on the ip field:

  dataset=myDataset
  | ip-lookup 'GeoLite2-City'

  Copy

• Lookup geolocation data on the my_ip field:

  dataset=myDataset
  | ip-lookup 'GeoLite2-City' on my_ip

  Copy

• Lookup geolocation data on the ip_address field and return only the prefixed ip_lat and ip_lon fields:

  dataset=myDataset
  | ip-lookup output=lat,lon prefix=ip_ 'GeoLite2-City' on ip_address

  Copy

• Lookup geolocation data on the ip_address field and return only the city and region fields in Spanish:

  dataset=myDataset
  | ip-lookup output=city,region lang=es 'GeoIP2-City' on ip_address

  Copy