MaxMind Response Integration via API

Purpose

This guide explains how to configure the MaxMind Response integration in Logsign, so that analysts can look up the geographic location of an IP address (city, country, continent) directly from within an Incident or Alarm, without leaving Logsign.

Before you configure anything, it is important to understand what this integration actually is, because its name is easy to misread. MaxMind is best known for two kinds of products: the GeoIP2/GeoLite2 databases (which you download and query locally) and the GeoIP2 Web Services / minFraud APIs (which you call over the internet with an Account ID and License Key, and which are billed per query). The Logsign MaxMind Response integration is the first kind, not the second. It performs an offline lookup against a local MaxMind database file (a .mmdb file) that is bundled with your Logsign appliance. It does not call MaxMind's GeoIP2 Web Services or minFraud APIs at query time, it does not require you to enter a MaxMind Account ID or License Key anywhere in the Logsign UI, and it is not a fraud or risk-scoring tool. If you were looking for real-time IP risk scoring (minFraud) or a hosted geolocation web service, that is not what this integration provides.

Prerequisites

• An Administrator-level account in Logsign with access to Settings > Integrations > Responses. The exact name of a restricted custom-role permission for this screen (if your organization uses custom roles instead of the built-in Administrator role) was not independently verified in this pass; check with your Logsign administrator if you use a scoped role.
• A Logsign appliance with a MaxMind GeoLite2-City (or GeoIP2-City) database file already present on disk. This file is shipped and kept up to date by Logsign as part of the product package; you do not need a MaxMind account of your own for the default, out-of-the-box setup.
• Only needed if you intend to supply your own database (see Step 1): a MaxMind account with permission to download a commercial GeoIP2 City-schema database, and OS-level (shell) access to the Logsign appliance, or a request to Logsign support/professional services to place the file for you. There is no self-service file upload option for this in the Logsign web UI.

Step 1: Locate the MaxMind Database File on Your Logsign Appliance

Logsign ships with a MaxMind GeoLite2-City database file already installed on the appliance, at /opt/logsign-3rdparty/GeoLite2-City.mmdb by default. Logsign keeps this file current by re-downloading it from MaxMind on a regular schedule, in line with MaxMind's own release cadence for GeoLite2 (MaxMind publishes new GeoLite2 releases on a weekly basis). For the default setup, you do not need to do anything with MaxMind directly: the file is already there, and step 2 below just needs to know its path.

Whether the Logsign UI pre-fills this path automatically when you add a new device, or whether you need to type it in yourself, was not independently verified in this pass. If the field is empty when you open the configuration screen, use the default path above.

If you want higher accuracy than the free GeoLite2-City database provides (MaxMind's own comparisons show GeoIP2 databases are more accurate than GeoLite2, because GeoIP2 incorporates additional commercial data sources), you can license your own GeoIP2-City or GeoIP2-Insights database from MaxMind and have it placed on the Logsign appliance at a path of your choosing, then point the configuration at that path instead. This requires an active MaxMind account and license, and OS-level access to the appliance to copy the file there; it is not a self-service change in the Logsign web UI. Contact Logsign support if you need help placing a custom database file.

Step 2: Configure the Integration in Logsign

In Logsign, go to Settings > Integrations > Responses, search for Maxmind Database, click Configure, then +Device, and fill in the following:

Format note: this field expects an absolute filesystem path readable by the Logsign service on the appliance itself, not an HTTP or HTTPS address. Do not enter a MaxMind web service URL here; it will not work, because the integration never makes an outbound HTTP call to MaxMind at query time.

Click Test to verify the configuration before saving. The test action only confirms that the file at the given path can be opened as a valid MaxMind database; it does not check connectivity to MaxMind or validate that the file contains current data. Click Create to save.

Available Methods

geolocate-ip: look up the geographic location of an IP address

Use this method from an Incident or Alarm action to resolve the city, country, and continent associated with a given IP address, such as an alarm's source IP.

The method returns the following fields, in English:

Only these three fields are returned. Even though the underlying MaxMind database also contains postal code, subdivision/region, latitude/longitude, time zone, and accuracy radius, this integration does not surface them. If your use case needs coordinates or postal-level detail, that data is not exposed by this Response integration today; note this as a product gap if a customer specifically asks for it.

For private, reserved, or otherwise unallocated IP addresses (for example internal RFC 1918 ranges like 10.0.0.0/8 or 192.168.0.0/16), MaxMind databases generally have no location record, and this is expected: based on the typical behavior of the underlying MaxMind Go library, the method returns an empty result (no city, country, or continent) rather than an error in that case. This was not independently tested against a live example in this pass.

Notes and Limits

• This is an offline, file-based lookup, not a live web service call. Query volume is not metered or billed by MaxMind, because MaxMind is never contacted at query time. There is no per-lookup rate limit to plan around on the MaxMind side.
• The database bundled by default is GeoLite2-City, MaxMind's free geolocation dataset. MaxMind's own accuracy comparisons state that its commercial GeoIP2 databases are more accurate than GeoLite2, since GeoIP2 incorporates additional data sources even when both are refreshed on the same day. Independent research on GeoLite2 city-level accuracy has found real-world results below MaxMind's own published figures, and IP geolocation of any kind should be treated as approximate, not authoritative, especially for city-level results outside the United States.
• Freshness depends entirely on how recently the database file on the appliance was refreshed. MaxMind itself publishes new GeoLite2 releases on a weekly cadence; if the appliance has not pulled a recent update (for example, if it lacks outbound internet access during scheduled maintenance windows, or updates were disabled), the data can be stale. This refresh happens on the Logsign side as part of appliance maintenance, not something the customer triggers from the Responses screen.
• This integration only supports IP-to-location lookup (city, country, continent). It does not do reverse lookups (location or ASN to IP), it does not return ISP/organization/ASN data, and it does not do fraud or risk scoring (minFraud). If a customer needs those, they are separate MaxMind products and would require a different integration.
• The "Database" field accepts any valid MaxMind DB file in the City schema (GeoLite2-City or GeoIP2-City, including commercial editions like GeoIP2-Insights that ship in the same City schema). Pointing it at a Country-only or ASN-only MaxMind database is not a supported configuration and was not tested.

Troubleshooting