Comprendre les API : REST

 

Orchestration, automatisation et réponse en matière de sécurité (SOAR) Les plateformes s'appuient fortement sur les API (interfaces de programmation d'applications) pour orchestrer différents outils (produits) de sécurité et déclencher les actions souhaitées. Outre les solutions SOAR, les API sont omniprésentes dans la quasi-totalité des services, outils et produits utilisés par les techniciens.

Bien que les API soient extrêmement courantes, il se peut que vous n'ayez aucune expérience de leur utilisation, ni même que vous sachiez qu'un service en possède une lorsque vous interagissez avec lui. Par exemple, Facebook utilise un framework d'API appelé API Graph.

“ L’API Graph est le principal moyen pour les applications de lire et d’écrire dans le graphe social de Facebook. ”

Les API se présentent sous de nombreuses formes, mais quel que soit le framework utilisé pour un service, elles permettent aux techniciens d'interagir avec un système ou un service. Les API nous permettent de développer et de connecter rapidement un système à un autre, que ce soit au sein d'une seule application ou à plus grande échelle, comme avec Swimlane.

L'utilisation des API offre aux individus (et aux organisations) du monde entier un moyen de partager et d'interagir avec l'information rapidement, en toute sécurité (à condition, bien sûr, qu'elle soit correctement mise en œuvre) et dans un format défini (décrit). Sans les API, l'automatisation telle que nous la connaissons aujourd'hui n'existerait pas.

Dans la première partie de cette série en deux parties, je vais vous présenter un aperçu des API REST (Representable State Transfer), ainsi que les points clés pour vous aider à démarrer rapidement votre compréhension des API.

Authentification

Les API REST nécessitent généralement un mécanisme d'authentification pour interagir avec elles. Cette exigence est standard pour les produits ou services payants, mais pas nécessairement pour les outils de renseignement en sources ouvertes (OSINT) ou autres services gratuits sur Internet.

Les API utilisent plusieurs méthodes d'authentification standard et personnalisées. Il est impossible de toutes les énumérer, mais vous rencontrerez fréquemment les types de méthodes suivants :

Taper	Exemple	Description
Aucune authentification	Interrogation de l'API de ThreatMiner et recherche du domaine google.com	Une API qui ne nécessite aucune information supplémentaire lors de la requête de données à une API
Nom d'utilisateur et mot de passe	Interrogation de l'API locale de Microsoft Exchange	Une API qui nécessite une authentification de base à l'aide de votre nom d'utilisateur et de votre mot de passe.
Jeton	Interroger haveibeenpwned.com, ce qui nécessite la création d'un compte gratuit et d'un jeton API.	Une API qui requiert un jeton unique pour utiliser le service. Ce jeton doit généralement être fourni dans l'en-tête de votre requête.
Délégation	Utilisation de l'API Microsoft Graph, qui requiert une authentification OAuth2	Une API qui fonctionne conjointement avec un service d'authentification qui vous fournit des jetons temporaires pour utiliser l'API.

Ce ne sont là que quelques exemples des différents mécanismes d'authentification qu'un service peut utiliser. Selon le produit et l'entreprise, il est possible d'opter pour une norme comme celles mentionnées ci-dessus ou de choisir une solution interne.

L'objectif principal de ces mécanismes d'authentification est de garantir que vous disposez des droits d'accès appropriés au service et de veiller à ce que vous respectiez les limites d'utilisation prescrites.

Si vous souhaitez approfondir le sujet de l'implémentation d'OAuth2 par Microsoft, consultez cette série en trois parties que j'ai écrite, qui explique plus en détail ce mécanisme d'authentification spécifique : Partie 1, Partie 2, et Partie 3.

Versions

À l'avenir, j'utiliserai un service fictif appelé Service de renseignement sur les menaces de Josh et l'URL de ce service est : https://joshsthreatintel.example.

Vous pouvez visiter un site de ce type et interagir avec lui comme vous le feriez avec n'importe quel autre site web, mais il cache une API qui vous permet d'accéder à des informations par programmation afin de piloter l'automatisation.

