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:
- Öffne in deinem GitHub-Repository Settings → Secrets and variables → Actions.
- Wähle New repository secret.
- Gib als Namen
CODEX_SECURITY_API_KEYein 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.
- Wähle in deinem Repository Add file → Create new file.
- Gib der Datei den Namen
.github/workflows/codex-security-repository.yml. - 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
- Kopiere den Workflow für Pull Requests nach
.github/workflows/codex-security-pr.yml. ErsetzeREPLACE_WITH_REVIEWED_COMMITdurcha98b35d7eef9f85c298c86229445bb64ac427aaf. Das ist der Commit, mit demaction-v0.9.1ausgeliefert wurde. - 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. - Ö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
0setzt die Actionscan-status: completedundpolicy-status: passed. - Bei Exit-Code
1setzt die Actionscan-status: completedundpolicy-status: failed. Der Schritt schlägt fehl, wenn der Schweregrad eines Befunds den konfigurierten Schwellenwert erreicht oder überschreitet. - Bei Exit-Code
2oder einem unterbrochenen Prozess setzt die Actionscan-status: failedundpolicy-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: 0aus. - Fehlende Zugangsdaten: Vergewissere dich, dass der vertrauenswürdige Workflow auf
CODEX_SECURITY_API_KEYzugreifen kann und das Secret im Scan-Schritt der UmgebungsvariablenOPENAI_API_KEYzuweist. - Fehler beim Python-Setup: Die Action benötigt Python ab Version 3.11.
- Fehlende SARIF-Datei: Prüfe
scan-status,report-statusundsarif-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: readundsecurity-events: writeerteilt.
Alle Befehle, Flags, Artefakte und Ausgabefelder findest du in der CLI-Referenz. Informationen zu anderen Anbietern findest du in der CI/CD-Übersicht.