Schnellstart für die Codex Security CLI

Führen Sie mit der eigenständigen Codex Security CLI einen Standardscan eines lokalen Repositorys durch. Am Ende dieser Schnellstartanleitung liegt ein gespeicherter Bericht vor, den Sie prüfen und später erneut aufrufen können. Für Scans innerhalb einer Codex-Unterhaltung verwenden Sie das Codex Security- Plugin.

Voraussetzungen prüfen

Verwenden Sie Node.js 24 oder 26 oder Node.js 22 ab Version 22.13.0. Sie benötigen außerdem Python 3.10 oder neuer. Python 3.10 benötigt zusätzlich tomli. Scans mit OpenAI-Inferenz setzen Zugriff auf Codex Security voraus. Je nach Konto und Repository erfordern Scans des gesamten Repositorys möglicherweise auch Trusted Access for Cyber.

Die CLI wird mit Ihren Betriebssystemberechtigungen ausgeführt und wartet nicht auf eine Genehmigung. Scanprozesse können Ihre Umgebung erben. Entfernen Sie daher nicht benötigte Zugangsdaten, bevor Sie beginnen. Siehe Berechtigungen für lokale Scans.

CLI einrichten und überprüfen

Führen Sie das öffentliche Paket mit npx aus:

npx @openai/codex-security --version

Der Befehl gibt die installierte Paketversion aus. Verwenden Sie info --json, um die Version des enthaltenen Plugins zu prüfen, oder --help, um die Befehle aufzulisten. Paketänderungen sind unter CLI- und SDK-Releases aufgeführt.

Anmelden

Melden Sie sich mit Ihrem ChatGPT-Konto an:

npx @openai/codex-security login

Fügen Sie auf einem Rechner ohne Browser --device-auth hinzu und folgen Sie den angezeigten Anmeldeanweisungen. Verwenden Sie --auth chatgpt in den folgenden Scanbefehlen, um diese Anmeldung auszuwählen, auch wenn Ihre Umgebung zusätzlich einen API key enthält.

Informationen zu API keys und anderen Anbietern finden Sie unter Authentifizierung für Scans auswählen. Verwenden Sie für Amazon Bedrock AWS-Zugangsdaten und Modellzugriff anstelle einer ChatGPT- Anmeldung oder eines OpenAI API key.

Einen Scan vorbereiten

Ersetzen Sie diese Pfade durch Ihr Repository und ein neues Ergebnisverzeichnis außerhalb seines Git-Arbeitsbaums:

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

Ergebnisse können Quellcodeauszüge und Details zu Schwachstellen enthalten. Wählen Sie einen privaten Speicherort. Wenn Sie --output-dir weglassen, verwendet die CLI ihr persistentes Zustandsverzeichnis.

Prüfen Sie das Ziel und den Ausgabespeicherort:

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

Ein erfolgreicher Testlauf bestätigt die lokalen Eingaben. Er startet keinen Scan, lädt keine Zugangsdaten und prüft den Python-Interpreter des Plugins nicht. Er belegt daher nicht, dass Authentifizierung und Einrichtung der Laufzeitumgebung erfolgreich sein werden.

Ihren ersten Scan ausführen

Entfernen Sie --dry-run, um den Scan zu starten:

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

Ein interaktives Terminal zeigt ein Live-Dashboard an. Nicht interaktive Terminals zeigen Fortschrittsmeldungen zeilenweise an. Fügen Sie --headless hinzu, um auch in einem interaktiven Terminal zeilenweise Fortschrittsmeldungen zu verwenden. Das Dashboard und gespeicherte Protokolle können Quellcode oder Zugangsdaten enthalten. Prüfen Sie diese vor der Weitergabe.

Nach Abschluss des Scans enthält stderr den Berichtspfad, die Anzahl der Befunde und die verstrichene Zeit. Zum Beispiel:

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

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

Standardmäßig führt der Schweregrad eines Befunds nicht dazu, dass ein Scan fehlschlägt. Für maschinenlesbare Ausgaben auf stdout fügen Sie --json hinzu. Damit Befunde eine CI-Prüfung fehlschlagen lassen, legen Sie eine Schweregradrichtlinie fest.

Ergebnisse prüfen

Öffnen Sie report.md im angegebenen Verzeichnis. Bestätigen Sie das Ziel und die Revision und lesen Sie dann die Angaben zur Prüfabdeckung, bevor Sie einzelne Befunde prüfen.

Prüfen Sie scan.status in scan-manifest.json, um sicherzustellen, dass der Scan abgeschlossen wurde. Prüfen Sie coverage.json auf untersuchte Bereiche, ausgeschlossene Pfade, zurückgestellte Arbeiten und offene Fragen.

Ein abgeschlossener Scan endet mit 0, sofern Befunde keinen konfigurierten Schweregradschwellenwert erreichen; in diesem Fall wird 1 zurückgegeben. Abdeckungslücken ändern den Exit-Code nicht, daher bedeutet der Exit-Code 0 nicht, dass jede Datei geprüft wurde. Fehler bei Eingabe, Ausführung, Ergebnisintegrität oder erforderlicher Ausgabe führen zum Exit-Code 2. Die CLI-Referenz erläutert die Exit-Codes.

Prüfen Sie für jeden Befund den betroffenen Code, die Voraussetzungen für Angreifer, die Validierungsnachweise und die verbleibenden Unsicherheiten. Ein auf dem Quellcode basierender Befund umfasst nicht zwangsläufig eine erfolgreiche Reproduktion zur Laufzeit. Wählen Sie einen Befund erst dann zur Behebung aus, wenn seine Nachweise das behauptete Problem belegen.

Geben Sie das Scanverzeichnis stets vollständig weiter und archivieren Sie es als Ganzes. Es enthält scan-manifest.json, findings.json und coverage.json sowie den Bericht und ergänzende Artefakte. Unter Scan- Artefakte finden Sie die vollständige Struktur.

Einen gespeicherten Scan erneut aufrufen

Listen Sie die Scans für das Repository auf:

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

Kopieren Sie eine Scan-ID aus den Ergebnissen:

npx @openai/codex-security scans show SCAN_ID

Nach einem vollständig abgeschlossenen interaktiven Scan mit Befunden bietet die CLI auch eine Befundübersicht an. Prüfen Sie dort die Nachweise, bevor Sie eine Korrektur auswählen. Verwenden Sie für gespeicherte Befunde die Befehle zum Validieren und Patchen.

Den nächsten Scan auswählen

Bei Authentifizierungsproblemen, Unterschieden zwischen wiederholten Scans oder Rückmeldungen zu falsch positiven Befunden finden Sie Informationen in den CLI-FAQ.