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
| Key | What |
|---|---|
risk, level, categories, reasons | as in the API; a reason has code, last_seen (Unix seconds) and contribution |
country | where 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.
- Where: the signed manifest lists it under
attackers, then"1"(the format version), withversion,path,sha256,size,builtAt,validUntil,entriesandkeyId. The file ishttps://data.foxtrust.dev/<path>, for examplehttps://data.foxtrust.dev/v1/attackers/1/a20261109T135000.txt, with its signature.txt.sig, signed with the same key as the snapshots. It is served astext/plainwith anETag; ask withIf-None-Matchand an unchanged list costs nothing. The current and the previous list stay published. - Bytes: UTF-8, one line per entry,
\nline ends. Line 1 is a JSON header; an empty list has the header only.
| Header key | What |
|---|---|
kind | always foxtrust-attackers |
format | 1; reject a format you do not know |
version | a + build time YYYYMMDDTHHMMSS, the same as in the manifest |
builtAt | build time, ISO 8601 UTC; always later than the previous list's |
validUntil | builtAt + 3 hours |
windowDays | entries were last seen at most this many days before builtAt |
entries, columns | the number of entry lines and the names of their fields |
rules, rulesSha256, dataVersion | what the list was built from |
dispute | where 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:
| Field | What |
|---|---|
network | an IPv4 address, or an IPv6 /64 such as 2001:db8:12:34::/64 |
code | login_bruteforce; skip lines with a code you do not know |
last_seen | Unix 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 |
band | weak, medium or strong: seen attacking on 1, 2, or 3 or more days of the window |
corroborated | 1 when at least two independent kinds of source saw it, else 0 |
- Lookup: an IPv4 address matches its own line; an IPv6 address matches the line whose
/64contains it. - Check it before use:
- Verify the manifest's signature with a pinned key and read
attackers["1"]. - If its
versionis the one you hold, stop; otherwise downloadpathandpath.sig. - Verify the file's signature with a pinned key (below) and compare its
sizeandsha256with the manifest. - Reject the file unless
kindisfoxtrust-attackers,formatis1,versionequals the manifest's,validUntilis in the future, andbuiltAtis later than the list you already accepted. Keep thatbuiltAtacross restarts if you can. - Once
validUntilhas passed and no newer list verifies, stop acting on the list (fail open).
- Verify the manifest's signature with a pinned key and read
- What is never listed: addresses in the
private_relaycategory (shared by many people), CDN edge networks, special-purpose addresses, listings removed after a dispute, and anything wider than one IPv4 address or one IPv6/64. The file names no source, server or risk. - Format promise: when the format changes, the old format keeps being published next to the new one for at least 4 weeks; the changelog gives the date it ends.
- If your address is listed and should not be, dispute it.
Where
Files are published under https://data.foxtrust.dev/v1/:
| Path | What |
|---|---|
manifest.json | the current full and delta versions, their sizes and SHA-256 hashes, and the dispute page |
keys.json | the 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.json | one 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:
- key id
731e0302:J8tD2l9BFu879cXgAK5lXy39gncA0BrHUo/Fr8w4cQU=
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.