Documentation ChatGPT
Français
Contact goolvyouyou@gmail.com

Exécuter Codex Security dans GitHub Actions

Analysez les pull requests et les dépôts avec l’Action Codex Security, enregistrez les rapports, envoyez les fichiers SARIF et configurez l’application des règles.

Exécutez Codex Security dans GitHub Actions pour examiner les modifications des pull requests ou analyser votre dépôt selon un calendrier. L’Action installe la CLI, enregistre des rapports structurés et ajoute un résumé du job ainsi que des annotations du code source. Commencez par des résultats à titre indicatif, puis configurez l’application des règles après avoir examiné la couverture et la qualité des analyses.

Préparer le workflow

L’exécution d’analyses nécessite un accès à Codex Security. Pour ajouter votre API key OpenAI :

  1. Dans votre dépôt GitHub, ouvrez Settings → Secrets and variables → Actions.
  2. Sélectionnez New repository secret.
  3. Saisissez CODEX_SECURITY_API_KEY comme nom et collez votre API key OpenAI comme valeur. Enregistrez le secret.

Les exemples de workflow ci-dessous transmettent ce secret à l’Action Codex Security automatiquement. Vous n’avez pas besoin de placer votre API key dans le fichier du workflow.

N’exécutez le workflow que pour des dépôts et des pull requests de confiance. Les analyses utilisent les autorisations locales du runner et ne s’interrompent pas pour demander une approbation. Placez les identifiants sans rapport avec l’analyse et les étapes de déploiement dans des jobs distincts.

Ajouter le workflow GitHub Actions

Analyser le dépôt selon un calendrier

Le workflow ci-dessous analyse votre branche par défaut chaque lundi à 07:23 UTC. Vous pouvez aussi l’exécuter manuellement depuis l’onglet Actions de GitHub. Il utilise un runner x64 Ubuntu 24.04 hébergé par GitHub et configure automatiquement le sandbox requis.

  1. Dans votre dépôt, sélectionnez Add file → Create new file.
  2. Nommez le fichier .github/workflows/codex-security-repository.yml.
  3. Collez le workflow ci-dessous et effectuez un commit sur votre branche par défaut.
name: Codex Security repository

on:
  workflow_dispatch:
  schedule:
    - cron: "23 7 * * 1" # Mondays at 07:23 UTC

permissions:
  contents: read

jobs:
  security:
    runs-on: ubuntu-24.04
    timeout-minutes: 120
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - name: Check out the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Scan the repository
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: repository
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

Adapter le runner : L’Action nécessite Node.js 24 et Python 3.11 ou une version ultérieure, que ce runner fournit. La configuration du sandbox installe le package bubblewrap et charge le profil AppArmor fourni avant l’analyse. L’installation du package seule ne suffit pas sur ce runner.

Pour exécuter le workflow manuellement, ouvrez Actions → Codex Security repository → Run workflow. Ouvrez une exécution terminée pour consulter le résumé, les annotations et les rapports téléchargeables.

Les problèmes détectés sont uniquement signalés, car fail-on-severity est défini sur none. Les erreurs du scanner et celles liées aux rapports obligatoires font tout de même échouer le job.

Pour analyser certains dossiers, ajoutez les chemins littéraux, un par ligne, au bloc with de l’étape d’analyse :

paths: |
  src/api
  src/auth

Ces chemins nécessitent scope: repository et ne font l’objet d’aucune expansion de motifs glob. Pour les analyses des différences, omettez paths. Conservez persist-credentials: false et exécutez l’analyse immédiatement après l’extraction du code.

Analyser les modifications d’une pull request

En utilisant le même secret, créez .github/workflows/codex-security-pr.yml :

name: Codex Security PR

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read

concurrency:
  group: codex-security-pr-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    name: Codex Security
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    steps:
      - name: Set up the Ubuntu sandbox
        run: |
          sudo apt-get update
          sudo apt-get install --yes bubblewrap apparmor-profiles
          sudo apparmor_parser -r /usr/share/apparmor/extra-profiles/bwrap-userns-restrict

      - name: Check out the pull request
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Scan PR changes
        id: security
        uses: openai/codex-security@3f61e5150981a5087c32e4395bbaa8ce5ce0c3e3 # action-v0.3.0
        with:
          scope: diff
          model: gpt-6-sol
          # For approved Daybreak Blue access, uncomment the next input.
          # cyber-access-program: daybreak_blue
          effort: high
          fail-on-severity: none
          upload-artifacts: "true"
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}

