zannotate

ZAnnotate

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

Jump to module setup: Censys · Cymru · GeoASN · GeoIP · GreyNoise · IPInfo.io · RDAP · RDNS/Reverse DNS · Routing/BGP · Spur

You can use any combination of the annotators, for example here is reverse DNS and IPInfo annotations together:

echo "1.1.1.1" | zannotate --rdns --ipinfo --ipinfo-database=./data-snapshots/ipinfo_lite.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"},
   "rdns":{"domain_names":["one.one.one.one"]}
}

The --help has more details on each annotator and it's available flags

zannotate --help

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

Input/Output

Input

New-line Separated IPs

By default, ZAnnotate expects new-line delimited IP addresses on standard input. For example:

printf "1.1.1.1\n8.8.8.8" | zannotate --rdns

{"ip":"1.1.1.1","rdns":{"domain_names":["one.one.one.one"]}}
{"ip":"8.8.8.8","rdns":{"domain_names":["dns.google"]}}

JSON

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"]}}}

If your JSON objects have a different field for the IP address than the default ip, you can specify that with the --input-ip-field flag. For example, if your JSON objects have an ip_address, you can use:

echo '{"ip_address": "1.1.1.1"}' | zannotate --rdns --input-file-type=json --input-ip-field=ip_address

{"ip_address":"1.1.1.1","zannotate":{"rdns":{"domain_names":["one.one.one.one"]}}}

CSV

If your input data is in CSV format, you can use the --input-file-type=csv flag.

printf "name,ip,date\n cloudflare,1.1.1.1,04-04-26\n google,8.8.8.8,04-04-26" | zannotate --rdns --input-file-type=csv

{"name":" cloudflare","ip":"1.1.1.1","date":"04-04-26","zannotate":{"rdns":{"domain_names":["one.one.one.one"]}}}
{"name":" google","ip":"8.8.8.8","date":"04-04-26","zannotate":{"rdns":{"domain_names":["dns.google"]}}}

Similar to JSON, you can use the --input-ip-field flag to specify a column other than ip that contains the IP address.

printf "name,ip_address,date\n cloudflare,1.1.1.1,04-04-26\n google,8.8.8.8,04-04-26" | zannotate --rdns --input-file-type=csv --input-ip-field=ip_address

{"date":"04-04-26","zannotate":{"rdns":{"domain_names":["dns.google"]}},"name":" google","ip_address":"8.8.8.8"}
{"date":"04-04-26","zannotate":{"rdns":{"domain_names":["one.one.one.one"]}},"name":" cloudflare","ip_address":"1.1.1.1"}

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"}

JSON and CSV Output Flags

The --output-annotation-field flag can be used to specify a different field name for the annotations instead of zannotate for both CSV and JSON file inputs.

For example using the output tag --output-annotation-field="info" with JSON input:

printf "name,ip_address,date\n cloudflare,1.1.1.1,04-04-26\n google,8.8.8.8,04-04-26" | zannotate --rdns --input-file-type=csv --input-ip-field=ip_address --output-annotation-field="info"

{"name":" cloudflare","ip_address":"1.1.1.1","date":"04-04-26","info":{"rdns":{"domain_names":["one.one.one.one"]}}}
{"ip_address":"8.8.8.8","date":"04-04-26","info":{"rdns":{"domain_names":["dns.google"]}},"name":" google"}

Modules

[!NOTE] URLs and instructions may change over time. These are up-to-date as of May 2026.

Censys

Censys provides internet-wide host and network data, including information on what services are running on an IP, what TLS certificates it has, and more. They offer a free tier that allows for a limited number of queries per month, which can be used to enrich IP annotations with Censys data.

[!NOTE] The free account (as of April 2026) allows a single concurrent request and 100 requests per month. Once you've used all your credits, the Censys API will return an error upon further requests until your credits reset at the beginning of the next month or you purchase additional credits. ZAnnotate will quit with an error if this occurs to prevent silent errors, so if you have a large dataset to annotate, be mindful of your credit usage and prioritize only annotating the IPs you have credits for. With the free account only offering a single concurrent request, you'll want to leave --censys-threads=1 unless you pay for a higher tier.

1. Create an account at Censys.io and get a Personal Access Token (PAT) from Personal Settings > Personal Access Tokens.
2. Annotate with Censys data:

echo "8.8.8.8" | zannotate --censys --censys-pat="CENSYS_PAT_HERE"

Results truncated for brevity:

