zmap/zannotateインターネットデータセットにコンテキストメタデータ（例: 発信元AS、MaxMind GeoIP2、リバースDNS、WHOIS）を注釈付けするためのユーティリティ。
ZAnnotateは、大規模なIPデータセットにネットワークメタデータを付与するためのGoユーティリティです。現在は以下に対応しています。
| 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 Intelligence（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 フラグを使用する必要があります。これにより、既存のJSONオブジェクトに zannotate フィールドが挿入されます。例:
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アドレスを読み取り、標準出力に1行ごとに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 フラグを使用すると、CSVおよびJSONファイル入力の両方で、アノテーションのフィールド名を zannotate の代わりに別の名前に指定できます。
例えば、JSON入力で出力タグ --output-annotation-field="info" を使用する場合:
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月時点）では、同時リクエストは1件、月間リクエストは100件までです。クレジットを使い切ると、翌月の初めにリセットされるか追加クレジットを購入するまで、以降のリクエストでCensys APIはエラーを返します。この場合、ZAnnotateはサイレントエラーを防ぐためにエラーで終了します。そのため、大規模なデータセットにアノテーションを付ける場合は、クレジット使用量に注意し、クレジットがあるIPのみにアノテーションを付けることを優先してください。無料アカウントは同時リクエストが1件のみなので、上位ティアを支払わない限り、
--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とピアAS、およびすべてのASNのAS詳細を取得します。サブセットのみが必要な場合は、次のフラグが利用可能です: --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