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"}]}}
Cymru는 IP 주소에 대한 ASN 및 BGP 피어링 정보를 제공합니다. --cymru 플래그를 사용하여 Cymru에 이 정보를 조회할 수 있습니다.
Cymru는 이 정보를 제공하기 위해 DNS 서비스를 설정했으며, 기본적으로 ZAnnotate는 시스템 기본 DNS 해석기를 사용하여 조회합니다.
로컬 DNS 해석기를 사용할 때 시간 초과가 발생하는 경우 --cymru-dns-servers 플래그로 사용자 정의 해석기를 지정할 수 있습니다.
--cymru-threads 및 --cymru-timeout 플래그도 Cymru 주석 성능을 조정하는 데 사용할 수 있으며, 대부분의 DNS 해석기에서 시간 초과를 피하면서 좋은 성능을 내도록 기본값이 설정되어 있습니다.
기본적으로 Cymru 주석 추가 모듈은 출처 및 피어 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
{"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는 위협 분류 및 관련 CVE와 같은 메타데이터를 제공하는 IP 인텔리전스 피드입니다.
Psychic 데이터 다운로드는 오프라인 데이터 풍부화에 적합한 데이터베이스 형태로 데이터 피드를 제공합니다.
다운로드를 zannotate와 함께 사용하려면 GreyNoise API 키를 사용하여 .mmdb 형식의 파일을 다운로드해야 합니다.
2026년 4월 기준으로 무료 계정에 가입하면 데이터 다운로드에 액세스할 수 있습니다.
mmdb 파일을 다운로드하세요. 아래 명령어는 단일 날짜(2026년 4월 7일)의 데이터를 다운로드합니다. 여러 날짜 범위 및 다양한 세부 수준의 모델 데이터도 다운로드할 수 있습니다. 자세한 내용은 GreyNoise의 Psychic 문서를 참조하세요.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] 아래 예제는 위
curl명령어에서 다운로드한 정확한 데이터를 사용합니다. 표시되는 결과는 다운로드한 데이터에 따라 다릅니다.
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"}
많은 IP가 GreyNoise 데이터셋에 없을 수 있으므로 다음과 같은 출력이 나타날 수 있습니다:
echo "1.1.1.1" | zannotate --greynoise --greynoise-database=/tmp/m3.mmdb
{"ip":"1.1.1.1","greynoise":{}}
IPInfo.io는 국가 수준으로 범위가 지정된 ASN 및 지리 위치 데이터를 포함한 무료 데이터셋을 제공합니다. 유료 등급은 더 세분화된 지리 위치 데이터를 제공합니다.
mmdb 파일을 다운로드하세요.
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는 무료(GeoLite) 및 유료(GeoIP) 버전 모두에서 IP 지리 위치 및 ASN 데이터를 위한 데이터셋을 제공합니다. 또한 GeoLite와 GeoIP 데이터셋 모두 두 가지 액세스 패턴(로컬에서 쿼리할 수 있는 다운로드 가능한 데이터베이스 파일과 웹 API)으로 제공됩니다. ZAnnotate의 GeoIP 모듈은 GeoLite 및 GeoIP 버전 모두에서 로컬 데이터베이스를 지원합니다.
다음은 무료 GeoLite 데이터셋을 사용하려는 경우를 가정하지만, 유료 GeoIP 데이터도 비슷한 과정을 거칩니다.
.mmdb 파일을 적절한 위치에 배치한 후 아래 명령어로 테스트하세요.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(등록 데이터 액세스 프로토콜)는 IP 주소 및 도메인 이름과 같은 인터넷 리소스의 등록 데이터에 액세스하는 데 사용되는 프로토콜이며 WHOIS의 후속입니다. ZAnnotate는 RDAP 서버를 조회하여 IP의 등록 데이터를 가져올 수 있습니다.
echo "1.1.1.1" | zannotate --rdap
길이를 줄이기 위해 결과를 축약했습니다:
{
"ip":"1.1.1.1",
"whois": {
"DecodeData": {},
"Lang": "",
"Conformance": [
"history_version_0",
"nro_rdap_profile_0",
"cidr0",
"rdap_level_0"
],
"ObjectClassName": "ip network"
}
}
이는 RDAP 서버에 직접 조회한 결과와 동일해야 합니다. 예:
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
...<이하 출력 생략>
ZAnnotate는 각 IP 주소에 대해 역방향 DNS 조회를 수행할 수 있습니다. 데이터 다운로드는 필요 없으며 --rdns는 라이브 DNS 서버를 직접 조회합니다.
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"]}}
IP에 PTR 레코드가 없는 경우 rdns 필드는 비어 있습니다:
echo "127.0.0.1" | zannotate --rdns
{"ip":"127.0.0.1","rdns":{}}
2025.09)RIBS/ 디렉터리 선택rib.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는 IP별 ASN 및 조직, 인프라 분류(예: 데이터센터, CDN, 모바일), 지리 위치 메타데이터와 같은 인텔리전스를 제공합니다. 다른 소스와 함께 spur.us를 조회하여 주석을 풍부하게 하고 데이터센터/Anycast 배포, CDN, ISP 소유권을 식별하는 데 도움을 줄 수 있습니다.
export SPUR_API_KEY=your_api_key_here
(이 설정을 영구적으로 하려면 위 줄을 셸 프로필(~/.bashrc 또는 ~/.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"}}