CrowdSec - Introduction à l'API Local

Qu’est-ce que CrowdSec ?

Si vous avez manqué les épisodes précédents sur CrowdSec, il s’agit d’un outil open source que vous installez sur un serveur et qui est capable de détecter et bloquer les adresses IP malicieuses en se basant sur des schémas locaux et une liste d’IP mutualisée entre les utilisateurs de CrowdSec. Pour tous les détails, je vous invite à lire mon article sur CrowdSec 1.0.

Dans cette version 1.x, CrowdSec a mis en place une API Local qui peut être requêtée par l’agent CrowdSec ou le client en ligne de commande, mais également par les machines CrowdSec distantes.

Que permet de faire l’API ?

Alors qu’est-ce qu’une “décision” dans le cadre de CrowdSec ? Et bien c’est tout simplement des règles de blocage par IP, par plage IP, par nom d’utilisateur ou ce que vous voulez puisqu’il est possible de faire du customisé.

Pour que cela fonctionne, le bouncer a besoin d’une clé API générée par CrowdSec et l’autorisant à consulter la liste des décisions en place.

Après si vous voulez aller plus loin, avec le client en ligne de commande ou vos propres scripts ou votre propre code, vous pouvez également agir sur l’API en mode “écriture”. C’est-à-dire supprimer ou ajouter des décisions, pousser des alertes, rechercher ou récupérer des alertes, mais également en supprimer.

Pour cela, il vous faudra vous authentifier sur l’API avec un ID de machine et un mot de passe.

Comment utiliser l’API ?

Bon je pars du principe que CrowdSec est en place et que vous disposez du client en ligne de commande (CLI).

S’authentifier sur l’API

Pour vous authentifier sur l’API vous avez besoin de générer une clé pour le bouncer. La plupart des Bouncers proposés sur le hub de CrowdSec sont équipés d’un script d’installation qui effectue cette démarche à votre place.

Toutefois si vous développez votre propre bouncer, voici comment obtenir une clé :

cscli bouncers add BouncerdeTest

Ce qui va vous donner alors une clé d’API que vous devrez indiquer dans la config de votre Bouncer.

cscli machines add MachinedeTest --auto

cscli lapi register -u <api_url>

Puis valider l’ajout de la machine, cette fois sur le serveur où se trouve l’API Local comme ceci :

cscli machines validate MachinedeTest

Ensuite pour lister les machines enregistrées, il suffit de faire :

Maintenant pour établir une connexion avec l’API, et bien comme pour toutes les API, de la requête HTTP (vous pouvez activer le HTTPS si vous bossez avec plusieurs machines. Pas besoin donc si vous tournez uniquement en local.

Avec

Concernant les appels à l’API à partir d’un Bouncer, vous avez 2 méthodes disponibles :

Query Mode (getDecisions)

Le Query mode permet au bouncer d’interroger l’API afin de récupérer des informations concernant les décisions prises au sujet de certaines plages IP, IP individuelles, nom d’utilisateur…etc.

Voici comment appeler l’API (avec Curl) pour demander des infos sur une IP bannie :

curl -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03" http://localhost:8080/v1/decisions\?ip=98.65.32.47

Comme vous pouvez le voir, on passe bien la clé de l’API et on invoque le paramètre ?ip pour spécifier l’adresse IP sur laquelle on souhaite avoir des infos.

Et la réponse renvoyée sera au format JSON comme ceci :

[{"duration":"2h25m47.212560128s","id":1023,"origin":"cscli","scenario":"manual 'ban' from '939972095cf1459c8b22cc608eff85daEb4yoi2wiTD7Y3fA'","scope":"Ip","type":"ban","value":"1.2.3.4"}]

Vous pouvez également utiliser le paramètre ?range pour spécifier une plage réseau, ou si vous le souhaitez, le couple de paramètres scope + value pour demander des infos sur un nom d’utilisateur précis, un ID de session…etc.

curl -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03" http://localhost:8080/v1/decisions\?scope\=username\&value\=korben

Très cool, n’est-ce pas ?

Stream Mode (getDecisionsStream)

Le stream mode a un fonctionnement un peu différent et plus basique puisqu’il permet au bouncer de récupérer les décisions en place ou les nouvelles décisions à intervalles réguliers.

Au lancement du bouncer, on peut par exemple récupérer les décisions actives, mais également celles fraichement supprimées en invoquant l’API à l’aide du paramètre ?startup à “true”, comme ceci :

curl -s -H "X-Api-Key: e73e3672427ecd8cd9a6487f7e8f4f03" http://localhost:8080/v1/decisions/stream\?startup\=true

En passant le paramètre ?startup à false, vous récupérerez ensuite uniquement les nouvelles décisions arrivées après le démarrage du bouncer.

{
"deleted": null,
"new": [
{
"duration": "3h59m57.641708614s",
"id": 2410,
"origin": "cscli",
"scenario": "manual 'ban' from '939972095cf1459c8b22cc608eff85daEb4yoi2wiTD7Y3fA'",
"scope": "Ip",
"type": "ban",
"value": "3.3.3.4"
}
]
}

Si aucune décision n’a été ajoutée, la réponse sera “null” :

{
"deleted": null,
"new": null
}

Utiliser l’API via un Watcher (cscli ou l’agent CrowdSec)

Comme je vous le disais en intro, il vous faudra ici fournir à l’API un ID de machine et un mot de passe. L’utilisation en écriture (POST / DELETE) ou en consultation (GET) de certaines fonctions de l’API se fait principalement via l’interface en ligne de commande ou l’agent CrowdSec, mais rien ne vous empêche également de l’utiliser en direct.

curl -X DELETE "https://localhost:8080/v1/decisions?ip=98.65.32.47" -H "accept: application/json"

Et en réponse, vous recevrez une chaine de caractère vous indiquant combien de décisions ont été supprimées.

Pour ceux qui veulent se lancer dans le code, sachez que le Github de CrowdSec contient du code écrit en Go qui montre comment se connecter et exploiter l’API.

Conclusion

Vous l’aurez compris, l’API Local de CrowdSec est assez simple à prendre en main, et la création d’un bouncer spécifique est abordable. Un bouncer écrit en Go et adaptable à vos besoins spécifiques est également disponible ici, en plus des bouncers spécifiques pour Nginx, Wordpress, HAProxy, iptables, nftables ou encore les firewalls cloud d’Amazon (AWS) et Google (Network FW et Cloud Armor) dont les sources sont également trouvables sur le Github. Vous trouverez aussi un bouncer en LUA et un autre en PHP ici.

Et bien sûr, vous trouverez toutes les informations dont vous avez besoin sur le site de CrowdSec.