ZAnnotate 是一个 Go 语言工具，用于为大型 IP 数据集添加网络元数据的注释。目前支持的注释器包括：
| CLI 标志 | 描述 | 需要 API 密钥 | 需要下载数据 |
|---|---|---|---|
--censys | Censys 互联网情报（实时 API） | 是 | |
--cymru | Cymru IP 源/对等 ASN 及 ASN 详细信息 | ||
--geoasn | MaxMind GeoIP ASN 数据 | 是 | |
--geoip2 | MaxMind GeoIP2 城市和地理位置数据 | 是 | |
--greynoise | GreyNoise Psychic 威胁情报和 CVE 数据 | 是（用于下载） | 是 |
--ipinfo | IPInfo.io ASN 和地理位置数据 | 是 | |
--rdap | RDAP（WHOIS 继任者）查询（实时） | ||
--rdns | 反向 DNS 查询（实时） | ||
--routing | 来自 MRT 路由表的 BGP/路由数据 | 是 | |
--spur | Spur 情报（ASN、组织、基础设施分类、地理位置） | 是 |
跳转到模块设置： Censys · Cymru · GeoASN · GeoIP · GreyNoise · IPInfo.io · RDAP · RDNS/反向 DNS · 路由/BGP · Spur
你可以使用任意注释器组合，例如下面同时使用反向 DNS 和 IPInfo 注释：
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"]}
}
--help 提供了更多关于每个注释器的详细信息以及可用的标志。
zannotate --help
ZAnnotate 可以通过 make install 安装：
make install
或者，如果你没有安装 make，可以使用以下命令：
cd cmd/zannotate && go install
无论哪种方式，都会将 zannotate 二进制文件安装到你的 $GOPATH/bin 目录中。
检查是否正确安装：
zannotate --help
默认情况下，ZAnnotate 期望标准输入提供换行分隔的 IP 地址。例如：
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 格式的数据进行注释。此时需要使用 --input-file-type=json 标志。这会将一个 zannotate 字段插入到现有 JSON 对象中。例如：
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"]}}}
如果你的 JSON 对象中 IP 地址的字段名不是默认的 ip，可以使用 --input-ip-field 标志指定。例如，如果 JSON 对象中有 ip_address 字段，可以这样使用：
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 格式，可以使用 --input-file-type=csv 标志。
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"]}}}
类似于 JSON，你可以使用 --input-ip-field 标志来指定包含 IP 地址的列，而不是默认的 ip 列。
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"}
默认情况下，ZAnnotate 从标准输入读取换行分隔的 IP 地址，并将 JSON 对象逐行输出到标准输出，如下所示：
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"]}}
如果某个 IP 地址因为错误或缺乏数据而无法注释，则该注释字段为空。 例如，如果 IP 地址是私有地址，因而没有 RDNS 或 ASN 数据，则输出如下：
echo "127.0.0.1" | zannotate --rdns --geoasn --geoasn-database=/path-to-geo-asn.mmdb
{"geoasn":{},"rdns":{},"ip":"127.0.0.1"}
--output-annotation-field 标志可用于指定注释的字段名，而不是默认的 zannotate，同时适用于 CSV 和 JSON 文件输入。
例如，使用输出标签 --output-annotation-field="info" 并配合 JSON 输入：
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] URL 和说明可能随时间变化。以下信息截至 2026 年 5 月是准确的。
Censys 提供全球范围的主机和网络数据，包括 IP 上运行的服务、TLS 证书等信息。他们提供免费套餐，每月可进行有限次数的查询，可用于使用 Censys 数据丰富 IP 注释。
[!NOTE] 免费账户（截至 2026 年 4 月）允许单次并发请求，每月 100 次请求。 一旦用完所有额度，Censys API 将在后续请求中返回错误，直到下个月额度重置或你购买更多额度。 如果发生这种情况，ZAnnotate 将退出并报错，以避免静默错误。因此，如果你有大量数据集需要注释，请注意你的额度使用情况，并优先注释你有额度支持的 IP。 由于免费账户仅提供单次并发请求，你需要保持
--censys-threads=1，除非你付费购买了更高层级。
echo "8.8.8.8" | zannotate --censys --censys-pat="CENSYS_PAT_HERE"
为简洁起见，结果已截断：
{
"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 提供 IP 地址的 ASN 和 BGP 对等信息。你可以使用 --cymru 标志向 Cymru 查询这些信息。
Cymru 设置了一个 DNS 服务来提供这些信息，默认情况下 ZAnnotate 将使用系统默认的 DNS 解析器进行查询。
如果你发现使用本地 DNS 解析器时出现超时，可以使用 --cymru-dns-servers 标志指定自定义解析器。
还可以使用 --cymru-threads 和 --cymru-timeout 来配置 Cymru 注释的性能，默认设置旨在获得良好性能的同时避免大多数 DNS 解析器的超时。
默认情况下，Cymru 注释器会获取源和对等 AS 以及所有 ASN 的详细信息。如果你只需要子集，可以使用以下标志：
--cymru-annotate-origin-as、--cymru-annotate-peer-as 和 --cymru-annotate-as-details。
printf "1.1.1.1" | ./zannotate --cymru --cymru-dns-servers=1.1.1.1,1.0.0.1