ZAnnotate

ZAnnotate est un utilitaire Go qui facilite l'annotation de grands ensembles d'adresses IP avec des métadonnées réseau. Actuellement, cela inclut :

Accéder à la configuration du module : Censys · Cymru · GeoASN · GeoIP · GreyNoise · IPInfo.io · RDAP · RDNS/DNS inversé · Routage/BGP · Spur

Vous pouvez utiliser n'importe quelle combinaison des annotateurs, par exemple voici les annotations DNS inversé et IPInfo ensemble :

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"]}
}

L'option --help donne plus de détails sur chaque annotateur et ses drapeaux disponibles.

zannotate --help

Installation

ZAnnotate peut être installé en utilisant make install

make install

ou si vous n'avez pas make d'installé, vous pouvez utiliser la commande suivante :

cd cmd/zannotate && go install

Dans les deux cas, cela installera le binaire zannotate dans votre répertoire $GOPATH/bin.

Vérifiez qu'il a été installé correctement avec :

zannotate --help

Entrée/Sortie

Entrée

Adresses IP séparées par des sauts de ligne

Par défaut, ZAnnotate attend des adresses IP délimitées par des sauts de ligne sur l'entrée standard. Par exemple :

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

Vous pouvez souhaiter annoter des données déjà au format JSON. Vous devrez alors utiliser le drapeau --input-file-type=json. Cela insérera un champ zannotate dans l'objet JSON existant. Par exemple :

echo '{"ip": "1.1.1.1"}' | zannotate --rdns --geoasn --geoasn-database=/chemin-vers-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"]}}}

Si vos objets JSON ont un champ différent pour l'adresse IP que le champ par défaut ip, vous pouvez le spécifier avec le drapeau --input-ip-field. Par exemple, si vos objets JSON ont un ip_address, vous pouvez utiliser :

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

Si vos données d'entrée sont au format CSV, vous pouvez utiliser le drapeau --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"]}}}

Comme pour JSON, vous pouvez utiliser le drapeau --input-ip-field pour spécifier une colonne autre que ip qui contient l'adresse 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"}

Sortie

Par défaut, ZAnnotate lit les adresses IP délimitées par des sauts de ligne depuis l'entrée standard et affiche un objet JSON par ligne sur la sortie standard, comme ceci :

echo "1.1.1.1" | zannotate --rdns --geoasn --geoasn-database=/chemin-vers-geo-asn.mmdb

{"ip":"1.1.1.1","geoasn":{"asn":13335,"org":"CLOUDFLARENET"},"rdns":{"domain_names":["one.one.one.one"]}}

Si une adresse IP ne peut pas être annotée, soit en raison d'une erreur soit d'un manque de données, le champ correspondant sera vide. Par exemple, si une adresse IP est privée et n'a donc ni données RDNS ni ASN, la sortie ressemblera à :

echo "127.0.0.1" | zannotate --rdns --geoasn --geoasn-database=/chemin-vers-geo-asn.mmdb

{"geoasn":{},"rdns":{},"ip":"127.0.0.1"}

Drapeaux de sortie JSON et CSV

Le drapeau --output-annotation-field peut être utilisé pour spécifier un nom de champ différent pour les annotations au lieu de zannotate pour les entrées de fichiers CSV et JSON.

Par exemple, en utilisant la balise de sortie --output-annotation-field="info" avec une entrée 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"}

Modules

[!NOTE] Les URL et les instructions peuvent changer avec le temps. Celles-ci sont à jour en mai 2026.

Censys

Censys fournit des données hôtes et réseau à l'échelle d'Internet, y compris des informations sur les services exécutés sur une IP, les certificats TLS qu'elle possède, et plus encore. Ils proposent un niveau gratuit qui permet un nombre limité de requêtes par mois, qui peut être utilisé pour enrichir les annotations IP avec les données Censys.