Ouvrez ou mettez à jour une PR depuis une branche du même dépôt. L’Action utilise l’historique complet pour trouver la base de fusion exacte et analyse les modifications jusqu’à la révision de tête de la PR extraite. Consultez la vérification Codex Security sous Checks dans la PR. Commencez par des résultats à titre indicatif, puis choisissez une politique de sévérité lorsque vous souhaitez conditionner l’acceptation des modifications.

Cet exemple ignore les PR issues de forks et les PR ouvertes par dependabot[bot]. Un job ignoré ne prouve pas qu’un examen de sécurité a eu lieu. Pour inclure ces PR de bots, supprimez l’exclusion de l’auteur et configurez aussi CODEX_SECURITY_API_KEY comme secret pour dependabot[bot]. L’Action ne prend en charge ni pull_request_target ni workflow_run.

Le scanner lit les instructions SECURITY.md applicables dans le code extrait, y compris les modifications de politique de la PR. Examinez ces modifications en même temps que le code.

Configurer l’accès facultatif à Daybreak

Daybreak est facultatif. Les deux exemples de workflow utilisent gpt-6-sol. Si votre organisation a été approuvée pour Trusted Access for Cyber, supprimez le # placé avant cyber-access-program dans le bloc with de l’étape d’analyse :

model: gpt-6-sol
cyber-access-program: daybreak_blue

Utilisez une API key issue d’un projet sur lequel Daybreak Blue est activé et qui a accès à gpt-6-sol.

Le paramètre d’entrée du programme accepte également standard. Sans accès à Daybreak, utilisez un modèle accessible avec votre API key dans le cadre des protections standard et omettez cyber-access-program ou définissez-le sur standard. Sélectionner un modèle ou un programme n’accorde aucun accès. Consultez les consignes d’accès à Daybreak de l’Action.

Un refus ou un blocage de sécurité qui interrompt l’analyse fait échouer l’Action, y compris lorsque fail-on-severity est défini sur none. Ce paramètre contrôle la politique relative aux problèmes détectés, pas les erreurs du scanner.

Définir un budget d’analyse facultatif

Les deux exemples de workflow omettent max-cost ; ils n’ont donc aucun seuil d’arrêt fondé sur le coût estimé. Pour en définir un, ajoutez un montant positif en USD avec le paramètre max-cost. Pour les analyses directes avec la CLI, utilisez --max-cost.

La limite de coût nécessite que la CLI prenne en charge les tarifs du modèle sélectionné. Le seuil estimé n’est pas un plafond de dépenses strict : le coût des requêtes déjà en cours peut le dépasser. Examinez les problèmes détectés et coverage.json si une analyse s’arrête au seuil. Consultez les options de sortie et de politique pour connaître le comportement de la limite de coût.

Enregistrer les rapports et envoyer les fichiers SARIF

Les exemples définissent upload-artifacts: "true" pour enregistrer des rapports téléchargeables avec une période de conservation de sept jours. Les rapports peuvent contenir des extraits de code source, des preuves de vulnérabilités et des détails de correction. Choisissez une période de conservation et des droits d’accès au dépôt adaptés à votre code. L’Action envoie uniquement les rapports validés figurant dans sa liste d’autorisation ; n’envoyez pas récursivement sa sortie results-directory.

L’envoi de SARIF est facultatif. Pour les dépôts privés ou internes, activez GitHub Code Security avant l’envoi. Remplacez le bloc permissions du workflow par :

permissions:
  contents: read
  security-events: write
  actions: read # Required for private repositories

Ajoutez ensuite cette étape après l’analyse dans l’un ou l’autre des workflows :

- name: Upload security findings
  if: ${{ always() && steps.security.outputs.sarif-upload-ready == 'true' }}
  uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
  with:
    sarif_file: ${{ steps.security.outputs.sarif-path }}
    sha: ${{ steps.security.outputs.scanned-sha }}
    ref: ${{ steps.security.outputs.analysis-ref }}
    category: codex-security-repository

Pour le workflow de PR, utilisez category: codex-security-pr afin que chaque périmètre ait une catégorie distincte. Conservez id: security sur l’étape d’analyse. Les rapports complets et validés restent disponibles pour l’envoi lorsque les problèmes détectés font échouer la politique de sévérité. Les fichiers SARIF ne sont pas envoyés pour les analyses échouées ou interrompues, les différences vides ou les exécutions à blanc.

Consultez la référence des entrées et sorties de l’Action pour connaître tous les paramètres, champs d’état et chemins des rapports.

Choisir une politique de sévérité

Les workflows GitHub commencent avec fail-on-severity: none. Pour échouer en présence de problèmes de sévérité élevée ou critique détectés par une analyse terminée, modifiez le paramètre de l’étape d’analyse :