{
   "ip":"8.8.8.8",
   "censys": {
      "whois":{
         "network":{ "name":"Google LLC","cidrs":["8.8.8.0/24"],"created":"2023-12-28T00:00:00Z","updated":"2023-12-28T00:00:00Z","allocation_type":"ALLOCATION","handle":"GOGL"},
         "organization":{"state":"CA","postal_code":"94043","country":"US","tech_contacts":[{"handle":"ZG39-ARIN","name":"Google LLC","email":"arin-contact@google.com"}],
            "handle":"GOGL","street":"1600 Amphitheatre Parkway","abuse_contacts":[{"handle":"ABUSE5250-ARIN","name":"Abuse","email":"network-abuse@google.com"}],
            "admin_contacts":[{"handle":"ZG39-ARIN","name":"Google LLC","email":"arin-contact@google.com"}],
            "name":"Google LLC",
            "city":"Mountain View"}},
      "services":[{
         "port":53,"protocol":"DNS","transport_protocol":"udp","ip":"8.8.8.8","scan_time":"2026-04-10T02:55:53Z"}]}}

Cymru

Cymru provides ASN and BGP peering info for IP addresses. You can use the --cymru flag to query Cymru for this information. Cymru has setup a DNS service to provide this information and by default ZAnnotate will use your system default DNS resolvers to query. If you find you're seeing timeouts using your local DNS resolver, you can specify custom resolvers with the --cymru-dns-servers flag. --cymru-threads and --cymru-timeout are also available to configure performance of Cymru annotations, defaults are set to get good performance while avoiding timeouts with most DNS resolvers. By default, the Cymru annotator fetches the origin and peer ASs' as well as AS details on all ASNs. Should you desire a subset, the following flags are available: --cymru-annotate-origin-as, --cymru-annotate-peer-as, and --cymru-annotate-as-details

printf "1.1.1.1" | ./zannotate --cymru --cymru-dns-servers=1.1.1.1,1.0.0.1

{"ip":"207.243.195.103","cymru":{"origin_asns":[7018],"peer_asns":[6939,1299,2914,3257,6461,6762],"asn_details":{"7018":{"asn":7018,"country_code":"US","registry":"arin","asn_allocation_date":"1996-07-30","asn_description":"ATT-INTERNET4 - AT&T Enterprises, LLC, US"},"6939":{"asn":6939,"country_code":"US","registry":"arin","asn_allocation_date":"1996-06-28","asn_description":"HURRICANE - Hurricane Electric LLC, US"},"1299":{"asn":1299,"country_code":"SE","registry":"ripencc","asn_allocation_date":"1993-09-01","asn_description":"TWELVE99 Arelion, fka Telia Carrier, SE"},"2914":{"asn":2914,"country_code":"US","registry":"arin","asn_allocation_date":"1998-12-07","asn_description":"NTT-DATA-2914 - NTT America, Inc., US"},"3257":{"asn":3257,"country_code":"US","registry":"ripencc","asn_allocation_date":"1994-09-30","asn_description""GTT-BACKBONE GTT, US"},"6461":{"asn":6461,"country_code":"US","registry":"arin","asn_allocation_date":"1996-04-22","asn_description":"ZAYO-6461 - Zayo Bandwidth, US"},"6762":{"asn":6762,"country_code":"IT","registry":"ripencc","asn_allocation_date":"1996-09-12","asn_description":"SEABONE-NET TELECOM ITALIA SPARKLE S.p.A., IT"}},"prefix_details":{"207.242.0.0/15":{"prefix":"207.242.0.0/15","origin_asns":[7018],"peer_asns":[1299,2914,3257,6461,6762,6939],"country_code":"US","registry":"arin","allocation_date":"1996-11-01" }}}}

GreyNoise Psychic

GreyNoise is an IP intelligence feed that provides metadata like threat classification and associated CVEs. Their Psychic data downloads provide their data feed in a database suitable for offline data enrichment. To use their download with zannotate, you'll want to download an .mmdb formatted file using your GreyNoise API key. As of April 2026, signing up with a free account gives access to data downloads.

1. Sign up for a free GreyNoise account here.
2. Copy your API key from the appropriate section of your account.
3. Download a mmdb file. The below command downloads data for a single date (April 7th, 2026). You can also download data for a range of days and for models of various levels of detail — see GreyNoise's Psychic documentation for more details.

curl -H "key: GREYNOISE_API_KEY_HERE" \
     https://psychic.labs.greynoise.io/v1/psychic/download/2026-04-07/3/mmdb \
     -o /tmp/m3.mmdb

1. Test GreyNoise data enrichment:

[!NOTE] The below examples use the exact data download from the above curl command. What results you see will depend on the data downloaded.

echo "14.1.105.157" | zannotate --greynoise --greynoise-database=/tmp/m3.mmdb