[!NOTE] Le compte gratuit (en avril 2026) permet une seule requête simultanée et 100 requêtes par mois. Une fois que vous avez utilisé tous vos crédits, l'API Censys renverra une erreur lors des requêtes suivantes jusqu'à ce que vos crédits soient réinitialisés au début du mois suivant ou que vous achetiez des crédits supplémentaires. ZAnnotate se terminera par une erreur si cela se produit pour éviter des erreurs silencieuses. Par conséquent, si vous avez un grand jeu de données à annoter, soyez attentif à l'utilisation de vos crédits et priorisez uniquement l'annotation des IP pour lesquelles vous avez des crédits. Avec le compte gratuit n'offrant qu'une seule requête simultanée, vous voudrez laisser --censys-threads=1 sauf si vous payez pour un niveau supérieur.

1. Créez un compte sur Censys.io et obtenez un jeton d'accès personnel (PAT) depuis Paramètres personnels > Jetons d'accès personnel.
2. Annoter avec les données Censys :

echo "8.8.8.8" | zannotate --censys --censys-pat="CENSYS_PAT_HERE"

Résultats tronqués par souci de concision :

{
   "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

Cymru fournit des informations ASN et de peering BGP pour les adresses IP. Vous pouvez utiliser le drapeau --cymru pour interroger Cymru pour ces informations. Cymru a mis en place un service DNS pour fournir ces informations et par défaut, ZAnnotate utilisera les résolveurs DNS par défaut de votre système pour interroger. Si vous constatez des délais d'attente en utilisant votre résolveur DNS local, vous pouvez spécifier des résolveurs personnalisés avec le drapeau --cymru-dns-servers. --cymru-threads et --cymru-timeout sont également disponibles pour configurer les performances des annotations Cymru ; les valeurs par défaut sont définies pour obtenir de bonnes performances tout en évitant les délais d'attente avec la plupart des résolveurs DNS. Par défaut, l'annotateur Cymru récupère les ASN d'origine et de peering, ainsi que les détails des ASN sur tous les ASN. Si vous souhaitez un sous-ensemble, les drapeaux suivants sont disponibles : --cymru-annotate-origin-as, --cymru-annotate-peer-as, et --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 Psychic

GreyNoise est un flux de renseignement IP qui fournit des métadonnées telles que la classification des menaces et les CVE associées. Leurs téléchargements de données Psychic fournissent leur flux de données dans une base de données adaptée à l'enrichissement de données hors ligne. Pour utiliser leur téléchargement avec zannotate, vous voudrez télécharger un fichier au format .mmdb en utilisant votre clé API GreyNoise. En avril 2026, s'inscrire avec un compte gratuit donne accès aux téléchargements de données.

1. Inscrivez-vous pour un compte GreyNoise gratuit ici.
2. Copiez votre clé API depuis la section appropriée de votre compte.
3. Téléchargez un fichier mmdb. La commande ci-dessous télécharge les données pour une seule date (7 avril 2026). Vous pouvez également télécharger des données pour une plage de jours et pour des modèles avec différents niveaux de détail — consultez la documentation Psychic de GreyNoise pour plus de détails.

curl -H "key: GREYNOISE_API_KEY_HERE" \
     https://psychic.labs.greynoise.io/v1/psychic/download/2026-04-07/3/mmdb \
     -o /tmp/m3.mmdb

4. Testez l'enrichissement des données GreyNoise :

[!NOTE] Les exemples ci-dessous utilisent le téléchargement de données exact de la commande curl ci-dessus. Les résultats que vous verrez dépendront des données téléchargées.

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"}

Notez que de nombreuses IP ne seront pas présentes dans l'ensemble de données GreyNoise, vous pouvez donc voir une sortie comme celle-ci :

echo "1.1.1.1" | zannotate --greynoise --greynoise-database=/tmp/m3.mmdb

{"ip":"1.1.1.1","greynoise":{}}

IPInfo.io

IPInfo.io fournit un jeu de données gratuit qui inclut les données ASN et de géolocalisation, limitées au niveau du pays. Les niveaux payants fournissent des données de géolocalisation plus granulaires.

1. Inscrivez-vous pour un compte gratuit sur IPInfo.io.
2. Naviguez vers la page Téléchargements de données
3. Téléchargez le fichier mmdb
4. Exemple d'utilisation en ligne de commande

echo "1.1.1.1" | zannotate --ipinfo --ipinfo-database=./chemin-vers-base-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"}}

MaxMind GeoIP ASN et Ville (anciennement GeoIP2)

MaxMind fournit des jeux de données pour la géolocalisation IP et les données ASN dans une version gratuite (GeoLite) et payante (GeoIP). De plus, les jeux de données GeoLite et GeoIP sont disponibles selon deux modes d'accès : un fichier de base de données téléchargeable pouvant être interrogé localement et une API Web. Le module GeoIP dans ZAnnotate prend en charge la base de données locale dans les versions GeoLite et GeoIP.

Ce qui suit suppose que vous souhaitez utiliser les jeux de données gratuits GeoLite, mais le processus est similaire pour les données GeoIP payantes.

1. Formulaire d'inscription pour l'accès MaxMind GeoLite
2. Connectez-vous à votre compte
3. Allez dans la section "GeoIP / GeoLite" > "Télécharger les fichiers" et téléchargez les fichiers zip pour les jeux de données GeoLite ASN ou GeoLite City.

4. Décompressez, placez les fichiers .mmdb quelque part et testez avec ce qui suit.

MaxMind GeoIP City

echo "171.67.71.209" | zannotate --geoip2 --geoip2-database=./chemin-vers-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":{}}
}

