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

Häufige Fragen zur CLI von Codex Security

Antworten auf Fragen zu Scans mit Codex Security, Befunden, Fehlalarmen, Scan-Abdeckung, Kosten und CI.

Hier findest du Antworten auf häufige Fragen dazu, wie du Repositorys im Terminal scannst und Sicherheitsbefunde verwaltest. Der CLI-Schnellstart führt dich durch die Installation und deinen ersten Scan.

Repositorys scannen

Warum verwendet ein Scan nach der Anmeldung einen API-Schlüssel?

Wenn OPENAI_API_KEY oder CODEX_API_KEY in deiner Umgebung gesetzt ist, verwenden Scans ohne interaktives Terminal sowie Scans mit JSON- oder JSONL-Ausgabe standardmäßig den API-Schlüssel aus der Umgebung. Das gilt auch nach erfolgreicher Anmeldung über ChatGPT oder mit einem Zugriffstoken. Bei interaktiven Scans mit Textausgabe fragt die CLI, welche Anmeldemethode du verwenden möchtest, wenn auch eine ChatGPT-Anmeldung verfügbar ist. Bei Probeläufen fragt die CLI nicht nach und lädt keine Anmeldedaten.

Um deine gespeicherten Anmeldedaten für einen Scan zu verwenden, wähle sie ausdrücklich aus:

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

Mit diesem Befehl legst du fest, dass der Scan einen API-Schlüssel aus OPENAI_API_KEY oder CODEX_API_KEY verwenden muss:

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

Damit die CLI standardmäßig deine gespeicherten Anmeldedaten verwendet, führe unset OPENAI_API_KEY CODEX_API_KEY aus. Alle unterstützten Anmeldemethoden findest du in der CLI-Referenz.

Lässt sich ein unterbrochener Sammelscan fortsetzen?

Ja. Führe denselben Befehl für den Sammelscan mit der ursprünglichen CSV-Datei und demselben Ausgabeverzeichnis erneut aus. Codex Security überspringt Repositorys, deren Scan bereits abgeschlossen ist.

Füge --max-attempts 3 hinzu, damit Codex Security es bei vorübergehenden Repository- oder Scanfehlern erneut versucht:

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

Die Ergebnisse abgeschlossener Scans bleiben erhalten. Codex Security wiederholt diese Scans auch dann nicht, wenn die Abdeckung Lücken aufweist. Solche Lücken führen nicht dazu, dass der Sammelscan mit Exit-Code 2 endet.

Befunde und Abdeckung

Wo finden Teams die Ergebnisse früherer Scans?

Liste die gespeicherten Scans für dein Repository auf:

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

Verwende eine Scan-ID aus der Liste, um die Befunde des jeweiligen Scans anzusehen:

npx @openai/codex-security scans show SCAN_ID

Für jeden abgeschlossenen Scan speichert Codex Security den Bericht, die Befunde, das Manifest und ergänzende Artefakte zusammen. Den vollständigen Verzeichnisaufbau findest du im Abschnitt Scan-Artefakte.

Mit scans logs SCAN_ID kannst du gespeicherte Scan- und Worker-Ereignisse einsehen. Sensible Inhalte werden in diesen Protokollen nicht unkenntlich gemacht. Die Protokolle können Quellcode oder Anmeldedaten enthalten.

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

Codex Security speichert den Scanverlauf in einer Workbench-Datenbank. Wenn du im Standardverzeichnis für Zustandsdaten keinen Schreibzugriff hast, wähle ein privates Verzeichnis außerhalb des Repositorys:

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

Wie unterscheiden Scans zwischen neuen und bekannten Befunden?

Liste die offenen Befunde aus allen Scans eines Repositorys auf:

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

Die Liste zeigt, welche Befunde der jüngste Scan bestätigt hat und welche offenen Befunde aus früheren Scans er nicht bestätigt hat.

Vergleiche die Befunde aus zwei Scans:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Beim Vergleich ordnet Codex Security Befunde anhand ihrer Ursache automatisch einander zu und verwendet gespeicherte Zuordnungen erneut. Es unterscheidet zwischen neuen, fortbestehenden, wiedereröffneten, nicht beobachteten und behobenen Befunden sowie Befunden mit unbekanntem Status. Erkennt ein späterer Scan einen früheren Befund im untersuchten Code nicht mehr, gilt der Befund als nicht beobachtet. Er gilt erst dann als behoben, wenn er ausdrücklich als bereits behoben geschlossen wurde. Bei ausgeschlossenen Pfaden und unsicheren Zuordnungen bleibt der Status unbekannt.

Wie kann ich einen Fehlalarm melden und was bewirkt die Meldung?

Rufe den gespeicherten Scan auf, um die ID des konkreten Vorkommens zu finden:

npx @openai/codex-security scans show SCAN_ID

Halte fest, warum der Befund in diesem Fall nicht zutrifft:

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

