Häufig gestellte Fragen zur Codex Security CLI

Hier finden Sie Antworten auf häufig gestellte Fragen zum Scannen von Repositorys und zum Verwalten von Sicherheitsbefunden im Terminal. Beginnen Sie für die Installation und einen ersten Scan mit dem CLI-Schnellstart.

Repository-Scans

Warum verwendet ein Scan nach der Anmeldung einen API key?

Wenn Ihre Umgebung OPENAI_API_KEY oder CODEX_API_KEY enthält, verwenden Scans ohne interaktives Terminal sowie JSON- und JSONL-Scans standardmäßig den API key aus der Umgebung, selbst nach einer erfolgreichen Anmeldung mit ChatGPT oder einem Zugriffstoken. Bei interaktiven Scans mit Textausgabe werden Sie zur Auswahl aufgefordert, wenn auch eine ChatGPT-Anmeldung verfügbar ist. Bei Testläufen werden weder Anmeldedaten abgefragt noch geladen.

Um Ihre gespeicherten Anmeldedaten für einen Scan zu verwenden, wählen Sie sie ausdrücklich aus:

npx @openai/codex-security scan . --auth chatgpt

Um einen API key aus OPENAI_API_KEY oder CODEX_API_KEY vorauszusetzen:

npx @openai/codex-security scan . --auth api-key

Um Ihre gespeicherten Anmeldedaten als automatische Standardeinstellung festzulegen, führen Sie unset OPENAI_API_KEY CODEX_API_KEY aus. Alle unterstützten Authentifizierungsmodi finden Sie in der CLI-Referenz.

Kann ein unterbrochener Massenscan fortgesetzt werden?

Ja. Führen Sie denselben bulk-scan-Befehl mit der ursprünglichen CSV-Datei und dem ursprünglichen Ausgabeverzeichnis aus. Codex Security überspringt abgeschlossene Repositorys.

Fügen Sie --max-attempts 3 hinzu, um vorübergehende Repository- oder Scanfehler erneut zu versuchen:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

Abgeschlossene Scans behalten ihre Ergebnisse und werden nicht wiederholt, auch wenn Abdeckungslücken verbleiben. Abdeckungslücken führen nicht dazu, dass die Kampagne mit Code 2 beendet wird.

Befunde und Abdeckung

Wo finden Teams frühere Scanergebnisse?

Listen Sie die gespeicherten Scans für Ihr Repository auf:

npx @openai/codex-security scans list /path/to/repository

Verwenden Sie eine Scan-ID aus den Ergebnissen, um die zugehörigen Befunde zu untersuchen:

npx @openai/codex-security scans show SCAN_ID

Bei jedem abgeschlossenen Scan werden der Bericht, die Befunde, die Abdeckung und die zugehörigen Artefakte gemeinsam gespeichert. Den vollständigen Aufbau finden Sie unter Scan- Artefakte.

Um gespeicherte Scan- und Worker-Ereignisse zu prüfen, führen Sie scans logs SCAN_ID aus. Diese Protokolle sind nicht geschwärzt und können Quellcode oder Anmeldedaten enthalten.

Was ist zu tun, wenn die CLI den Scanverlauf nicht speichern kann?

Codex Security speichert den Scanverlauf in einer Workbench-Datenbank. Wenn das standardmäßige Statusverzeichnis nicht beschreibbar ist, wählen Sie ein privates Verzeichnis außerhalb des Repositorys aus:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Wie unterscheiden Scans zwischen neuen und bekannten Befunden?

Listen Sie die offenen Befunde aus allen Scans eines Repositorys auf:

npx @openai/codex-security findings list /path/to/repository

Die Liste kennzeichnet Befunde, die im neuesten Scan bestätigt wurden, sowie frühere offene Befunde, die der Scan nicht bestätigt hat.

Vergleichen Sie die Befunde der beiden Scans:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Der Vergleich ordnet Befunde automatisch anhand ihrer Ursache zu, verwendet gespeicherte Zuordnungen erneut und erkennt neue, fortbestehende, wieder geöffnete, nicht beobachtete, behobene und unbekannte Befunde. Wenn ein späterer Scan einen früheren Befund im gescannten Code nicht findet, gilt der Befund als nicht beobachtet. Er zählt erst dann als behoben, wenn er explizit als bereits behoben geschlossen wird. Ausgeschlossene Pfade und unsichere Zuordnungen bleiben unbekannt.

Wie funktioniert Feedback zu falsch positiven Ergebnissen?

Untersuchen Sie den gespeicherten Scan, um die Vorkommnis-ID zu ermitteln:

npx @openai/codex-security scans show SCAN_ID

Erfassen Sie, warum dieser Befund nicht zutrifft:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

Künftige Scans desselben Repositorys erhalten diese Erklärung als Kontext. Sie prüfen dennoch unabhängig den aktuellen Quellcode, die Schutzmaßnahmen und die Erreichbarkeit. Eine Verwerfung unterdrückt weder eine Regel noch einen Pfad oder eine Schwachstellenklasse.

Einzelheiten zu den Befehlen finden Sie in der Referenz zu Befunden.

Warum können wiederholte Scans unterschiedliche Befunde liefern?

