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

Codeänderungen auf Sicherheitsprobleme prüfen

Prüfe Pull Requests und lokale Änderungen manuell oder in CI/CD auf Sicherheitsregressionen.

Mit einer Sicherheitsprüfung kannst du feststellen, ob ein bestimmter Satz von Änderungen in Git die Sicherheit beeinträchtigt. Codex prüft jede geänderte Datei mit Quellcode oder vergleichbaren Inhalten und den Code, auf den sie sich unmittelbar stützt. Die Prüfung beschränkt sich auf diesen Umfang.

Wenn du das gesamte Repository scannen möchtest, folge der Anleitung Sicherheitsscan ausführen.

Änderungen manuell prüfen

Öffne in der Desktop-App Sicherheit, wähle Scans und dann + Scan. Wähle das Repository und anschließend Änderungen. Du kannst Änderungen ohne Commit, einen einzelnen Commit oder die Änderungen zwischen einer Basis- und einer Head-Revision prüfen. Tiefenscan ist für die Prüfung von Änderungen nicht verfügbar.

Du kannst Codex auch in einem Chat bitten, deine Änderungen ohne Commit zu prüfen:

Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.

Wenn du mehrere Commits oder die Änderungen eines Branches prüfen möchtest, gib bei Bedarf beide Revisionen an:

Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.

Du kannst auch einen Pull Request angeben, wenn seine Basis- und Head-Revision im lokalen Checkout verfügbar sind.

Änderungen im Setup bestätigen

  1. Wähle Änderungen.
  2. Bestätige das ausgecheckte Repository, den aktuellen Branch und den neuesten Commit.
  3. Wähle unter Zu prüfende Änderungen die passende Option:
    • Uncommitted changes für Änderungen im aktuellen Arbeitsbaum.
    • Den neuesten Commit, um nur diesen Commit zu prüfen.
    • Eine Basis- und eine Head-Revision, um die Änderungen eines Branches oder Pull Requests zwischen diesen Revisionen zu prüfen.
  4. Vergewissere dich, dass die Zusammenfassung die Änderungen beschreibt, die du prüfen möchtest.
  5. Wähle Scan starten.

Codex checkt keinen anderen Branch aus und wechselt den ausgewählten Arbeitsbaum nicht. Wenn eine angeforderte Revision lokal fehlt, rufe sie vor der Prüfung ab oder gib eine lokal verfügbare Basis- und Head-Revision an.

Befunde bearbeiten

Nachdem du die Ergebnisse geprüft hast, kannst du eine bestätigte Schwachstelle beheben und die Behebung überprüfen oder Befunde exportieren und nachverfolgen.

Prüfungen in CI/CD automatisieren

Wie du mit der eigenständigen CLI strukturierte JSON-Daten ausgibst, eine Richtlinie für Schweregrade festlegst und SARIF-Dateien hochlädst, erfährst du in Codex Security in CI ausführen. Dieser Abschnitt zeigt dir, wie du den Skill des installierten Plugins über codex exec aufrufst.

Führe $codex-security:security-diff-scan in CI aus, wenn der Runner die Codex CLI ohne Benutzereingabe aufrufen kann. Installiere zuerst die CLI, ohne ihr den Zugangsschlüssel für den Scan zur Verfügung zu stellen:

npm install --global @openai/codex

Installiere das Plugin für Codex Security in der CLI:

codex plugin add codex-security@openai-curated

Der Installationsbefehl nutzt den öffentlichen Plugin-Marketplace der Codex CLI. Die Anforderungen für die jeweilige Version findest du im Änderungsprotokoll des Plugins.

Stelle anschließend einen OpenAI-API-Schlüssel aus dem Secret-Speicher deiner CI-Umgebung als CODEX_SECURITY_API_KEY bereit. Mache den Schlüssel nur für den Scan zugänglich:

CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
  --sandbox workspace-write \
  "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

Dank des Schreibzugriffs in der Sandbox kann der Scan temporäre Artefakte erstellen. Der Prompt weist Codex weiterhin an, den ausgecheckten Quellcode unverändert zu lassen.

