GeoIP attribution

Geographic and network attribution — the countries and networks on the globe, the ASN on a flow — comes from two local MaxMind-compatible databases that you supply. Nyxtrace ships neither.

Choosing a source

Source	License	Notes
DB-IP Lite	CC-BY 4.0	Free. Attribution is required — keep it visible where you publish results.
MaxMind GeoLite / GeoIP2	MaxMind’s terms	Requires an account.

You need both a City database and an ASN database. They are read by independent readers, so one valid database stays usable if the other is missing or broken.

Installing them

Store both files root-owned and not writable by group or others, record where they came from and their checksums, then pass all four values to the installer:

export NDR_GEOIP_CITY_SOURCE=/root/release/dbip-city-lite.mmdb
export NDR_GEOIP_CITY_SHA256=<sha256>
export NDR_GEOIP_ASN_SOURCE=/root/release/dbip-asn-lite.mmdb
export NDR_GEOIP_ASN_SHA256=<sha256>

The installer verifies both hashes before mutating anything, installs the databases with fixed runtime paths under the state directory, and writes only those paths into the root-only environment file.

Home coordinates are separate

The globe’s home point comes from home_coordinates in your site configuration, not from the databases and not from telemetry. Production configuration validation rejects a tenant whose site file omits it. A tenant without coordinates simply gets no home point — the globe does not guess.

Running without them

Entirely supported. The geo fields stay null, health states the databases are missing, and nothing pretends otherwise. The globe draws no arcs because it refuses to invent locations; the network map and everything else work normally.

Refreshing

Refresh monthly, or at your provider’s publication cadence. Attribution data ages badly: a network reassignment turns a correct answer into a confidently wrong one.

The procedure, in order:

1. Copy both current databases and the environment file to a timestamped root-only backup.
2. Install both new files atomically.
3. Restart the API, then the web service.
4. Require all of: ndr-health green, no enrichment error in the journal, the configured coordinates coming back from the site endpoint, and real external nodes actually being located in the graph.

That last check is the one that catches a database that installed fine and contains nothing useful.

Rolling back

Restore the two database files and the environment file from the timestamped backup, then restart the same two services.

Never log or copy the other secrets from that environment file while doing so. It holds the service credentials, and a rollback is not a reason to put them in a shell history.

Threat intelligence

Separately from GeoIP, an optional local list file can carry domains, addresses and networks. Matches are marked on flow, destination, domain and graph records.

A list match never invents risk: scores stay incident-derived, and the marker is a fact on the record rather than a score contribution. A list is a hint, not a verdict.