iploc ↗

Use the iploc stage to enrich event data by associating IPv4 addresses with predefined geolocation attributes. This capability is fundamental for security analysts to understand the geographic origin or destination of network activity within their environment.

Syntax

iploc <field> [loc_field1 [as <alias1>], loc_field2 [as <alias2>], ...]

Parameters

Name Type Required Description
field string, integer Yes The input field containing the IPv4 address to be geolocated.
loc_field string No Specific geolocation attributes to return (for example, loc_country, loc_city). If omitted, a default set is added.
alias string No The alias name for the geolocation field, using the as clause.

Returns

The iploc stage returns the original event records enriched with additional columns containing geolocation information (such as loc_country, loc_city, loc_latlon, etc.) corresponding to the provided IPv4 address.

Usage notes

  • The iploc stage can only be used with fields that contain numbers or strings.
  • Geolocation data generated by this stage can be visualized on a graph of type = map, where the x-axis is set to loc_country or loc_latlon, and the y-axis is a number field.
  • Optimization: It is crucial to optimize queries for performance and cost. Apply filter stages before iploc to reduce the dataset size, ensuring iploc only processes relevant records.
  • Optimization: Use the fields stage early in your query to select only the necessary columns, minimizing the data processed by subsequent stages including iploc.

Examples

Example 1: Basic iploc (default geolocation fields)

Goal: Enrich the ipv4_address field with the default set of geolocation attributes.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| limit 5
| iploc ipv4_address

Explanation: The query applies the iploc stage to the ipv4_address field. Since no specific output fields are defined, it returns the default geolocation columns. Note that for private IPs (RFC1918), the country is often identified as "Private" with NULL values for granular details.

Output:

EVENT_ID IPV4_ADDRESS LOC_COUNTRY LOC_CITY LOC_LATLON
101 192.168.1.10 Private NULL NULL
102 10.0.0.5 Private NULL NULL
103 NULL NULL NULL NULL
104 172.31.255.255 Private NULL NULL
105 192.168.10.20 Private NULL NULL

Example 2: Specifying selected geolocation fields

Goal: Enrich the ipv4_address field but return only the Country and City attributes.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| limit 5
| iploc ipv4_address loc_country, loc_city

Explanation: The query uses iploc on ipv4_address but explicitly requests only the loc_country and loc_city columns to be added to the result set.

Output:

EVENT_ID IPV4_ADDRESS LOC_COUNTRY LOC_CITY
101 192.168.1.10 Private NULL
102 10.0.0.5 Private NULL
103 NULL NULL NULL
104 172.31.255.255 Private NULL
105 192.168.10.20 Private NULL

Example 3: Aliasing geolocation fields

Goal: Enrich the ipv4_address field with specific attributes and rename the output columns for clarity.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| limit 5
| iploc ipv4_address loc_country as IP_Country, loc_latlon as IP_LatLon

Explanation: The query extracts loc_country and loc_latlon for the ipv4_address, renaming them to IP_Country and IP_LatLon respectively using the as clause.

Output:

EVENT_ID IPV4_ADDRESS IP_COUNTRY IP_LATLON
101 192.168.1.10 Private NULL
102 10.0.0.5 Private NULL
103 NULL NULL NULL
104 172.31.255.255 Private NULL
105 192.168.10.20 Private NULL

Example 4: Viewing iploc results as a map graph

Goal: Combine iploc with aggregation to count IP addresses by country and visualize the data.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| iploc ipv4_address loc_country as country
| filter country != null and ipv4_address != null
| comp count() as ip_count by country
| view graph type = map xaxis = country yaxis = ip_count
| limit 10

Explanation: The query enriches the data with loc_country (aliased as country), filters out nulls, and aggregates the count of IPs per country. The view stage then configures the output to be displayed as a map graph. The table output below represents the underlying data for the visualization.

Output:

COUNTRY IP_COUNT
Private 8
NULL 2