ChatGPT-Dokumentation
Deutsch
Kontakt goolvyouyou@gmail.com

Schnellstart für die Codex Security CLI

Richten Sie Codex Security ein, führen Sie einen lokalen Scan aus und prüfen Sie den Bericht, die Befunde und die Abdeckung.

Codex Security hilft Sicherheits- und Entwicklungsteams dabei, Schwachstellen zu finden, zu bestätigen und zu beheben. Verwenden Sie die Befehlszeilenschnittstelle (CLI), um Repositorys zu scannen, die Ihnen gehören oder zu deren Prüfung Sie berechtigt sind, Befunde im Zeitverlauf zu prüfen und Änderungen vor ihrer Übernahme zu kontrollieren.

Voraussetzungen prüfen

Die CLI erfordert Node.js 22 (22.13.0 oder höher), 24 oder 26. Scans, Massenscans, Exporte, der Scanverlauf und gespeicherte Befunde erfordern außerdem Python 3.10 oder höher. Weitere Informationen finden Sie unter Authentifizierung und Voraussetzungen.

CLI einrichten und überprüfen

Führen Sie die CLI mit npx aus und prüfen Sie ihre Version:

npx @openai/codex-security --version

Führen Sie den folgenden Befehl aus, um sowohl die Paketversion als auch die Version des enthaltenen Plugins anzuzeigen:

npx @openai/codex-security info --json

Informationen zu Paketänderungen finden Sie unter CLI- und SDK-Versionen.

Listen Sie die verfügbaren Befehle auf:

npx @openai/codex-security --help

Siehe auch CLI-Referenz.

Anmelden

Melden Sie sich für die lokale Nutzung mit Ihrem ChatGPT-Konto an:

npx @openai/codex-security login

Verwenden Sie auf einem entfernten oder monitorlosen Computer die Geräteauthentifizierung:

npx @openai/codex-security login --device-auth

Legen Sie für CI und andere automatisierte Workflows einen OpenAI API key fest:

export OPENAI_API_KEY="<your-api-key>"

Informationen zu AWS-Anmeldedaten finden Sie unter Einrichtung von Amazon Bedrock. Legen Sie für OpenRouter oder Fireworks den API key des Anbieters fest und wählen Sie mit --provider und --model ein Modell aus.

Um Ihre ChatGPT-Anmeldung zu verwenden, wenn zugleich ein API key festgelegt ist, wählen Sie sie ausdrücklich aus:

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

Um den API key aus der Umgebung zwingend zu verwenden, wählen Sie die API-key-Authentifizierung:

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

Abhängig von Ihrem Konto und Repository können Scans des vollständigen Repositorys außerdem Trusted Access for Cyber erfordern.

Einen Scan vorbereiten

Wählen Sie ein vertrauenswürdiges Repository aus, zu dessen Prüfung Sie berechtigt sind. Scans verwenden Ihre lokalen Betriebssystemberechtigungen und halten nicht an, um eine Genehmigung einzuholen. Scan- Prozesse können Ihre Umgebung übernehmen. Entfernen Sie daher nicht benötigte Anmeldedaten, bevor Sie beginnen. Weitere Informationen finden Sie unter Berechtigungen für lokale Scans.

Wählen Sie für die Scanergebnisse ein Verzeichnis außerhalb des Repositorys aus:

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

Wenn Sie --output-dir weglassen, speichert Codex Security die Ergebnisse in seinem eigenen persistenten Statusverzeichnis. Ergebnisse können Quellcodeauszüge und Schwachstellendetails enthalten. Wählen Sie daher einen privaten Speicherort und eine geeignete Aufbewahrungsrichtlinie.

Wenn das standardmäßige Statusverzeichnis nicht beschreibbar ist, wählen Sie ein beschreibbares Verzeichnis außerhalb des gescannten Repositorys aus:

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

Prüfen Sie vor dem Start eines Scans das Repository, das Ziel und das Ausgabeverzeichnis:

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

Der Probelauf prüft lokale Eingaben einschließlich aller --knowledge-base-Pfade, ohne Codex zu starten, Anmeldedaten zu laden oder den Python- Interpreter des Plugins zu untersuchen.

Ihren ersten Scan ausführen

Führen Sie einen Standardscan aus und speichern Sie dessen Ergebnisse im ausgewählten Verzeichnis:

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

Interaktive Terminals zeigen ein Live-Scan-Dashboard an. Fügen Sie --headless hinzu, um stattdessen einfache Fortschrittszeilen anzuzeigen. CI und Terminals ohne interaktive Sitzung verwenden automatisch die einfache Fortschrittsanzeige.

Das Dashboard zeigt außerdem Live-Sitzungsdetails an. Diese können Quellcode oder Anmeldedaten enthalten. Prüfen Sie sie daher vor der Weitergabe.

Standardmäßig schreibt die CLI den Scanfortschritt und die Abschlusszusammenfassung nach stderr. Das vollständige Scanergebnis wird nicht nach stdout ausgegeben. Ein abgeschlossener Scan gibt eine Zusammenfassung wie die folgende aus:

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

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

