42crunch/api-security-audit-actionAutomatise l'audit de sécurité statique des contrats OpenAPI dans les pipelines CI/CD, exécutant plus de 300 contrôles pour l'authentification, l'autorisation et les contraintes de données, avec des seuils de score minimal et une sortie SARIF.
L'action de test de sécurité statique des API REST localise les contrats d'API REST qui suivent la spécification OpenAPI (OAS, anciennement connue sous le nom de Swagger) et exécute des contrôles de sécurité approfondis sur ceux-ci. Les versions OAS v2 et v3.0.x sont toutes deux prises en charge, aux formats JSON et YAML.
Vous pouvez utiliser cette action dans les scénarios suivants :
L'action est propulsée par 42Crunch API Security Audit. Security Audit effectue une analyse statique de la définition d'API qui comprend plus de 300 contrôles sur les bonnes pratiques et les vulnérabilités potentielles liées à l'authentification, à l'autorisation ainsi qu'aux contraintes de données.
Par défaut, cette action va :
.json et .yaml dans le dépôt.Vous pouvez ainsi localiser tout contrat d'API nouveau ou modifié dans le dépôt.
Vous pouvez affiner le comportement de l'action en spécifiant des parties précises du dépôt ou des masques de noms de fichiers à inclure ou exclure dans la découverte des API. Vous pouvez même désactiver complètement la découverte et lister uniquement des fichiers d'API spécifiques à contrôler, puis les mapper à vos API existantes dans la plateforme de sécurité API 42Crunch. Vous configurez tous ces paramètres dans le fichier de configuration 42c-conf.yaml. Pour des exemples avancés, voir ici.
Toutes les API découvertes sont téléversées dans une collection d'API sur la plateforme 42Crunch. Par défaut, l'action utilise les variables d'environnement GITHUB_REPOSITORY et GITHUB_REF pour nommer le dépôt et la branche/tag/PR d'où provient la collection d'API. Vous pouvez remplacer ce nom à l'aide du paramètre d'action default-collection-name. Lors des exécutions suivantes, les API de la collection restent synchronisées avec les modifications de votre dépôt.
Ajoutez cette action à vos workflows CI/CD dans GitHub et faites-la échouer sur les définitions d'API qui contiennent des problèmes de sécurité.
Security Audit attribue à chaque contrat d'API un score d'audit de 0 à 100 reflétant la surface de sécurité de vos API. Vous pouvez utiliser le paramètre min-score de l'action GitHub pour définir le seuil de score d'audit auquel l'action échoue (la valeur par défaut est 75, si aucune autre valeur n'est spécifiée). Cela permet de détecter les définitions d'API de mauvaise qualité et de traiter les problèmes dès la phase de conception.
Des conditions d'échec plus avancées peuvent être définies dans le fichier de configuration 42c-conf.yaml, comme le score d'audit par catégorie (sécurité ou validation des données), le niveau de gravité des problèmes, ou même des problèmes spécifiques identifiés par leur ID. Pour des exemples avancés, voir ici.
De plus, le plugin applique les portes de qualité de sécurité définies au niveau de la plateforme (par défaut ou pilotées par des tags). Les portes de qualité de sécurité imposent les exigences de sécurité applicative définies au sein de l'entreprise.
Chaque fois que l'action s'exécute, elle inclut un lien vers le rapport détaillé, priorisé et exploitable pour chacun de vos fichiers OpenAPI :
Suivez les liens pour lire le rapport détaillé dans la plateforme 42Crunch :
Vous pouvez également suivre les problèmes détectés par l'audit 42Crunch directement dans GitHub, sous l'onglet Security dans la section Code scanning alerts.
Pour activer cette fonctionnalité, il suffit d'inclure upload-to-code-scanning:true dans les paramètres de l'action de votre workflow GitHub.
Cliquez sur l'une des alertes pour voir son emplacement exact dans votre code et obtenir les détails de la vulnérabilité ainsi que les étapes de remédiation recommandées.
Cette action utilise le service 42Crunch API Security Audit. Avant d'utiliser l'action, vous devez disposer d'un compte sur la plateforme 42Crunch. Si vous n'êtes pas client de 42Crunch, vous pouvez demander un compte gratuit à partir de cette page : https://42crunch.com/get-started/.
Ensuite, suivez les étapes décrites dans la documentation pour créer un jeton API permettant à l'action de s'authentifier auprès de la plateforme 42Crunch, et enregistrez-le comme secret dans GitHub.
api-tokenRequis Le jeton API que l'action GitHub utilise pour s'authentifier auprès de la plateforme 42Crunch. Ne placez pas votre jeton API directement dans le fichier de workflow ! Créez plutôt un secret GitHub dans les paramètres de votre dépôt et référencez-le comme indiqué dans l'exemple ci-dessous.
min-scoreLe score d'audit minimum que les fichiers OpenAPI doivent atteindre, sinon l'action échoue. La valeur par défaut est 75.
upload-to-code-scanningTéléverse les résultats d'audit vers GitHub Code Scanning. La valeur par défaut est false. Notez que le workflow doit disposer d'autorisations spécifiques pour que cette étape réussisse.
...
jobs:
run_42c_audit:
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
...
ignore-failuresSi la valeur est true, force la fin de l'exécution en succès même si les conditions d'échec que vous avez définies (comme min-score ou les critères SQG) sont remplies. La valeur par défaut est false.
Ce paramètre peut être utile si vous souhaitez détecter des scénarios d'échec SQG sans les appliquer (c'est-à-dire accorder une période de grâce aux équipes de développement avant de commencer à casser les builds).
ignore-network-errorsSi la valeur est true, force la fin de l'exécution en succès même si une erreur réseau s'est produite (comme un échec de connexion à la plateforme 42Crunch, etc.). La valeur par défaut est false.
skip-local-checksSi la valeur est true, désactive toutes les conditions d'échec (comme le score minimum) définies dans le fichier 42c-conf.yaml et ne fait échouer l'exécution que si les critères définis dans les SQG ne sont pas respectés. La valeur par défaut est false.
platform-urlL'URL à laquelle vous accédez à la plateforme 42Crunch. La valeur par défaut est https://us.42crunch.cloud.
Si vous êtes un client entreprise, saisissez l'URL que vous utilisez pour accéder à votre plateforme de production.
root-directoryLe répertoire racine qui contient le fichier de configuration 42c-conf.yaml. S'il n'est pas spécifié, le répertoire de travail actuel du plugin est utilisé à la place, ce qui correspond normalement à la racine du dépôt cloné.
default-collection-nameLe nom de collection par défaut utilisé lors de la création des collections pour les API découvertes. Si aucun nom n'est fourni, un nom par défaut est créé à partir du dépôt et des informations de branche/PR.
log-levelNiveau de détail des journaux, l'un des suivants : FATAL, ERROR, WARN, INFO, DEBUG. La valeur par défaut est INFO.
share-everyonePartage automatiquement les collections d'API créées par la tâche CI/CD avec tout le monde dans votre organisation sur la plateforme 42Crunch. Les valeurs acceptées sont : OFF, READ_ONLY, READ_WRITE. La valeur par défaut est OFF. Notez que l'identité sous laquelle l'action s'exécute (le propriétaire du jeton API) doit disposer de la permission Share with Everyone, sinon la tâche échouera avec une erreur 403.
json-reportÉcrit un rapport d'exécution d'audit au format JSON dans le fichier spécifié. Un rapport d'exécution détaille la liste des API créées, mises à jour et supprimées. Cela est utile si vous souhaitez consommer automatiquement les résultats de l'exécution de l'audit dans une étape de pipeline ultérieure. Par défaut, aucun rapport n'est écrit.
api-tagsLa tâche CI/CD peut automatiquement attribuer des tags aux API nouvellement créées. Les tags sont spécifiés au format suivant : category1:name1 category2:name2. Ce paramètre est facultatif.
sarif-reportConvertit le format JSON brut de l'audit en SARIF et enregistre les résultats dans le fichier spécifié. Par défaut, aucun rapport n'est écrit.
audit-timeoutDéfinit le délai d'expiration maximal (en secondes) pour le rapport d'audit. La tâche échouera si le résultat n'est pas prêt dans cet intervalle. Valeur par défaut : 600
Créez un jeton API sur la plateforme 42Crunch et copiez sa valeur dans un secret de dépôt nommé API_TOKEN.
Une nouvelle étape typique dans un workflow existant ressemblerait à ceci :
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
Un workflow typique qui vérifie le contenu du dépôt, exécute Security Audit sur chacun des fichiers OpenAPI trouvés dans le projet et enregistre le fichier d'exécution comme artefact ressemblerait à ceci :
name: "42crunch-audit-workflow"
# follow standard Code Scanning triggers
on:
push:
branches: [ "main" ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ "main" ]
schedule:
- cron: '19 9 * * 6'
env:
PLATFORM_URL: https://us.42crunch.cloud
jobs:
run_42c_audit:
environment: QA
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
platform-url: ${{ env.PLATFORM_URL}}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
# Upload results to Github code scanning
upload-to-code-scanning: false
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
- name: save-audit-report
if: always()
uses: actions/upload-artifact@v3
with:
name: auditaction-report-${{ github.run_id }}
path: audit-action-report-${{ github.run_id }}.json
if-no-files-found: error
L'action est maintenue par l'équipe écosystèmes de 42Crunch. Si vous rencontrez un problème ou avez une question sans réponse ici, vous pouvez créer un ticket de support sur support.42crunch.com.
Lorsque vous signalez un problème, veuillez inclure :