Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Codex Security in GitHub Actions ausführen

Scanne Pull Requests und Repositorys mit der Codex Security Action, speichere Berichte, lade SARIF-Dateien hoch und lege fest, wann ein Scan das Zusammenführen von Änderungen blockiert.

Mit Codex Security in GitHub Actions kannst du Änderungen in Pull Requests prüfen oder dein Repository nach einem Zeitplan scannen. Die Action installiert die CLI, speichert strukturierte Berichte, erstellt eine Jobzusammenfassung und markiert betroffene Stellen im Quellcode. Lass dir die Befunde zunächst als Hinweise anzeigen. Prüfe die Abdeckung und die Qualität der Scans, bevor du festlegst, welche Befunde Änderungen blockieren sollen.

Workflow vorbereiten

Für die Scans brauchst du Zugriff auf Codex Security. So hinterlegst du deinen OpenAI-API-Schlüssel:

  1. Öffne in deinem GitHub-Repository Settings → Secrets and variables → Actions.
  2. Wähle New repository secret.
  3. Gib als Namen CODEX_SECURITY_API_KEY ein und füge deinen OpenAI-API-Schlüssel als Wert ein. Speichere das Secret.

Die folgenden Workflows übergeben dieses Secret automatisch an die Codex Security Action. Du brauchst deinen API-Schlüssel nicht in die Workflow-Datei einzutragen.

Führe den Workflow nur für Repositorys und Pull Requests aus, denen du vertraust. Scans verwenden die lokalen Berechtigungen des Runners und warten nicht auf eine Genehmigung. Verwende für andere Zugangsdaten und Deployment-Schritte separate Jobs.

Workflow für GitHub Actions hinzufügen

Scankosten: Diese Workflows verwenden deinen API-Schlüssel und können Kosten verursachen. Im Beispiel für zeitgesteuerte Scans ist max-cost nicht gesetzt. Im PR-Workflow gilt für die geschätzten Kosten ein Schwellenwert von 5 USD pro Scan. Durch bereits laufende Anfragen können die Kosten diesen Schwellenwert überschreiten. Weitere Informationen findest du im Abschnitt Optionales Scanbudget festlegen.

Repository nach einem Zeitplan scannen

Der folgende Workflow scannt deinen Standard-Branch jeden Montag um 07:23 Uhr UTC. Du kannst ihn auch manuell über den GitHub-Tab Actions starten. Der Workflow verwendet einen von GitHub gehosteten x64-Runner mit Ubuntu 24.04 und richtet die erforderliche Sandbox automatisch ein.

  1. Wähle in deinem Repository Add file → Create new file.
  2. Gib der Datei den Namen .github/workflows/codex-security-repository.yml.
  3. Füge den folgenden Workflow ein und speichere ihn mit einem Commit auf deinem Standard-Branch.
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: 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@a98b35d7eef9f85c298c86229445bb64ac427aaf # action-v0.9.1
        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 }}

Die Action prüft die Codex-Sandbox, bevor sie den API-Schlüssel für den Scan verwendet. Auf einer von GitHub gehosteten VM mit Ubuntu 24.04 installiert sie die erforderlichen Pakete und lädt bei Bedarf das AppArmor-Profil. Stelle auf selbst gehosteten Runnern und in Job-Containern eine funktionsfähige Sandbox, Linux für x64, Node.js 24 und Python ab Version 3.11 bereit.

Um den Workflow manuell zu starten, öffne Actions → Codex Security repository → Run workflow. Öffne einen abgeschlossenen Lauf, um die Zusammenfassung, die Anmerkungen im Quellcode und die herunterladbaren Berichte einzusehen.

Befunde erscheinen nur im Bericht, weil fail-on-severity auf none steht. Bei Fehlern im Scanner oder bei der Erstellung der erforderlichen Berichte schlägt der Job weiterhin fehl.

Um ausgewählte Ordner zu scannen, trage im with-Block des Scan-Schritts jeden Pfad in einer eigenen Zeile genau so ein, wie er im Repository lautet:

paths: |
  src/api
  src/auth

Pfadangaben setzen scope: repository voraus. Glob-Muster werden nicht aufgelöst. Lass paths bei Diff-Scans weg. Behalte persist-credentials: false bei und führe den Scan unmittelbar nach dem Checkout aus.

Änderungen in Pull Requests scannen

  1. Kopiere den Workflow für Pull Requests nach .github/workflows/codex-security-pr.yml. Ersetze REPLACE_WITH_REVIEWED_COMMIT durch a98b35d7eef9f85c298c86229445bb64ac427aaf. Das ist der Commit, mit dem action-v0.9.1 ausgeliefert wurde.
  2. Wähle ein Modell, auf das dein API-Schlüssel Zugriff hat. Die Vorlage legt für die geschätzten Scankosten einen Schwellenwert von 5 USD fest. Der Workflow schlägt bei Befunden mit hohem oder kritischem Schweregrad fehl. Wenn Befunde nur als Hinweise erscheinen sollen, verwende fail-on-severity: none.
  3. Öffne einen PR aus einem Branch desselben Repositorys. Öffne unter Checks den Check Scan changes, um die Ergebnisse zu prüfen. Der Workflow meldet außerdem einen Check, dessen Name den Ziel-Branch enthält, zum Beispiel Codex Security / main.

