FoxTrust pre-alpha

Signed snapshots

The whole data set is published as MaxMind DB (MMDB) files: a full file every day and a delta every hour. Any standard MMDB reader can open them, and every record is the same verdict the API gives: risk, level, categories and reasons, without sources.

Record

KeyWhat
risk, level, categories, reasonsas in the API; a reason has code, last_seen (Unix seconds) and contribution
countrywhere the address is located, {"iso_code": "<ISO 3166-1 alpha-2>"}, as in GeoIP2 Country records; absent when unknown; see data sources

Location data: IP Geolocation by DB-IP, CC BY 4.0; keep this notice where you show country.

The AS of an address (number, name and registration country), its region and its city are not in the published files: the API gives them per address.

Attacker list

A small signed text file of the addresses seen guessing passwords in the last 7 days, built every hour from the same data as the snapshot. FoxAuth refuses a sign-in on it only when the address has also just failed passwords on that server; anyone may read it the same way.

Header keyWhat
kindalways foxtrust-attackers
format1; reject a format you do not know
versiona + build time YYYYMMDDTHHMMSS, the same as in the manifest
builtAtbuild time, ISO 8601 UTC; always later than the previous list's
validUntilbuiltAt + 3 hours
windowDaysentries were last seen at most this many days before builtAt
entries, columnsthe number of entry lines and the names of their fields
rules, rulesSha256, dataVersionwhat the list was built from
disputewhere to dispute a listing

Unknown header keys are ignored; new ones may appear without a new format. Every other line has five fields separated by a tab:

FieldWhat
networkan IPv4 address, or an IPv6 /64 such as 2001:db8:12:34::/64
codelogin_bruteforce; skip lines with a code you do not know
last_seenUnix seconds of the hour of the latest sighting. For some sources it is the hour the address was still on the source's own list, which covers attacks of the previous 48 hours
bandweak, medium or strong: seen attacking on 1, 2, or 3 or more days of the window
corroborated1 when at least two independent kinds of source saw it, else 0

Where

Files are published under https://data.foxtrust.dev/v1/:

PathWhat
manifest.jsonthe current full and delta versions, their sizes and SHA-256 hashes, and the dispute page
keys.jsonthe signing keys (for information only; see below)
full/daily full files
delta/hourly delta files
attackers/the hourly attacker list, one directory per format version
archive/index.jsonone year of earlier releases
reports/the report of each release

Every file has a detached signature next to it: <file>.sig, the 64-byte raw Ed25519 signature of the exact file bytes.

Check a signature

openssl pkeyutl -verify -rawin -pubin -inkey foxtrust.pub.pem -in f20261007.mmdb -sigfile f20261007.mmdb.sig

foxtrust.pub.pem is a trusted key below in PEM form. Check the manifest's signature first, then compare each file's SHA-256 and size with the manifest.

Trusted keys

Pin these public keys (base64, raw 32-byte Ed25519) in your verifier, for example in FOXTRUST_TRUSTED_KEYS for /verify:

A verifier trusts only the keys it pins, never the keys a publication lists, so a changed publication cannot bring its own key. When the key changes, the new key is listed here first; trust both, and remove the old one after the switch.

Look an address up

mmdblookup --file f20261007.mmdb --ip 203.0.113.7

If an address you control is listed and the listing is wrong, dispute it.