Skip to content

README.md

Latest commit

 

History

History
163 lines (118 loc) · 5.43 KB

README.md

File metadata and controls

163 lines (118 loc) · 5.43 KB

ZAnnotate

ZAnnotate is a Go utility that facilitates annotating large datasets with network metadata. Right now this includes:

  • Maxmind GeoIP2
  • AS/Routing Data (based on an MRT routing table)
  • IPInfo.io ASN and Geolocation data

For example, you can add Maxmind geolocation data to a list of IPs:

cat ips.csv | zannotate --geoip2 --geoip2-database=geoip2.mmdb

Installation

ZAnnotate can be installed using make install

make install

or if you don't have make installed, you can use the following command:

cd cmd/zannotate && go install

Either way, this will install the zannotate binary in your $GOPATH/bin directory.

Check that it was installed correctly with:

zannotate --help

Acquiring Datasets

Note

URLs and instructions may change over time. These are up-to-date as of September 2025.

Below are instructions for getting datasets from the below providers.

GeoLite2-ASN

  1. Sign-up form for MaxMind GeoLite Access
  2. Login to your account
  3. Go to the "GeoIP / GeoLite" > "Download files" section where you should see a list of available databases
  4. Download the .mmdb files for GeoLite ASN
  5. Unzip the downloaded file and test with:
echo "1.1.1.1" | zannotate --geoasn --geoasn-database=/path-to-downloaded-file/GeoLite2-ASN_20250923/GeoLite2-ASN.mmdb
{"ip":"1.1.1.1","geoasn":{"asn":13335,"org":"CLOUDFLARENET"}}

BGP Routing Tables

  1. Go to https://archive.routeviews.org/route-views2/bgpdata/
  2. Select a month directory (e.g. 2025.09)
  3. Select the RIBS/ directory
  4. Download a BZiped MRT file (e.g. rib.20250923.1200.bz2)
  5. Unzip the file with:
bzip2 -d ./path-to-downloaded-file/rib.20250923.1200.bz2
  1. Test with:
echo "1.1.1.1" | ./zannotate --routing --routing-mrt-file=/tmp/rib.20250923.1200
{"ip":"1.1.1.1","routing":{"prefix":"1.1.1.0/24","asn":13335,"path":[3561,209,3356,13335]}}

Spur IP Enrichment + Intelligence

spur.us provides per‑IP intelligence such as ASN and organization, infrastructure classification (e.g., datacenter, CDN, mobile), and geolocation metadata. We can query spur.us alongside other sources to enrich annotations and help identify datacenter/Anycast deployments, CDNs, and ISP ownership.

  1. You'll need an API key from Spur to enable ZAnnotate to enrich IPs with their dataset as we'll need to make an API request for each IP address to be enriched. Depending on current pricing, you may need to sign up for a paid account. Check out spur.us/pricing for more details.
  2. Once you have an API key, set it as an environment variable in your current shell session:
export SPUR_API_KEY=your_api_key_here

(If you want to make this permanent, add the above line to your shell profile, e.g. ~/.bashrc or ~/.zshrc) 2. Test with:

$ echo "1.1.1.1" | ./zannotate --spur

Example Output:

{"ip":"1.1.1.1","spur":{"as":{"number":13335,"organization":"Cloudflare, Inc."},"infrastructure":"DATACENTER","ip":"1.1.1.1","location":{"city":"Anycast","country":"ZZ","state":"Anycast"},"organization":"Taguchi Digital Marketing System"}}

Input/Output

Output

By default, ZAnnotate reads new-line delimited IP addresses from standard input and outputs a JSON object per line to standard output like:

echo "1.1.1.1" | zannotate --rdns --geoasn --geoasn-database=/path-to-geo-asn.mmdb
{"ip":"1.1.1.1","geoasn":{"asn":13335,"org":"CLOUDFLARENET"},"rdns":{"domain_names":["one.one.one.one"]}}

If an IP address cannot be annotated, either because of an error or lack of data, there will be an empty field for that annotation. For example, if an IP address is private and therefore has no RDNS or ASN data, the output will look like:

echo "127.0.0.1" | zannotate --rdns --geoasn --geoasn-database=/path-to-geo-asn.mmdb
{"geoasn":{},"rdns":{},"ip":"127.0.0.1"}

Input

You may wish to annotate data that is already in JSON format. You'll then need to use the --input-file-type=json flag. This will insert a zannotate field into the existing JSON object. For example:

echo '{"ip": "1.1.1.1"}'  | ./zannotate --rdns --geoasn --geoasn-database=/path-to-geo-asn.mmdb --input-file-type=json    
{"ip":"1.1.1.1","zannotate":{"geoasn":{"asn":13335,"org":"CLOUDFLARENET"},"rdns":{"domain_names":["one.one.one.one"]}}}

Acquiring Datasets

Note

URLs and instructions may change over time. These are up-to-date as of September 2025. Below are instructions for getting datasets from the below providers.

IPInfo.io

IPInfo.io provides a free dataset that includes ASN and geolocation data, scoped to the country level. Paid tiers provide more granular geo-location data.

  1. Sign up for a free account at IPInfo.io.
  2. Navigate to the Data Download page
  3. Download the mmdb file IPInfo Download Page
  4. Example CLI usage
echo "1.1.1.1" | ./zannotate --ipinfo --ipinfo-database=./path-to-ipinfo-db.mmdb
{"ip":"1.1.1.1","ipinfo":{"country":"Australia","country_code":"AU","continent":"Oceania","continent_code":"OC","asn":"AS13335","as_name":"Cloudflare, Inc.","as_domain":"cloudflare.com"}}