> For the complete documentation index, see [llms.txt](https://docs.scanner.dev/scanner/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/data-transformation-and-enrichment/lookup-table-enrichment/geoip.md).

# GeoIP

GeoIP integrations automatically enrich your logs with location and Autonomous System (AS) context for IP addresses during ingestion. By matching ip addresses against a GeoIP database as logs are indexed, you can:

* Detect activity from unexpected countries, continents, or networks
* Investigate incidents faster with geographic and ownership context already embedded in your log data
* Filter and group logs by country, continent, ASN, or AS organization just like any other log field
* Reduce manual lookups — GeoIP context is searchable and filterable alongside the rest of your data

Scanner syncs GeoIP databases from external providers into [MMDB-format lookup tables](/scanner/using-scanner-complete-feature-reference/data-transformation-and-enrichment/lookup-table-enrichment/custom-lookup-tables.md), then uses those tables to enrich your logs as they're ingested. Once enriched, the GeoIP data becomes part of your searchable log data and can be used in queries and detection rules.

## Supported Providers

Scanner currently supports:

* **IPinfo Lite**: a free GeoIP dataset from [IPinfo](https://ipinfo.io/) that provides country, continent, and ASN/AS organization information for IPv4 and IPv6 addresses. The dataset is distributed in MMDB format and is updated by IPinfo on an ongoing basis.

{% hint style="info" %}
IPinfo Lite is the free tier of IPinfo's offering. An IPinfo account and API token are required to download the file even though the dataset itself is free.
{% endhint %}

## Setting Up IPinfo Integration

### Prerequisites

You will need:

* An IPinfo account and API token from <https://ipinfo.io/>

### Creating the Integration

{% stepper %}
{% step %}

#### Add the integration

In Scanner, navigate to **Settings** → **Integrations**, click **Add Integration**, and select **IPinfo**.
{% endstep %}

{% step %}

#### Provide credentials

Enter a descriptive name for the connection and your IPinfo API token.
{% endstep %}

{% step %}

#### Create a synced lookup table

Click **New Table** to create a synced lookup table backed by IPinfo Lite.
{% endstep %}

{% step %}

#### Name the table

Provide a name for the synced lookup table. Allow 10–15 minutes for the initial sync to complete and the table to appear in the Library.

{% hint style="info" %}
Lookup table names cannot be changed after creation, since they're used as identifiers in transformation references.
{% endhint %}
{% endstep %}

{% step %}

#### Finalize

Scanner will automatically create the synced lookup table and keep it up to date with new IPinfo Lite releases. Note: these lookup tables cannot be manually modified.
{% endstep %}
{% endstepper %}

## Auto-Syncing

GeoIP lookup tables are automatically synced on a regular schedule. When you create a new integration, Scanner queues up an initial background sync that typically completes within 10–15 minutes.

During each sync:

* Scanner checks IPinfo's published checksum for the dataset and skips the download entirely if the file hasn't changed since the last sync
* When the file has changed, Scanner downloads the latest MMDB and atomically replaces the previous version
* All transformations referencing the table pick up the new data on subsequent log ingestion

## Using IPinfo Enrichment

Once you've set up your IPinfo integration and created a synced lookup table, you can add the **Enrich with IPinfo** [transformation](/scanner/using-scanner-complete-feature-reference/data-transformation-and-enrichment/data-transformations.md) to your Index Rules to automatically enrich logs during ingestion.

This transformation reads an IP address from a configurable field on each event, looks it up in the synced MMDB, and merges location and AS context into the event under a configurable target path.

### Parameters

When configuring the transformation in your Index Rule, you'll need to specify:

* **Variant**: The IPinfo dataset to use. Currently only **IPinfo Lite** is supported.
* **Lookup Table**: A lookup table synced from your IPinfo integration with a matching variant.
* **Source Path**: The field path containing the IP address to enrich (e.g., `@ecs.source.ip`, `@ecs.destination.ip`). If the field is missing, empty, or doesn't match any record in the database, the log is left unchanged.
* **Target Path**: The base path under which `geo` and `as` sub-objects are merged. For example, a target path of `@ecs.source` writes results to `@ecs.source.geo.*` and `@ecs.source.as.*`. Existing fields under `geo` and `as` are preserved (the transformation merges into them rather than overwriting).

To enrich both source and destination IPs, add the transformation twice — once with `@ecs.source.ip` / `@ecs.source` and once with `@ecs.destination.ip` / `@ecs.destination`.

### Output Structure

When a match is found, the transformation merges fields aligned with the [Elastic Common Schema](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html) under `<target_path>.geo` and `<target_path>.as`:

Under `<target_path>.geo`:

* `country_iso_code`: ISO 3166-1 alpha-2 country code (e.g., `"DE"`)
* `country_name`: Country name (e.g., `"Germany"`)
* `continent_code`: 2-letter continent code (e.g., `"EU"`)
* `continent_name`: Continent name (e.g., `"Europe"`)

Under `<target_path>.as`:

* `number`: Autonomous System Number as an integer (e.g., `15169`)
* `organization.name`: Name of the organization that owns the AS (e.g., `"Google LLC"`)

Empty fields from the underlying dataset are skipped, so events are never polluted with empty strings.

### Example

For an enrichment configured with **Source Path** `@ecs.source.ip` and **Target Path** `@ecs.source`:

```json
// Input log event
{
  "@ecs": {
    "source": {
      "ip": "8.8.8.8"
    }
  }
}

// Output log event (assuming match)
{
  "@ecs": {
    "source": {
      "ip": "8.8.8.8",
      "geo": {
        "country_iso_code": "US",
        "country_name": "United States",
        "continent_code": "NA",
        "continent_name": "North America"
      },
      "as": {
        "number": 15169,
        "organization": {
          "name": "Google LLC"
        }
      }
    }
  }
}
```

## Troubleshooting

### Lookup table hasn't appeared yet

* The initial sync can take up to 10–15 minutes after you create the integration.
* Confirm in **Settings** → **Integrations** that the IPinfo integration is connected and that the API token is valid.

### Enrichment not appearing in logs

* Confirm the **Enrich with IPinfo** transformation is added to your Index Rule and that the rule applies to the logs you're inspecting.
* Verify the **Source Path** matches your actual log structure (e.g., your logs really do contain `@ecs.source.ip`). Use the Index Rule preview to inspect a sample event.
* Remember that enrichment is best-effort — private/reserved address ranges and IPs not present in the dataset will not produce any output.

## Managing Integrations

{% hint style="warning" %}
**Note**: Deleting an integration will not delete the lookup table. The table will remain available for transformations but will no longer sync with new GeoIP data. This means your GeoIP data will become stale over time. Stale tables can be re-connected to a new integrations of the same type.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/data-transformation-and-enrichment/lookup-table-enrichment/geoip.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.