Token-Nutzung und geschätzte Kosten werden angezeigt, sofern verfügbar. Fordern Sie ausdrücklich eine strukturierte Ausgabe an, um das vollständige Ergebnis als maschinenlesbares JSON auszugeben:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

Scans dienen standardmäßig nur der Berichterstellung, sodass Befunde zur lokalen Prüfung verfügbar bleiben. Wenn Sie bereit sind, Scans in CI auszuführen, können Sie einen Schweregrad-Schwellenwert hinzufügen.

Modell und Reasoning-Aufwand auswählen

Scans verwenden standardmäßig gpt-5.6-sol mit dem Reasoning-Aufwand xhigh. Wählen Sie ein anderes Modell und einen anderen Aufwand aus, wenn die Aufgabe dies erfordert:

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Unterstützte Aufwandsstufen sind minimal, low, medium, high, xhigh und max.

Ergebnisse prüfen

Öffnen Sie report.md, um das lesbare Ergebnis anzuzeigen. Das Scanverzeichnis enthält außerdem die von Automatisierungen verwendeten strukturierten Dateien:

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json erfasst das Ziel, den Umfang, den Ersteller und die versiegelten Artefakte.
  • findings.json erfasst für jeden Befund Schweregrad, Konfidenz, Fundstellen, Nachweise und Abhilfemaßnahmen.
  • coverage.json erfasst geprüfte Bereiche, Ausschlüsse, zurückgestellte Arbeiten, offene Fragen und die Vollständigkeit der Abdeckung.

Die Abdeckung kann complete, partial oder unknown sein. Lesen Sie alle zurückgestellten Bereiche und offenen Fragen, bevor Sie den Scan als Nachweis einer Prüfung behandeln. Die CLI-Referenz beschreibt den vollständigen Vertrag für Artefakte und Ausgaben.

Befunde prüfen und korrigieren

Nach einem vollständigen interaktiven Scan mit Befunden bietet die CLI einen Befund- Browser an. Prüfen Sie die Nachweise und wählen Sie aus, welche Befunde behoben werden sollen. Die gespeicherten Aufgaben finden Sie in der Codex-Desktop-App.

So korrigieren Sie Befunde mit hohem und kritischem Schweregrad ohne den Browser:

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

Fügen Sie --create-pr hinzu, um verifizierte Korrekturen zu committen und einen GitHub Pull Request zu öffnen.

Sie können außerdem gespeicherte Befunde korrigieren oder Linear-Issues importieren. Weitere Informationen finden Sie in der Referenz zu validate und patch.

Nächsten Scan auswählen

Verwenden Sie einen Pfadscan, wenn ein Repository getrennte Dienste oder Pakete enthält:

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Prüfen Sie committete Änderungen zwischen der Basisrevision und HEAD:

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Prüfen Sie zum Staging vorgemerkte und nicht vorgemerkte Änderungen gegenüber HEAD:

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Bei Diff- und Working-Tree-Scans muss das Repository-Argument auf das Stammverzeichnis des Git- Worktrees verweisen. Rufen Sie die ausgewählten Revisionen ab, bevor Sie einen Diff-Scan starten.

Verwenden Sie den Tiefenmodus, wenn ein Repository oder Pfad umfassender geprüft werden muss:

npx @openai/codex-security scan "$REPOSITORY" --mode deep

So steuern Sie Worker, Subagents und den Zeitpunkt, zu dem der Scan beendet wird:

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

Diese Optionen erfordern den Tiefenmodus, der Repository- und Pfadziele unterstützt, nicht jedoch Diff- oder Working-Tree-Scans. Hier steuert --workers unabhängige Standardscan-Worker innerhalb eines Scans; bulk-scan --workers steuert gleichzeitig ausgeführte Repository-Scans. --max-time-hours akzeptiert eine positive Zahl bis 96, einschließlich Bruchteilen von Stunden. Beim Erreichen des Limits beendet der Scan nicht abgeschlossene Worker, bewahrt abgeschlossene Scanergebnisse auf und fasst sie im Abschlussbericht zusammen.

Architektur- und Sicherheitskontext hinzufügen

Stellen Sie Architekturdokumente, Bedrohungsmodelle oder Sicherheitsrichtlinien als Scan- Kontext bereit. Dadurch kann Codex Security Befunde anhand der tatsächlichen Funktionsweise Ihres Systems bewerten:

npx @openai/codex-security scan "$REPOSITORY" \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Benutzerdefinierte Scananweisungen hinzufügen

Fügen Sie Anweisungen hinzu, die den Scan auf Ihre Sicherheitsprioritäten ausrichten. Verwenden Sie eine zweite Datei für Folgeanweisungen:

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

Der Folgeschritt wird nach erfolgreichen Scans sowie nach Scans mit unvollständiger Abdeckung oder Fehlern in derselben authentifizierten Sitzung ausgeführt. Wenn der Folgeschritt fehlschlägt, meldet die CLI eine Warnung und behält den abgeschlossenen Scan bei. Nach einem Abbruch oder einem Scan, der sein Kostenlimit erreicht, wird er nicht ausgeführt. Beide Optionen funktionieren auch mit bulk-scan; eine CSV-Spalte prompt fügt Repository-spezifische Anweisungen hinzu.

