zmap/zannotate인터넷 데이터셋에 컨텍스트 메타데이터(예: origin AS, MaxMind GeoIP2, 역방향 DNS, WHOIS)를 주석 처리하는 유틸리티
ZAnnotate는 대규모 IP 데이터셋에 네트워크 메타데이터를 주석(annotation)으로 추가할 수 있게 해주는 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 인텔리전스 (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 주소를 읽고 각 줄에 대해 표준 출력으로 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 주소가 사설 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"}
CSV 및 JSON 파일 입력 모두에 대해 --output-annotation-field 플래그를 사용하여 주석의 필드 이름을 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월 기준) 무료 계정은 단일 동시 요청과 월 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"}]}}