Exécutez Codex Security dans GitHub Actions

Exécutez Codex Security dans GitHub Actions pour examiner les modifications d’une pull request ou analyser votre dépôt à intervalles réguliers. L’action installe le CLI, enregistre des rapports structurés, ajoute un résumé du job et annote le code source. Commencez par consulter les résultats à titre indicatif. Une fois la couverture et la qualité des analyses évaluées, configurez les règles de blocage.

Préparez le workflow

Vous devez avoir accès à Codex Security pour lancer des analyses. Pour ajouter votre clé API OpenAI, procédez comme suit :

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 clé API OpenAI dans le champ de valeur. Enregistrez le secret.

Les exemples de workflows ci-dessous transmettent automatiquement ce secret à l’action Codex Security. Vous n’avez pas besoin d’inscrire votre clé API dans le fichier du workflow.

Exécutez le workflow uniquement sur des dépôts et des pull requests de confiance. Les analyses utilisent les permissions locales du runner et s’exécutent sans attendre d’approbation. Réservez des jobs distincts aux identifiants sans rapport avec l’analyse et aux étapes de déploiement.

Ajoutez le workflow GitHub Actions

Planifiez l’analyse du dépôt

Le workflow ci-dessous analyse votre branche par défaut chaque lundi à 07 h 23 UTC. Vous pouvez également le lancer manuellement depuis l’onglet Actions de GitHub. Il utilise un runner x64 sous Ubuntu 24.04 hébergé par GitHub et configure automatiquement le bac à sable nécessaire.

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 créez 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 }}

Adaptation du runner : L’action nécessite Node.js 24 et Python 3.11 ou une version ultérieure de Python. Ce runner les fournit. Avant l’analyse, l’étape de configuration du bac à sable installe le paquet bubblewrap et charge le profil AppArmor fourni. Sur ce runner, installer le paquet seul ne suffit pas.

Pour lancer 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 vaut none. Une erreur de l’outil d’analyse ou de production d’un rapport obligatoire fait néanmoins échouer le job.

Pour analyser certains dossiers, ajoutez leurs chemins littéraux, à raison d’un chemin par ligne, dans le bloc with de l’étape d’analyse :

paths: |
  src/api
  src/auth

Les chemins nécessitent scope: repository. Les motifs de type glob ne sont pas interprétés. Pour analyser un diff, omettez paths. Conservez persist-credentials: false et lancez l’analyse immédiatement après la récupération du code.

Analysez les modifications d’une pull request

Réutilisez le même secret et créez le fichier .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 déterminer la base de fusion exacte et analyse les modifications depuis cette base jusqu’au commit de tête récupéré pour la PR. Consultez le contrôle Codex Security dans l’onglet Checks de la PR. Commencez par examiner les problèmes signalés à titre indicatif, puis choisissez une règle de sévérité lorsque vous souhaitez bloquer certaines modifications.

Cet exemple ignore les PR issues de forks et celles ouvertes par dependabot[bot]. Si le job a été ignoré, rien n’atteste qu’une revue de sécurité a eu lieu. Pour inclure les PR de ce bot, supprimez la condition qui l’exclut et configurez également CODEX_SECURITY_API_KEY comme secret pour dependabot[bot]. L’action ne prend en charge ni pull_request_target ni workflow_run.

L’outil d’analyse lit les consignes applicables dans les fichiers SECURITY.md de la copie de travail, y compris les règles modifiées par la PR. Examinez ces modifications en même temps que le code.

Configurez l’accès facultatif à Daybreak

Daybreak est facultatif. Les deux exemples de workflows utilisent gpt-6-sol. Si votre organisation a obtenu l’accès au programme Trusted Access for Cyber, retirez le # devant cyber-access-program dans le bloc with de l’étape d’analyse :

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

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

Le paramètre de sélection du programme accepte également standard. Sans accès à Daybreak, utilisez un modèle accessible avec votre clé API dans le cadre des protections standard et omettez cyber-access-program ou donnez-lui la valeur standard. Sélectionner un modèle ou un programme ne donne pas accès à celui-ci. Consultez les consignes de l’action sur l’accès à Daybreak.

Si un refus ou un blocage de sécurité interrompt l’analyse, l’action échoue, même lorsque fail-on-severity vaut none. Ce paramètre détermine le traitement des problèmes détectés. Il ne s’applique pas aux erreurs de l’outil d’analyse.

Définissez un budget d’analyse facultatif

Les deux exemples de workflows omettent max-cost. Aucun seuil n’interrompt donc l’analyse en fonction de son coût estimé. Pour fixer un seuil, indiquez un montant strictement positif en dollars américains dans le paramètre max-cost. Pour les analyses lancées directement avec le CLI, utilisez --max-cost.

