ChatGPT-Dokumentation
Deutsch
Kontakt goolvyouyou@gmail.com

Codex Security in GitHub Actions ausführen

Scannen Sie Pull Requests und Repositorys mit der Codex Security Action, speichern Sie Berichte, laden Sie SARIF hoch und konfigurieren Sie die Richtliniendurchsetzung.

Führen Sie Codex Security in GitHub Actions aus, um Änderungen aus Pull Requests zu prüfen oder Ihr Repository nach einem Zeitplan zu scannen. Die Action installiert die CLI, speichert strukturierte Berichte und fügt eine Jobzusammenfassung sowie Quellcodeannotationen hinzu. Beginnen Sie mit Ergebnissen, die nur als Hinweise dienen, und konfigurieren Sie die Durchsetzung, nachdem Sie Abdeckung und Scanqualität geprüft haben.

Den Workflow vorbereiten

Für Scans benötigen Sie Zugriff auf Codex Security. So fügen Sie Ihren OpenAI API key hinzu:

  1. Öffnen Sie in Ihrem GitHub-Repository Settings → Secrets and variables → Actions.
  2. Wählen Sie New repository secret.
  3. Geben Sie CODEX_SECURITY_API_KEY als Namen ein und fügen Sie Ihren OpenAI API key als Wert ein. Speichern Sie das Secret.

Die folgenden Workflowbeispiele übergeben dieses Secret automatisch an die Codex Security Action. Sie müssen Ihren API key nicht in die Workflowdatei eintragen.

Führen Sie den Workflow nur für Repositorys und Pull Requests aus, denen Sie vertrauen. Scans verwenden die lokalen Berechtigungen des Runners und warten nicht auf eine Genehmigung. Verwenden Sie separate Jobs für nicht zugehörige Zugangsdaten und Bereitstellungsschritte.

Den GitHub Actions-Workflow hinzufügen

Das Repository nach einem Zeitplan scannen

Der folgende Workflow scannt Ihren Standardbranch jeden Montag um 07:23 UTC. Sie können ihn auch manuell über die Registerkarte Actions in GitHub ausführen. Er verwendet einen von GitHub gehosteten Ubuntu 24.04-Runner mit x64-Architektur und richtet die erforderliche Sandbox automatisch ein.

  1. Wählen Sie in Ihrem Repository Add file → Create new file.
  2. Nennen Sie die Datei .github/workflows/codex-security-repository.yml.
  3. Fügen Sie den folgenden Workflow ein und committen Sie ihn in Ihren Standardbranch.
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 }}

Den Runner anpassen: Die Action benötigt Node.js 24 und Python 3.11 oder höher, was dieser Runner bereitstellt. Die Sandboxeinrichtung installiert das Paket bubblewrap und lädt vor dem Scan das mitgelieferte AppArmor-Profil. Die Installation des Pakets allein reicht auf diesem Runner nicht aus.

Um den Workflow manuell auszuführen, öffnen Sie Actions → Codex Security repository → Run workflow. Öffnen Sie einen abgeschlossenen Lauf, um die Zusammenfassung, Annotationen und herunterladbaren Berichte zu prüfen.

Befunde werden nur gemeldet, da fail-on-severity auf none gesetzt ist. Fehler des Scanners und bei der erforderlichen Berichterstellung lassen den Job weiterhin fehlschlagen.

Um ausgewählte Ordner zu scannen, fügen Sie durch Zeilenumbrüche getrennte wörtliche Pfade in den Block with des Scanschritts ein:

paths: |
  src/api
  src/auth

Pfade erfordern scope: repository; Glob-Muster werden nicht expandiert. Lassen Sie bei Diff-Scans paths weg. Behalten Sie persist-credentials: false bei und führen Sie den Scan unmittelbar nach dem Checkout aus.

Änderungen aus Pull Requests scannen

Erstellen Sie unter Verwendung desselben Secrets .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 }}

Öffnen oder aktualisieren Sie einen PR aus einem Branch desselben Repositorys. Die Action verwendet den vollständigen Verlauf, um die exakte Merge-Basis zu ermitteln, und scannt Änderungen bis zum ausgecheckten PR-Head. Sehen Sie sich die Prüfung Codex Security im PR unter Checks an. Beginnen Sie mit Befunden, die nur als Hinweise dienen, und wählen Sie eine Schweregradrichtlinie, sobald Sie Änderungen auf dieser Grundlage zulassen oder blockieren möchten.

