zmap/zannotateUtilitário para anotar conjuntos de dados da Internet com metadados contextuais (ex.: AS de origem, MaxMind GeoIP2, DNS reverso e WHOIS)
ZAnnotate é um utilitário Go que facilita a anotação de grandes conjuntos de dados IP com metadados de rede. Atualmente, isso inclui:
| CLI Flag | Descrição | Precisa de Chave API | Precisa de Download de Dados |
|---|---|---|---|
--censys | Inteligência de internet da Censys (API ao vivo) | Sim | |
--cymru | ASN de Origem/Peer da Cymru e detalhes do ASN | ||
--geoasn | Dados GeoIP ASN da MaxMind | Sim | |
--geoip2 | Dados de cidade e geolocalização MaxMind GeoIP2 | Sim | |
--greynoise | Inteligência de ameaças Psychic da GreyNoise e dados de CVE | Sim (para download) | Sim |
--ipinfo | Dados ASN e geolocalização da IPInfo.io | Sim | |
--rdap | Consultas RDAP (sucessor do WHOIS) (ao vivo) | ||
--rdns | Consultas de DNS reverso (ao vivo) | ||
--routing | Dados BGP/Roteamento a partir de uma tabela de roteamento MRT | Sim | |
--spur | Spur Intelligence (ASN, organização, classificação de infraestrutura, geolocalização) | Sim |
Ir para configuração do módulo: Censys · Cymru · GeoASN · GeoIP · GreyNoise · IPInfo.io · RDAP · RDNS/DNS Reverso · Roteamento/BGP · Spur
Você pode usar qualquer combinação dos anotadores. Por exemplo, aqui estão anotações de DNS reverso e IPInfo juntas:
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"]}
}
O --help tem mais detalhes sobre cada anotador e suas flags disponíveis.
zannotate --help
O ZAnnotate pode ser instalado usando make install
make install
ou, se você não tiver o make instalado, pode usar o seguinte comando:
cd cmd/zannotate && go install
De qualquer forma, isso instalará o binário zannotate no diretório $GOPATH/bin.
Verifique se foi instalado corretamente com:
zannotate --help
Por padrão, o ZAnnotate espera endereços IP delimitados por nova linha na entrada padrão. Por exemplo:
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"]}}
Você pode desejar anotar dados que já estão em formato JSON. Nesse caso, precisará usar a flag --input-file-type=json. Isso inserirá um campo zannotate no objeto JSON existente. Por exemplo:
echo '{"ip": "1.1.1.1"}' | zannotate --rdns --geoasn --geoasn-database=/caminho-para-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"]}}}
Se seus objetos JSON tiverem um campo diferente para o endereço IP além do padrão ip, você pode especificá-lo com a flag --input-ip-field. Por exemplo, se seus objetos JSON tiverem um campo ip_address, você pode usar:
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"]}}}
Se seus dados de entrada estiverem em formato CSV, você pode usar a flag --input-file-type=csv.
printf "nome,ip,data\n cloudflare,1.1.1.1,04-04-26\n google,8.8.8.8,04-04-26" | zannotate --rdns --input-file-type=csv
{"nome":" cloudflare","ip":"1.1.1.1","data":"04-04-26","zannotate":{"rdns":{"domain_names":["one.one.one.one"]}}}
{"nome":" google","ip":"8.8.8.8","data":"04-04-26","zannotate":{"rdns":{"domain_names":["dns.google"]}}}
Semelhante ao JSON, você pode usar a flag --input-ip-field para especificar uma coluna diferente de ip que contenha o endereço IP.
printf "nome,ip_address,data\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
{"data":"04-04-26","zannotate":{"rdns":{"domain_names":["dns.google"]}},"nome":" google","ip_address":"8.8.8.8"}
{"data":"04-04-26","zannotate":{"rdns":{"domain_names":["one.one.one.one"]}},"nome":" cloudflare","ip_address":"1.1.1.1"}
Por padrão, o ZAnnotate lê endereços IP delimitados por nova linha da entrada padrão e gera um objeto JSON por linha para a saída padrão, como:
echo "1.1.1.1" | zannotate --rdns --geoasn --geoasn-database=/caminho-para-geo-asn.mmdb
{"ip":"1.1.1.1","geoasn":{"asn":13335,"org":"CLOUDFLARENET"},"rdns":{"domain_names":["one.one.one.one"]}}
Se um endereço IP não puder ser anotado, seja por erro ou falta de dados, haverá um campo vazio para essa anotação. Por exemplo, se um endereço IP for privado e, portanto, não tiver dados RDNS ou ASN, a saída será assim:
echo "127.0.0.1" | zannotate --rdns --geoasn --geoasn-database=/caminho-para-geo-asn.mmdb
{"geoasn":{},"rdns":{},"ip":"127.0.0.1"}
A flag --output-annotation-field pode ser usada para especificar um nome de campo diferente para as anotações em vez de zannotate para entradas de arquivo CSV e JSON.
Por exemplo, usando a tag de saída --output-annotation-field="info" com entrada JSON:
printf "nome,ip_address,data\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"
{"nome":" cloudflare","ip_address":"1.1.1.1","data":"04-04-26","info":{"rdns":{"domain_names":["one.one.one.one"]}}}
{"ip_address":"8.8.8.8","data":"04-04-26","info":{"rdns":{"domain_names":["dns.google"]}},"nome":" google"}
[!NOTE] URLs e instruções podem mudar ao longo do tempo. Estas estão atualizadas até maio de 2026.
A Censys fornece dados de host e rede em toda a internet, incluindo informações sobre quais serviços estão rodando em um IP, quais certificados TLS ele possui e muito mais. Eles oferecem um nível gratuito que permite um número limitado de consultas por mês, que pode ser usado para enriquecer anotações de IP com dados da Censys.
[!NOTE] A conta gratuita (em abril de 2026) permite uma única requisição simultânea e 100 requisições por mês. Depois de usar todos os seus créditos, a API da Censys retornará um erro em requisições subsequentes até que seus créditos sejam redefinidos no início do próximo mês ou você compre créditos adicionais. O ZAnnotate será encerrado com um erro se isso ocorrer para evitar erros silenciosos. Portanto, se você tiver um conjunto de dados grande para anotar, esteja atento ao uso de seus créditos e priorize apenas a anotação dos IPs para os quais você tem créditos. Como a conta gratuita oferece apenas uma requisição simultânea, você deve deixar
--censys-threads=1a menos que pague por um nível superior.
echo "8.8.8.8" | zannotate --censys --censys-pat="CENSYS_PAT_AQUI"
Resultados truncados por brevidade:
{
"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"}]}}
A Cymru fornece informações de ASN e peering BGP para endereços IP. Você pode usar a flag --cymru para consultar a Cymru por essas informações.
A Cymru configurou um serviço DNS para fornecer essas informações e, por padrão, o ZAnnotate usará os resolvedores DNS padrão do seu sistema para realizar a consulta.
Se você perceber que está tendo timeouts ao usar seu resolvedor DNS local, pode especificar resolvedores personalizados com a flag --cymru-dns-servers.
As flags --cymru-threads e --cymru-timeout também estão disponíveis para configurar o desempenho das anotações Cymru. Os padrões são definidos para obter um bom desempenho evitando timeouts com a maioria dos resolvedores DNS.
Por padrão, o anotador Cymru busca os ASNs de origem e peer, bem como detalhes do ASN para todos os ASNs. Caso deseje um subconjunto, as seguintes flags estão disponíveis:
--cymru-annotate-origin-as, --cymru-annotate-peer-as e --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 é um feed de inteligência IP que fornece metadados como classificação de ameaças e CVEs associados.
Os downloads de dados Psychic fornecem o feed de dados em um banco de dados adequado para enriquecimento offline.
Para usar o download com zannotate, você deve baixar um arquivo no formato .mmdb usando sua chave de API GreyNoise.
A partir de abril de 2026, cadastrar-se com uma conta gratuita dá acesso aos downloads de dados.
mmdb. O comando abaixo baixa dados para uma única data (7 de abril de 2026). Você também pode baixar dados para um intervalo de dias e para modelos de vários níveis de detalhe — consulte a documentação Psychic da GreyNoise para mais detalhes.curl -H "key: GREYNOISE_API_KEY_AQUI" \
https://psychic.labs.greynoise.io/v1/psychic/download/2026-04-07/3/mmdb \
-o /tmp/m3.mmdb
[!NOTE] Os exemplos abaixo usam o download de dados exato do comando
curlacima. Os resultados que você verá dependerão dos dados baixados.
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"}
Observe que muitos IPs não estarão no conjunto de dados GreyNoise, então você pode ver uma saída como a seguinte:
echo "1.1.1.1" | zannotate --greynoise --greynoise-database=/tmp/m3.mmdb
{"ip":"1.1.1.1","greynoise":{}}
O IPInfo.io fornece um conjunto de dados gratuito que inclui dados ASN e de geolocalização, limitados ao nível de país. Níveis pagos fornecem dados de geolocalização mais granulares.
mmdb
echo "1.1.1.1" | zannotate --ipinfo --ipinfo-database=./caminho-para-banco-ipinfo.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"}}
A MaxMind fornece conjuntos de dados para geolocalização IP e dados ASN em versões gratuita (GeoLite) e paga (GeoIP). Além disso, ambos os conjuntos de dados GeoLite e GeoIP vêm em dois padrões de acesso — um arquivo de banco de dados baixável que pode ser consultado localmente e uma API web. O módulo GeoIP no ZAnnotate suporta o banco de dados local tanto nas versões GeoLite quanto GeoIP.
O que se segue pressupõe que você deseja usar os conjuntos de dados gratuitos GeoLite, mas o processo é semelhante para os dados pagos GeoIP.
.mmdb em algum lugar e teste com o comando abaixo.echo "171.67.71.209" | zannotate --geoip2 --geoip2-database=./caminho-para-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=/caminho-para-arquivo-asn.mmdb
{"ip":"171.67.71.209","geoasn":{"asn":32,"org":"STANFORD"}}
RDAP (Registration Data Access Protocol) é um protocolo usado para acessar dados de registro de recursos da internet, como endereços IP e nomes de domínio, e é o sucessor do WHOIS. O ZAnnotate pode consultar servidores RDAP para obter dados de registro de IPs.
echo "1.1.1.1" | zannotate --rdap
Resultados truncados por brevidade:
{
"ip":"1.1.1.1",
"whois": {
"DecodeData": {},
"Lang": "",
"Conformance": [
"history_version_0",
"nro_rdap_profile_0",
"cidr0",
"rdap_level_0"
],
"ObjectClassName": "ip network"
}
}
Isso deve fornecer a mesma saída que uma consulta direta a um servidor RDAP, por exemplo:
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>
O ZAnnotate pode realizar consultas de DNS reverso para cada endereço IP. Nenhum download de dados é necessário, --rdns consulta servidores DNS ao vivo diretamente.
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"]}}
Se um IP não tiver um registro PTR, o campo rdns ficará vazio:
echo "127.0.0.1" | zannotate --rdns
{"ip":"127.0.0.1","rdns":{}}
2025.09)RIBS/rib.20250923.1200.bz2)bzip2 -d ./caminho-para-arquivo-baixado/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 fornece inteligência por IP, como ASN e organização, classificação de infraestrutura (ex.: datacenter, CDN, móvel) e metadados de geolocalização. Podemos consultar o spur.us junto com outras fontes para enriquecer anotações e ajudar a identificar implantações de datacenter/Anycast, CDNs e propriedade de ISPs.
export SPUR_API_KEY=sua_chave_api_aqui
(Se quiser tornar isso permanente, adicione a linha acima ao seu perfil de shell, ex.: ~/.bashrc ou ~/.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"}}