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

Schnellstart mit der Codex Security CLI

Melde dich an, scanne ein lokales Repository und prüfe den Scanumfang und die Befunde.

Führe mit der eigenständigen Codex Security CLI einen Standardscan deines lokalen Repositorys aus. Am Ende dieses Schnellstarts hast du einen gespeicherten Bericht, den du prüfen und später erneut öffnen kannst. Für Scans in einem Codex-Chat verwendest du das Plugin für Codex Security.

Voraussetzungen prüfen

Verwende Node.js 24 oder 26 oder eine Version von Node.js 22 ab 22.13.0. Außerdem brauchst du Python 3.10 oder neuer. Wenn du Python 3.10 verwendest, installiere tomli. Für bestimmte Anfragen zur Cybersicherheit und für geschützte Befunde brauchst du Trusted Access for Cyber.

Die CLI läuft mit deinen Berechtigungen im Betriebssystem und wartet nicht auf eine Genehmigung. Scanprozesse können deine Umgebungsvariablen erben. Entferne deshalb vor dem Start alle Zugangsdaten aus der Umgebung, die du für den Scan nicht brauchst. Weitere Informationen findest du im Abschnitt Berechtigungen für lokale Scans.

CLI einrichten und prüfen

Installiere das öffentliche Paket global und prüfe anschließend die Version.

npm install -g @openai/codex-security
codex-security --version

Das Paket stellt den Befehl codex-security und den Alias cs bereit. Stelle sicher, dass dein PATH das Verzeichnis für global installierte npm-Befehle enthält.

Ohne globale Installation kannst du die CLI mit npx ausführen.

npx @openai/codex-security --version

Die folgenden Beispiele verwenden npx @openai/codex-security. Nach einer globalen Installation kannst du stattdessen codex-security verwenden.

Der Befehl gibt die installierte Paketversion aus. Mit info --json prüfst du die Version des mitgelieferten Plugins. Mit --help listest du die Befehle auf.

Anmelden

Melde dich mit deinem ChatGPT-Konto an.

npx @openai/codex-security login

Füge auf einem Rechner ohne Browser --device-auth hinzu, sofern dein Workspace die Geräteauthentifizierung zulässt. Folge dann den angezeigten Anweisungen zur Anmeldung. Ist die Geräteauthentifizierung deaktiviert, folge der Anleitung zur Anmeldung über SSH. Mit --auth chatgpt in den folgenden Scanbefehlen verwendest du die ChatGPT-Anmeldung auch dann, wenn deine Umgebung zusätzlich einen API-Schlüssel enthält.

Informationen zu API-Schlüsseln und anderen Anbietern findest du im Abschnitt Authentifizierung für Scans auswählen. Für Amazon Bedrock verwendest du AWS-Zugangsdaten und Modellzugriff anstelle einer ChatGPT-Anmeldung oder eines OpenAI-API-Schlüssels.

Scan vorbereiten

Ersetze die Beispielpfade durch den Pfad zu deinem Repository und den Pfad zu einem neuen Ergebnisverzeichnis außerhalb seines Git-Worktrees.

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Die Ergebnisse können Quellcodeauszüge und Details zu Schwachstellen enthalten. Wähle einen privaten Speicherort. Wenn du --output-dir weglässt, verwendet die CLI das Verzeichnis, in dem sie ihren Zustand dauerhaft speichert.

Prüfe das Scanziel und das Ausgabeverzeichnis.

npx @openai/codex-security scan "$REPOSITORY" \
  --auth chatgpt --output-dir "$SCAN_DIR" --dry-run

Ein erfolgreicher Probelauf bestätigt die lokalen Eingaben. Er startet keinen Scan, lädt keine Zugangsdaten und prüft den Python-Interpreter des Plugins nicht. Ob die Authentifizierung funktioniert und die Laufzeitumgebung korrekt eingerichtet ist, bleibt daher offen.

Ersten Scan ausführen

Entferne --dry-run, um den Scan zu starten.

npx @openai/codex-security scan "$REPOSITORY" \
  --auth chatgpt --output-dir "$SCAN_DIR"

Wenn du in deinem ChatGPT-Workspace Zugriff auf Daybreak Blue hast, ergänze den Scanbefehl um --model gpt-6-sol --cyber-access-program daybreak_blue.

In einem interaktiven Terminal siehst du ein Live-Dashboard. In nicht interaktiven Terminals gibt die CLI den Fortschritt zeilenweise aus. Mit --headless erhältst du diese Ausgabe auch in einem interaktiven Terminal. Das Dashboard und die gespeicherten Protokolle können Quellcode oder Zugangsdaten enthalten. Prüfe sie, bevor du sie teilst.

