Codex Security in GitLab CI/CD ausführen

Führen Sie Codex Security in GitLab CI/CD aus, um eingecheckte Änderungen und geschützte Branches zu scannen, Ergebnisse in GitLab Security zu veröffentlichen und optional verifizierte Korrekturen in Entwurfs-Merge-Requests vorzuschlagen.

Der Workflow hält Scan-Anmeldedaten von Schreibzugriffen auf das Repository getrennt. Generierte Änderungen müssen vor dem Zusammenführen immer von einem Menschen geprüft werden.

Beginnen Sie mit reinen Scan-Berichten. Aktivieren Sie die Behebung erst, nachdem Sie Runner, Ergebnisse und Anmeldedatengrenzen für Ihr Projekt geprüft haben.

Vorbereitung

Sie benötigen:

• 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 Sie CI/CD-Variablen des Projekts und geschützte Ressourcen konfigurieren können.
• Einen OpenAI API key mit Zugriff auf Codex Security. Organisationen, die Platform API keys verwenden, können Trusted Access for Cyber anfordern. Einzelpersonen, die die ChatGPT-Authentifizierung verwenden, können den persönlichen Trusted-Access-Ablauf nutzen. Bei einigen Konten oder Repositorys ist dieser Zugriff für Scans des vollständigen Repositorys erforderlich.
• GitLab Ultimate 19.2 oder höher für die Aufnahme von SARIF 2.1.0.
• Den vollständigen Git-Verlauf, damit Merge-Request-Jobs die Merge-Basis berechnen können.

Das Pipeline-Image installiert Node.js 26, Python 3, Git, rg und die festgelegte Codex Security CLI. Für die automatisierte Behebung sind zusätzlich ein vorhandener Regressionstest und ein Runner erforderlich, der vom Repository gesteuerte Befehle ohne geschützte Anmeldedaten ausführen kann.

Mit einer reinen Scan-Pipeline beginnen

Erstellen Sie eine maskierte, ausgeblendete und geschützte GitLab-CI/CD-Variable namens CODEX_SECURITY_API_KEY. Verwenden Sie einen OpenAI Platform API key mit Zugriff auf Codex Security und legen Sie dessen Umgebungsbereich auf codex-security/openai fest. Weitere Informationen finden Sie unter umgebungsbezogene CI/CD-Variablen.

Fügen Sie diese minimale Pipeline zunächst einem Testprojekt hinzu. Sie scannt eingecheckte Änderungen in geeigneten geschützten Merge Requests, veröffentlicht SARIF aus einem erfolgreichen Berichtsjob und stellt das Scanner-Ergebnis in einer separaten Prüfung wieder her:

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:
    - npm install --prefix /tmp/codex-security-cli --ignore-scripts --no-audit --no-fund @openai/codex-security@0.1.20
  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" \
          --json
      scan_exit="$?"
      set -e
      unset codex_security_api_key

      case "$scan_exit" in
        0|1|2) ;;
        *) 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üfen Sie jede Änderung an .gitlab-ci.yml, bevor Sie einen Job mit Geheimnissen ausführen. Das Minimalbeispiel lässt vollständige Scans und die Behebung bewusst aus.

Die Produktions-Pipeline übernehmen

1. Laden Sie die vollständige GitLab-Pipeline herunter und speichern Sie sie als .gitlab-ci.yml im Stammverzeichnis des Repositorys. Wenn Ihr Repository bereits über eine Pipeline verfügt, führen Sie die Stages, ausgeblendeten Vorlagen und Jobs des Beispiels mit der vorhandenen Datei zusammen.
2. Behalten Sie vorhandene Build-, Test- und Bereitstellungs-Stages bei. Falls das Projekt workflow: rules verwendet, vergewissern Sie sich, dass dadurch die Pipeline-Ereignisse zugelassen werden, die Sie scannen möchten.

Das Beispiel fügt die Stages security_scan, security_remediation, security_publish und security_gate hinzu. Für reine Scan-Berichte ist nur CODEX_SECURITY_API_KEY erforderlich.

