OCSF

Package

Time-Travel for Investigators: Live & Retro GeoIP/ASN Enrichment

Aug 7, 2025

Aug 7, 2025

In threat detection, investigation, and response (TDIR), context is everything. The value of an IP address in a log entry multiplies when you can instantly map it to a geographic location and the autonomous system (AS) it belongs to. Tenzir's geo-open package, available in the Tenzir Library, delivers this context dynamically, providing daily-updated GeoIP and ASN data for your security analytics workflows.

The Power of Dynamic Context

The geo-open package is built on Tenzir's powerful enrichment framework. This design separates the process of updating contextual data from its application.

The result is a highly efficient model: one pipeline continuously updates the geo-open context in the background, while any number of security pipelines can query this fresh data in real time.

This architecture offers distinct advantages:

  • Centralized Enrichment: Manage your GeoIP and ASN intelligence from a single, authoritative source within Tenzir.

  • Decoupled Pipelines: Your analysis pipelines remain clean and focused on logic, as they don't need to perform their own lookups. They simply query the context.

  • Retro-Enrichment: This is a unique capability for investigators. Need to analyze an incident from last Tuesday? You can use the GeoIP database snapshot from that specific day. The internet's structure changes daily, and accurate historical investigation requires historical context.

The geo-open package uses the Geo-Open dataset, which is generated daily from public BGP AS announcements. This provides a fresh snapshot of the internet's routing landscape, directly at your fingertips.

The Update Pipeline in Action

So, how does Tenzir keep this data fresh? The geo-open package contains a simple but powerful pipeline that runs automatically in the background:

every 24h {
  from_http "https://cra.circl.lu/opendata/geo-open/mmdb-country-asn/latest.mmdb" {
    context::load "geo-open-country-asn"

Let's break it down:

  • every 24h: This trigger automatically runs the pipeline once a day.

  • from_http: This operator fetches the latest combined Country and ASN MMDB database directly from CIRCL's repository.

  • context::load: This operator takes the fetched database and loads it into the Tenzir context named geo-open-country-asn, overwriting the previous day's version.

This pipeline is the engine that powers the dynamic enrichment. It runs silently, ensuring that any other pipeline using context::enrich "geo-open-country-asn" always has access to the most recent data without any manual intervention.

On-Demand Time-Travel for Investigations

The automated daily update is perfect for ensuring your live and recent data is always enriched with the correct context. But what if you're digging into an incident from six months ago and need to load the exact GeoIP database from that specific day for your analysis?

This is where the "Time-Travel" capability becomes a powerful, interactive tool for investigators. Tenzir allows you to load a specific historical database on the fly. For example, to analyze events from August 3rd, 2025, you could run the following pipeline:

from {date: "2025-08-03"}
http f"https://cra.circl.lu/opendata/geo-open/mmdb-country-asn/{date}-GeoOpen-Country-ASN.mmdb" {
  context::load "geo-open-country-asn"

This pipeline dynamically constructs the URL for the desired date, fetches that specific historical MMDB file, and loads it into the context. Your subsequent queries will now use the internet's snapshot from that exact day. This provides an unparalleled level of accuracy for historical investigations, ensuring your findings are based on the ground truth of that moment in time.

Actionable Data for SecDataOps Engineers

For SecDataOps teams, the geo-open package streamlines operations and enhances analytical depth:

  • Improved Situational Awareness: Enriching logs with real-time GeoIP and ASN data helps you better understand network traffic patterns and identify anomalous activity.

  • Effective Threat Hunting: Correlating network events with up-to-date location and organization information aids proactive threat hunting.

  • Accurate Incident Response: During an incident, using the correct GeoIP data for the specific time of an event is crucial for sound analysis.

  • OCSF Integration: The package is designed to work with the Open Cybersecurity Schema Framework (OCSF), making it straightforward to enrich your security events and add valuable, actionable fields.

Here is a simple TQL query to enrich a few IP addresses:

from {server: 1.1.1.1},
     {server: 8.8.8.8},
     {server: 9.9.9.9}
context::enrich "geo-open-country-asn", key=server

This pipeline produces a clean, structured output:

{
  server: 1.1.1.1,
  "geo-open-country-asn": {
    country: {
      iso_code: "US",
      AutonomousSystemNumber: "13335",
      AutonomousSystemOrganization: "CLOUDFLARENET",
    },
  },
}
{
  server: 8.8.8.8,
  "geo-open-country-asn": {
    country: {
      iso_code: "US",
      AutonomousSystemNumber: "15169",
      AutonomousSystemOrganization: "GOOGLE",
    },
  },
}
{
  server: 9.9.9.9,
  "geo-open-country-asn": {
    country: {
      iso_code: "US",
      AutonomousSystemNumber: "19281",
      AutonomousSystemOrganization: "QUAD9-AS-1"

More practically, you can deploy a pipeline to automatically enrich OCSF-compliant events. The following pipeline enriches network activity events by adding location and ASN details to the source and destination endpoints:

subscribe "{{ inputs.enrich-input }}"
if src_endpoint?.ip? != null {
  context::enrich "geo-open-country-asn", key=src_endpoint.ip, into=_tmp
  if _tmp != null {
    if _tmp.country.iso_code != "None" {
      src_endpoint.location.country = _tmp.country.iso_code
    }
    src_endpoint.autonomous_system = {
      name: _tmp.country.AutonomousSystemOrganization,
      number: _tmp.country.AutonomousSystemNumber.int(),
    }
  }
  drop _tmp
}
if dst_endpoint?.ip? != null {
  context::enrich "geo-open-country-asn", key=dst_endpoint.ip, into=_tmp
  if _tmp != null {
    if _tmp.country.iso_code != "None" {
      dst_endpoint.location.country = _tmp.country.iso_code
    }
    dst_endpoint.autonomous_system = {
      name: _tmp.country.AutonomousSystemOrganization,
      number: _tmp.country.AutonomousSystemNumber.int(),
    }
  }
  drop _tmp
}
publish "{{ inputs.enrich-output }}"

This pipeline transparently enriches any OCSF event in the Network Activity category, making your standardized data immediately more useful for analysis.

A Nod to the Community

We'd like to acknowledge the team at CIRCL for their work on the Geo-Open dataset and the mmdb-server project. Open source intelligence initiatives are vital to the security community, and we appreciate their work.

The geo-open package is available in the Tenzir Library. We invite you to explore it and see how dynamic context can elevate your security data operations.