fail-on-severity: high

Définissez Codex Security comme vérification de statut obligatoire dans les règles de votre dépôt pour bloquer les fusions lorsque le job de PR échoue. GitHub considère un job ignoré sous condition comme réussi, même pour les vérifications obligatoires. Les PR issues de forks et celles de dependabot[bot] réussissent cette vérification sans analyse. Pour bloquer ces cas, exigez une analyse réussie et terminée.

L’Action suit le résultat de la CLI :

  • Le code de sortie 0 définit scan-status: completed et policy-status: passed.
  • Le code de sortie 1 définit scan-status: completed et policy-status: failed ; l’étape échoue si des problèmes atteignent ou dépassent la sévérité configurée.
  • Le code de sortie 2 ou un processus interrompu définit scan-status: failed et policy-status: not-evaluated ; l’étape échoue.
  • Des rapports obligatoires invalides ou manquants, une modification du code extrait, l’échec de l’envoi des artefacts demandés et les échecs du nettoyage de l’environnement d’exécution font également échouer l’étape.

Une analyse terminée signifie que l’analyse configurée a produit un résultat valide. Les exclusions de périmètre, les investigations différées et les autres notes dans coverage.json ne créent pas de résultat d’analyse distinct et ne permettent pas de contourner la politique de sévérité. La fin de l’analyse ne garantit pas que toutes les vulnérabilités ont été détectées. Consultez coverage.json lors de l’évaluation du résultat.

Exiger une analyse réussie et terminée

Pour une politique plus stricte, ajoutez un contrôle distinct qui s’exécute même si le job d’analyse échoue ou si GitHub l’ignore. Une étape du job d’analyse ne peut pas vérifier un job ignoré, car aucune de ses étapes ne s’exécute.

Dans le workflow de PR, ajoutez cette correspondance outputs au job security existant, au même niveau d’indentation que runs-on et steps :

outputs:
  scan-status: ${{ steps.security.outputs.scan-status }}

Ajoutez ensuite ce job sous jobs, à côté du job security existant :

security-gate:
  name: Codex Security gate
  needs: security
  if: ${{ always() }}
  runs-on: ubuntu-24.04
  steps:
    - name: Require a successful, completed scan
      env:
        SCAN_RESULT: ${{ needs.security.result }}
        SCAN_STATUS: ${{ needs.security.outputs.scan-status }}
      run: test "$SCAN_RESULT" = success && test "$SCAN_STATUS" = completed

Définissez Codex Security gate comme vérification de statut obligatoire pour cette politique. Elle exige à la fois un job d’analyse réussi et scan-status: completed. La vérification de ces deux conditions maintient l’échec du contrôle en cas d’erreur liée à la politique de sévérité, aux rapports ou au nettoyage, même lorsque l’analyse elle-même est terminée.

Avec les exclusions de l’exemple, ce contrôle bloque les PR issues de forks et celles de dependabot[bot]. Il bloque aussi les différences vides et les exécutions à blanc, que l’Action marque comme skipped. Ce contrôle n’analyse pas les PR exclues. Choisissez cette politique uniquement si ces cas doivent empêcher la fusion.

Résoudre les problèmes d’analyse

  • Référence Git inconnue ou différences inattendues : Extrayez la révision de tête de la PR avec fetch-depth: 0.
  • Erreur de démarrage du sandbox : Sur Ubuntu 24.04, installez le package bubblewrap et chargez le profil AppArmor avant l’Action. L’installation du package seule ne charge pas le profil requis.
  • Identifiants manquants : Vérifiez que CODEX_SECURITY_API_KEY est accessible au workflow de confiance et associé à la variable d’environnement OPENAI_API_KEY de l’étape d’analyse.
  • Erreur de configuration de Python : L’Action nécessite Python 3.11 ou une version ultérieure.
  • Notes de couverture : Examinez les exclusions de périmètre et les investigations différées dans coverage.json. Ces notes ne provoquent pas d’échecs d’exécution et ne permettent pas de contourner la politique de sévérité.
  • SARIF manquant : Examinez scan-status, report-status et sarif-upload-ready. Si le fichier SARIF facultatif manque, l’Action émet un avertissement sans modifier le résultat de l’analyse ; les échecs d’envoi des artefacts demandés font tout de même échouer le job.
  • Erreur d’envoi de SARIF : Vérifiez que votre organisation a activé GitHub Code Security pour le dépôt et que le workflow accorde actions: read, contents: read et security-events: write.

Pour chaque commande, option, artefact et champ de sortie, consultez la référence de la CLI. Pour les autres fournisseurs, consultez la présentation de CI/CD.