Pour appliquer cette limite, le CLI doit prendre en charge les tarifs du modèle sélectionné. Le seuil repose sur une estimation : les requêtes déjà en cours peuvent porter les dépenses au-delà du montant fixé. Si l’analyse s’arrête au seuil prévu, examinez les problèmes détectés et le fichier coverage.json. Consultez les options de sortie et de configuration des règles pour savoir comment s’applique la limite de coût.

Enregistrez les rapports et envoyez les résultats au format SARIF

Les exemples utilisent upload-artifacts: "true" pour enregistrer des rapports téléchargeables et les conserver pendant sept jours. Les rapports peuvent contenir des extraits de code source, des éléments attestant de vulnérabilités et des indications pour les corriger. Choisissez une durée de conservation et des droits d’accès au dépôt adaptés à votre code. L’action envoie uniquement les rapports validés qui figurent dans sa liste d’autorisation. N’envoyez pas récursivement le contenu du répertoire indiqué par sa sortie results-directory.

L’envoi au format 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 celui-ci :

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

Dans l’un ou l’autre des workflows, ajoutez ensuite cette étape après l’analyse :

- 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 des PR, utilisez category: codex-security-pr afin que chaque périmètre d’analyse ait sa propre catégorie. Conservez id: security dans l’étape d’analyse. Les rapports complets et validés restent disponibles pour l’envoi même si les problèmes détectés font échouer le contrôle de sévérité. Aucun rapport SARIF n’est envoyé si l’analyse échoue, est interrompue, porte sur un diff vide ou s’exécute en mode simulation.

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

Choisissez une règle de sévérité

Les workflows GitHub utilisent initialement fail-on-severity: none. Pour faire échouer l’étape si une analyse terminée signale des problèmes de sévérité élevée ou critique, modifiez le paramètre de l’étape d’analyse :

fail-on-severity: high

Dans les règles du dépôt, rendez le contrôle d’état Codex Security obligatoire pour bloquer les fusions lorsque le job de la PR échoue. GitHub considère qu’un job ignoré en raison d’une condition a réussi, même pour les contrôles obligatoires. Les PR issues de forks et celles de dependabot[bot] passent ce contrôle sans analyse. Pour bloquer la fusion dans ces cas, exigez une analyse terminée avec succès.

L’action tient compte du résultat du 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 la sévérité d’un problème détecté atteint ou dépasse le seuil configuré.
• Le code de sortie 2 ou l’interruption du processus entraîne scan-status: failed et policy-status: not-evaluated. L’étape échoue.
• L’étape échoue également si un rapport obligatoire est invalide ou manquant, si la copie de travail a changé, si l’envoi d’un artefact demandé échoue ou si le nettoyage de l’environnement d’exécution échoue.

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 remarques figurant dans coverage.json ne donnent pas lieu à un état d’analyse distinct et ne permettent pas de contourner la règle 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 pour évaluer le résultat.

Exigez une analyse terminée avec succès

Pour appliquer une règle 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 si ce job a été ignoré, car dans ce cas aucune de ses étapes ne s’exécute.

Dans le workflow des PR, ajoutez ce bloc 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, au même niveau que le 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

Pour appliquer cette règle, rendez le contrôle d’état Codex Security gate obligatoire. Il exige à la fois que le job d’analyse réussisse et que l’analyse ait l’état scan-status: completed. En vérifiant ces deux conditions, le contrôle tient compte des échecs liés à la règle de sévérité, aux rapports et au nettoyage, même si 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 également les diffs vides et les simulations, que l’action marque comme skipped. Le contrôle n’analyse pas les PR exclues. Choisissez cette règle uniquement si ces cas doivent empêcher la fusion.

Résolvez les problèmes d’analyse

• Référence Git inconnue ou diff inattendu : Récupérez le commit de tête de la PR avec fetch-depth: 0.
• Erreur au démarrage du bac à sable : Sur Ubuntu 24.04, installez le paquet bubblewrap et chargez le profil AppArmor avant d’exécuter l’action. La seule installation du paquet ne charge pas le profil requis.
• Identifiants manquants : Vérifiez que le workflow de confiance a accès à CODEX_SECURITY_API_KEY et que ce secret est affecté à 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.
• Remarques sur la couverture : Consultez les exclusions de périmètre et les investigations différées dans coverage.json. Ces remarques ne font pas échouer l’exécution et ne permettent pas de contourner la règle de sévérité.
• Rapport SARIF manquant : Examinez scan-status, report-status et sarif-upload-ready. Si le rapport SARIF facultatif manque, l’action émet un avertissement sans modifier le résultat de l’analyse. En revanche, si l’envoi d’un artefact demandé échoue, le job échoue.
• Erreur d’envoi du rapport SARIF : Vérifiez que votre organisation a activé GitHub Code Security pour le dépôt et que le workflow accorde les permissions actions: read, contents: read et security-events: write.

Pour connaître toutes les commandes, les options, les artefacts et les champs de sortie, consultez la référence du CLI. Pour les autres fournisseurs, consultez la présentation de la CI/CD.