Der Workflow prüft vor dem Scan den PR-Head, den Ziel-Branch und den aktuellen Stand der Basisrevision. Bevor er das Ergebnis akzeptiert, prüft er alle drei erneut. Wenn der Basis-Branch inzwischen neue Commits enthält, aktualisiere den PR-Branch, um einen neuen Scan auszulösen. Damit diese Prüfung beim Zusammenführen verbindlich ist, beachte die Anforderungen an den Branch-Schutz und die Aktualität des Scans.

Der Scan-Job überspringt PRs aus Forks. Diese PRs können den erforderlichen Check dieses Workflows daher nicht bestehen. Um PRs von Dependabot zu scannen, hinterlege CODEX_SECURITY_API_KEY zusätzlich als Dependabot-Secret.

Der Scanner liest die für den Scan geltenden Vorgaben aus SECURITY.md im Checkout. Dazu gehören auch Änderungen an diesen Vorgaben, die der PR enthält. Prüfe sie zusammen mit den Codeänderungen.

Optionalen Daybreak-Zugriff konfigurieren

Wenn deine Organisation für Trusted Access for Cyber zugelassen ist, wähle im with-Block des Scan-Schritts das Programm und ein kompatibles Modell aus:

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

Verwende einen API-Schlüssel aus einem Projekt, das für Daybreak Blue freigeschaltet ist und Zugriff auf gpt-6-sol hat.

Für Projekte mit Red-Zugriff ist auch der Wert daybreak_red zulässig. Um die standardmäßigen Schutzmaßnahmen zu verwenden, setze cyber-access-program auf standard. Lässt du die Einstellung weg, gelten die Standardwerte der CLI. Weitere Informationen findest du in den Hinweisen zum Daybreak-Zugriff in der Dokumentation der Action.

Bricht der Scan ab, weil eine Anfrage abgelehnt oder aus Sicherheitsgründen blockiert wurde, schlägt die Action fehl. Das gilt auch, wenn fail-on-severity auf none steht. Diese Einstellung regelt den Umgang mit Befunden. Auf Scannerfehler hat sie keinen Einfluss.

Optionales Scanbudget festlegen

Im zeitgesteuerten Workflow ist max-cost nicht gesetzt. Um einen Schwellenwert festzulegen, gib für max-cost einen positiven Betrag in USD an. Für Scans, die du direkt über die CLI startest, verwende --max-cost.

Damit die Kostenbegrenzung funktioniert, muss die CLI die Preisinformationen für das gewählte Modell unterstützen. Durch bereits laufende Anfragen können die Kosten den geschätzten Schwellenwert überschreiten. Prüfe die Befunde und scan-manifest.json, wenn ein Scan am Schwellenwert stoppt. Wie die Kostenbegrenzung funktioniert, erfährst du im Abschnitt Ausgabe- und Richtlinienoptionen.

Berichte speichern und SARIF-Dateien hochladen

Verwende upload-artifacts: "true", um Berichte zum Download zu speichern. Die Aufbewahrungsdauer beträgt standardmäßig sieben Tage. Berichte können Auszüge aus dem Quellcode, Belege für Schwachstellen und Angaben zu deren Behebung enthalten. Wähle eine Aufbewahrungsdauer und Zugriffsrechte für das Repository, die für deinen Code angemessen sind. Die Action lädt nur validierte Berichte hoch, die auf ihrer Zulassungsliste stehen. Lade das über results-directory ausgegebene Verzeichnis nicht rekursiv hoch.

Der SARIF-Upload ist optional. Aktiviere für private oder interne Repositorys vor dem Upload GitHub Code Security. Für den SARIF-Upload benötigt der Scan-Job folgende Berechtigungen:

permissions:
  contents: read
  security-events: write
  actions: read # Required for private repositories
  pull-requests: read # Required only in the PR workflow

Füge dann im jeweiligen Workflow nach dem Scan diesen Schritt hinzu:

- 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

Verwende im PR-Workflow category: codex-security-pr, damit jeder Scanumfang eine eigene Kategorie hat. Behalte id: security im Scan-Schritt bei. Vollständige, validierte Berichte stehen auch dann zum Upload bereit, wenn der Schritt aufgrund des Schweregrads der Befunde fehlschlägt. Bei fehlgeschlagenen oder unterbrochenen Scans, leeren Diffs und Testläufen wird keine SARIF-Datei hochgeladen.

Alle Einstellungen, Statusfelder und Berichtspfade findest du in der Referenz zu den Ein- und Ausgaben der Action.

