zmap/zannotateUtility for annotating Internet datasets with contextual metadata (e.g., origin AS, MaxMind GeoIP2, reverse DNS, and WHOIS)
ZAnnotate is a Go utility that facilitates annotating large IP datasets with network metadata. Right now this includes:
| CLI Flag | Description | Needs API Key | Needs Data Download |
|---|---|---|---|
--censys | Censys internet intelligence (live API) | Yes | |
--cymru | Cymru IP Origin/Peer ASN and ASN details | ||
--geoasn | MaxMind GeoIP ASN data | Yes | |
--geoip2 | MaxMind GeoIP2 city and geolocation data | Yes | |
--greynoise | GreyNoise Psychic threat intelligence and CVE data | Yes (to download) | Yes |
--ipinfo | IPInfo.io ASN and geolocation data | Yes | |
--rdap | RDAP (WHOIS successor) lookups (live) | ||
--rdns | Reverse DNS lookups (live) | ||
--routing | BGP/Routing data from an MRT routing table | Yes | |
--spur | Spur Intelligence (ASN, organization, infrastructure classification, geolocation) | Yes |
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
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
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"]}}
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"]}}}
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"}
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"}
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"}
[!NOTE] URLs and instructions may change over time. These are up-to-date as of May 2026.
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.