Dieses Beispiel überspringt Fork-PRs und PRs, die von dependabot[bot] geöffnet wurden. Ein übersprungener Job ist kein Nachweis einer Sicherheitsprüfung. Um diese Bot-PRs einzubeziehen, entfernen Sie den Ausschluss des Akteurs und konfigurieren Sie CODEX_SECURITY_API_KEY zusätzlich als Secret für dependabot[bot]. Die Action unterstützt weder pull_request_target noch workflow_run.

Der Scanner liest die geltenden SECURITY.md-Anweisungen aus dem Checkout, einschließlich Richtlinienänderungen im PR. Prüfen Sie diese Änderungen zusammen mit dem Code.

Optionalen Daybreak-Zugriff konfigurieren

Daybreak ist optional. Beide Workflowbeispiele verwenden gpt-6-sol. Wenn Ihre Organisation für Trusted Access for Cyber zugelassen wurde, entfernen Sie # vor cyber-access-program im Block with des Scanschritts:

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

Verwenden Sie einen API key aus einem Projekt, für das Daybreak Blue aktiviert ist und das Zugriff auf gpt-6-sol hat.

Die Programmeingabe akzeptiert auch standard. Verwenden Sie ohne Daybreak-Zugriff ein Modell, auf das Ihr API key unter den standardmäßigen Schutzmaßnahmen zugreifen kann, und lassen Sie cyber-access-program weg oder setzen Sie es auf standard. Die Auswahl eines Modells oder Programms gewährt keinen Zugriff. Siehe die Hinweise zum Daybreak-Zugriff der Action.

Eine Ablehnung oder Sicherheitsblockierung, die den Scan abbricht, lässt die Action fehlschlagen, auch wenn fail-on-severity auf none gesetzt ist. Diese Eingabe steuert die Befundrichtlinie, nicht die Behandlung von Scannerfehlern.

Ein optionales Scanbudget festlegen

Beide Workflowbeispiele lassen max-cost weg und haben daher keinen Schwellenwert für die geschätzten Kosten, bei dessen Erreichen der Scan anhält. Um einen festzulegen, geben Sie über die Eingabe max-cost einen positiven USD-Betrag an. Für direkte CLI-Scans verwenden Sie --max-cost.

Das Kostenlimit erfordert, dass die CLI Preisdaten für das ausgewählte Modell unterstützt. Der geschätzte Schwellenwert ist keine feste Ausgabenobergrenze: Die Kosten bereits laufender Anfragen können ihn überschreiten. Prüfen Sie die Befunde und coverage.json, wenn ein Scan am Schwellenwert anhält. Unter Ausgabe- und Richtlinienoptionen finden Sie Informationen zum Verhalten des Kostenlimits.

Berichte speichern und SARIF hochladen

Die Beispiele setzen upload-artifacts: "true", um herunterladbare Berichte mit einer Aufbewahrungsdauer von sieben Tagen zu speichern. Berichte können Quellcodeausschnitte, Schwachstellennachweise und Details zur Behebung enthalten. Wählen Sie eine Aufbewahrungsdauer und einen Repositoryzugriff, die zu Ihrem Code passen. Die Action lädt nur validierte Berichte von ihrer Positivliste hoch; laden Sie ihre results-directory-Ausgabe nicht rekursiv hoch.

Der SARIF-Upload ist optional. Aktivieren Sie für private oder interne Repositorys vor dem Upload GitHub Code Security. Ersetzen Sie den Block permissions des Workflows durch:

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

Fügen Sie dann in einem der beiden Workflows diesen Schritt nach dem Scan 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

Verwenden Sie für den PR-Workflow category: codex-security-pr, damit jeder Prüfumfang eine eigene Kategorie hat. Behalten Sie id: security im Scanschritt bei. Vollständige, validierte Berichte bleiben für den Upload verfügbar, wenn Befunde die Schweregradrichtlinie verletzen. Bei fehlgeschlagenen oder unterbrochenen Scans, leeren Diffs oder Testläufen wird SARIF nicht hochgeladen.

Alle Einstellungen, Statusfelder und Berichtspfade finden Sie in der Referenz zu Ein- und Ausgaben der Action.

Eine Schweregradrichtlinie auswählen

Die GitHub-Workflows beginnen mit fail-on-severity: none. Damit hohe oder kritische Befunde aus einem abgeschlossenen Scan zum Fehlschlagen führen, ändern Sie die Eingabe des Scanschritts:

fail-on-severity: high

Legen Sie Codex Security in Ihren Repositoryregeln als erforderliche Statusprüfung fest, um Merges zu blockieren, wenn der PR-Job fehlschlägt. GitHub behandelt einen aufgrund einer Bedingung übersprungenen Job als erfolgreich, auch bei erforderlichen Prüfungen. Fork-PRs und PRs von dependabot[bot] bestehen diese Prüfung ohne Scan. Um solche übersprungenen Scans zu blockieren, verlangen Sie einen erfolgreichen, abgeschlossenen Scan.

