api_utils

api_utils

Exemples de programmes pour accéder à l'API

appel-api

Voici deux programmes, un en Python et un en Perl pour aider à l'exécution et à l'accès aux données via les API.

Pour que l'un ou l'autre de ces programmes fonctionne, ils s'attendent à ce qu'un fichier appelé ~/.shadowserver.api existe et contienne votre clé API et votre secret. A titre d'exemple :

 [api]
key = <<API-KEY>>
secret = <<SECRET>>
uri = https://transform.shadowserver.org/api2/

Si une erreur comme celle-ci se produit, cela signifie que la requête traite beaucoup de données et que le délai d'attente du programme doit être augmenté :

 $ ./call-api.py reports/query '{"report":"united-states", "date":"2020-10-27", "query":{"city":"ashburn"}, "limit":3}' pretty
API Exception: The read operation timed out

Des détails supplémentaires peuvent être trouvés sur https://github.com/The-Shadowserver-Foundation/api_utils/wiki.

gestionnaire de rapports

Ce programme utilise l'API de rapports pour maintenir une arborescence du système de fichiers avec la possibilité d'envoyer des notifications lorsque de nouveaux rapports sont téléchargés pour traitement.

Options de file d'attente :

• Apache Kafka
• Rédis
• STOMP (ActiveMQ, RabbitMQ)

Utilisation : report-manager.py /path/to/config.ini [ days ]

L'argument facultatif « jours » correspond au nombre de jours précédents pour lesquels télécharger les rapports. La valeur par défaut est 2.

Exemple de fichier de configuration :

 [reports]
directory = /var/tmp/reports
min_disk_free = 512
notifier = none
url_prefix = http://myserver/reports/

[stomp]
server = 127.0.0.1
port = 61613
user = guest
password = guest
queue = /queue/mytest

[redis]
server = 127.0.0.1
port = 6379
;password = guest
queue = mytest

[kafka]
server = 127.0.0.1
port = 9092
queue = mytest

La section [reports] est obligatoire et doit contenir la clé 'directory'.

Paramètres:

• directory : répertoire de niveau supérieur dans lequel stocker les rapports
• min_disk_free : disque minimum libre en Mo pour tenter le téléchargement (par défaut 512)
• notifier : spécifiez un type de file d'attente de notification [aucun, stomp, redis ou kafka]
• url_prefix : remplacement du préfixe d'URL pour le répertoire de niveau supérieur pour les messages de notification
• rapports : liste facultative de noms de listes de diffusion sur lesquels vous souhaitez filtrer
• type : type de rapport facultatif à filtrer

Si un « notificateur » est configuré dans la section [reports], une section supplémentaire avec un nom correspondant est requise.

Paramètres:

• serveur : adresse IP du serveur ou nom d'hôte
• port : port du serveur
• file d'attente : identifiant de la file d'attente
• user : nom d'utilisateur (si requis)
• mot de passe : mot de passe (si requis)

L'entrée de notification est un objet JSON qui contient un horodatage, une date de rapport, un type de rapport et un URI :

 {
   "timestamp" : "2022-09-01 11:32:45",
   "report_date" : "2022-08-31",
   "report_type" : "scan_stun",
   "uri" : "http://myserver/reports/2022/08/31/2022-08-31-scan_stun_example_com-asn.csv"
}

Exemple de crontab pour vérifier les nouveaux téléchargements une fois par heure :

 15 * * * * /opt/shadowserver/report-manager.py /opt/shadowserver/reports.ini