Mit Codex Security in GitLab CI/CD kannst du Änderungen aus Commits und geschützte Branches scannen, Befunde in GitLab Security veröffentlichen und bei Bedarf verifizierte Korrekturen in Merge-Request-Entwürfen vorschlagen.
Der Workflow trennt die Zugangsdaten für den Scan vom Schreibzugriff auf das Repository. Generierte Änderungen müssen vor dem Merge immer von einem Menschen geprüft werden.
Beginne mit einer Pipeline, die nur scannt und die Ergebnisse meldet. Aktiviere die automatische Behebung erst, wenn du den Runner, die Befunde und die Zugriffsbeschränkungen für die Zugangsdaten deines Projekts geprüft hast.
Voraussetzungen
Du brauchst:
- Ein GitLab-Projekt mit einem vertrauenswürdigen Runner, der den Benutzernamensraum der Codex-Sandbox unterstützt.
- Die Rolle Maintainer oder Owner im GitLab-Projekt, damit du die CI/CD-Variablen des Projekts und geschützte Ressourcen konfigurieren kannst.
- Einen OpenAI-API-Schlüssel mit Zugriff auf Codex Security. Organisationen, die API-Schlüssel der OpenAI Platform verwenden, können Trusted Access for Cyber beantragen. Wenn du dich als Einzelperson über ChatGPT authentifizierst, kannst du Trusted Access für dich persönlich beantragen. Bei manchen Konten oder Repositorys ist dieser Zugriff erforderlich, um das gesamte Repository zu scannen.
- GitLab Ultimate ab Version 19.2 für den Import von SARIF-Berichten in Version 2.1.0.
- Den vollständigen Git-Verlauf, damit Jobs für Merge Requests die gemeinsame Basis der Branches ermitteln können.
Das Pipeline-Image installiert Node.js 26, Python 3, Git, rg und die festgelegte Version der Codex Security CLI. Für die automatische Behebung brauchst du außerdem einen vorhandenen Regressionstest und einen Runner, der im Repository definierte Befehle ohne geschützte Zugangsdaten ausführen kann.
Mit einer reinen Scan-Pipeline beginnen
Erstelle in GitLab eine maskierte, verborgene und geschützte CI/CD-Variable namens CODEX_SECURITY_API_KEY. Verwende als Wert einen API-Schlüssel der OpenAI Platform mit Zugriff auf Codex Security und beschränke die Variable auf die Umgebung codex-security/openai. Weitere Informationen findest du in der Dokumentation zu umgebungsspezifischen CI/CD-Variablen.
Füge diese Pipeline zunächst einem Testprojekt hinzu. Sie scannt Änderungen aus Commits in geschützten Merge Requests, die die Voraussetzungen erfüllen. Ein erfolgreicher Berichtsjob veröffentlicht den SARIF-Bericht. Ein separater Prüfjob übernimmt anschließend den Exit-Code des Scanners:
stages:
- security_scan
- security_gate
.codex-security-merge-request:
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID && $CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED == "true" && $CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED == "true"'
codex-security:
extends: .codex-security-merge-request
stage: security_scan
image: node:26-bookworm-slim
environment:
name: codex-security/openai
action: access
variables:
GIT_DEPTH: "0"
before_script:
- apt-get update -qq
- apt-get install -y -qq --no-install-recommends ca-certificates git python3 ripgrep
- npm install --prefix /tmp/codex-security-cli --ignore-scripts --no-audit --no-fund @openai/codex-security@0.8.1
script:
- |
set -eu
test -n "${CODEX_SECURITY_API_KEY:-}"
CODEX_SECURITY_BIN="/tmp/codex-security-cli/node_modules/.bin/codex-security"
RESULTS_DIR="/tmp/codex-security-results-$CI_JOB_ID"
ARTIFACT_DIR="codex-security-artifacts"
BASE_REVISION="$(git merge-base \
"$CI_MERGE_REQUEST_DIFF_BASE_SHA" "$CI_COMMIT_SHA")"
install -d -m 700 "$RESULTS_DIR" "$ARTIFACT_DIR/results"
codex_security_api_key="$CODEX_SECURITY_API_KEY"
unset CODEX_SECURITY_API_KEY
set +e
OPENAI_API_KEY="$codex_security_api_key" \
"$CODEX_SECURITY_BIN" scan . \
--diff "$BASE_REVISION" \
--head "$CI_COMMIT_SHA" \
--auth api-key \
--output-dir "$RESULTS_DIR" \
--fail-on-severity high \
--json
scan_exit="$?"
set -e
unset codex_security_api_key
case "$scan_exit" in
0|1) ;;
*) exit "$scan_exit" ;;
esac
"$CODEX_SECURITY_BIN" export "$RESULTS_DIR" \
--export-format sarif \
--source-root "$CI_PROJECT_DIR" \
--output "$ARTIFACT_DIR/results.sarif"
test -s "$ARTIFACT_DIR/results.sarif"
cp -R "$RESULTS_DIR"/. "$ARTIFACT_DIR/results/"
printf '%s\n' "$scan_exit" > "$ARTIFACT_DIR/scan-exit-code.txt"
exit 0
artifacts:
when: always
access: maintainer
expire_in: 7 days
paths:
- codex-security-artifacts/
reports:
sarif: codex-security-artifacts/results.sarif
codex-security-gate:
extends: .codex-security-merge-request
stage: security_gate
image: alpine:3.20
needs:
- job: codex-security
artifacts: true
script:
- exit "$(cat codex-security-artifacts/scan-exit-code.txt)"
Prüfe jede Änderung an .gitlab-ci.yml, bevor du einen Job mit Zugriff auf Geheimnisse ausführst. Dieses Beispiel enthält weder vollständige Scans noch eine automatische Behebung.
Die Pipeline für den Produktivbetrieb übernehmen
- Lade die vollständige GitLab-Pipeline herunter und speichere sie als
.gitlab-ci.ymlim Stammverzeichnis des Repositorys. Wenn dein Repository bereits eine Pipeline hat, übernimm die Stages, verborgenen Vorlagen und Jobs aus dem Beispiel in die vorhandene Datei. - Behalte die vorhandenen Build-, Test- und Deployment-Stages bei. Falls das Projekt
workflow: rulesverwendet, prüfe, ob diese Regeln die Pipeline-Ereignisse zulassen, bei denen du einen Scan ausführen möchtest.
Das Beispiel fügt die Stages security_scan, security_remediation, security_publish und security_gate hinzu. Für reine Scans mit Berichterstattung brauchst du nur CODEX_SECURITY_API_KEY.
Standardmäßig läuft der Scanjob nur für Merge Requests zwischen geschützten Branches desselben Projekts. Setze CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH=true, um bei Pushes auf den geschützten Standard-Branch und bei manuellen Pipelines auf diesem Branch zu scannen. Setze CODEX_SECURITY_SCHEDULED_DEEP_SCAN=true und lege Zeit- und Kostenbudgets fest, um zeitgesteuerte Tiefenscans auf dem geschützten Standard-Branch zu aktivieren.
Eine Merge-Request-Pipeline kann nur unter folgenden Bedingungen auf geschützte Variablen und Runner zugreifen:
- Du schützt den Quell- und den Ziel-Branch im selben Projekt.
- Das Projekt erlaubt Merge-Request-Pipelines den Zugriff auf geschützte Variablen und Runner.
- Wer die Pipeline startet, darf Änderungen in den Ziel-Branch pushen oder mergen.
Pipelines in Forks und ungeschützte Merge Requests erhalten keine Zugangsdaten für den Scan. Prüfe jede Änderung an .gitlab-ci.yml, bevor du einen Job mit Zugriff auf Geheimnisse ausführst. Auch wenn du eine Variable maskierst und verbirgst, bleibt nicht vertrauenswürdiger CI-Code ein Risiko.
Einen Scan ausführen und Befunde prüfen
Erstelle einen geschützten Merge Request, der die Voraussetzungen erfüllt, oder führe die Pipeline auf dem geschützten Standard-Branch aus. Beginne mit einem kleinen Diff, bevor du einen kostenpflichtigen Scan des gesamten Repositorys startest.
Öffne den Job codex-security und prüfe, ob seine Artefakte folgende Dateien enthalten:
results/scan-manifest.jsonresults/findings.jsonresults/report.mdresults.sarifscan-exit-code.txt
Öffne anschließend den Tab Security der Pipeline. Prüfe die Warnungen zum Import sowie die Kennungen, Schweregrade und Fundstellen der Befunde im Quellcode. Bei Scans auf dem Standard-Branch legt GitLab zusätzlich Schwachstelleneinträge für das Projekt an. Befunde aus Merge Requests erscheinen im Tab Security der Pipeline oder im Sicherheits-Widget des Merge Requests. Für diese Befunde legt GitLab keine projektweiten Schwachstelleneinträge an.
Beschränke den Zugriff auf die Artefakte. Scanergebnisse können Ausschnitte aus verwundbarem Quellcode, Belege für Schwachstellen und Details zu deren Behebung enthalten.
Ein Scanprofil auswählen
Die Pipeline wählt das Profil anhand des Auslösers aus:
| Auslöser | Scanziel | Modus | Reasoning-Aufwand |
|---|---|---|---|
| Geschützter Merge Request innerhalb desselben Projekts | Diff der eingecheckten Änderungen | standard |
low |
| Push auf den geschützten Standard-Branch oder manueller Start auf diesem Branch (nach Aktivierung) | Gesamtes Repository | standard |
high |
| Zeitplan auf dem geschützten Standard-Branch (nach Aktivierung) | Gesamtes Repository | deep |
xhigh |
Scans für Merge Requests liefern gezielte Rückmeldungen zu den eingecheckten Änderungen. Scans auf dem Standard-Branch prüfen den zusammengeführten Stand des Repositorys. Zeitgesteuerte Tiefenscans prüfen das Repository regelmäßig und umfassender. Ein abgeschlossener Diff-Scan gilt nur für die untersuchte Änderung. Er belegt nicht, dass das gesamte Repository frei von Schwachstellen ist.
Der Workflow installiert die CLI außerhalb des Repositorys und ruft sie über ihren absoluten Pfad auf. Der Probelauf vor dem Scan verwendet einen auf den Prozess beschränkten API-Schlüssel. Er startet keinen kostenpflichtigen Scan und prüft weder die API-Authentifizierung noch den Zugriff auf Codex Security, das Kontingent oder die Verfügbarkeit des Modells.
Der Workflow speichert den Scanstatus und die Ergebnisse außerhalb des Worktrees und beschränkt OPENAI_API_KEY auf den Scanprozess. Die CLI erhält nur die ausdrücklich vorgesehenen Umgebungsvariablen, statt alle GitLab-Variablen zu erben. Bei Diff-Scans ermittelt der Workflow die gemeinsame Basis der Branches und bindet den Scan an die geprüften Basis- und Head-Revisionen.
Das Beispiel legt für @openai/codex-security die Version 0.8.1 fest. Teste die Authentifizierung, die Artefakte, den SARIF-Import und die Durchsetzung der Richtlinie erneut, bevor du die Version änderst.
Berichterstattung und Durchsetzung der Richtlinie trennen
GitLab importiert SARIF-Berichte aus einem erfolgreichen Berichtsjob. Die Pipeline veröffentlicht zuerst den Bericht. Anschließend übernimmt ein separater Job namens codex-security-gate den Exit-Code des Scanners.
Der Berichtsjob exportiert Befunde nur bei den Exit-Codes 0 und 1. Bei jedem anderen Exit-Code entfällt der SARIF-Export und die Pipeline wird blockiert. Ein fehlgeschlagener Export blockiert die Pipeline ebenfalls.
Der Berichtsjob gibt Ausführungsfehler und Unterbrechungen weiter. Ist er erfolgreich, übernimmt der abschließende Prüfjob das Ergebnis der Richtlinienprüfung des Scanners:
| Exit-Code | Bedeutung |
|---|---|
0 |
Der Scan wurde abgeschlossen und die Richtlinie ist erfüllt. |
1 |
Der Scan wurde abgeschlossen und hat ein Problem gefunden, dessen Schweregrad den konfigurierten Schwellenwert erreicht oder überschreitet. |
2 |
Beim Scan ist ein Fehler bei der Eingabe, zur Laufzeit, bei der Integrität des Scanziels oder bei einer erforderlichen Ausgabe aufgetreten. |
130 / 143 |
Der Scan wurde unterbrochen oder abgebrochen. |
Das Beispiel übergibt --fail-on-severity high. Befunde mit hohem oder kritischem Schweregrad lassen den Prüfjob daher fehlschlagen. Ohne Schwellenwert geben abgeschlossene Scans standardmäßig den Exit-Code 0 zurück. In results/scan-manifest.json findest du unter scan.scope den konfigurierten Scanumfang und unter scan.review.excludedPaths die Pfade, die beim Vergleich der Befunde ausgeschlossen sind. Hinweise zu weiteren Schritten findest du in results/report.md.
Die Behebung und die Veröffentlichung erfolgen vor der abschließenden Richtlinienprüfung. Für einen Befund, der die Voraussetzungen erfüllt, kann der Workflow einen Merge-Request-Entwurf mit einer verifizierten Korrektur erstellen, selbst wenn die Pipeline später an der Richtlinienprüfung scheitert.
Automatische Behebung mit Verifizierung aktivieren
Die automatische Behebung ist optional und läuft nur in Pipelines auf dem geschützten Standard-Branch. Weder der Codex-Prozess zur Behebung noch die im Repository definierten Prüfbefehle erhalten das GitLab-Projektzugriffstoken oder vom Runner bereitgestellte Zugangsdaten.
Der Workflow geht wie folgt vor:
- Er setzt ein Manifest eines abgeschlossenen Scans für die aktuelle Revision und einen Befund mit dem Schweregrad
highodercriticalvoraus. - Er prüft, ob der konfigurierte Regressionstest vor dem Anwenden des Patches fehlschlägt.
- Er generiert einen Patch und weist Änderungen an CI-Dateien, Dateien mit Zugangsdaten, Binärdateien oder anderen geschützten Dateien zurück.
- Er führt den Regressionstest ohne Zugangsdaten für OpenAI, GitLab, Registrys oder Deployments und ohne Job-Token aus.
- Er ruft
verify-fixauf und erhält als Ergebnisfixed,still_vulnerableoderinconclusive. Der Job veröffentlicht den Patch nur, wennverify-fixden Wertfixedzurückgibt und die Verifizierung den Patch unverändert lässt.
Setze die folgenden geschützten Variablen, um die automatische Behebung zu aktivieren:
- Setze
CODEX_SECURITY_ENABLE_REMEDIATIONauftrue. - Setze
CODEX_SECURITY_VERIFICATION_COMMANDauf den Befehl für einen vorhandenen Regressionstest, der vor der Korrektur den Exit-Code1und danach0zurückgibt. - Optional kannst du mit
CODEX_SECURITY_SETUP_COMMANDeinen Befehl festlegen, der die Abhängigkeiten ohne Benutzereingabe einrichtet.
Wähle einen Regressionstest, der die zugrunde liegende Sicherheitsinvariante unabhängig von der konkreten Implementierung prüft. Prüfe generierte Änderungen an Tests genauso sorgfältig wie generierte Änderungen am Quellcode.
Für Fortgeschrittene: Befehle aus dem Repository isolieren
Die Befehle validate, patch und verify-fix erhalten einen auf den jeweiligen Prozess beschränkten OPENAI_API_KEY und verwenden --auth api-key. Im Repository definierte Setup- und Testbefehle laufen unter einem separaten, unprivilegierten Benutzerkonto in einer beschreibbaren Kopie der von Git verwalteten Quelldateien. Die Kopie enthält weder Git-Metadaten noch Submodulinhalte oder heruntergeladene Artefakte. Setup- und Testbefehle, die .git oder Submodule benötigen, musst du in einem eigens dafür konfigurierten Job ohne Zugangsdaten ausführen.
Nur die Codex-Schritte unter dem Root-Konto können auf den maßgeblichen Checkout oder das benachbarte GitLab-Verzeichnis für Dateivariablen zugreifen. Die bereinigte Umgebung der Kopie enthält nur PATH, HOME, LANG, CI und CI_PROJECT_DIR. Benötigt ein Befehl einen weiteren Wert, der nicht geheim ist, prüfe den Befehl, bevor du die zugehörige Variable zur Liste der zulässigen Variablen hinzufügst. Wenn dein Runner das Benutzerkonto nicht wechseln kann, verlagere die Verifizierung in einen separaten Job ohne Zugangsdaten, bevor du die automatische Behebung aktivierst.
Einen Merge Request als Entwurf veröffentlichen
Erstelle ein GitLab-Projektzugriffstoken mit der Rolle Developer und den Berechtigungsbereichen api und write_repository. Speichere es als geschützte, maskierte und verborgene Variable GITLAB_REMEDIATION_TOKEN und beschränke sie auf die Umgebung codex-security/publish.
Setze CODEX_SECURITY_CREATE_MR=true, um die Veröffentlichung zu aktivieren. Lege außerdem mit der nicht geheimen Variablen CODEX_SECURITY_MR_TEST_COMMAND den projektspezifischen Sicherheitsregressionstest fest, den jeder generierte Branch mit einer Korrektur bestehen muss. Lass diese Variable ungeschützt, damit der generierte, ungeschützte Merge Request den Befehl auslesen kann. Für die Veröffentlichung gilt:
- Der Workflow erhält das Token für den Schreibzugriff auf das Repository, aber keine OpenAI-Zugangsdaten.
- Er erstellt einen Branch namens
codex-security/fix-<finding-hash>. - Er öffnet einen Merge Request als Entwurf. Ist bereits ein entsprechender Entwurf offen, verwendet er diesen erneut, um Duplikate zu vermeiden.
- Er führt den Regressionstest des ungeschützten Branches mit der Korrektur unter einem unprivilegierten Benutzerkonto ohne geschützte Zugangsdaten aus. Die Arbeitskopie enthält nur von Git verwaltete Dateien.
- Er führt die generierte Änderung niemals automatisch zusammen.
Ersetze das Projektzugriffstoken nicht durch CI_JOB_TOKEN. Mit dem Job-Token lässt sich der erforderliche Merge Request nicht erstellen. Prüfe vor dem Merge den vorgeschlagenen Patch, die Nachweise aus der Verifizierung und den Befund.
Optionale Variablen konfigurieren
Konfiguriere nur die Variablen für die Funktionen, die du aktivierst:
| Variable | Wann erforderlich | Standardwert oder Zweck |
|---|---|---|
CODEX_SECURITY_API_KEY |
Bei jedem Scan | Geschützt, maskiert und verborgen. Auf codex-security/openai beschränken. |
CODEX_SECURITY_VERSION |
Beim Upgrade der CLI | Auf 0.8.1 festgelegt. Vor einer Änderung erneut testen. |
CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH |
Für vollständige Scans auf dem Standard-Branch | Standardmäßig deaktiviert. Muss ausdrücklich aktiviert werden. |
CODEX_SECURITY_SCHEDULED_DEEP_SCAN |
Für zeitgesteuerte Tiefenscans | Standardmäßig deaktiviert. Muss ausdrücklich aktiviert werden. |
CODEX_SECURITY_DEEP_MAX_TIME_MINUTES |
Für zeitgesteuerte Tiefenscans | Erforderliches Zeitbudget in Minuten, größer als 0 und kleiner als 480 |
CODEX_SECURITY_DEEP_MAX_COST |
Für zeitgesteuerte Tiefenscans | Erforderlicher Richtwert für die geschätzten Kosten in USD, größer als 0 |
CODEX_SECURITY_ENABLE_REMEDIATION |
Zum Generieren von Patches | Geschützte Variable zur ausdrücklichen Aktivierung. Standardmäßig deaktiviert. |
CODEX_SECURITY_VERIFICATION_COMMAND |
Zum Generieren von Patches | Geschützte Variable für den Regressionstest |
CODEX_SECURITY_SETUP_COMMAND |
Für das optionale Setup zur Behebung | Geschützte Variable für die Installation von Abhängigkeiten |
CODEX_SECURITY_REMEDIATION_EFFORT |
Zum Anpassen des Reasoning-Aufwands bei der Behebung (optional) | high |
CODEX_SECURITY_MAX_CHANGED_FILES |
Zum Begrenzen der Patchgröße (optional) | 8. Zulässiger Bereich: 1 bis 20 |
CODEX_SECURITY_CREATE_MR |
Zum Erstellen eines Merge-Request-Entwurfs | Geschützte Variable zur ausdrücklichen Aktivierung. Standardmäßig deaktiviert. |
GITLAB_REMEDIATION_TOKEN |
Zum Erstellen eines Merge-Request-Entwurfs | Projekttoken mit der Rolle Developer, beschränkt auf codex-security/publish |
CODEX_SECURITY_GITLAB_INTERNAL_URL |
Für die optionale Veröffentlichung auf einer selbst gehosteten Instanz | Vom Runner erreichbare Ursprungsadresse der GitLab-Instanz |
CODEX_SECURITY_MR_TEST_COMMAND |
Zum Veröffentlichen eines Merge-Request-Entwurfs | Erforderlicher, nicht geheimer Befehl für den projektspezifischen Regressionstest |
CODEX_SECURITY_MR_SETUP_COMMAND |
Für das optionale Setup des Branches mit der Korrektur | Nicht geheimer Befehl zum Einrichten der Abhängigkeiten |
GitLab stellt die CI_*-Variablen bereit. Die Pipeline verwaltet CODEX_SECURITY_BIN, CODEX_SECURITY_EFFORT, CODEX_SECURITY_MODE, CODEX_SECURITY_STATE_DIR und CODEX_SECURITY_TARGET. Konfiguriere sie nicht als Projektvariablen. Bei Diff-Scans leitet die CLI die kanonische Identität des Scanziels aus den normalisierten Basis- und Head-Revisionen ab.
Richtlinienprüfung und Kosten anpassen
Nutze Diff-Scans für Rückmeldungen zu Merge Requests, Standardscans des Repositorys für den Standard-Branch und zeitgesteuerte Tiefenscans für umfassendere Prüfungen. Beide Profile für Scans des gesamten Repositorys sind standardmäßig deaktiviert. Ein zeitgesteuerter Tiefenscan erfordert außerdem CODEX_SECURITY_DEEP_MAX_TIME_MINUTES und CODEX_SECURITY_DEEP_MAX_COST. Halte das Zeitbudget der CLI unter dem Job-Timeout von acht Stunden. Wenn du die neue YAML-Konfiguration übernimmst, rechne vorhandene Stundenangaben in Minuten um. Miss Laufzeit und Kosten repräsentativer Scans, bevor du ein Budget festlegst. --max-cost ist ein Richtwert für die geschätzten Kosten. Er setzt keine feste Abrechnungsobergrenze.
In diesem Beispiel schlägt die Richtlinienprüfung bei Befunden mit hohem oder kritischem Schweregrad fehl. Entferne --fail-on-severity high, wenn der Scan Befunde nur melden soll. Prüfe repräsentative Befunde, Scanabdeckung, Kosten und Laufzeit, bevor du einen Schwellenwert festlegst. Die CI/CD-Übersicht erläutert Richtlinien für Schweregrade. Einzelheiten zu den Exit-Codes findest du in der CLI-Referenz.
Wenn ein Job fehlschlägt:
- Fehlende Scanartefakte deuten auf ein Problem mit der Konfiguration oder dem Runner hin.
- Wenn der Scan unerwartet Pfade ausschließt, prüfe den Scanumfang und die Details zur Prüfung in
results/scan-manifest.json. - Wenn in GitLab Befunde fehlen, prüfe, ob der SARIF-Berichtsjob erfolgreich war und ob GitLab den Bericht angenommen hat.
- Wenn die automatische Behebung übersprungen wurde, prüfe den geschützten Branch, das Scanmanifest, den Schweregrad des Befunds, den Prüfbefehl und die Variablen zur Aktivierung der Behebung.
- Wenn die Veröffentlichung fehlschlägt, prüfe die Rolle und die Berechtigungsbereiche des Projekttokens sowie seine Beschränkung auf die vorgesehene Umgebung.
Alle Befehle, Optionen und Artefakte findest du in der Referenz zur Codex Security CLI.