API REST

L'interface d'API REST intégrée vous permet de visualiser les services Web RESTful. La documentation API est élaborée à l'aide de Swagger. Vous pouvez y tester des opérations API et consulter instantanément les résultats afin d'examiner vos applications plus rapidement.

Pourquoi et quand exécuter cette tâche

Apprenez à utiliser l'infrastructure interactive en suivant cet exemple pour importer un inventaire d'applications en utilisant l'API REST /api/v4/Apps/ImportFile.

Procédure

Sélectionnez Outils > API.
Cliquez sur le lien Swagger sur le côté droit de la page. Vous êtes automatiquement connecté à Swagger.
Créez un groupe d'actifs :
1. Développez l'API Groupes de fichiers métadonnées et cliquez sur POST /api/v4/AssetGroups.
2. Remplacez les paramètres "string" par un nom et une description pour le groupe d'actifs. Conservez les guillemets.
3. Cliquez sur Exécuter.
4. Prenez note de l'identifiant dans la section Corps de la réponse ; vous aurez besoin de l'utiliser pour accéder à l'API suivante.
Importez un fichier d'inventaire d'applications :
1. Développez l'API Applications et cliquez sur POST /api/v4/Apps/ImportFile.
  La section Implementation contient un exemple de fichier que vous pouvez télécharger pour obtenir une notion des types d'attributs à inclure dans votre fichier.
2. Saisissez l'assetGroupId de l'étape 3d dans le champ Value de la section Paramètres.
3. Cliquez sur Parcourir dans la section uploadedFile afin de localiser votre fichier CSV d'applications à importer.
4. Cliquez sur Exécuter.
  Une importation réussie s'affiche comme suit :

Exemple

Importation de fichiers d'examen, y compris les résultats à l'aide de l'API REST

Vous pouvez importer un fichier d'examen, y compris les résultats, sans exécuter l'examen dans AppScan 360° en procédant comme suit :

Assurez-vous d'être connecté à Swagger à l'aide de l'API : api/V4/Account/ApiKeyLogin.
Téléchargez le fichier d'examen à l'aide de l'API : api/V4/FileUpload et enregistrez l'ID de fichier pour plus tard. Par exemple,
"FileId": "274bd3a7-a231-41d0-80f6-d22d684af50d"
Développez l'API Examens et cliquez sur POST /api/v4/Scans/Dast. Mettez à jour les paramètres suivants pour générer uniquement les rapports sans exécuter l'examen.
1. ScanOrTemplateFileId : Mettez à jour l'ID de fichier que vous avez copié à l'étape 2.
  "ScanOrTemplateFileId": "274bd3a7-a231-41d0-80f6-d22d684af50d"
2. TestOperation : Définissez sur ReportOnly
  "TestOperation": "ReportOnly"
Remarque : Assurez-vous d'avoir mappé l'AppID, ScanName et les autres paramètres requis pour exécuter l'API POST /API/V4/Scans/DAST.

S'authentifier à l'aide d'une clé d'API directe

Authentifiez les requêtes API en envoyant votre ID de clé d'API et votre secret dans un en-tête HTTP personnalisé. La méthode Clé d'API directe ignore l'échange de votre clé contre un jeton de session. Cela simplifie les scripts d'automatisation et les intégrations CI/CD, car vous n'avez plus besoin de gérer les cycles de vie ou l'expiration des jetons. Les principaux avantages sont les suivants :

Automatisation simplifiée : Il n'est pas nécessaire d'écrire la logique pour « Login », « Get Token » ou « Refresh Token ».
Expérience sans état : Envoyez la clé avec chaque requête ; le système gère la session en arrière-plan.
Complexité réduite : Idéal pour les scripts simples, les tâches ponctuelles ou les intégrations où le maintien de l'état de la session est difficile.

Spécifications techniques :

Pour utiliser cette fonction, incluez l'en-tête suivant dans vos requêtes HTTP :

Nom d'en-tête : X-Api-Key
Format de valeur d'en-tête : La valeur doit être composée de votre ID de clé et de votre secret de clé séparés par deux points (:). KeyID:KeySecret
Exemple : Si vos informations d'identification sont :
- Key ID: b0977ee5-c9df-0c8a-5909-184c690cbfa5
- Key Secret: UnKUn7HupAX9MFviJqYHRy6w7Fk50anSlheQJxQhTiux
  L'en-tête doit ressembler à ceci :
```
X-Api-Key: b0977ee5-c9df-0c8a-5909-184c690cbfa5:UnKUn7HupAX9MFviJqYHRy6w7Fk50anSlheQJxQhTiux
```

Exemples de mise en œuvre :

cURL

curl -X GET "https://cloud.appscan.com/api/v4/Scans" \
                                    -H "Accept: application/json" \
                                    -H "X-Api-Key: <Your_Key_ID>:<Your_Key_Secret>"

Python (bibliothèque de requêtes)

import requests
                                        
                                        url = "https://cloud.appscan.com/api/v4/Scans"
                                        key_id = "your_key_id"
                                        key_secret = "your_key_secret"
                                        
                                        # Construct the header value
                                        header_value = f"{key_id}:{key_secret}"
                                        
                                        headers = {
                                        "Accept": "application/json",
                                        "X-Api-Key": header_value
                                        }
                                        
                                        response = requests.get(url, headers=headers)
                                        
                                        if response.status_code == 200:
                                        print("Success:", response.json())
                                        else:
                                        print("Error:", response.status_code, response.text)

Remarques sur la sécurité et le comportement :

Expiration et actualisation : Le système maintient une session de 30 minutes pour les performances, mais vous n'avez pas besoin de la suivre. Si la session expire, votre clé est revalidée et une nouvelle session est créée automatiquement.
Révocation : Si vous supprimez votre clé d'API dans le portail AppScan, l'accès est immédiatement révoqué. Toutes les sessions actives utilisant cette clé sont interrompues et les requêtes suivantes renvoient un code d'erreur 401, indiquant un accès non autorisé.
Droits : Les requêtes authentifiées avec cette méthode héritent des mêmes droits que le compte utilisateur propriétaire de la clé d'API.

Résolution des problèmes :

401 Non autorisé : Vérifiez que votre ID de clé et votre secret sont corrects et que la clé n'a pas été révoquée ou supprimée.
Erreur de format : Assurez-vous qu'il n'y a pas d'espace entre l'ID de clé, les deux points et le secret de clé (par exemple, ID:Secret, pas ID : Secret).