{"greynoise":{"classification":"malicious","cves":["CVE-2015-2051","CVE-2016-20016","CVE-2018-10561","CVE-2018-10562","CVE-2016-6277","CVE-2024-12847"],"date":"2026-04-07","handshake_complete":true,"last_seen":"2026-04-07T00:00:00Z","seen":true,"tags":["Mirai TCP Scanner","Mirai","Telnet Protocol","Generic IoT Default Password Attempt","Web Crawler","Generic Suspicious Linux Command in Request","HNAP Crawler","Telnet Login Attempt","D-Link Devices HNAP SOAPAction Header RCE Attempt","MVPower CCTV DVR RCE CVE-2016-20016 Attempt","JAWS Webserver RCE","GPON CVE-2018-10561 Router Worm","Generic ${IFS} Use in RCE Attempt","CCTV-DVR RCE","NETGEAR Command Injection CVE-2016-6277","NETGEAR DGN setup.cgi CVE-2024-12847 Command Execution Attempt","CGI Script Scanner"],"actor":"unknown"},"ip":"14.1.105.157"}

Note that many IPs will not be in the GreyNoise dataset, so you may see output like the following:

echo "1.1.1.1" | zannotate --greynoise --greynoise-database=/tmp/m3.mmdb

{"ip":"1.1.1.1","greynoise":{}}

IPInfo.io

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

1. Sign up for a free account at IPInfo.io.
2. Navigate to the Data Download page
3. Download the mmdb file
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"}}

MaxMind GeoIP ASN and City (Formerly GeoIP2)

MaxMind provides datasets for IP geolocation and ASN data in both a free (GeoLite) and paid (GeoIP) version. Additionally, both the GeoLite and GeoIP datasets come in two access patterns - a downloadable database file that can be queried locally and a web API. The GeoIP module in ZAnnotate supports the local database in both GeoLite and GeoIP versions.

The following assumes you want to use the free GeoLite datasets, but the process is similar for the paid GeoIP data.

1. Sign-up form for MaxMind GeoLite Access
2. Login to your account
3. Go to the "GeoIP / GeoLite" > "Download files" section and download the zip files for either GeoLite ASN or GeoLite City datasets.

1. Unzip, place the .mmdb files somewhere and test with the below.

MaxMind GeoIP City

echo "171.67.71.209" | zannotate --geoip2 --geoip2-database=./path-to-geolite2.mmdb

{
   "ip":"171.67.71.209",
   "geoip2":{
      "city":{"name":"Vallejo","id":5405380},
      "country":{"name":"United States","code":"US","id":6252001},
      "continent":{"name":"North America","code":"NA","id":6255149},
      "postal":{"code":"94590"},
      "latlong":{"accuracy_radius":50,"latitude":38.1043,"longitude":-122.2442,"metro_code":807,"time_zone":"America/Los_Angeles"},
      "represented_country":{},
      "registered_country":{"name":"United States","code":"US","id":6252001},
      "metadata":{}}
}

MaxMind GeoLite ASN

echo "171.67.71.209" | zannotate --geoasn --geoasn-database=/path-to-asn-file.mmdb

{"ip":"171.67.71.209","geoasn":{"asn":32,"org":"STANFORD"}}

RDAP (WHOIS successor)

RDAP (Registration Data Access Protocol) is a protocol used to access registration data for internet resources such as IP addresses and domain names and is the successor to WHOIS. ZAnnotate can query RDAP servers to pull registration data for IPs.

echo "1.1.1.1" | zannotate --rdap

Results truncated for brevity:

{
   "ip":"1.1.1.1",
   "whois": {
     "DecodeData": {},
     "Lang": "",
     "Conformance": [
       "history_version_0",
       "nro_rdap_profile_0",
       "cidr0",
       "rdap_level_0"
     ],
     "ObjectClassName": "ip network"
   }
}

This should give you the same output as a direct query to an RDAP server, for example:

rdap 1.1.1.1

IP Network:
  Handle: 1.1.1.0 - 1.1.1.255
  Start Address: 1.1.1.0
  End Address: 1.1.1.255
  IP Version: v4
  Name: APNIC-LABS
  Type: ASSIGNED PORTABLE
...<further output truncated for brevity>

Reverse DNS (RDNS)

ZAnnotate can perform reverse DNS lookups for each IP address. No data download is required, --rdns queries live DNS servers directly.

printf "1.1.1.1\n8.8.8.8" | zannotate --rdns

{"ip":"1.1.1.1","rdns":{"domain_names":["one.one.one.one"]}}
{"ip":"8.8.8.8","rdns":{"domain_names":["dns.google"]}}

If an IP doesn't have a PTR record, the rdns field will be empty:

echo "127.0.0.1" | zannotate --rdns

{"ip":"127.0.0.1","rdns":{}}

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 zipped 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. Get an API key from Spur. Depending on current pricing, you may need to sign up for a paid account — check spur.us/pricing for details.
2. Set your API key as an environment variable:

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)

1. Test with:

echo "1.1.1.1" | zannotate --spur

{"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"}}