API REST de Barracuda WAF-as-a-Service

Version imprimable, PDF et e-mail

Vous êtes plutôt flemmard(e) ? Vous aimeriez en faire plus, avec moins d'efforts, et en plus éviter les attaques contre vos sites Web ? Alors, lisez ce qui suit, cet article est fait pour vous ! Nous avons une, et même plusieurs choses à vous dire sur l'API REST de Barracuda WAF-as-a-Service. Je sais ce que vous êtes en train de vous dire, mais faites-moi confiance, cet article est vraiment fait pour vous. Ce n'est pas un livre blanc. Ce n'est pas non plus un manuel technique. Ce n'est pas davantage un traité sur l'automatisation cloud dernier cri. Nous n'avons besoin de rien de tout ça. En d'autres termes, aucun utilisateur moyen de WAF n'a été blessé lors de la réalisation de ce blog. Dans tout ce que j'enseigne, et cette fois-ci ne fera pas exception, mon mantra est toujours : vous n'avez pas besoin d'être expert.

Barracuda WAF-as-a-Service fournit une solution cloud de sécurité des applications de niveau professionnel sans les surcoûts administratifs d'une appliance virtuelle ou matérielle. À l'aide de WAF-as-a-Service, vous pouvez sécuriser vos applications en quelques minutes, où qu'elles soient hébergées. Aucune infrastructure à déployer, à dimensionner ou à maintenir. Et bien que vous puissiez utiliser notre super interface graphique REACT moderne, WAF-as-a-Service propose également une fantastique API REST pour que vous puissiez automatiser vos tâches.

En quoi consiste cette « API REST » dont vous nous parlez ?

Les interfaces de programmation d'application (ou API, pour Application Programming Interfaces en anglais) enrichissent notre monde en nous permettant d'écrire des applications qui s'occupent d'échanger automatiquement des données et des actions avec d'autres applications. Ces programmes interagissent avec d'autres programmes pour configurer des paramètres, observer et mesurer des données mais aussi pour agir et réagir de la manière la plus appropriée. Ces programmes peuvent consister en quelque chose d'aussi simple que quelques lignes de script bash ou d'aussi complexe qu'une application de production totalement opérationnelle.

Les API nous facilitent la vie car elles nous permettent d'accomplir des tâches de toutes tailles de manière hautement reproductible et fiable. Les API effectueront les mêmes tâches en boucle, des milliers de fois, exactement de la même manière. Sans API, nous serions obligés d'effectuer nous-mêmes ces tâches, de manière répétée, sans jamais faire d'erreur, à une vitesse folle. Et aussi intuitive que puisse être notre interface graphique, cette approche manuelle n'est pas prête d'égaler la vitesse et la précision d'une approche par API.

Les API sont également très courantes dans notre monde fait de réseaux, de sécurité et de cloud. Lors de notre récente enquête sur l'état de la sécurité des applications en 2021, les personnes interrogées nous ont dit travailler avec une moyenne de 33 API publiques, ce qui me paraît peu mais qui est un chiffre compréhensible étant donné l'existence d'API inconnues dans de nombreuses entreprises.

Si protéger ses API est vital dans la mesure où une API non protégée présente encore plus de risque qu'un site Web non protégé, ce dont nous allons parler aujourd'hui, c'est d'utiliser des API pour configurer et gérer le WAF-as-a-Service. Nous allons nous concentrer sur les API de type Representational State Transfer (REST), le plus souvent simplement appelées API REST.  Voici comment fonctionne une API REST :

  • Une application client démarre un appel d'API pour récupérer des informations — ce que l'on appelle une requête.
  • Cette requête est transmise en HTTPS et comprend un verbe de requête, des en-têtes, et parfois un corps de requête.
  • Le serveur reçoit la requête et renvoie une réponse HTTPS contenant les informations demandées.
  • L'application client reçoit la réponse de l'API et possède désormais les informations demandées.

