Four GeoIP lookup commands are provided

lookup geo
inputs: clientip
outputs: client_country client_region client_city client_lat client_lon

lookup asn
inputs: src_ip dest_ip
outputs: src_asn dest_asn

lookup geoasn
inputs: src_ip dest_ip
outputs: src_country dest_country src_asn src_as src_org dest_asn dest_as dest_org

lookup ga
inputs: ip
ouputs: country asn org

Background

This app includes GeoLite data created by MaxMind, available from http://www.maxmind.com/

The Add-On is based on Will Hayes @ Splunk's MAXMIND Geo Location Lookup Script, but it has been rewritten to use the native Maxmind C libraries, for increased speed and functionality. GeoASN requires that you build the Maxmind C SDK and Python SDK, and copy the resulting libraries to $SPLUNK_HOME (see detailed instructions in the README file).

The GeoASN lookup commands scales better, and can thus be used from within props.conf to provide automatic Country, Organization and ASN information for any search where an IP address is encountered.

Example Searches

If you have logs with a single IP address field:

| lookup ga ip
| lookup ga ip AS the_name_of_your_ip_addr_field

If you have logs with two IP address fields:

| lookup geoasn src_ip dest_ip
| lookup geoasn src_ip AS your_1st_field dest_ip AS your_2nd_field

Example props.conf

If you always want your searches to lookup the Country, Organization and ASN for IP addresses, you can configure props.conf to do this:

LOOKUP-geoasn = geoasn src_ip dest_ip

We typically use this for sourcetypes that have field extractions for src_ip and dest_ip, e.g., firewall logs.

It produces the following fields:

src_country : The Country as found in the Maxmind GeoCity database
dest_country : The Country as found in the Maxmind GeoCity database
src_asn : The AS number and Org as found in the Maxmind ASN database
src_as : The AS number, without the 'AS' prefix
src_org : The Organization, without the AS number
dest_asn : The AS number and Org as found in the Maxmind ASN database
dest_as : The AS number, without the 'AS' prefix
dest_org : The Organization, without the AS number

If the IP address being looked up is within the ranges defined in RFC 1918 (Private IP addresses), the Country and Organization is set to 'RFC1918', to make it easy to filter on Private IP addresses. AS number is set to 0.

If the address was not found in the database, and it is not an RFC 1918 address, the Country and Organization is set to 'Unknown', and the AS number is set to 0.

Performance

Benchmarking from Maxmind has shown that the native C libraries are capable of doing 400.000 IP address lookups per second, when memory caching is not used. The C implementation is capable of more than 1 million lookups/s when memory caching is used. GeoASN uses both the native C libraries and memory caching for maximum performance.

Another optimization is the lookup of the Country, Organization and ASN for both the src_ip and dest_ip in one single command. Instead of executing multiple lookup commands, we only execute once.

Typical Use Cases

All logs containing IP addresses will be easier to analyze if you, for each IP address, can tell which Country and Organization it belongs to. This is especially relevant for security analysis, where one can perform queries and reports to e.g., show all foreign communications.

Enjoy!

Henrik Strom
Telenor Norway