Der Scan-Job wird standardmäßig nur für projektinterne Merge Requests zwischen geschützten Branches ausgeführt. Legen Sie CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH=true fest, um Pushes auf den geschützten Standard-Branch und manuelle Pipelines zu scannen. Legen Sie CODEX_SECURITY_SCHEDULED_DEEP_SCAN=true fest und konfigurieren Sie explizite Zeit- und Kostenbudgets, um geplante 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:

• Sie schützen den Quell- und Ziel-Branch im selben Projekt.
• Das Projekt erlaubt Merge-Request-Pipelines den Zugriff auf geschützte Variablen und Runner.
• Der Benutzer, der die Pipeline startet, kann Änderungen auf den Ziel-Branch pushen oder darin zusammenführen.

Pipelines aus Forks und ungeschützte Merge Requests erhalten keine Scan-Anmeldedaten. Prüfen Sie jede Änderung an .gitlab-ci.yml, bevor Sie einen Job mit Geheimnissen ausführen. Durch das Maskieren und Ausblenden einer Variablen wird nicht vertrauenswürdiger CI-Code nicht sicher.

Einen Scan ausführen und Ergebnisse prüfen

Erstellen Sie einen geeigneten geschützten Merge Request oder führen Sie die Pipeline auf dem geschützten Standard-Branch aus. Beginnen Sie mit einem kleinen Diff, bevor Sie einen kostenpflichtigen Scan des vollständigen Repositorys ausführen.

Öffnen Sie den Job codex-security und vergewissern Sie sich, dass dessen Artefakte Folgendes enthalten:

• scan-manifest.json
• findings.json
• coverage.json
• results.sarif
• scan-exit-code.txt

Öffnen Sie anschließend die Registerkarte Security der Pipeline, prüfen Sie die Aufnahmewarnungen und bestätigen Sie Ergebniskennungen, Schweregrade und Quellpositionen. Scans des Standard-Branches erstellen außerdem Schwachstelleneinträge für das Projekt. Ergebnisse aus Merge Requests werden auf der Registerkarte Security der Pipeline oder im Sicherheits-Widget des Merge Requests angezeigt, erstellen jedoch keine projektweiten Schwachstelleneinträge.

Beschränken Sie den Zugriff auf Artefakte, da Scan-Ergebnisse anfällige Quellcodeausschnitte, Belege und Details zur Behebung enthalten können.

Ein Scan-Profil auswählen

Die Pipeline wählt anhand des Auslösers ein Profil aus:

Merge-Request-Scans konzentrieren das Feedback auf die eingecheckte Änderung. Scans des Standard-Branches prüfen das integrierte Repository. Geplante Tiefenscans bieten eine breitere regelmäßige Abdeckung. Ein abgeschlossener Diff-Scan gilt nur für diese Änderung und weist nicht nach, dass das gesamte Repository frei von Problemen ist.

Der Workflow installiert die CLI außerhalb des Repositorys und führt sie über einen absoluten Pfad aus. Die Dry-Run-Vorabprüfung verwendet den prozessbezogenen API key, startet jedoch keinen kostenpflichtigen Scan und überprüft weder API-Authentifizierung noch Zugriff auf Codex Security, Kontingent oder Modellverfügbarkeit.

Der Workflow schreibt Scan-Status und Ergebnisse außerhalb des Arbeitsbaums und beschränkt OPENAI_API_KEY auf den Scan-Prozess. Die CLI erhält eine kleine, explizit festgelegte Umgebung, statt alle GitLab-Variablen zu erben. Bei Diff-Scans berechnet der Workflow die Merge-Basis und bindet den Scan an die geprüften Basis- und Head-Revisionen.

Das Beispiel legt @openai/codex-security auf 0.1.20 fest. Testen Sie Authentifizierung, Artefakte, SARIF-Aufnahme und Richtlinienprüfung erneut, bevor Sie diese Festlegung ändern.

Berichterstellung von der Richtliniendurchsetzung trennen