Les API REST sont conçues selon le principe d'actions indiquées à l'aide de méthodes HTTP telles que POST, GET, PUT et DELETE via des routes généralement similaires. (Dans le contexte d'une API, le mot route fait référence au chemin vers le point de terminaison d'une API ce qui est à peu près la même chose qu'une URL, si ce terme vous parle davantage). Ces API nous permettent de créer, récupérer, mettre à jour ou supprimer des éléments au sein d'un service donné, sans avoir à créer une URL unique pour chaque action.

Par exemple, imaginons que vous gérez une base de données concernant les services de soins et de toilettage d'une grande entreprise de services aux animaux de compagnie. Admettons que cette base de données contient les informations de plusieurs dizaines de milliers d'animaux.

Nous avons créé une API REST pour notre base de données d'animaux afin que notre équipe de développeurs qui s'occupe de l'interface Web puisse interagir avec la base. Il est important de pouvoir suivre l'historique médical d'un animal donc nous avons donné à chaque animal un identifiant unique qui ne change jamais. Nous utilisons ce numéro plutôt que le nom de l'animal car le nom peut éventuellement changer à un moment donné.

Les animaux ont également des surnoms, donc en partant de l'identifiant de l'animal 10369, nous pouvons imaginer par exemple les transactions REST API suivantes pour effectuer des tâches simples en rapport avec les surnoms.

Action désirée Méthode HTTP (et données, le cas échéant) Route API (en gros, une URL)
Récupérer la liste des surnoms pour l'animal dont l'identifiant est 10639 GET /api/2.2/pets/10639/nicknames
Ajouter le nouveau surnom « museau » à la liste des surnoms pour l'animal n° 10639

 

article,

{“nicknames”:{“name”:”museau”,}}

 

/api/2.2/pets/10639/nicknames

 

Modifier le surnom « museau » en « destructor »

 

PUT

{“name”:”destructor”}

 

 

/api/2.2/pets/10639/nicknames/museau
Supprimer le surnom « destructor » Supprimer /api/2.2/pets/10639/nicknames/destructor

 

Ce qui fait de cet exemple une API REST est que l'URL (la « route ») reste à peu près identique, seule la méthode HTTP change en fonction de ce qu'on cherche à faire. Il n'y a pas besoin d'utiliser une URL (ou « route ») différente pour chaque action (obtenir, ajouter, modifier, supprimer). À la place, on garde grosso modo la même URL et on change la méthode HTTP.

Par rapport à d'autres technologies d'API utilisées sur le Web comme XML ou SOAP, les API REST sont une technologie plus moderne de développement d'API. On peut en mentionner une poignée d'autres comme graphQL et gRPC.

Ensemble, elles forment les trois grandes technologies de développement d'API modernes. Sur ces trois-là, les API REST sont de loin les plus populaires. Selon l'enquête sur les API RapidAPI 2019-2020, 70,9 % des personnes interrogées utilisent REST API soit en production, soit en phase de preuve de concept (POC), alors que graphQL n'est utilisé que par 12,4 % et gRPC seulement par 7,3 %.

Après cette présentation assez complète des API REST, voyons rapidement ce qu'est Barracuda WAF-as-a-Service.

Barracuda WAF-as-a-Service

Barracuda WAF-as-a-Services (WAFaaS) est un service cloud de sécurité des applications complet, proposé par Barracuda et inclus sur Azure Marketplace et AWS Marketplace.

API REST, je vous présente WAF-as-a-Service !

L'API REST centrale de Barracuda WAF-as-a-Service a pour route de départ https://api.waas.barracudanetworks.com/

Dans cet article, nous utiliserons une approche « low-code », le but étant que vous puissiez utiliser ces astuces même si vous n'êtes pas développeur ou créateur de scripts. Nous allons également utiliser une approche de type « ramper, puis marcher, puis courir », qui correspond bien à ma manière d'enseigner. C'est-à-dire que nous allons, dans l'ordre, commencer par utiliser Swagger (ramper), c'est-à-dire une simple page Web, donc une solution à interface graphique, puis nous utiliserons un peu cURL (marcher), et enfin un peu de Python (courir... mais plutôt trottiner que sprinter pour le coup).

Abordons à présent les différentes versions d'une API et leur apparence respective dans les routes : Il n'est pas rare que les routes d'une API REST mentionnent une version. Pour les approches par cURL et Python, nous allons partir sur une utilisation de la « v2 » de notre API, si bien que la route de départ sera https://api.waas.barracudanetworks.com/v2/

Nous allons également utiliser l'interface Swagger, qui prend la forme d'une page Web depuis laquelle nous pouvons tester l'API et lancer quelques appels d'API avec une interface graphique. (Oui, je sais, c'est un peu contradictoire, mais accrochez-vous, tout deviendra clair à la fin.) Swagger n'utilise pas la /v2, par conséquent l'URL complète est https://api.waas.barracudanetworks.com/.

Ramper avec Swagger

Swagger est un framework open source qui permet d'automatiser la documentation, de générer du code et ainsi que des cas de test.

L'URL de Swagger est la suivante : https://api.waas.barracudanetworks.com/swagger/#/, adresse à laquelle vous pouvez accéder depuis votre navigateur.

Se connecter

La première étape consiste à se connecter pour utiliser le WAF-as-a-Service à l'aide de l'identifiant et de la clé d'autorisation d'API. Une fois l'autorisation obtenue, vous pourrez utiliser toutes les commandes de l'API.

Cliquez sur login (Connexion), cliquez sur Try it Out (Essayer), puis saisissez votre nom d'utilisateur et votre mot de passe et cliquez sur Execute (Exécuter).

Remarque : Vos identifiants sont protégés par SSL, mais affichés en clair, il est donc fortement recommandé de cacher votre écran, par exemple si vous faites du partage d'écran. Autrement dit, évitez de faire une gaffe sur Zoom à ce moment vital !

 

 

 

Une fois connecté, descendez jusqu'à voir le corps de la réponse, puis sélectionnez et copiez la clé complète telle qu'elle est affichée, tout ce qui se situe entre le signe deux points et le guillemet de fin.

Par exemple, comme le montre la partie surlignée en jaune ci-dessous, si la clé est  « AAAAasdlfkjasdlfkjasdflkjasdflkj..asdflkjZZZZ », vous devez sélectionner et copier tout ce qui se trouve entre « auth-api: » et « -d » (sans les guillemets).  Vous copierez donc tout du premier A jusqu'au dernier Z, sans guillemets :

curl -X POST "https://api.waas.barracudanetworks.com/v2/waasapi/api_login/" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "auth-api: AAAAdflkjasdflkjasdflkjasdflkjasdflkjasdflkjasdflkjasdflkjasdflkjasdflkjasdflkjasdlkfjasdlkjasldfkjasdlfkjasdflkjasdlfkjasldfkjasldfkjalsdZZZZ" -d "email=brett%40wolmarans.com&password=MASQUÉ"

Lorsque vous copiez le contenu, vous pouvez utiliser la souris pour mettre en surbrillance et copier, ou bien utiliser ctrl+C, selon ce que vous utilisez habituellement — faites comme vous préférez.

À présent que votre clé d'API (aussi appelée « jeton » ou « token »), vous attend patiemment dans votre presse-papier, rendez-vous dans le coin supérieur droit et cliquez sur Authorize (Autoriser) comme indiqué ici :

Collez votre clé d'API, cliquez sur Authorize (Autoriser) encore une fois, puis vérifiez qu'il est bien indiqué « Authorized » (Autorisé), comme dans l'image ci-dessous.

 

 

 

Cela va sans dire, mais sait-on jamais : ne cliquez pas sur le bouton de déconnexion. Même si la tentation est grande, c'est non. Cliquez simplement sur Close (Fermer).

Si tout s'est bien passé, vous verrez à présent une petite icône de cadenas du côté droit de votre interface Swagger, comme vous pouvez le voir ici. Le cadenas est fermé, ce qui veut dire que vous êtes connecté (oui je sais, ce n'est pas très intuitif).

 

 

Obtenir la liste des applications

Cliquez sur Applications, puis sur Try it out (Essayer). Cliquez sur Execute (Exécuter)

 

 

Vous verrez un résultat indiquant le nombre d'applications, l'identifiant d'application et l'identifiant du point de terminaison.

Dans cet exemple, il y a deux applications disponibles, mais seule la première est visible sur la capture d'écran.

Vous pouvez voir l'identifiant de la première application ainsi que celui de son point de terminaison.

Vous pouvez également observer que le code de réponse du serveur est 200, ce qui est très important car un code 200 indique que la commande a fonctionné et ne contenait pas de faute de frappe.

 

Et voilà, c'est tout bon. C'est aussi simple que ça ! Pour plus d'informations sur Swagger, rendez-vous sur https://swagger.io. Pour la suite, on va se redresser et apprendre à marcher un peu en découvrant comment utiliser cURL pour effectuer quelques actions avec l'API REST.

Quelques mots sur les identifiants d'application

Vous pouvez voir ci-dessus que l'identifiant de mon application est 11818. Chacune de vos applications possède un identifiant unique ; cet identifiant vous sera utile pour concevoir vos routes lors de vos appels d'API. Par conséquent, vous entendrez parler d'identifiant d'application un peu partout dans les exemples qui suivent.

Quelques mots sur le copier-coller des exemples cURL de Swagger

Swagger propose d'excellents exemples d'utilisation de cURL lorsque vous exécutez des commandes. Vous pouvez les copier-coller pour les utiliser dans vos actions cURL. Cela vous simplifiera grandement la vie ! Par exemple, si je veux faire quelque chose d'assez classique, comme passer une application du mode « passif » (c'est-à-dire qu'elle enregistre les attaques, mais ne les bloque pas) au mode « actif » (dans lequel les attaques seront bloquées), je peux d'abord faire ça sous Swagger en me rendant dans la section « basic security » (sécurité de base) comme indiqué ici. Les flèches vous montrent l'endroit où j'ai saisi mon identifiant d'application et celui où j'ai saisi « Active ».

Puis, un peu plus bas, vous trouverez l'exemple cURL :

 

 

Vous pouvez désormais le copier-coller, sans qu'il soit nécessaire de modifier ou de taper quoi que ce soit, et vous obtiendrez l'effet suivant (les flèches indiquent l'identifiant et le mode de protection actif).  Aucun ongle n'a été cassé lors de la réalisation de cet exemple. Tout ce qu'il y a à faire, c'est de cliquer !

 

 

Marcher : cURL

Pour la suite de notre découverte de l'API, nous avons appris à ramper avec Swagger. Apprenons à présent à marcher avec cURL !

cURL (client URL) est une autre méthode permettant des appels API « rapides et simples ». Elle prend en charge divers protocoles, est utilisable sur pratiquement n'importe quelle plateforme et n'importe quelle machine existante à ce jour. Elle n'est pas recommandée pour l'automatisation en production mais reste plus automatisable que l'utilisation de Swagger avec un navigateur Web.

Lorsque vous utilisez cURL, vous devrez utiliser votre clé d'identification à chaque fois car nous allons autoriser ces appels.

Il peut être intéressant d'utiliser un petit script utilitaire pour paramétrer une variable d'environnement qui contient votre clé d'identification. En voici un que j'ai écrit il y a un certain temps, vous pouvez l'obtenir à cette adresse :

https://raw.githubusercontent.com/bwolmarans/legendary-disco/main/bwafaas_login.sh

Et voici un exemple d'utilisation du script de connexion : Alors, vous aurez peut-être remarqué que tel qu'est écrit ce script, les identifiants de connexion sont transmis en clair à la ligne de commande bash, ce qui n'est pas exactement ce qu'on peut appeler une bonne pratique, cela va sans dire. Mais bien qu'il existe plusieurs bons moyens de transmettre des identifiants à des scripts bash de manière sécurisée, nous allons volontairement nous abstenir d'en utiliser un ici.

Là où je veux en venir, c'est que je vous invite à éviter de partager votre écran sur Zoom lorsque vous vous connectez pour la première fois.

 

 

Cet avertissement posé, une fois connecté(e), et une fois votre variable d'environnement WAAS_API_KEY paramétrée, vous pouvez effectuer des appels d'API via cURL sans jamais avoir besoin de transmettre ces horribles identifiants de connexion : le jeton s'occupe de tout.

À présent, en faisant un peu défiler la page, vous pourrez partager votre écran sur Zoom sans crainte et montrer avec fierté à vos collègues toutes sortes de commandes cURL pour diriger votre WAFaaS au doigt et à l'œil, comme on le voit ici, sans jamais avoir à révéler vos identifiants.

Exemple permettant d'obtenir tous les détails de toutes les applications de votre compte WAFaaS :

 

 

Si vous voulez vous épargner les détails un peu pénibles, vous pouvez voir rapidement les noms et identifiants de vos applications sans faire trop compliqué. Là, on ne va pas chercher à atteindre des records de vitesse ou d'efficacité, et on ne va pas chercher à mériter une médaille chez https://www.topcoder.com/. Tout ce qu'on veut, c'est un exemple à l'appui d'une affirmation. Et notre affirmation, c'est que c'est facile.

 

 

Vous vous souvenez que les identifiants d'application sont très importants ? Voilà comment les récupérer. C'est une valeur importante parce que si, admettons, vous voulez faire passer une application du mode « actif » au mode « passif », c'est tout à fait faisable sous cURL, mais vous aurez besoin de son identifiant (et non pas du nom), comme vous pouvez le voir ici :

 

 

Et n'oubliez pas, comme vous le confirmeront tous ceux qui me connaissent, je suis quelqu'un de feignant, je préfère taper au clavier le moins possible. Donc, je ne me suis pas pris la tête à taper à la main ces longues commandes cURL, je les ai copiées-collées depuis l'interface Web de Swagger, comme on l'a vu dans la partie « ramper ». C'est super important.

Courir : Python

Python est un langage de programmation très populaire. En matière d'automatisation, c'est l'approche recommandée. C'est l'étape suivante dans notre continuum « ramper, marcher, courir ».

Voici un exemple de script Python simple, permettant de se connecter et de lister les applications. Vous pouvez vous procurer le script à l'adresse suivante :

https://raw.githubusercontent.com/barracudanetworks/waf-automation/master/waf-as-a-service-api/waas_rest_api_example.py

 

 

L'exécution de ce script d'exemple amène à un résultat similaire à celui obtenu avec cURL : nous obtenons la liste de nos applications.

 

 

En résumé :

En conclusion, et pour dire les choses simplement, nous disposons d'une API REST très complète pour Barracuda WAF-as-a-Service. Cette API vous permet de faire toutes sortes de choses qui servent de blocs essentiels à la mise en place d'automatisations et de DevOps, et tout particulièrement d'effectuer une même tâche, à l'identique, un très grand nombre de fois à l'aide de différents types d'interfaces de programmations.

Nous avons vu trois manières de se lancer dans l'utilisation de l'API, avec une approche de type « ramper, puis marcher, puis courir ». Nous avons démarré avec le plus simple en utilisant l'interface Swagger, puis nous sommes passés à l'utilisation de commandes cURL et nous avons terminé en observant comment utiliser l'API en Python.

« Mais », me demanderez-vous, « comment passer de ça à un pipeline applicatif CI/CD complet ? Trottiner c'est sympa, mais moi je veux sprinter ! Peut-on voir quelques exemples de la manière de concevoir un pipeline qui nous permette de déployer notre configuration de WAF-as-a-Service avec les mêmes processus DevOps que ceux que nous utilisons déjà pour déployer nos applications ? » Ma foi, pour une réponse à cette question, et à bien d'autres encore, nous passerons au niveau supérieur en matière d'API dans un prochain billet, à paraître dans un avenir raisonnablement proche. On vous tient au courant !

And, please, if you have any questions on this basic introduction to our REST API, or if you find any bugs in my examples, don’t hesitate to reach out to me, Brett Wolmarans, at bwolmarans@barracuda.com

 

 

Remonter en haut de page
Tweeter
Partager
Partager