Der Scan speichert seine Ergebnisse in $TMPDIR/codex-security-scans/<repository>/<scan-id>/:

Datei Inhalt
report.md Übersicht, die als Einstieg in das gesamte Scan-Verzeichnis dient.
findings/<slug>/ Auf Wunsch detaillierte Berichte zu Schwachstellen und ergänzende Proof-of-Concept-Dateien.
hardening/ Auf Wunsch Hinweise zur strukturellen Härtung und konkrete Vorschläge dazu.
findings.json Befunde mit stabilen Kennungen, Schweregrad, Konfidenz, Fundstellen im Quellcode und Maßnahmen zur Behebung. Du kannst diese Felder in Sicherheitsworkflows oder nachgelagerten Tools verwenden.
scan-manifest.json Versiegelter Scan-Nachweis mit dem geprüften Ziel, den Revisionen und den Hashwerten der Artefakte.
coverage.json Geprüfte, zurückgestellte und ausgeschlossene Bereiche sowie Angaben dazu, wie vollständig der Scan das Ziel abgedeckt hat.

Die Felddefinitionen findest du im Schema für Befunde. Mit findingId identifizierst du den Befund und mit occurrenceId sein konkretes Vorkommen in diesem Scan.

Dieser Befehl gibt beispielsweise für jeden Befund eine Zeile mit tabulatorgetrennten Feldern aus:

jq -r '
  .findings[] |
  [.findingId, .severity.level, .confidence.level, .locations[0].path, .locations[0].startLine, .title] |
  @tsv
' findings.json

Die Beispiele setzen einen vertrauenswürdigen Linux-Runner mit Node.js und npm, Git, Python 3, jq und den Befehlszeilentools des jeweiligen Anbieters voraus. Der Runner braucht Schreibzugriff auf das Verzeichnis, das npm als Präfix für globale Pakete verwendet.

Scan-Ergebnisse können sensible Details zu Schwachstellen enthalten. Halte die Artefakte privat und prüfe vor der Veröffentlichung von Befunden, wo und mit welchen Inhalten du sie veröffentlichst. Wähle das Beispiel für deinen CI-Anbieter:

Choose an option
name: Codex Security review

on:
  pull_request:

jobs:
  security-review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Install Codex Security
        env:
          CODEX_HOME: ${{ runner.temp }}/codex-home
        run: |
          npm install --global @openai/codex
          codex plugin add codex-security@openai-curated

      - name: Review code changes
        env:
          CODEX_SECURITY_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_HOME: ${{ runner.temp }}/codex-home
          TMPDIR: ${{ runner.temp }}/codex-security
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_REVISION: ${{ github.event.pull_request.head.sha }}
        run: |
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_REVISION")"
          CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
            --sandbox workspace-write \
            "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: codex-security-review
          path: ${{ runner.temp }}/codex-security/codex-security-scans

Die Beispiele überspringen Pull Requests aus Forks. Führe Jobs mit Zugangsschlüssel nur über eine geschützte Pipeline-Definition aus und nur für Beiträge von Personen, denen du den Scan-Schlüssel anvertraust. Archiviere codex-security-scans, um die strukturierten Befunde, das Manifest, die Angaben zur Prüfabdeckung und report.md zusammen aufzubewahren. Das Archiv enthält auch die angeforderten Ausgaben in findings/ oder hardening/. Nutze die Ergebnisse zunächst als Hinweise. Prüfe Abdeckung und Laufzeit, bevor du den Job zur Pflichtprüfung machst.

Weitere Informationen zum Umgang mit API-Schlüsseln und zu den Einstellungen der Sandbox findest du in Nicht interaktiver Modus. Wenn deine Organisation die Codex GitHub Action zulässt, kann diese die CLI zur Laufzeit installieren. Du musst das Plugin trotzdem zuerst installieren und für den Eingabeparameter codex-home der Action dasselbe Verzeichnis angeben wie für CODEX_HOME.