ip-api (Geolocation API)

📘

TL;DR

To integrate the IPAPI (Geolocation API) Connector with Query:

• Create an IPAPI (Geolocation API) Connector.
• Use Query Search to parallelize searches and surface details about IP address geolocation and OSINT information for incident response (IR), threat hunting, investigations, and other security and observability enrichment use cases.

Overview

ip-api is a free-to-use online API that contains several APIs, the most useful being the Geolocation API, which contains geolocation, ASN, ISP, BGP/RIR, reverse DNS, and hosting data information on nearly every public IPv4 and IPv6 address. This information is normalized by Query into a distinct entry per-IP address to provide decision support to analysts using the Query Federated Search platform. Instead of needing to enrich every single record, you can easily filter and pivot from the data from ip-api and always return a result no matter how many records match a specific (set) of IP Address(es).

All federated searches have their searches and results expressed in the terms of the Query Data Model (QDM), which is based on the Open Cybersecurity Schema Framework (OCSF). Each API source is normalized into a specific QDM/OCSF Event Class to standardize and normalize the data for increased situational awareness, ease of aggregation of filtering, and easy pivoting.

When searching for any IP Address in Query Federated Search, if there is a match in the ip-api Geolocation API, then the result is brought back and collated without any configuration needed. This can be useful information for analysts making decisions about potentially malicious or otherwise anomalous IP addresses. For instance, while searching or pivoting from IP results from network activity from Amazon VPC Flow Logs in Amazon Security Lake or from Authentication logs from the Google Workspace Reports API, you will receive matches by default from ip-api if it is available. The Geolocation, ASN, and BGP/RIR metadata can be useful for determining impossible travel or potential maliciousness of an otherwise-unknown IP address in your log and event data.

Prerequisites

To connect a ip-api (Geolocation API) Connector with Query Federated Search you do not require any additional information. If you have an Enterprise agreement and have a different HTTPS/TLS-enabled URL endpoint, you can provide that detail as the base URL when configuring the Connector.

To learn how to configure a ip-api (Geolocation API) Connector, proceed to the next section.

Setting up the ip-api (Geolocation API) Connector

Use the following steps to create a new Query Federated Search Connector for ip-api (Geolocation API).

1. Navigate to the Connectors page, select Add Connector, and selectip-api (Geolocation API) from the Threat Intelligence and Enrichment category as shown below (FIG. 1). You can also search for ip-api (Geolocation API) using the search bar in the Add Connector page.

   

2. In the Configure Connector tab, add the following detail as shown below (FIG. 2):

   1. Connector Alias Name: The human-readable name you want to give to this connector.

   2. Default Login: Leave the default value: Default Login.

   3. IP-API IP Geolocation API URL: Leave the default value of http://ip-api.com unless you have a different base URL as part of an enterprise agreement.

      

3. Select Save to save and activate the Connector.

4. Finally, select Test Connection from the bottom-right of the connection pane to ensure that Query can connect the the endpoint and dispatch a search.

You will now see ip-api (Geolocation API) added as an available Connector within the Query Search and Query Summary Insights UI.

Querying ip-api (Geolocation API) Connectors

Within the Query Search UI, all Connectors are enabled by default. To check that your specified Connector(s) for INTEGRATION are enabled, navigate to the category_name section of the Selected Connectors dropdown and ensure that your specified ip-api (Geolocation API) Connector(s) are are selected (denoted by a checkbox) before running your searches as shown below (FIG. 3).

Entity-based Search

The ip-api (Geolocation API) Connector is a static schema Connector which means that all normalization and search translation is completely defined by the Query team. Refer back to the Introduction section and refer to the table to learn which Entities map against which API(s). In the case of ip-api only the Geolocation API is used, which means only IP Address Entities are supported.

In the Federated Search console, select the search dropdown, ensure the Entities radio button is selected and search for your desired Entity as shown below (FIG. 4). For instance, you can search for an IP address such as "8.8.8.8", these can be further correlated against other different Query Connectors.

After selecting an Entity, most allow you to specify an Operator. This allows you to perform simple equality searches or to perform more generalized searches using Contains, Starts With, or Ends With Operators. Only equality search is support for the ip-api Connector.

When you search for multiple values that may be present across different Connectors, the Query Federated Search query planner inspects the Configure Schema metadata to ensure searches are sent to the appropriate Connectors, this operates more as a collated window function within Query and not as an expensive SQL join.

Additionally, you can specify case-sensitivity for the entire search criteria. An example of a multi-value CVE search that uses the equals operator and toggled case-sensitivity is shown below (FIG. 5).

Event-based Search

Event-based searches allow you to broadly search across the entirety of results from a downstream API, or, search for very specific results based on filters.

The ip-api Connector does not currently support Event-based searches, as an IP must always be provided.

Resources

• IP Geolocation - JSON endpoint
• ip-api | pro

Troubleshooting Steps

• Ensure that the Base URL was not changed, unless you have an enterprise agreement.
• API Keys for Pro and Enterprise licenses are not currently supported.

If you have exhausted the above Troubleshooting list, please contact your designated Query Sales Engineer or Customer Success Manager. If you are using a free tenant, please contact Query Customer Success via the Support email in the Help section, or via Intercom within your tenant.