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.