Une bonne API possède une documentation très complète qui détaille la procédure d'authentification et d'utilisation du service. Une norme courante est : Fanfaronnade, mais nous n'avons pas besoin de comprendre ce qu'est Swagger (c'est une norme qui permet un développement plus rapide des API et une standardisation de leur documentation).

À https://joshsthreatintel.example Notre API est versionnée et accessible en ajoutant /v1 à notre URL. Si vous accédez à ce dossier sur notre site web, il peut être vide, vous pouvez recevoir un message d'erreur d'authentification, ou il peut s'agir d'une page affichant la documentation de l'API. Dans tous les cas, la racine de notre API est accessible via cette URL : https://joshsthreatintel.example/v1/.

Chaque API que vous rencontrerez peut avoir une ou plusieurs versions. Par exemple, havibeenpwned.com en propose trois :

1. https://haveibeenpwned.com/API/v1
2. https://haveibeenpwned.com/API/v3

Méthodes

Les API REST sont conçues pour être utilisées via des méthodes spécifiques définies dans leur code source. Ces méthodes réagissent différemment selon le type utilisé et les données envoyées à l'API. Les méthodes typiques que vous rencontrerez lors de l'interaction avec une API sont répertoriées dans le tableau ci-dessous :

Méthode	Description du terme	Description
OBTENIR	Récupérer ou lire	Les méthodes GET sont utilisées pour récupérer des informations à partir d'une API.
POSTE	Créer, ajouter ou invoquer	Les méthodes POST sont utilisées pour créer ou ajouter des données, ou pour déclencher une action.
METTRE	Correctif ou mise à jour	Les méthodes PUT sont utilisées pour mettre à jour ou modifier des données d'une manière ou d'une autre.
SUPPRIMER	Détruire ou enlever	Les méthodes DELETE sont utilisées pour supprimer des données ou pour interrompre une action.

Les méthodes les plus courantes sont GET et POST. Selon le type d'API (REST ou SOAP) et de service, vous devrez peut-être fournir des informations supplémentaires dans les en-têtes de votre requête API.

En règle générale, une requête GET consiste à envoyer une requête HTTP à un point de terminaison (chemin dans une URL) afin de récupérer des informations spécifiques de l'API. Par exemple, imaginons que notre service fictif de veille sur les menaces possède un point de terminaison appelé adresse IP et exige que vous fournissiez une adresse IP à ce point de terminaison. Ce point de terminaison peut ressembler à : /ip/123.123.123.123, que nous ajoutons à notre URL racine : https://joshsthreatintel.example/v1/ip/123.123.123.123.

Dans le cadre de notre requête, nous précisons dans notre appel à ce point de terminaison que nous effectuons une OBTENIR nous avons formulé une demande et nous souhaitons obtenir des informations concernant l'adresse IP 123.123.123.123.

Voici deux exemples de mise en œuvre en Python et PowerShell Core :

• Python:
  • demandes d'importation
  • réponse = requests.get('https://joshsthreatintel.example/v1/ip/123.123.123.123')
• PowerShell :

   

  • $response = Invoke-RestMethod -Uri '‘https://joshsthreatintel.example/v1/ip/123.123.123.123’' -Méthode GET

Un autre point de terminaison peut être disponible et vous permettre de POSTE une URL spécifique vers notre service fictif (Service de renseignement sur les menaces de Josh) afin qu'il puisse être analysé pour détecter toute activité malveillante. Ce point de terminaison est appelé URL et serait ajouté à notre URL racine : https://joshsthreatintel.example/v1/url.

En plus de la requête HTTP normale, lorsque nous envoyons des données à ce faux service pour analyser une URL, nous devons fournir dans le corps de notre requête l'URL que nous voulons Service de renseignement sur les menaces de Josh pour scanner. Voici un exemple en Python :

import requests body = { 'url': 'http://some.malicious.website.com' } response = requests.post('https://joshsthreatintel.example/v1/url', data=body}

Vous constaterez que l'exemple ci-dessus est courant et privilégié par la plupart des API, mais ce point de terminaison pourrait également vous permettre de OBTENIR une URL utilisant des paramètres de requête.

Un paramètre de requête, en termes simples, permet de filtrer ou de sélectionner des informations provenant d'une API. On rencontre généralement des paramètres de requête lorsqu'un service permet à l'utilisateur d'influencer les résultats renvoyés par un appel d'API, mais ils peuvent également servir à déclencher une action ; par exemple, analyser une URL au lieu de fournir des attributs dans le corps d'une requête HTTP.

Les paramètres de requête sont généralement accolés, ce qui, à mon avis, nuit à la lisibilité. Voici un exemple que vous pourriez rencontrer lors de l'utilisation de paramètres de requête avec des API :

https://joshsthreatintel.example/v1/url?url=some.malicious.website.com {chemin vers l'API}/{point de terminaison}?{param=valeur}

Comme vous pouvez le constater dans l'exemple ci-dessus, nous avons le chemin racine de notre API, puis le point de terminaison ; qui est le URL dans ce cas. Après le URL Au niveau du point de terminaison, nous pouvons voir notre paramètre de requête. Notre paramètre de requête commence par un ? et est ensuite suivi du nom du paramètre et de la valeur que nous utilisons pour ce paramètre.

Un point de terminaison d'API peut vous permettre de spécifier plusieurs paramètres de requête. Par exemple, voici la syntaxe d'URL pour récupérer des informations de l'API REST de RIPE (Réseaux IP Européens) pour une adresse IP spécifique :

https://rest.db.ripe.net/search?source=ripe&query-string={querystring} {chemin vers l'API}/{endpoint}?{param=value}&{param=value}

Vous avez peut-être remarqué l'ajout d'un et, Cela indique la présence d'un autre paramètre de requête. Ce paramètre contient également son nom et sa valeur. Une API peut permettre d'en ajouter plusieurs à la suite. Consultez la documentation de l'API pour connaître les règles applicables à un point de terminaison spécifique.

Vous constaterez que les API réelles utilisent généralement des paramètres de requête ou exigent que vous fournissiez une paire clé-valeur de données dans le corps de la requête.

En-têtes

Lors de l'utilisation d'API, il peut vous être demandé d'ajouter des informations supplémentaires à un OBTENIR ou POSTE ou une autre méthode pour le en-têtes d'une requête HTTP. Il peut s'agir d'un jeton d'authentification, d'une spécification du type de contenu ou d'autres informations.

En termes simples, un en-tête La valeur est une métadonnée utilisée pour établir une connexion avec une API. Cette métadonnée sert à l'API pour s'authentifier ou configurer l'environnement en fonction du type d'action/requête à effectuer.

Il est très fréquent que les API nécessitant une authentification demandent la fourniture d'un jeton dans les en-têtes des requêtes HTTP. Ce jeton peut être permanent ou, dans le cas d'un système d'authentification par délégation (par exemple OAuth2), temporaire et renouvelable périodiquement. Dans tous les cas, cette authentification est courante pour les API.

Vous devrez peut-être également préciser Accepter ou Type de contenu en-têtes ainsi qu'un Autorisation En-tête. En termes simples, un en-tête se présente généralement sous la forme d'une paire clé-valeur. Voici un exemple en Python de ce à quoi peuvent ressembler ces deux en-têtes :

custom_headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {SOME_AUTHENTICATION_TOKEN}' }

Ces en-têtes sont ensuite envoyés au serveur avec notre requête HTTP. Leur utilisation peut être facultative lors de l'utilisation d'une API ; s'ils sont requis par une API, ils le seront généralement pour toutes les méthodes utilisées dans vos requêtes HTTP.

J'espère que cela vous aidera à comprendre les bases des API REST. Dans le prochain article, j'aborderai les API SOAP (Simple Object Access Protocol), qui sont bien plus complexes que les API REST.