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.
[!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=1unless you pay for a higher tier.
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":"[email protected]"}],
"handle":"GOGL","street":"1600 Amphitheatre Parkway","abuse_contacts":[{"handle":"ABUSE5250-ARIN","name":"Abuse","email":"[email protected]"}],
"admin_contacts":[{"handle":"ZG39-ARIN","name":"Google LLC","email":"[email protected]"}],
"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 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 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.
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
[!NOTE] The below examples use the exact data download from the above
curlcommand. 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 provides a free dataset that includes ASN and geolocation data, scoped to the country level. Paid tiers provide more granular geolocation data.
mmdb file
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 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.
.mmdb files somewhere and test with the below.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":{}}
}
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 (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>
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":{}}
2025.09)RIBS/ directoryrib.20250923.1200.bz2)bzip2 -d ./path-to-downloaded-file/rib.20250923.1200.bz2
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.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.
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)
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"}}