Enrichment

Enrichment

prohori enrich adds context to IP addresses: country and city, network owner (ASN), and reputation. Every source is optional, and Prohori works fully offline without any of them.

uv run prohori enrich 203.0.113.7 --offline                 # bundled demo data, no network
uv run prohori enrich 203.0.113.7 --offline --format json   # one JSON report per address
uv run prohori enrich 8.8.8.8 1.1.1.1                       # configured providers, cached
uv run prohori enrich 8.8.8.8 --no-cache                    # ignore cached answers

Arguments are checked before any lookup: anything that is not an IP address (a mistyped hostname, for example) is rejected with exit code 2 and nothing is sent.

Sources

Source	What it gives	What you need	Free-tier limits (checked 2026-10-26)
Bundled demo data	Synthetic data for the documentation addresses in Prohori's samples	Nothing; used with --offline	None
MaxMind GeoLite2	Country, city, ASN, from database files on your computer	A free MaxMind account and uv sync --extra geoip	None (local files)
AbuseIPDB	Abuse confidence score, reports, Tor, network type	ABUSEIPDB_API_KEY	1,000 checks per day
VirusTotal	Security vendors flagging the address	VIRUSTOTAL_API_KEY	4 requests per minute, 500 per day

Both API free tiers are for non-commercial use only. The terms are summarised in docs/LICENSES.md.

Privacy

• Private, reserved and documentation addresses never leave your machine (RFC 1918, loopback, link-local, carrier-grade NAT, documentation and benchmarking ranges and more, including IPv6 forms that embed them).
• Looking up an address tells the provider you are interested in it. VirusTotal adds the addresses you query to its dataset, visible to its other users.
• API keys are read from environment variables or a git-ignored .env file. They are sent only in request headers and are never printed, logged or cached.

Offline mode

--offline never opens a network connection. Answers come from the bundled demo data (marked "not real data"), local GeoLite2 databases and earlier cached answers.

Cache and limits

• Answers are cached for 24 hours in a local SQLite file, so repeated lookups cost nothing. Failures are never cached.
• Daily budgets (1,000 for AbuseIPDB, 500 for VirusTotal) are counted across runs; VirusTotal is held to 4 requests per minute.
• A lookup is tried at most 3 times. A provider that runs out of quota or rejects its key is skipped for the rest of the run, with a note. Nothing retries forever.

Setting up the providers

1. Copy .env.example to .env in the project folder (git ignores it). Never share or commit it.
2. AbuseIPDB: create a free account at abuseipdb.com, open Account -> API, create a key and set ABUSEIPDB_API_KEY= in .env.
3. VirusTotal: create a free account at virustotal.com, open your profile menu -> API key and set VIRUSTOTAL_API_KEY=.
4. GeoLite2: create a free MaxMind account and a licence key, install MaxMind's geoipupdate tool (your MaxMind credentials go in its own GeoIP.conf), download GeoLite2-City and GeoLite2-ASN, run uv sync --extra geoip, and set GEOLITE2_CITY_DB= and GEOLITE2_ASN_DB= to the file paths. The licence requires replacing old databases within 30 days of an update, so run geoipupdate regularly.
5. Try uv run prohori enrich 8.8.8.8.

All settings are listed in docs/ENRICHMENT.md.

Limits of the data

Reputation is evidence, not proof: shared hosting, VPNs, mobile carriers and NAT gateways carry the history of many users. Geolocation is approximate and must never be used to locate a person.