KI-gestützte Scans können selbst bei derselben Scan-Konfiguration variieren. Führen Sie zunächst Ihren Baseline-Scan erneut aus:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

Bei der erneuten Ausführung werden die ursprüngliche Scan-Konfiguration und dieselbe Plugin- Version beibehalten. Wenn sich das installierte Plugin geändert hat, wird der Befehl abgebrochen.

Vergleichen Sie den Baseline-Scan mit dem neuen Scan:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Stellen Sie gemeinsame Architektur- und Sicherheitsvorgaben bereit, wenn fehlender Kontext zu den Abweichungen beitragen könnte. Durch die Zuordnung kann derselbe zugrunde liegende Befund über mehrere Durchläufe hinweg erkannt werden, sie macht Scans jedoch nicht deterministisch. Prüfen Sie jeden wichtigen Befund, der nicht mehr erscheint, direkt erneut.

Wie kann ein Team bestätigen, dass eine Korrektur funktioniert hat?

Prüfen Sie den ursprünglichen Befund erneut anhand des geänderten Checkouts. Übergeben Sie aus diesem Checkout seinen Bericht und das Problem, das Sie validieren möchten:

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

Prüfen Sie die Nachweise dafür, dass der anfällige Ausführungspfad geschlossen ist und legitimes Verhalten weiterhin funktioniert. Führen Sie, sofern vorhanden, den ursprünglichen Reproduktionstest oder Regressionstest aus. Falls die Prüfung nicht ausgeführt werden kann, vermerken Sie die verbleibende Unsicherheit im Ergebnis.

Ein Scan-Vergleich kann zeigen, wie sich Befunde verändert haben. Ein fehlender Befund allein bestätigt jedoch keine Behebung.

Was bedeutet unvollständige Abdeckung?

Prüfen Sie coverage.json auf ausgeschlossene Pfade, zurückgestellte Bereiche und offene Fragen. Neue Ergebnisse enthalten kein Feld zur Vollständigkeit der Abdeckung. Prüfen Sie scan.status in scan-manifest.json auf den Ausführungsstatus.

Abdeckungslücken ändern den Exit-Code eines abgeschlossenen Scans nicht. Exit-Code 0 bedeutet nicht, dass jede Datei geprüft wurde. Ein späterer Scan kann nicht feststellen, dass ein früherer Befund nicht mehr besteht, wenn er den ursprünglichen Pfad dieses Befunds nicht abdeckt.

Automatisierung und Kosten

Wie funktionieren Zeitlimits für Tiefenscans?

Legen Sie beim Start eines Tiefenscans eine Frist für Worker fest:

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

Der Standardwert beträgt 96 Stunden. Verwenden Sie einen beliebigen positiven Wert bis 96, auch Bruchteile. Bei Erreichen des Zeitlimits stoppt Codex Security noch laufende Worker, behält abgeschlossene Standard-Scan-Ergebnisse bei und führt sie im Abschlussbericht zusammen. Prüfen Sie den Bericht auf überprüfte Bereiche und zurückgestellte Arbeiten. Das Zeitlimit allein bestimmt nicht den Exit-Code; maßgeblich sind der Ausführungsstatus und die Schweregradrichtlinie.

Legen Sie für dauerhafte Einstellungen oder Massenkampagnen max_time_hours unter [deep_scan] in der Tiefenscan- Konfiguration fest.

Wie funktionieren Kostenlimits für Scans?

Legen Sie vor dem Start des Scans ein geschätztes Kostenlimit in USD fest:

npx @openai/codex-security scan . --max-cost 5

Das Limit ist eine Schätzung und keine feste Ausgabenobergrenze. Bereits laufende Anfragen können mit Kosten oberhalb dieses Limits abgeschlossen werden. Wenn ein Deep-Scan das Limit erreicht, nachdem Codex Security die Ergebnisse abgeschlossener Worker zusammengeführt hat, kann die CLI einen abgeschlossenen Bericht mit einer Budgetwarnung speichern. Sie gibt 0 zurück oder 1, wenn Befunde den konfigurierten Schweregradschwellenwert erreichen. Wenn sie kein gültiges abgeschlossenes Ergebnis erzeugen kann, gibt sie 2 zurück und behält alle verfügbaren Ausgaben bei.

Verwenden Sie für GitHub-Pull-Request-Prüfungen und geplante Repository-Scans die Codex Security GitHub Action. Mit action-v0.3.0 bedeutet ein abgeschlossener Scan, dass die konfigurierte Analyse ein gültiges Ergebnis erzeugt hat. Ausschlüsse vom Scan-Umfang und zurückgestellte Untersuchungen umgehen die Schweregradrichtlinie nicht. Prüfen Sie coverage.json, um den Umfang und die Einschränkungen des Scans einzuschätzen. Um auch leere Diffs und Testläufe abzulehnen, verlangen Sie, dass die Ausgabe scan-status der Action den Wert completed hat; siehe Schweregradrichtlinie auswählen.

Informationen zu anderen Anbietern finden Sie in der CI/CD-Übersicht. Für eine Prüfung vor jedem Commit verwenden Sie install-hook.