GitLab nimmt SARIF aus einem erfolgreichen Berichtsjob auf. Die Pipeline veröffentlicht zunächst den Bericht und stellt den Exit-Status des Scanners in einem separaten Job codex-security-gate wieder her.

Der Berichtsjob akzeptiert Ergebnisse mit den Exit-Codes 0 und 1. Er akzeptiert den Exit-Code 2 nur, wenn das Scan-Manifest belegt, dass der Scan abgeschlossen wurde, die Abdeckung explizit partial lautet und ein nicht leerer SARIF-Bericht vorhanden ist. Andere Laufzeit-, Konfigurations- oder Exportfehler bleiben blockierend.

Die abschließende Prüfung behält diese Scanner-Exit-Codes bei:

Das Beispiel lässt Exit 2 vorübergehend zu, während Sie die partielle Abdeckung kalibrieren. Entfernen Sie diese Ausnahme, wenn eine unvollständige Abdeckung die Pipeline blockieren muss.

Behebung und Veröffentlichung werden vor der abschließenden Richtlinienprüfung ausgeführt. Ein geeignetes Ergebnis kann einen verifizierten Entwurfs-Merge-Request erzeugen, selbst wenn die Prüfung später die Pipeline fehlschlagen lässt.

Verifizierte Behebung aktivieren

Die automatisierte Behebung ist optional und wird nur für Pipelines des geschützten Standard-Branches ausgeführt. Der Codex-Behebungsprozess und die vom Repository gesteuerten Verifizierungsbefehle erhalten weder das GitLab-Projektzugriffstoken noch vom Runner bereitgestellte Anmeldedaten.

Der Sicherheitsvertrag besteht aus drei Teilen: Vom Repository gesteuerte Befehle erhalten niemals OpenAI- oder GitLab-Anmeldedaten, nur der Veröffentlichungsjob erhält Schreibzugriff auf das Repository und jede generierte Änderung bleibt ein Entwurf, bis sie von einem Menschen geprüft und zusammengeführt wird.

Der Workflow:

1. Erfordert eine vollständige Scan-Abdeckung und ein Ergebnis mit dem Schweregrad high oder critical.
2. Bestätigt, dass der konfigurierte Regressionstest vor dem Patchen fehlschlägt.
3. Generiert einen gezielten Patch und lehnt Änderungen an CI-, Anmeldedaten-, Binär- oder anderen geschützten Dateien ab.
4. Führt den Regressionstest ohne OpenAI-, GitLab-, Registry-, Bereitstellungs- oder Job-Token-Anmeldedaten aus.
5. Verwendet verify-fix, um fixed, still_vulnerable oder inconclusive zurückzugeben. Der Job veröffentlicht einen Patch nur, wenn verify-fix den Wert fixed zurückgibt und der Verifizierungsprozess den Patch unverändert lässt.

Legen Sie diese geschützten Variablen fest, um die Behebung zu aktivieren:

• Setzen Sie CODEX_SECURITY_ENABLE_REMEDIATION auf true.
• Setzen Sie CODEX_SECURITY_VERIFICATION_COMMAND auf einen vorhandenen Regressionstest, der vor der Korrektur mit 1 und danach mit 0 beendet wird.
• Optional können Sie CODEX_SECURITY_SETUP_COMMAND auf einen nicht interaktiven Befehl zur Einrichtung von Abhängigkeiten setzen.

Wählen Sie einen Regressionstest, der die zugrunde liegende Sicherheitsinvariante prüft und nicht eine bestimmte Implementierung. Prüfen Sie generierte Test- und Quellcodeänderungen ebenso sorgfältig.

Einen Entwurfs-Merge-Request veröffentlichen

Erstellen Sie ein GitLab-Projektzugriffstoken mit der Rolle Developer und den Berechtigungsbereichen api und write_repository. Speichern Sie es als geschützte, maskierte und ausgeblendete Variable GITLAB_REMEDIATION_TOKEN, die nur auf die Umgebung codex-security/publish beschränkt ist.