MaxMind GeoLite ASN

echo "171.67.71.209" | zannotate --geoasn --geoasn-database=/chemin-vers-fichier-asn.mmdb

{"ip":"171.67.71.209","geoasn":{"asn":32,"org":"STANFORD"}}

RDAP (successeur WHOIS)

RDAP (Registration Data Access Protocol) est un protocole utilisé pour accéder aux données d'enregistrement pour les ressources internet telles que les adresses IP et les noms de domaine, et il est le successeur de WHOIS. ZAnnotate peut interroger les serveurs RDAP pour récupérer les données d'enregistrement pour les IP.

echo "1.1.1.1" | zannotate --rdap

Résultats tronqués par souci de concision :

{
   "ip":"1.1.1.1",
   "whois": {
     "DecodeData": {},
     "Lang": "",
     "Conformance": [
       "history_version_0",
       "nro_rdap_profile_0",
       "cidr0",
       "rdap_level_0"
     ],
     "ObjectClassName": "ip network"
   }
}

Cela devrait vous donner la même sortie qu'une requête directe à un serveur RDAP, par exemple :

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
...<suite de la sortie tronquée par souci de concision>

DNS inversé (RDNS)

ZAnnotate peut effectuer des recherches DNS inversées pour chaque adresse IP. Aucun téléchargement de données n'est nécessaire, --rdns interroge directement les serveurs DNS en direct.

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"]}}

Si une IP n'a pas d'enregistrement PTR, le champ rdns sera vide :

echo "127.0.0.1" | zannotate --rdns

{"ip":"127.0.0.1","rdns":{}}

Tables de routage BGP

1. Allez sur https://archive.routeviews.org/route-views2/bgpdata/
2. Sélectionnez un répertoire de mois (par ex. 2025.09)
3. Sélectionnez le répertoire RIBS/
4. Téléchargez un fichier MRT compressé (par ex. rib.20250923.1200.bz2)
5. Décompressez le fichier avec :

bzip2 -d ./chemin-vers-fichier-telecharge/rib.20250923.1200.bz2

6. Testez avec :

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]}}

Enrichissement et renseignement Spur IP

spur.us fournit du renseignement par IP tel que l'ASN et l'organisation, la classification de l'infrastructure (par ex., centre de données, CDN, mobile), et des métadonnées de géolocalisation. Nous pouvons interroger spur.us en parallèle d'autres sources pour enrichir les annotations et aider à identifier les déploiements en centre de données/Anycast, les CDN et la propriété des FAI.

1. Obtenez une clé API auprès de Spur. Selon la tarification actuelle, vous devrez peut-être vous inscrire pour un compte payant — consultez spur.us/pricing pour plus de détails.
2. Définissez votre clé API comme variable d'environnement :

export SPUR_API_KEY=votre_cle_api_ici

(Si vous souhaitez rendre cela permanent, ajoutez la ligne ci-dessus à votre profil shell, par ex. ~/.bashrc ou ~/.zshrc)

3. Testez avec :

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"}}