Configuration des analyses DAST avec des définitions OpenAPI en utilisant les API REST

Aperçu

Cette section explique comment utiliser les API REST pour configurer les analyses Dynamic Application Security Testing (DAST) à l'aide de définitions OpenAPI.

Cette méthode prend en charge les définitions OpenAPI basées sur des fichiers (JSON, YAML, YML) et sur des URL, et ajoute un nouveau support pour configurer l'autorisation et des paramètres supplémentaires pour vos analyses d'API.

Vous suivrez un processus en deux étapes :

Étape 1 : Utilisez POST /jobs/{jobId}/dastconfig/openapi/specification/process pour télécharger un fichier OpenAPI ou traiter une URL OpenAPI. Cette API extrait et retourne le chemin du fichier ainsi qu'une liste des paramètres disponibles à partir de la définition.
Étape 2 : Utilisez POST /jobs/{jobId}/dastconfig/openapi/configure pour appliquer la configuration. Vous transmettez l'emplacement du fichier/URL avec le baseUrl et toutes valeurs d'autorisation ou de paramètres optionnelles.

Remarque :

Vous ne pouvez utiliser ces API que pour les tâches DASTConfig. Vous ne pouvez pas les utiliser avec les tâches Content-Scan.
Si une tâche DASTConfig possède déjà une configuration OpenAPI, l'utilisation de l'API .../configure remplace la configuration existante.

Points de terminaison d'API pour la configuration basée sur OpenAPI

POST /jobs/{jobId}/dastconfig/openapi/specification/process – Télécharge un fichier de description OpenAPI ou traite une URL pour une utilisation ultérieure dans la configuration et la récupération de paramètres.
POST /jobs/{jobId}/dastconfig/openapi/configure – Crée ou met à jour la configuration DAST en utilisant une définition OpenAPI.

Prérequis

Vous avez besoin d'une tâche DASTConfig existante. Nous recommandons d'utiliser le modèle 'Analyse régulière' pour éviter les problèmes de performance. Vous pouvez créer une tâche DASTConfig en utilisant l'une des API suivantes :
- POST/jobs/{templateId}/dastconfig/createjob
- POST/jobs/createjobBasedOnTemplateFile
- POST/jobs
Vous avez besoin du jobId de la tâche DASTConfig. Vous pouvez l'obtenir en utilisant le point de terminaison API GET /folders/{folderId}/jobs.
Vous avez besoin d'un asc_xsrf_token valide pour l'authentification des requêtes API. Vous pouvez l'obtenir depuis le point de terminaison API POST /login. Vous devez envoyer ce jeton en tant qu'en-tête de requête.

Référence API : POST /jobs/{jobId}/dastconfig/openapi/specification/process

Objectif : Utilisez cette API pour télécharger un fichier de description OpenAPI ou une URL OpenAPI, que vous pouvez ensuite référencer avec l'API .../configure. Cette API extrait également et retourne une liste de paramètres supplémentaires disponibles dans le fichier téléchargé ou depuis une URL fournie.

Méthode HTTPS et point de terminaison : POST /jobs/{jobId}/dastconfig/openapi/specification/process

Paramètres de chemin :

jobId (Entier, Requis) : L'identifiant unique de la tâche DASTConfig.

Paramètres de requête (multipart/form-data) :

openApiDescriptionFile (Fichier, Optionnel) : Le fichier de spécification OpenAPI au format .json, .yaml, ou .yml.
openApiUrl (Chaîne, Optionnel) : Une URL publiquement accessible pointant vers un document OpenAPI au format .json, .yaml, ou .yml.

Remarque :

Pour la configuration OpenAPI basée sur fichier, vous devez utiliser cette API pour télécharger le fichier avant d'appeler .../configure.
Pour la configuration basée sur URL, l'utilisation de cette API est facultative. Vous pouvez l'utiliser pour prévisualiser et récupérer les paramètres disponibles depuis l'URL avant la configuration.

Réponse de succès (200 OK) :

L'API retourne un 200 OK en cas de succès, avec le chemin du fichier (si téléchargé) ou l'URL (si fournie), et les paramètres extraits de la spécification OpenAPI.

Classe de réponse (modèle) :

OpenApiProcessResponse {
  openApiFileLocation (string) : L'emplacement (URL ou chemin) du fichier OpenAPI généré,
 
  parameters (array[OpenApiAdditionalParameters], optional) : Une liste de paramètres d'API extraits de la spécification OpenAPI
}

OpenApiAdditionalParameters {
  path (string, optional):
      Le chemin de le point de terminaison d'API (par ex., /login, /account/{accountNo}),
 
  name (string, optional):
      Le nom du paramètre (par ex., username, password, accountNo),
 
  location (string, optional):
      L'emplacement du paramètre (par ex., body, path, query)
}

Voir Messages de réponse pour les codes d'erreur.

Référence API : POST /jobs/{jobId}/dastconfig/openapi/configure

Objectif : Utilisez cette API pour configurer une tâche DAST pour OpenAPI. Vous ne pouvez pas ajouter cette configuration à une tâche Content-Scan. Si une configuration existante est présente, cet appel d'API la remplace.

Méthode HTTPS et point de terminaison: POST /jobs/{jobId}/dastconfig/openapi/configure

Paramètres de chemin :

jobId (Integer, Required) : Le paramètre de chemin pour la tâche DASTConfig à laquelle vous appliquez la configuration.

Paramètres du corps de requête (JSON) :

openApiFileLocation (String, Required) : Fournissez soit un URI accessible publiquement pointant vers un document OpenAPI standardisé (.json, .yaml, .yml), soit le chemin de fichier retourné par l'API .../openapi/specification/process pour la configuration par fichier.
baseUrl (String, Required) : Spécifiez l'URL racine qui définit le préfixe de chemin commun pour tous les points de terminaison API dans la description OpenAPI.
additionalDomains (String, Optional) : Spécifiez d'autres domaines à tester, comme valeurs séparées par des virgules.
authorization (Object, Optional) : Fournir une paire clé-valeur pour l'autorisation de l'API. Ces valeurs sont mises à jour dans le travail de configuration DAST et utilisées pour les requêtes API authentifiées.
```
{ "key": "string", "value": "string" }
```

parameters (Array[Object], Optional) : Fournissez une liste de paramètres supplémentaires à définir dans la tâche de configuration DAST. Vous pouvez récupérer des paramètres supplémentaires en utilisant l'API .../openapi/specification/process.


                                [
                                {
                                "path": "string",
                                "name": "string",
                                "location": "string",
                                "value": "string"
                                }
                                ]

Exemple de corps de requête (JSON) :


                        {
                        "openApiFileLocation": "string",
                        "baseUrl": "string",
                        "additionalDomains": "string",
                        "authorization": {
                        "key": "string",
                        "value": "string"
                        },
                        "parameters": [
                        {
                        "path": "string",
                        "name": "string",
                        "location": "string",
                        "value": "string"
                        }
                        ]
                        }

Remarque :

Si vous ajoutez un fichier de description JSON ou YAML local au lieu d'une URL à une configuration, vous ne pouvez pas l'exporter en tant que fichier SCANT (modèle), car le fichier de spécification ne peut pas être inclus dans un modèle. Vous devez soit supprimer le fichier de spécification, soit l'enregistrer en tant que fichier SCAN.

Réponse en cas de succès (200 OK) :

En cas de succès, l'API renvoie un code de statut HTTP 200 OK.

Classe de réponse en cas d'erreur (modèle) :


                        ErrorMessage {
                        errorMessage (string)
                        }

Voir Messages de réponse pour les autres codes d'erreur.