2.7. API
2.7.1. Présentation
Note
La liste des endpoints est donnée dans la Liste des endpoints.
L'exécution de ces endpoints peut se faire :
- via SWAGGER (Utilisation via l'interface graphique swagger)ceci permet l'utilisation des endpoints et de comprendre son paramétrage et pouvoir tester son exécution et d'analyser ses résultats
- via CURL (Utilisation via CURL)ceci permet d'exécuter directement une requête Curl et de ne pas passer par l'interface graphique
2.7.2. Utilisation via l'interface graphique swagger
Chaque endpoint de l'API :
effectue une opération précise. Son nom et sa description sont indiquées dans l'interface graphique (ou dans la Liste des endpoints)
effectue une méthode parmi les quatre possibles : GET (Obtenir), DELETE (Supprimer), POST (Publier), PUT (Modifier)
a besoin de droits d'authentification qui sont les mêmes que pour l'interface graphique (Operators ou Administrators)
peut avoir besoin de paramètres de fonctionnement (entrée et /ou sortie) : par exemple, dans le cas d'un filtre, la valeur de ce filtre doit être indiquée
Cette interface permet de :
avoir la liste des endpoints existants (listés par thème)
avoir le détail des paramètres éventuels pour l'exécution d'un endpoint
avoir des informations sur le résultat attendu (modèle des données et un exemple avec des valeurs par défaut)
exécuter des requêtes
récupérer la commande Curl équivalente à la requête via l'API
Note
Un known bug affecte le endpoint /api/alerts (voir la release note du GCenter). Il est recommandé de privilégier le requêtage des données par l'API elasticsearch sur le endpoint /api/data/es/search.
2.7.3. Utilisation via CURL
`Responses`.Pour un utilisateur appelé username et disposant des droits opérateurs.
Récupération du token d’API :
curl -X POST "https://<hostname>/api/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"username\": \"username\", \"password\": \"password\"}" -koù hostname est celui du GCenter.
Réponse :
{"token":"urxn5hlezbk3vnlgq1t45rifhg0vi951","expiration_date":"2021-04-13T16:26:45.743826"}
Envoi d’une requête :
curl -X POST "https://<hostname>/api/<endpoint> -H "accept: application/json" -H "Content-Type: application/json" -H "API-KEY: x0zc5py1e2lrppe6ws0kgc8le0oxm9hg" -d "{\"test\": \"test\"}" -k
Exemple d’une requête qui interrogera elasticsearch sur ses index suricata* et récupérera 100 logs sur les 24 dernières heures :
curl -X POST "https://<hostname>/api/<endpoint> -H "accept: application/json" -H "Content-Type: application/json" -H "API-KEY: x0zc5py1e2lrppe6ws0kgc8le0oxm9hg" -d "{ \"size\" : 100, \"query\" : { \"bool\": { \"must\": [], \"filter\": [ { \"match_all\": {} }, { \"range\": { \"@timestamp\": { \"gte\": \"now-24h\", \"lte\": \"now\" } } } ], \"should\": [], \"must_not\": [] } } }" -k
2.7.4. Authentification et accès à l'API
`API`.