Die Action folgt dem CLI-Ergebnis:

  • Exitcode 0 setzt scan-status: completed und policy-status: passed.
  • Exitcode 1 setzt scan-status: completed und policy-status: failed; der Schritt schlägt bei Befunden fehl, deren Schweregrad den konfigurierten Schwellenwert erreicht oder überschreitet.
  • Exitcode 2 oder ein unterbrochener Prozess setzt scan-status: failed und policy-status: not-evaluated; der Schritt schlägt fehl.
  • Ungültige oder fehlende erforderliche Berichte, ein veränderter Checkout, Fehler beim Hochladen angeforderter Artefakte und Fehler bei der Laufzeitbereinigung lassen den Schritt ebenfalls fehlschlagen.

Ein abgeschlossener Scan bedeutet, dass die konfigurierte Analyse ein gültiges Ergebnis erzeugt hat. Ausnahmen vom Prüfumfang, zurückgestellte Untersuchungen und andere Hinweise in coverage.json erzeugen kein separates Scanergebnis und umgehen die Schweregradrichtlinie nicht. Der Abschluss bestätigt nicht, dass jede Schwachstelle gefunden wurde. Prüfen Sie coverage.json bei der Bewertung des Ergebnisses.

Einen erfolgreichen, abgeschlossenen Scan verlangen

Für eine strengere Richtlinie fügen Sie eine separate Freigabeprüfung hinzu, die auch ausgeführt wird, wenn der Scanjob fehlschlägt oder GitHub ihn überspringt. Ein Schritt innerhalb des Scanjobs kann einen übersprungenen Job nicht prüfen, da keiner seiner Schritte ausgeführt wird.

Fügen Sie im PR-Workflow diese outputs-Zuordnung zum vorhandenen Job security hinzu, auf derselben Einrückungsebene wie runs-on und steps:

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

Fügen Sie dann diesen Job unter jobs neben dem vorhandenen Job security hinzu:

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

Legen Sie Codex Security gate als erforderliche Statusprüfung für diese Richtlinie fest. Sie verlangt sowohl einen erfolgreichen Scanjob als auch scan-status: completed. Durch die Prüfung beider Bedingungen bleiben Fehler aus der Schweregradrichtlinie, der Berichterstellung und der Bereinigung wirksam, selbst wenn der Scan selbst abgeschlossen wurde.

Mit den Ausschlüssen des Beispiels blockiert diese Freigabeprüfung Fork-PRs und PRs von dependabot[bot]. Sie blockiert auch leere Diffs und Testläufe, die die Action als skipped kennzeichnet. Die Freigabeprüfung scannt ausgeschlossene PRs nicht. Wählen Sie diese Richtlinie nur, wenn diese Fälle einen Merge verhindern sollen.

Scanprobleme beheben

  • Unbekannte Git-Referenz oder unerwarteter Diff: Checken Sie den PR-Head mit fetch-depth: 0 aus.
  • Fehler beim Start der Sandbox: Installieren Sie unter Ubuntu 24.04 das Paket bubblewrap und laden Sie vor der Action das AppArmor-Profil. Die Installation des Pakets allein lädt das erforderliche Profil nicht.
  • Fehlende Zugangsdaten: Stellen Sie sicher, dass CODEX_SECURITY_API_KEY dem vertrauenswürdigen Workflow zur Verfügung steht und der Umgebungsvariablen OPENAI_API_KEY des Scanschritts zugeordnet ist.
  • Fehler bei der Python-Einrichtung: Die Action benötigt Python 3.11 oder höher.
  • Hinweise zur Abdeckung: Prüfen Sie Ausnahmen vom Prüfumfang und zurückgestellte Untersuchungen in coverage.json. Diese Hinweise verursachen keine Ausführungsfehler und umgehen die Schweregradrichtlinie nicht.
  • Fehlendes SARIF: Prüfen Sie scan-status, report-status und sarif-upload-ready. Fehlt optionales SARIF, gibt die Action eine Warnung aus, ohne das Scanergebnis zu ändern; Fehler beim angeforderten Artefaktupload lassen den Job weiterhin fehlschlagen.
  • Fehler beim SARIF-Upload: Stellen Sie sicher, dass Ihre Organisation GitHub Code Security für das Repository aktiviert hat und der Workflow actions: read, contents: read und security-events: write gewährt.

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