Richtlinie für den Schweregrad festlegen

Der zeitgesteuerte Workflow verwendet zunächst fail-on-severity: none. Soll der Scan-Schritt fehlschlagen, wenn ein abgeschlossener Scan Befunde mit hohem oder kritischem Schweregrad meldet, verwende die Einstellung aus dem PR-Workflow:

fail-on-severity: high

Lege für jeden geschützten Ziel-Branch den zugehörigen Check der GitHub Actions App als erforderlich fest, zum Beispiel Codex Security / main für main. GitHub wertet einen aufgrund einer Bedingung übersprungenen Job als erfolgreich. Der erforderliche Check des Workflows prüft zusätzlich, ob der Scan-Job ausgeführt wurde. Er akzeptiert einen abgeschlossenen Scan oder einen nachweislich leeren Diff. Um auch leere Diffs zu blockieren, setze einen erfolgreichen, abgeschlossenen Scan voraus.

Die Action übernimmt das Ergebnis der CLI:

  • Bei Exit-Code 0 setzt die Action scan-status: completed und policy-status: passed.
  • Bei Exit-Code 1 setzt die Action scan-status: completed und policy-status: failed. Der Schritt schlägt fehl, wenn der Schweregrad eines Befunds den konfigurierten Schwellenwert erreicht oder überschreitet.
  • Bei Exit-Code 2 oder einem unterbrochenen Prozess setzt die Action scan-status: failed und policy-status: not-evaluated. Der Schritt schlägt fehl.
  • Der Schritt schlägt auch fehl, wenn erforderliche Berichte ungültig sind oder fehlen, sich der Checkout geändert hat, angeforderte Artefakte nicht hochgeladen werden können oder das Bereinigen der Laufzeitumgebung fehlschlägt.

Einen erfolgreichen, abgeschlossenen Scan voraussetzen

Für eine strengere Richtlinie füge einen separaten Prüfjob hinzu, der auch dann läuft, wenn der Scan-Job fehlschlägt oder GitHub ihn überspringt. Ein Schritt innerhalb des Scan-Jobs kann einen übersprungenen Job nicht prüfen, da in diesem Fall keiner seiner Schritte läuft.

Der PR-Workflow stellt den Scanstatus über den Job security bereit:

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

Füge anschließend unter jobs den folgenden Job auf derselben Ebene wie den vorhandenen Job security hinzu:

security-gate:
  name: ${{ github.event.action == 'edited' && github.event.changes.base == null && 'metadata / ' || '' }}Codex Security gate / ${{ github.event.pull_request.base.ref }}
  needs: security
  if: always() && (github.event.action != 'edited' || github.event.changes.base != null)
  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

Lege für jeden geschützten Branch zusätzlich zum Scan-Check auch den zugehörigen Prüfjob als erforderlich fest. Für main sind das Codex Security gate / main und Codex Security / main. Der Prüfjob setzt sowohl einen erfolgreichen Scan-Job als auch scan-status: completed voraus. So blockiert er das Zusammenführen auch dann, wenn der Scan selbst abgeschlossen wurde, aber die Richtlinie für den Schweregrad verletzt wurde, die Berichterstellung fehlgeschlagen ist oder beim Bereinigen ein Fehler aufgetreten ist.

Mit den Ausschlüssen aus dem Beispiel blockiert der Prüfjob PRs aus Forks. Er blockiert auch leere Diffs und Testläufe, die die Action als skipped kennzeichnet. Der Prüfjob scannt ausgeschlossene PRs nicht. Wähle diese Richtlinie nur, wenn das Zusammenführen in diesen Fällen blockiert werden soll.

Scanfehler beheben

  • Unbekannte Git-Referenz oder unerwarteter Diff: Checke den PR-Head mit fetch-depth: 0 aus.
  • Fehlende Zugangsdaten: Vergewissere dich, dass der vertrauenswürdige Workflow auf CODEX_SECURITY_API_KEY zugreifen kann und das Secret im Scan-Schritt der Umgebungsvariablen OPENAI_API_KEY zuweist.
  • Fehler beim Python-Setup: Die Action benötigt Python ab Version 3.11.
  • Fehlende SARIF-Datei: Prüfe scan-status, report-status und sarif-upload-ready. Fehlt die optionale SARIF-Datei, gibt die Action eine Warnung aus. Das Scanergebnis bleibt gleich. Schlägt der Upload angeforderter Artefakte fehl, schlägt weiterhin auch der Job fehl.
  • Fehler beim SARIF-Upload: Vergewissere dich, dass deine Organisation GitHub Code Security für das Repository aktiviert hat und der Workflow die Berechtigungen actions: read, contents: read und security-events: write erteilt.

Alle Befehle, Flags, Artefakte und Ausgabefelder findest du in der CLI-Referenz. Informationen zu anderen Anbietern findest du in der CI/CD-Übersicht.