Bei künftigen Scans desselben Repositorys steht diese Begründung als Kontext zur Verfügung. Jeder Scan prüft weiterhin unabhängig den aktuellen Quellcode, die Schutzmaßnahmen und die Erreichbarkeit des betroffenen Codes. Wenn du einen Befund als Fehlalarm einstufst, wird dadurch weder eine Regel noch ein Pfad oder eine Schwachstellenklasse von der Prüfung ausgenommen.

Einzelheiten zu den Befehlen findest du in der Referenz für Befunde.

Warum können wiederholte Scans unterschiedliche Befunde liefern?

KI-gestützte Scans können auch bei gleicher Konfiguration unterschiedliche Ergebnisse liefern. Führe zunächst deinen Referenzscan erneut aus:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

Der erneute Scan verwendet die ursprüngliche Konfiguration und erfordert dieselbe Plugin-Version. Hat sich das installierte Plugin geändert, bricht der Befehl ab.

Vergleiche den Referenzscan mit dem neuen Scan:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Wenn fehlender Kontext zu den Abweichungen beitragen könnte, stelle für die Scans dieselben Hinweise zu Architektur und Sicherheit bereit. Der Abgleich kann erkennen, wenn Befunde aus verschiedenen Scans auf dasselbe Problem zurückgehen. Die Scans können dennoch unterschiedliche Ergebnisse liefern. Prüfe jeden wichtigen Befund, der bei einem späteren Scan ausbleibt, noch einmal direkt.

Wie kann ein Team prüfen, ob eine Schwachstelle behoben ist?

Prüfe den ursprünglichen Befund anhand der geänderten Arbeitskopie erneut. Führe dazu in dieser Arbeitskopie den folgenden Befehl aus. Gib den Bericht des ursprünglichen Scans und das Problem an, das du überprüfen möchtest:

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

Prüfe anhand der Belege, ob der betroffene Codepfad die Schwachstelle nicht mehr aufweist und die vorgesehene Funktion weiterhin wie erwartet arbeitet. Führe das ursprüngliche Reproduktionsbeispiel oder den Regressionstest aus, sofern verfügbar. Lässt sich die Prüfung nicht durchführen, halte im Ergebnis fest, was noch unklar ist.

Ein Scanvergleich kann zeigen, wie sich Befunde verändert haben. Das Ausbleiben eines Befunds allein bestätigt jedoch nicht, dass das Problem behoben ist.

Was bedeutet eine unvollständige Abdeckung?

Prüfe in scan-manifest.json anhand von scan.status, ob der Scan abgeschlossen ist. scan.scope gibt den konfigurierten Prüfumfang an. scan.review.excludedPaths listet die Pfadmuster auf, die der Scan von der Prüfung ausgeschlossen hat. In scan.scope.limitations findest du dokumentierte Lücken, etwa wenn bei einem Tiefenscan das Zeitlimit abläuft, bevor auch nur eine Prüfung abgeschlossen ist.

Lücken in der Abdeckung ändern den Exit-Code eines abgeschlossenen Scans nicht. Exit-Code 0 bedeutet nicht, dass jede Datei geprüft wurde. Wenn ein späterer Scan den ursprünglichen Pfad eines Befunds nicht abdeckt, kann er nicht nachweisen, dass der Befund dort nicht mehr besteht.

Automatisierung und Kosten

Wie funktionieren Zeitlimits für Tiefenscans?

Lege beim Start eines Tiefenscans ein Zeitlimit für die Worker fest:

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

Der Standardwert ist zugleich der Höchstwert und beträgt 5.760 Minuten (96 Stunden). Du kannst auch Bruchteile einer Minute angeben. Nach Ablauf des Zeitlimits endet die Suche nach weiteren potenziellen Schwachstellen. Der Bericht fasst die Ergebnisse der abgeschlossenen Prüfungen zusammen. Im Bericht siehst du, welche Bereiche geprüft wurden und welche Untersuchungen noch ausstehen.

Um ein Zeitlimit wiederzuverwenden, lege scan.max_time_minutes in deiner Projektkonfiguration fest. Bei Sammelscans gilt dieses Limit für jeden einzelnen Scanversuch.

Wie funktionieren Kostenlimits für Scans?

Lege vor dem Start des Scans ein Limit für die geschätzten Kosten in US-Dollar fest:

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

Das Limit beruht auf einer Schätzung. Bereits laufende Anfragen können dazu führen, dass die tatsächlichen Ausgaben darüber liegen. Erreicht ein Tiefenscan das Limit, nachdem Codex Security die Ergebnisse der bereits abgeschlossenen Worker zusammengeführt hat, kann die CLI einen Abschlussbericht mit einer Budgetwarnung speichern. Sie gibt 0 zurück oder 1, wenn Befunde den konfigurierten Schwellenwert für den Schweregrad erreichen oder überschreiten. Kann die CLI kein gültiges Abschlussergebnis erzeugen, gibt sie 2 zurück und behält alle verfügbaren Ausgaben bei.

Wie du Scans in deiner CI-Pipeline ausführst, erfährst du in der CI/CD-Übersicht. Für eine Prüfung vor jedem Commit verwende install-hook.