Setzen Sie CODEX_SECURITY_CREATE_MR=true, um die Veröffentlichung zu aktivieren. Setzen Sie außerdem das nicht geheime CODEX_SECURITY_MR_TEST_COMMAND auf den projektspezifischen Sicherheitsregressionstest, den jeder generierte Behebungs-Branch bestehen muss. Lassen Sie diese Variable ungeschützt, damit der generierte ungeschützte Merge Request den Befehl lesen kann. Der Veröffentlichungsworkflow:

• Erhält das Token für Schreibzugriffe auf das Repository, aber keine OpenAI-Anmeldedaten.
• Erstellt einen Branch codex-security/fix-<finding-hash>.
• Öffnet einen Entwurfs-Merge-Request und verwendet einen bereits vorhandenen offenen Entwurf erneut, statt ein Duplikat zu erstellen.
• Führt den Regressionstest des ungeschützten Behebungs-Branches als unprivilegierter Benutzer in einer Kopie aus, die nur nachverfolgte Dateien und keine geschützten Anmeldedaten enthält.
• Führt die generierte Änderung niemals automatisch zusammen.

Ersetzen Sie das Projektzugriffstoken nicht durch CI_JOB_TOKEN. Dieses kann den erforderlichen Vorgang zum Erstellen eines Merge Requests nicht ausführen. Prüfen Sie den vorgeschlagenen Patch, die Verifizierungsbelege und das Ergebnis vor dem Zusammenführen.

Optionale Variablen konfigurieren

Konfigurieren Sie nur die Variablen, die für die von Ihnen aktivierten Funktionen erforderlich sind:

GitLab stellt die Variablen CI_* bereit. Die Pipeline verwaltet CODEX_SECURITY_BIN, CODEX_SECURITY_EFFORT, CODEX_SECURITY_MODE, CODEX_SECURITY_STATE_DIR und CODEX_SECURITY_TARGET; konfigurieren Sie sie nicht als Projektvariablen. Bei Diff-Scans leitet die CLI die kanonische Zielidentität aus den normalisierten Basis- und Head-Revisionen ab.

Durchsetzung und Kosten abstimmen

Verwenden Sie fokussierte Diff-Scans für Feedback zu Merge Requests, Standard-Repository-Scans für den Standard-Branch und geplante Tiefenscans für eine breitere Abdeckung. Beide Profile für vollständige Repositorys sind standardmäßig deaktiviert. Ein geplanter Tiefenscan erfordert außerdem CODEX_SECURITY_DEEP_MAX_TIME_HOURS und CODEX_SECURITY_DEEP_MAX_COST; halten Sie das Zeitbudget der CLI unter dem achtstündigen Timeout des Jobs. Messen Sie repräsentative Läufe, bevor Sie ein Budget festlegen. Behandeln Sie --max-cost als Schutzgrenze für geschätzte Kosten und nicht als feste Abrechnungsobergrenze.

Beginnen Sie mit reinen Berichts-Scans. Fügen Sie --fail-on-severity hinzu, nachdem Ihr Team repräsentative Ergebnisse, Abdeckung, Kosten und Laufzeit geprüft hat. Weitere Informationen zu Schweregradrichtlinien und Exit-Code-Details finden Sie unter Codex Security in CI ausführen.

Wenn ein Job fehlschlägt:

• Fehlende Scan-Artefakte weisen auf ein Konfigurations- oder Runner-Problem hin.
• Bei vorhandenen Artefakten mit partieller Abdeckung muss coverage.json geprüft werden.
• Bei fehlenden GitLab-Ergebnissen müssen Sie prüfen, ob der SARIF-Berichtsjob erfolgreich war und GitLab den Bericht akzeptiert hat.
• Bei übersprungener Behebung müssen der geschützte Branch, die vollständige Abdeckung, der Schweregrad des Ergebnisses, der Verifizierungsbefehl und die Aktivierungsvariablen geprüft werden.
• Bei Veröffentlichungsfehlern müssen Rolle, Berechtigungsbereiche und Umgebungseinschränkung des Projekttokens geprüft werden.

Informationen zu allen Befehlen, Flags und Artefakten finden Sie in der Referenz zur Codex Security CLI.