Nach Abschluss des Scans gibt die CLI auf stderr unter anderem den Pfad zum Bericht, die Anzahl der Befunde und die verstrichene Zeit aus. Die Ausgabe kann so aussehen.

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  SCOPE     repository: .
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

Standardmäßig führt der Schweregrad eines Befunds nicht dazu, dass der Scan fehlschlägt. Für eine maschinenlesbare Ausgabe auf stdout füge --json hinzu. Soll eine CI-Prüfung bei Befunden ab einem bestimmten Schweregrad fehlschlagen, lege eine Richtlinie für Schweregrade fest.

Ergebnisse prüfen

Öffne report.md im Ergebnisverzeichnis. Vergewissere dich, dass Scanziel und Revision stimmen, und prüfe dann die Befunde. Den aufgezeichneten Status und den Scanumfang findest du in den Feldern scan.status und scan.scope in scan-manifest.json.

Ein abgeschlossener Scan liefert den Exit-Code 0. Erreicht mindestens ein Befund den konfigurierten Schwellenwert für den Schweregrad, liefert der Scan stattdessen 1. Der Exit-Code 0 belegt nicht, dass jede Datei geprüft wurde. Bei Fehlern in den Eingaben, bei der Ausführung, bei der Integrität der Ergebnisse oder bei einer erforderlichen Ausgabe liefert die CLI 2. Die CLI-Referenz erläutert die Exit-Codes.

Prüfe bei jedem Befund den betroffenen Code, die Voraussetzungen für einen Angriff und die Belege aus der Validierung. Kläre auch, welche Fragen offenbleiben. Bei einem Befund aus der Quellcodeanalyse gehört eine erfolgreiche Reproduktion zur Laufzeit nicht unbedingt zu den Belegen. Entscheide dich erst dann für eine Behebung, wenn die Belege das beschriebene Problem stützen.

Teile oder archiviere das Scanverzeichnis als Ganzes. Es enthält scan-manifest.json und findings.json sowie den Bericht und die zugehörigen Artefakte. Die vollständige Verzeichnisstruktur findest du im Abschnitt Scanartefakte.

Gespeichertes Bedrohungsmodell exportieren

Standard-, Deep- und Diff-Scans speichern ihr Bedrohungsmodell zusammen mit den Ergebnissen. Du kannst es als Markdown exportieren, ohne dich anzumelden oder das Modell erneut aufzurufen.

npx @openai/codex-security export "$SCAN_DIR" \
  --artifact threat-model --output "$SCAN_DIR/exports/threatmodel.md"

Wenn kein Bedrohungsmodell gespeichert wurde, gibt export einen Fehler zurück. Wie du gespeicherte Scans und andere Ausgabeformate auswählst, erfährst du in der Referenz zum Exportbefehl.

Gespeicherten Scan erneut ansehen

Liste die Scans für dein Repository auf.

npx @openai/codex-security scans list "$REPOSITORY"

Kopiere eine Scan-ID aus der Ergebnisliste und setze sie in den folgenden Befehl ein.

npx @openai/codex-security scans show SCAN_ID

Nach einem abgeschlossenen interaktiven Scan mit Befunden kannst du die Befunde auch direkt in der CLI durchsehen. Prüfe dort die Belege, bevor du dich für eine Korrektur entscheidest. Für gespeicherte Befunde verwendest du die Befehle zur Validierung und Behebung.

Nächsten Scan auswählen

Ziel Anleitung
Ausgewählte Pfade oder einen Diff scannen Scanziel auswählen
Komponenten eines Repositorys parallel scannen Komponenten scannen
Mögliche Befunde mit einem Testskript validieren Eigene Validierung
Deep-Scans ausführen oder ihre Laufzeit begrenzen Deep-Scans konfigurieren
Angaben zur Architektur oder Sicherheitsrichtlinien bereitstellen Sicherheitskontext hinzufügen
Modell oder Reasoning-Aufwand ändern Laufzeitumgebung konfigurieren
Obergrenze für die geschätzten Kosten festlegen Optionen für Ausgabe und Richtlinien
Mehrere Repositorys scannen Scans für mehrere Repositorys
Pull Requests auf GitHub scannen oder Scans nach Zeitplan ausführen Anleitung für GitHub Actions
Einen anderen CI-Anbieter auswählen CI/CD-Übersicht

Hilfe bei Authentifizierungsproblemen, Informationen zu abweichenden Ergebnissen bei wiederholten Scans und Hinweise zum Melden von Fehlalarmen findest du in den häufigen Fragen zur CLI.