Scanbudget festlegen

Verwenden Sie --max-cost, um einen Scan anzuhalten, wenn seine geschätzten Modellkosten ein Limit in USD überschreiten:

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Bereits laufende Anfragen können geringfügig über dem Limit abgeschlossen werden. Wenn ein Tiefen- scan das Limit erreicht, nachdem Codex Security die Ergebnisse abgeschlossener Worker zusammengefasst hat, speichert die CLI den abgeschlossenen Bericht, kennzeichnet dessen Abdeckung als partial und gibt den Exit-Code 2 zurück. Wenn der Scan keinen abgeschlossenen Bericht erstellen kann, bleiben alle verfügbaren Teilausgaben auf dem Datenträger erhalten.

Änderungen vor jedem Commit scannen

Installieren Sie eine Git-Pre-Commit-Sicherheitsprüfung für Ihr Repository:

npx @openai/codex-security install-hook

Die Prüfung scannt zum Staging vorgemerkte und nicht vorgemerkte Änderungen vor jedem Commit. Sie blockiert Befunde mit hohem Schweregrad und Scanfehler, ohne ein vorhandenes Pre-Commit-Skript zu ersetzen.

Repositorys gesammelt scannen

Melden Sie sich bei GitHub an, bevor Sie Repositorys suchen:

gh auth login

Suchen und wählen Sie Repositorys aus Ihrem GitHub-Konto oder Ihrer Organisation aus:

npx @openai/codex-security bulk-scan

Der interaktive Ablauf schließt archivierte Repositorys und Forks aus. Sie werden aufgefordert, die ausgewählten Repositorys vor dem Scannen zu bestätigen.

Um eine vorbereitete Repository-Liste zu scannen, stellen Sie eine CSV und ein Ausgabeverzeichnis bereit:

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

Führen Sie denselben Befehl erneut aus, um einen vorhandenen Massenscan fortzusetzen. Codex Security überspringt abgeschlossene Repositorys. Fügen Sie --max-attempts 3 hinzu, wenn Sie vorübergehende Repository- oder Scanfehler erneut versuchen möchten.

Informationen zur GitHub-Suche, CSV-Vorbereitung, zu Kampagnenergebnissen und zur Docker-Einrichtung finden Sie unter Massensicherheits-Scans ausführen.

Massenscans in Docker ausführen

Wenn Ihr Zugriff das Docker-Image von Codex Security umfasst, verwenden Sie die bereitgestellte gehärtete Compose-Konfiguration und das Sicherheitsprofil auf einem Linux-Docker-Host. Der Host muss die Erstellung nicht privilegierter Benutzer-Namespaces unterstützen. Stellen Sie eine Repository- CSV bereit, bewahren Sie Ergebnisse und Anmeldestatus in persistent eingebundenen Verzeichnissen auf und stellen Sie Anmeldedaten über Ihre Umgebung oder einen Geheimnismanager bereit:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Der Container führt Massenscans ohne interaktive Eingabeaufforderungen aus. Verwenden Sie die CLI außerhalb von Docker, wenn Sie Repositorys interaktiv suchen möchten. Stellen Sie für private Repositorys GH_TOKEN oder GITHUB_TOKEN über Ihre Umgebung oder einen Geheimnismanager bereit. Die Anmeldeanforderungen, einschließlich Konto- und Repository-Zugriff, gelten auch für containerisierte Scans.

Einen gespeicherten Scan erneut aufrufen

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

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

Kopieren Sie eine Scan-ID aus den Ergebnissen, um die Befunde und die Konfiguration zu untersuchen:

npx @openai/codex-security scans show SCAN_ID

So untersuchen Sie die gespeicherten Ereignisse eines Scans und seiner Worker:

npx @openai/codex-security scans logs SCAN_ID

Gespeicherte Protokolle sind nicht anonymisiert und können Quellcode oder Anmeldedaten enthalten. Prüfen Sie sie vor der Weitergabe.

Listen Sie offene Befunde aus allen Scans des Repositorys auf:

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

Ein früherer Befund bleibt offen, wenn der neueste Scan ihn nicht bestätigt.

Um einen geprüften Befund als falsch positiv zu kennzeichnen, erläutern Sie, warum der Befund nicht zutrifft:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Spätere Scans berücksichtigen diese Erklärung, prüfen den aktuellen Code jedoch weiterhin erneut.

Führen Sie denselben Scan mit seiner ursprünglichen Konfiguration für den aktuellen Checkout aus:

npx @openai/codex-security scans rerun SCAN_ID

Vergleichen Sie zwei Scans, um neue, fortbestehende, erneut geöffnete, behobene oder unbekannte Befunde zu ermitteln:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Der Vergleich ordnet Befunde automatisch anhand ihrer Grundursache zu und verwendet gespeicherte Zuordnungen erneut.

Informationen zum CSV-Format für Massenscans, zu Scanverlaufsfiltern und Befehlsoptionen finden Sie in der CLI-Referenz.

Fahren Sie mit dem Workflow fort, der zu Ihrem Ziel passt: