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

CLI-Referenz für Codex Security

Argumente, Ausgabeformate, Scan-Artefakte und Exitcodes der CLI für Codex Security.

Hier erfährst du, welche Befehle, Flags und Ausgabeformate codex-security unterstützt und welche Exitcodes die CLI zurückgibt. Folge für deinen ersten Scan dem CLI-Schnellstart.

Scans verwenden deine lokalen Berechtigungen und warten nicht auf eine Genehmigung. Für bestimmte Cybersicherheitsanfragen und geschützte Befunde benötigst du Trusted Access for Cyber. Weitere Informationen findest du unter Berechtigungen für lokale Scans.

Starte die CLI mit npx @openai/codex-security. Das installierte Paket stellt auch den Alias cs bereit.

Befehlsübersicht

usage: codex-security [--version] <command> [options]

Die CLI bietet folgende Befehle:

Befehl Zweck
codex-security scan Einen Scan mit Codex Security ausführen.
codex-security scan import Befunde aus CSV oder JSON als Scan speichern.
codex-security import github Warnmeldungen aus dem Code-Scanning von GitHub lesen.
codex-security policy Eine Sicherheitsrichtlinie für das Repository entwerfen oder aktualisieren.
codex-security init Eine Projektkonfiguration in YAML oder JSON erstellen.
codex-security install-hook Einen Sicherheitsscan installieren, der vor jedem Git-Commit läuft.
codex-security bulk-scan Repositorys finden und fortsetzbare Sammelscans ausführen.
codex-security scan-components Projektkomponenten separat scannen.
codex-security scans Gespeicherte Scans auflisten, untersuchen und vergleichen sowie ihre Protokolle abrufen.
codex-security findings Gespeicherte Sicherheitsbefunde prüfen und aktualisieren.
codex-security export Befunde oder ein gespeichertes Bedrohungsmodell exportieren.
codex-security publish Einen gespeicherten Scan prüfen oder veröffentlichen oder externe Befunde importieren.
codex-security classify-severity Gespeicherte Befunde anhand eines Bewertungsschemas nach Schweregrad einstufen.
codex-security suggest-owners Anhand von CODEOWNERS und dem Git-Verlauf Zuständige für Befunde vorschlagen.
codex-security dedupe Gespeicherte Befunde deduplizieren.
codex-security validate Einen oder mehrere mögliche Sicherheitsbefunde prüfen.
codex-security patch Ein oder mehrere Sicherheitsprobleme beheben.
codex-security verify-fix Prüfen, ob gemeldete Probleme behoben sind.
codex-security feedback Feedback an OpenAI senden und eine Feedback-ID zurückgeben.
codex-security login Dich anmelden, Zugangsdaten speichern oder den Anmeldestatus prüfen.
codex-security logout Die gespeicherte Anmeldung entfernen.
codex-security info Metadaten des SDK und des mitgelieferten Plugins ohne Schreibzugriff anzeigen.

Für Integrationen bietet die CLI außerdem folgende Befehle:

Befehl Zweck
codex-security completions Skripte für die automatische Vervollständigung in der Shell generieren.
codex-security mcp Die CLI als MCP-Server registrieren.
codex-security skills Skills von Codex Security mit deinen Agenten synchronisieren.

Liste alle verfügbaren Befehle auf:

npx @openai/codex-security --help

Ergänze einen Befehl um --help, um seine Argumente und Optionen anzuzeigen:

npx @openai/codex-security scan --help

codex-security --version gibt die installierte Version aus und beendet sich. codex-security info --json zeigt die Versionen des SDK und des mitgelieferten Plugins an. Beide Befehle funktionieren ohne Python. Mit codex-security --update aktualisierst du die installierte CLI.

Befehle erkunden und Agenten anbinden

Gib das für Agenten lesbare Befehlsmanifest aus:

npx @openai/codex-security --llms

Zeige das Schema der Scan-Argumente als JSON an:

npx @openai/codex-security scan --schema --format json

Generiere das Skript für die automatische Vervollständigung in Bash:

npx @openai/codex-security completions bash

Ersetze bash durch zsh oder fish, wenn du eine dieser Shells verwendest.

Für Scan-Ergebnisse stehen --format toon|json|yaml|jsonl und --full-output zur Verfügung. Mit --export-format wählst du das Format eines Artefakts, das du aus einem abgeschlossenen Scan exportierst. Die allgemeine Befehlshilfe führt auch md auf, Scan-Ergebnisse lassen sich aber nicht als Markdown ausgeben.

Registriere die CLI als MCP-Server:

npx @openai/codex-security mcp add

Synchronisiere die Skills von Codex Security mit deinen Agenten:

npx @openai/codex-security skills add

Über ihren MCP-Server stellt die CLI ausschließlich den Metadatenbefehl info ohne Schreibzugriff bereit. Scans, Exporte, Veröffentlichungen, Authentifizierung, Validierung und Patches sind nur über die CLI verfügbar.

codex-security scan

Scanne ein Repository, ausgewählte Pfade, Änderungen aus Commits oder den Arbeitsbaum.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--config FILE]
                           [--cyber-access-program PROGRAM]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH] [--scan-prompt-file FILE]
                           [--validation-prompt-file FILE] [--rubric FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--max-time MINUTES]
                           [--model MODEL]
                           [--effort EFFORT]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--validate] [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--show-cost] [--dry-run] [--mock]
                           [--workflow-id ID] [--safety-identifier ID]
                           [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

Ohne Angabe von repository verwendet die CLI das aktuelle Verzeichnis.

Projektkonfiguration laden

Erstelle eine Ausgangskonfiguration und wähle sie ausdrücklich aus:

npx @openai/codex-security init codex-security.yaml
npx @openai/codex-security scan . --config codex-security.yaml

init überschreibt keine vorhandene Datei. Verwende -c FILE als Kurzform für --config FILE oder setze CODEX_SECURITY_PROJECT_CONFIG. Ein ausdrücklich gesetztes Flag hat Vorrang vor der Umgebungsvariablen. Die CLI sucht nicht automatisch nach einer Projektdatei.

Wähle nur eine Konfiguration, die du kontrollierst. Sie hat dieselben Befugnisse wie CLI-Optionen. Native Codex-Einstellungen können MCP-Serverprozesse starten und festlegen, an welche Dienste Modellanfragen gehen. Verwende keine Datei, die ein nicht vertrauenswürdiges Repository oder ein nicht vertrauenswürdiger Pull Request vorgibt. Bewahre die Scannerkonfiguration in CI außerhalb des zu prüfenden Checkouts auf. Einzelheiten zu Einstellungen und ihrer Rangfolge findest du im Leitfaden zur Projektkonfiguration.

Authentifizierung für Scans auswählen

Mit der Standardeinstellung --auth auto wählt die CLI die Zugangsdaten automatisch aus. Wenn sowohl eine ChatGPT-Anmeldung als auch OPENAI_API_KEY oder CODEX_API_KEY verfügbar sind, fragen interaktive Scans mit Textausgabe, welche Zugangsdaten sie verwenden sollen. Scans in CI, Scans mit JSON- oder JSONL-Ausgabe und andere Scans ohne interaktives Terminal verwenden den API-Schlüssel aus der Umgebung. Probeläufe fragen nicht nach Zugangsdaten und laden auch keine.

Mit --auth chatgpt verwendest du deine gespeicherten Zugangsdaten:

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

Mit --auth api-key verwendest du einen API-Schlüssel aus der Umgebung:

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

Verwende für einen Scan mit Daybreak Blue einen API-Schlüssel aus einem Projekt, für das Daybreak Blue aktiviert ist, und ergänze den Befehl um --model gpt-6-sol --cyber-access-program daybreak_blue. Angaben zu anderen Modellen findest du in der Tabelle der Modelle und Zugangsprogramme.

Damit die CLI standardmäßig die gespeicherten Zugangsdaten auswählt, führe unset OPENAI_API_KEY CODEX_API_KEY aus.

Scans einzelnen Personen zuordnen

Wenn du im Auftrag anderer Personen scannst und dich mit einem API-Schlüssel authentifizierst, kannst du mit --safety-identifier ID eine stabile, gehashte Kennung übergeben. Verwende 1–64 Zeichen ohne NUL-Zeichen oder personenbezogene Daten wie E-Mail-Adressen.

Wähle für die Weitergabe der Kennung mit CODEX_CLI_PATH einen Codex-Build, der diese Option unterstützt, und verwende ein Plugin, das die Kennung an die Worker weitergibt. Die mitgelieferte Codex-Laufzeit unterstützt die Option nicht.

OpenRouter oder Fireworks verwenden

Wähle OpenRouter mit dem zugehörigen API-Schlüssel und gib ein Modell an:

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

Wähle Fireworks mit dem zugehörigen API-Schlüssel und gib ein Modell an:

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

Beide Anbieter unterstützen auch bulk-scan.

Amazon Bedrock verwenden

Verwende --provider amazon-bedrock und eine Bedrock-Modell-ID mit scan oder bulk-scan. Bedrock-Scans verwenden AWS-Zugangsdaten. Du brauchst dafür weder --auth noch eine OpenAI-Anmeldung oder einen OpenAI-API-Schlüssel.

Daybreak Blue und Daybreak Red

Beantrage den Zugang zu Daybreak über dein OpenAI-Account-Team oder über den Zugangsantrag für Unternehmen. Die Genehmigung für Daybreak Red umfasst den Zugriff auf GPT-5.6 Cyber. Sobald OpenAI deinen Antrag genehmigt hat, bitte dein AWS-Account-Team, das Modell in dem Konto bereitzustellen, das du für Scans verwendest.

Zugang Bedrock-Modell-ID AWS-Region
Daybreak Blue openai.gpt-daybreak-blue-5.6-sol us-east-2
Daybreak Red openai.gpt-5.6-cyber us-east-2

Informationen zur Verfügbarkeit findest du in den AWS-Modellkarten für Daybreak Blue und Daybreak Red.

Wähle ein AWS-Profil mit Zugriff auf das Modell. Führe für Daybreak Blue die folgenden Befehle aus:

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-daybreak-blue-5.6-sol --effort high

Führe für Daybreak Red die folgenden Befehle aus:

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-cyber --effort high

Du kannst dich auch mit AWS_BEARER_TOKEN_BEDROCK oder der standardmäßigen AWS-Anmeldeinformationskette authentifizieren. Temporäre Zugriffsschlüssel erfordern AWS_SESSION_TOKEN. Setze die Zugangsdaten und AWS_REGION in derselben Shell oder demselben CI-Job, in dem der Scan läuft.

Lokale Ergebnisse und Zugriffsprüfung

Gespeicherte lokale Berichte, scans show und export lassen sich ohne Cloud-Zugangsdaten nutzen.

info und scan --dry-run prüfen weder die AWS-Zugangsdaten noch den Modellzugriff. Führe einen Scan aus, um den Zugriff zu prüfen. Wenn die AWS-Authentifizierung fehlschlägt oder AWS den Zugriff verweigert, prüfe deine Zugangsdaten, die Region und die Modellberechtigungen.

Kostenschätzungen für Bedrock

Für die oben aufgeführten Modell-IDs von Daybreak Blue und Daybreak Red unterstützt die CLI Kostenschätzungen und --max-cost. Die Schätzungen basieren auf den AWS-Standardpreisen einschließlich der AWS-Gebühr. Das Kostenlimit bezieht sich auf estimatedUsd, den Basiswert für kurze Kontexte. Bereits laufende Anfragen können dazu führen, dass die Schätzung das Limit überschreitet. Bei langen Kontexten kann der ausgewiesene Kostenbereich estimatedUsdRange aufgrund der Preisgestaltung darüber liegen. Das Limit begrenzt nicht den Rechnungsbetrag.

Scan-Ziel auswählen

Wähle für jeden Scan genau einen Zieltyp.

Argument Beschreibung
--path PATH Scannt einen Pfad relativ zum Repository. Wiederhole das Flag für weitere Pfade.
--diff BASE Scannt Änderungen aus Commits von BASE bis --head. Die Zielrevision ist standardmäßig HEAD.
--head HEAD Legt die Zielrevision für --diff fest.
--working-tree Scannt Änderungen innerhalb und außerhalb des Staging-Bereichs im Vergleich zu --base. Die Basis ist standardmäßig HEAD.
--base BASE Legt die Basisrevision für --working-tree fest.
--mode {standard,deep} Wählt den Scan-Modus. Standardwert ist standard.

--path, --diff und --working-tree schließen sich gegenseitig aus. --head erfordert --diff und --base erfordert --working-tree. Im Modus für eingehende Scans kannst du Repositorys und Pfade als Ziele wählen.

Bei Scans von Diffs oder des Arbeitsbaums muss das Repository-Argument auf das Stammverzeichnis des Git-Worktrees verweisen. Die gewählten Git-Referenzen müssen in diesem Checkout vorhanden sein.

Scanne das gesamte Repository:

npx @openai/codex-security scan .

Scanne ausgewählte Pfade:

npx @openai/codex-security scan . --path src --path tests

Scanne Änderungen aus Commits:

npx @openai/codex-security scan . --diff origin/main --head HEAD

Scanne Änderungen innerhalb und außerhalb des Staging-Bereichs:

npx @openai/codex-security scan . --working-tree --base HEAD

Prüfe das Repository eingehender:

npx @openai/codex-security scan . --mode deep

Eingehende Scans konfigurieren

Mit diesen Optionen steuerst du bei --mode deep die Suche nach Sicherheitsproblemen:

Argument Beschreibung
--workers N Höchstzahl der Standardprüfungen, die gleichzeitig laufen. Standardwert ist 4.
--subagents N Anzahl der Subagenten pro Worker. Standardwert ist 3. Mit 0 deaktivierst du sie.
--stop-after-no-new N Beendet die Suche, wenn N aufeinanderfolgende abgeschlossene Worker-Scans keine neuen Probleme finden. Standardwert ist 4.
--max-discovery-runs N Höchstzahl der gestarteten Prüfungen. Fehlgeschlagene Versuche zählen mit. Standardwert ist 40.
--max-time MINUTES Zeitlimit für die Suche in Minuten. Positive Werte mit Nachkommastellen sind zulässig. Standard- und Höchstwert sind 5.760 Minuten.

So setzt du zwei Worker ein, lässt bis zu zehn Durchläufe zu und beendest die Suche nach spätestens 90 Minuten:

npx @openai/codex-security scan . \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time 90

Speichere diese Grenzwerte zur Wiederverwendung in einer Projektkonfigurationsdatei:

scan:
  mode: deep
  max_time_minutes: 90
  deep:
    workers: 2
    subagents_per_worker: 0
    stop_after_no_new: 3
    max_discovery_runs: 10

Befehlszeilenoptionen haben Vorrang vor der Projektkonfiguration. Mit scan.deep.stop_after_consecutive_errors legst du fest, nach wie vielen aufeinanderfolgenden Worker-Fehlern die Suche endet. Standardwert ist 3. Bei bulk-scan steuert --workers die Anzahl gleichzeitiger Repository-Scans.

Sicherheitskontext hinzufügen

Mit --knowledge-base PATH stellst du Architekturdokumente, Bedrohungsmodelle oder Sicherheitsrichtlinien bereit. Wiederhole die Option für weitere Dateien oder Verzeichnisse:

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

Unterstützt werden unter anderem UTF-8-Textdateien (einschließlich JSON und SARIF) sowie PDF- und DOCX-Dateien. Die CLI durchsucht Verzeichnisse rekursiv, lehnt Eingabepfade mit Verknüpfungen ab und überspringt verknüpfte Verzeichniseinträge. Damit sich der Scan fortsetzen lässt, speichert sie die extrahierten Dokumente in der privaten Datei .scan-knowledge.json neben den Scan-Artefakten. Bewahre diese Datei zusammen mit dem Scan-Verzeichnis auf. Die maßgeblichen Scan-Berichte enthalten den Dokumenttext nicht.

Scan-Anweisungen hinzufügen

Übergib mit --scan-prompt-file eine Text- oder Markdown-Datei mit Scan-Anweisungen. Mit --post-scan-prompt-file führst du nach einem erfolgreichen Scan oder einem Scan mit Fehlerrückgabe weitere Anweisungen in derselben authentifizierten Sitzung aus:

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

Beispielsweise kannst du den Scan-Prompt auf Berechtigungsgrenzen ausrichten und Codex in der Nachbereitung anweisen, eine neue Datei post-scan-summary.md im Scan-Verzeichnis anzulegen. Schlägt die Nachbereitung fehl, gibt die CLI eine Warnung aus und behält den abgeschlossenen Scan. Nach einem Abbruch oder beim Erreichen des Kostenlimits entfällt die Nachbereitung. Ihre Kosten werden weder in der Kostenerfassung des Scans noch bei --max-cost berücksichtigt.

Befunde in deiner Umgebung validieren

Mit --validation-prompt-file FILE ersetzt du den letzten Validierungsschritt durch dein eigenes Testverfahren. Codex prüft zuerst den Quellcode und überspringt die Validierung, wenn es keine möglichen Befunde findet. Lege den Prompt und das Testskript außerhalb des Checkouts in einem Verzeichnis ab, das du kontrollierst:

npx @openai/codex-security scan . \
  --validation-prompt-file /path/to/security-tests/validation.md

Wenn dein lokaler Testserver läuft, kannst du beispielsweise diese Anweisungen in validation.md aufnehmen:

Führe /path/to/security-tests/validate.sh mit http://localhost:3000 als Ziel aus.
Gib an, welche Befunde sich reproduzieren lassen, und füge die relevanten Testausgaben bei.

Verwende dieses Flag bei Standardscans für Repositorys, Pfade, Diffs oder den Arbeitsbaum. Für Standardscans einzelner Komponenten setze scan.validation_file in der Projektkonfiguration. Eingehende Scans lassen keine eigene Validierung zu.

Ergänze einen neuen Scan-Befehl um --validate, um jeden gemeldeten Befund separat und ausschließlich anhand des Quellcodes bewerten zu lassen. Meldet der Scan Befunde, schreibt die CLI die Bewertungen in einen Bericht im Scan-Verzeichnis. Die Bewertungen ändern weder die Befunde noch die Entscheidung anhand der Schweregradrichtlinie. Du kannst --validate nicht mit --dry-run, --mock oder einem Kostenlimit kombinieren, das du auf der Befehlszeile oder in der Projektkonfiguration festlegst.

Bewertungsschema für den Schweregrad auswählen

Standardscans und eingehende Scans verwenden standardmäßig das mitgelieferte Bewertungsschema für den Schweregrad. Mit --rubric FILE verwendest du deine eigene Richtlinie im Markdown-Format.

Ausgabe und Richtlinien konfigurieren

Mit diesen Optionen kannst du Artefakte speichern, frühere Ergebnisse aufbewahren oder ein maschinenlesbares Ergebnis erzeugen.

Argument Beschreibung
--output-dir DIR Schreibt Scan-Artefakte in ein privates Verzeichnis außerhalb des umgebenden Git-Worktrees. Standardmäßig verwendet die CLI den persistenten Speicher von Codex Security.
--archive-existing Verschiebt vorhandene Ergebnisse in ein Verzeichnis auf derselben Ebene und gibt den Archivpfad aus. Erfordert --output-dir.
--fail-on-severity LEVEL Gibt den Exitcode 1 zurück, wenn ein abgeschlossener Scan einen Befund mit mindestens dem gewählten Schweregrad critical, high, medium oder low meldet.
--patch Behebt ausgewählte Befunde nach einem vollständigen Scan und überprüft die Korrekturen.
--patch-severity LEVEL Behebt Befunde ab dem gewählten Schweregrad critical, high, medium oder low. Standardwert ist low.
--create-pr Erstellt einen Commit mit den überprüften Patch-Dateien und öffnet einen Pull Request auf GitHub oder einen Merge Request auf GitLab als Entwurf. Erfordert --patch.
--max-cost USD Stoppt den Scan, wenn die geschätzten Modellkosten den angegebenen Betrag in US-Dollar überschreiten.
--show-cost Zeigt die geschätzten Kosten in der Fortschritts- und Abschlussausgabe an.
--mock Speichert synthetische Befunde eines Standardscans ohne Modellaufruf.
--workflow-id ID Verwendet abgeschlossene Arbeit aus dem angegebenen lokalen Workflow für Befunde erneut.
--dry-run Prüft Repository, Ziel, Wissensbasis, Ausgabeverzeichnis und Codex-Konfiguration, ohne einen Scan zu starten.
--headless Zeigt den Fortschritt als Klartext statt im interaktiven Scan-Dashboard an.
--verbose Gibt zusätzliche Diagnoseinformationen zu Ablauf, Authentifizierung, Fortschritt und Kosten auf stderr aus.
--json Gibt Manifest, Befunde, von der Prüfung ausgeschlossene Einträge, Pfade und Metadaten der Interaktionsschritte als ein JSON-Dokument aus.
--format FORMAT Gibt das vollständige Scan-Ergebnis als toon, json, yaml oder jsonl aus.
--full-output Gibt das vollständige Ergebnis im standardmäßigen strukturierten Ausgabeformat aus.

Der Mock-Modus unterstützt Standardscans von Repositorys, Pfaden und Diffs. Du kannst ihn nicht mit --dry-run, --patch, dem Modus für eingehende Scans, eigener Validierung oder Prompts für die Nachbereitung kombinieren. Scan-Prompts und Wissensbasen ändern die synthetischen Befunde nicht. Verwende ein separates CODEX_SECURITY_STATE_DIR, damit Mock-Ergebnisse nicht in deinem Scan-Verlauf erscheinen.

Das Kostenlimit bezieht sich auf estimatedUsd, den Basiswert für kurze Kontexte. Bereits laufende Anfragen können dazu führen, dass die Schätzung das Limit überschreitet. Bei langen Kontexten kann estimatedUsdRange aufgrund der Preisgestaltung darüber liegen. Das Limit begrenzt nicht den Rechnungsbetrag.

Erreicht ein eingehender Scan das Kostenlimit nach der Suche nach Sicherheitsproblemen, kann die CLI das abgeschlossene Ergebnis mit einer Budgetwarnung versiegeln. Unter scan.scope.limitations im Manifest siehst du, ob der Scan die Validierung zurückgestellt hat. Ein abgeschlossener Scan gibt 0 zurück oder 1, wenn Befunde den konfigurierten Schweregrad erreichen oder überschreiten. Kann die CLI das Ergebnis nicht abschließen, gibt sie 2 zurück und behält alle vorhandenen Ausgaben.

Ohne --output-dir bleiben die Ergebnisse unter $CODEX_HOME/state/plugins/codex-security/scans/<repository> gespeichert. CODEX_HOME ist standardmäßig ~/.codex. Setze CODEX_SECURITY_STATE_DIR, um Ergebnisse unter $CODEX_SECURITY_STATE_DIR/scans/<repository> zu speichern. Diese Verzeichnisse können Quellcodeauszüge und Einzelheiten zu Schwachstellen enthalten. Lege Berechtigungen und Aufbewahrungsfristen entsprechend fest.

Die Workbench speichert den Scan-Verlauf in $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Wenn du CODEX_SECURITY_STATE_DIR setzt, ändert sich auch der Speicherort der Workbench-Datenbank.

Das Ausgabeverzeichnis muss außerhalb des gescannten Verzeichnisses und aller umgebenden Git-Worktrees liegen. Verwende --archive-existing, um frühere Ergebnisse zu sichern, bevor du ein Ausgabeverzeichnis erneut verwendest:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

Standardmäßig erstellen Scans nur Berichte. Ergänze --fail-on-severity, um in CI eine Schweregradrichtlinie auszuwerten:

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

Ein Probelauf prüft lokale Eingaben einschließlich der Dokumente der Wissensbasis. Dabei lädt er keine Zugangsdaten, startet Codex nicht und prüft den Python-Interpreter des Plugins nicht:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Laufzeit konfigurieren

Mit den Laufzeitoptionen wählst du ein Modell, einen Interpreter, ein Plugin oder einen Codex-Konfigurationswert aus.

Argument Beschreibung
--auth {auto,chatgpt,api-key} Wählt die Zugangsdaten für den Scan. Standardwert ist auto.
--provider {openai,openrouter,fireworks,amazon-bedrock} Wählt den Inferenzanbieter. Standardwert ist openai.
--cyber-access-program PROGRAM Verwende für Scans mit OpenAI standard, daybreak_blue oder daybreak_red.
--model MODEL Wählt das Modell. Standardwert ist gpt-5.6-sol. Für OpenRouter, Fireworks und Amazon Bedrock musst du ein Modell angeben.
--effort EFFORT Wählt den Reasoning-Aufwand des Modells. Standardwert ist xhigh. Die unterstützten Werte hängen vom Modell und Anbieter ab.
--plugin-path PATH Verwendet ein Plugin-Verzeichnis oder ZIP-Archiv für Codex Security anstelle des mitgelieferten Plugins.
--python PATH Wählt den Python-Interpreter für die Plugin-Laufzeit.
--codex KEY=VALUE Überschreibt einen Wert in der isolierten Codex-Konfiguration. Werte verwenden TOML-Syntax. Wiederhole das Flag für weitere Werte.

Codex Security akzeptiert Modell-IDs und Werte für den Reasoning-Aufwand als Zeichenfolgen. Welche Kombinationen unterstützt werden, hängt vom Modell, vom Anbieter, von der Codex-Version und von deinen Zugangsdaten ab.

Um ein Codex-Profil aus einer Datei wiederzuverwenden, speichere seine Einstellungen in $CODEX_HOME/review.config.toml (standardmäßig ~/.codex/review.config.toml). Wähle es mit --codex "profile='review'" aus oder setze codex.profile in deiner Projektkonfiguration auf review. Ausdrücklich festgelegte Scan-Einstellungen haben Vorrang vor den Werten der Profildatei. Diese haben wiederum Vorrang vor den Standardwerten des Scanners. Ergänze deinen Scan-Befehl um --dry-run --verbose, um vor dem Scan das tatsächlich gewählte Modell und den Reasoning-Aufwand zu prüfen.

Um Modell und Reasoning-Aufwand festzulegen, wähle ein Codex-Modell, auf das dein Konto Zugriff hat:

npx @openai/codex-security scan . --model gpt-6.1-sol --effort medium

Setze Zeichenfolgen, die du mit --codex übergibst, in Anführungszeichen, damit der TOML-Parser sie als Zeichenfolgen erkennt:

npx @openai/codex-security scan . --codex 'model="gpt-6.1-sol"'

Die CLI gibt Modell und Reasoning-Aufwand unverändert an Codex weiter. Bei nicht unterstützten Kombinationen erhältst du eine Fehlermeldung von Codex oder vom Anbieter. Die CLI wechselt nicht zu einem anderen Modell oder Reasoning-Aufwand.

codex-security scan import

Speichere vorhandene Befunde als abgeschlossenen Scan im lokalen Verlauf, ohne eine Sicherheitsanalyse oder Modellaufrufe auszuführen. Der Import erfordert keine Authentifizierung für den Modellzugriff.

usage: codex-security scan import (--csv FILE | --json FILE)
                                  [--output-dir DIR] [--archive-existing]
                                  [--dry-run] [--format json]

Gib genau eine Eingabe an. CSV verwendet die Exportspalten von Codex Security. Als JSON akzeptiert die CLI ein vollständiges codex-security.findings-Dokument oder ein Objekt mit einem findings-Array, das dem Befundschema entspricht. Beliebige JSON-Ausgaben anderer Scanner und unverarbeitete Arrays mit GitHub-Warnmeldungen lassen sich nicht als Befunde speichern.

Speichere dieses synthetische Beispiel als findings.csv:

occurrence_id,finding_id,title,summary,severity,confidence,status,close_reason,note,remediation,path,start_line,end_line
occ_000000000000000000000001,csf_000000000000000000000001,Missing authorization check,The route reads a record without checking ownership,high,high,open,,,Check record ownership before returning data,src/routes.ts,18,18

Validiere die Datei und importiere sie anschließend:

npx @openai/codex-security scan import --csv findings.csv --dry-run --format json
npx @openai/codex-security scan import --csv findings.csv --format json

Der Probelauf meldet dryRun: true und findingCount: 1, ohne einen Scan zu speichern. Der Import gibt die ID des gespeicherten Scans und die Ergebnispfade zurück. So importierst du stattdessen JSON:

npx @openai/codex-security scan import --json findings.json --format json

Bei diesem Befehl wählt --json FILE die Eingabedatei aus. Verwende --format json für die JSON-Ausgabe.

Option Verhalten
--csv FILE Liest Befunde im CSV-Exportformat von Codex Security.
--json FILE Liest ein Befunddokument oder ein Objekt mit einem findings-Array.
--dry-run Validiert die Eingabe, ohne einen Scan zu speichern.
--output-dir DIR Wählt das Artefaktverzeichnis. Standardmäßig verwendet die CLI den persistenten Speicher von Codex Security.
--archive-existing Archiviert vorhandene Ergebnisse vor dem Import. Erfordert --output-dir.

Verwende eine reguläre Eingabedatei ohne symbolische Links oder Verzeichnisverbindungen im Pfad. Jeder Import bewahrt die einzelnen Vorkommen der Befunde einschließlich Duplikaten auf und speichert die Eingabe unter artifacts/import/. Die ursprünglichen Kennungen stehen in extensions.import. Der Status „abgeschlossen“ bedeutet, dass der Import beendet ist. Er sagt nichts darüber aus, ob der Quellcode geprüft wurde. scans rerun SCAN_ID importiert die gespeicherte Eingabe erneut.

Um ein Repository namens import zu scannen, verwende scan ./import.

codex-security import github

Lies Warnmeldungen aus dem Code-Scanning von GitHub, ohne etwas auf GitHub zu ändern oder Code auszuchecken:

npx @openai/codex-security import github example/repository --format json > /path/outside/repository/alerts.json
npx @openai/codex-security import github example/repository \
  --github-alert 12 --github-alert 18 --format json

Ersetze example/repository durch dein Repository. Authentifiziere dich mit Zugangsdaten für die GitHub CLI, die Lesezugriff auf das Code-Scanning gewähren. Standardmäßig liest der Import offene Warnmeldungen des Standard-Branchs, einschließlich Meldungen aus SARIF-Uploads von Drittanbietern.

Option Verhalten
--github-alert NUMBER Wählt unabhängig vom Status genau die angegebene Warnmeldung aus. Wiederhole die Option für weitere Meldungen.
--github-ref REF Wählt eine Git-Referenz anstelle des Standard-Branchs.
--github-state STATE Listet Warnmeldungen für open, closed, dismissed, fixed oder all auf. Standardwert ist open.

Kombiniere einzelne Meldungsnummern nicht mit einem anderen Status als open. Der Befehl gibt die ursprünglichen Warnmeldungen als Array zurück und speichert keinen Scan. Führe im zugehörigen lokalen Repository codex-security validate /path/outside/repository/alerts.json aus, um die Meldungen zu bewerten. Speichere für die Validierung das vollständige JSON ohne Ausgabefilter oder Tokenlimits. Für Befunde, die bereits dem Schema von Codex Security entsprechen, verwende scan import. Zum Importieren von Dependabot-Warnmeldungen verwende publish findings.

codex-security install-hook

Installiere die CLI außerhalb des Repositorys, prüfe dessen vorhandenen Pre-Commit-Hook und führe die installierte CLI außerhalb des Checkouts aus:

git -C /path/to/repository rev-parse --git-path hooks/pre-commit
codex-security install-hook /path/to/repository

Vor jedem Commit prüft der Hook Änderungen innerhalb und außerhalb des Staging-Bereichs. Bei Befunden mit hohem oder kritischem Schweregrad sowie bei Scan-Fehlern blockiert er den Commit. Lokale Hooks sind optional. Wenn du die Prüfung durchsetzen möchtest, verwende einen verpflichtenden CI-Check. Überlasse eigene, verknüpfte oder gemeinsam genutzte Hooks und Hook-Verzeichnisse den dafür Verantwortlichen. Das Installationsprogramm ersetzt kein fremdes Pre-Commit-Skript. Bei Bedarf kannst du einen anderen Schweregrad als Schwelle festlegen:

codex-security install-hook /path/to/repository --fail-on-severity medium

codex-security policy

Entwirf eine Richtlinie in SECURITY.md, die die Sicherheitsgrenzen des Projekts beschreibt und festlegt, was als Befund gelten soll:

npx @openai/codex-security policy .
npx @openai/codex-security policy . --headless --json

Der Befehl speichert den Entwurf außerhalb des Repositorys und lässt vorhandene Dateien unverändert. Prüfe Entwurf, Diff und Prüfnotizen. Kopiere dann nur die geprüfte SECURITY.md an den angezeigten Zielpfad für die Richtlinie. Im Headless-Modus bleiben unbeantwortete Fragen in den Prüfnotizen stehen. Das Erstellen einer Richtlinie ist optional. Scans können eine vorhandene Richtlinie verwenden oder ohne Richtlinie laufen. Angaben zu Geltungsbereichen für Pfade und zu den Optionen findest du im Leitfaden zu Sicherheitsrichtlinien.

codex-security scan-components

Mit scan-components scannst du Dienste oder Pakete innerhalb eines Repositorys separat. Jeder Durchlauf benötigt ein neues oder leeres Ausgabeverzeichnis außerhalb des umgebenden Git-Worktrees, auch wenn du nur einen Plan erstellst. Lege das Verzeichnis mit --output-dir oder über output.directory in der Projektkonfiguration fest.

So scannst du beispielsweise zwei Dienste parallel:

npx @openai/codex-security scan-components . \
  --component apps/api --component apps/web \
  --output-dir /path/outside/repository/manual-components

Anders als scan --path führt dieser Befehl pro Komponente einen Scan aus. Anschließend führt er die Befunde zusammen und gleicht sie miteinander ab. Standardmäßig können vier Komponentenscans gleichzeitig laufen. Mit --workers N änderst du dieses Limit. --max-cost USD begrenzt die Kosten pro Komponentenscan. Die automatische Planung und der komponentenübergreifende Abgleich sind davon ausgenommen.

Wenn Codex eine Aufteilung vorschlagen soll, speichere vor dem Scan einen Plan zur Prüfung:

npx @openai/codex-security scan-components . --auto --plan-only \
  --output-dir /path/outside/repository/component-plan

Prüfe die Namen und Pfade der Komponenten in components.json und führe den gespeicherten Plan mit einem neuen Ausgabeverzeichnis aus:

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/component-plan/components.json \
  --output-dir /path/outside/repository/components

Öffne report.md im Ausgabeverzeichnis, um die zusammengeführten Befunde zu prüfen. Schlägt der Scan einer Komponente fehl, kannst du mit dem gespeicherten Wiederholungsplan nur die fehlgeschlagenen Komponentenscans erneut ausführen:

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/components/retry-components.json \
  --output-dir /path/outside/repository/retry-results

Der neue Bericht umfasst nur die erneut gescannten Komponenten. Bewahre den ursprünglichen Bericht auf, um die Befunde der bereits im ersten Durchlauf erfolgreich gescannten Komponenten prüfen zu können.

Bei Fehlern im Scan oder beim Abgleich gibt die CLI 2 zurück, bei Verstößen gegen die Schweregradrichtlinie 1. Informationen zur Plansyntax und zu Wiederholungsversuchen findest du im Leitfaden zu Komponentenscans.

codex-security bulk-scan

Suche und scanne GitHub-Repositorys oder führe anhand einer CSV-Datei mit Repositorys einen fortsetzbaren Scan aus.

Informationen zur Suche auf GitHub, zu CSV-Inventaren, Kampagnenergebnissen und Scans in Containern findest du unter Sammelscans für die Sicherheitsprüfung ausführen.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort EFFORT]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Führe npx @openai/codex-security bulk-scan ohne Argumente aus, um Repositorys interaktiv auszuwählen. Dafür musst du bei der GitHub CLI angemeldet sein.

Wähle für die interaktive Suche ein Codex-Modell, auf das dein Konto Zugriff hat:

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

Wenn du bereits eine Liste mit Repositorys vorbereitet hast, gib eine CSV-Datei und --output-dir an:

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

Die CSV-Datei muss die Spalten id, repository und revision enthalten. Revisionen müssen vollständige Commit-Hashes sein. Über die optionalen Spalten scope, mode und prompt konfigurierst du einzelne Repositorys:

id,repository,revision,scope,mode,prompt
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Prüfe die Berechtigungsgrenzen.

Mit --knowledge-base PATH stellst du Sicherheitsdokumente für alle Repositorys bereit. Mit --scan-prompt-file FILE fügst du gemeinsame Scan-Anweisungen hinzu. Anweisungen aus der CSV-Spalte prompt folgen für das jeweilige Repository auf den gemeinsamen Prompt. --post-scan-prompt-file FILE führt nach jedem Scan weitere Anweisungen aus, auch wenn der Scan Fehler zurückgibt. Nach einem Abbruch oder beim Erreichen des Kostenlimits entfällt dieser Schritt.

--workers begrenzt die Anzahl gleichzeitiger Repository-Scans. Standardwert ist 4. Für --mode gilt standardmäßig standard, für --max-attempts gilt 1. Setze --max-attempts, um bei Repository- oder Scan-Fehlern weitere Versuche zuzulassen. Ausschlüsse und Hinweise aus der Nachbereitung lösen keine Wiederholung abgeschlossener Scans aus. Bleiben Ausführungsfehler bestehen, gibt die CLI 2 zurück. Bei abgeschlossenen Scans mit Verstößen gegen die Schweregradrichtlinie gibt sie 1 zurück.

Führe denselben Befehl erneut aus, um die Kampagne mit einem vorhandenen Ausgabeverzeichnis fortzusetzen. Die CLI überspringt abgeschlossene Scans. Mit --recover wiederholst du fehlgeschlagene oder unterbrochene Versuche in einer passenden Kampagne.

Informationen zu Kampagnen in Containern findest du unter Sammelscans in Docker ausführen.

codex-security scans

Gespeicherte Scans finden

Liste gespeicherte Scans für das aktuelle Verzeichnis auf:

npx @openai/codex-security scans

Liste Scans für ein anderes Repository auf:

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

Suche Scans, die unter einem bestimmten Ausgabeverzeichnis gespeichert sind:

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Einen Scan untersuchen oder wiederholen

Zeige die Ergebnisse und die Konfiguration eines gespeicherten Scans an:

npx @openai/codex-security scans show SCAN_ID

Ergänze --show-linked-findings, um Verknüpfungen zu Befunden früherer Scans einzubeziehen.

Führe einen gespeicherten Scan erneut aus:

npx @openai/codex-security scans rerun SCAN_ID

Beim erneuten Ausführen entsteht ein neuer Scan mit den gespeicherten Einstellungen und der zuvor gewählten Authentifizierungsmethode. Er verwendet den aktuellen Checkout und die aktuellen Kontextdateien. Er lädt keine Projektkonfigurationsdateien neu und verwendet keine gespeicherten Zugangsdaten aus dem früheren Scan. Falls der ursprüngliche Scan einen Scan-Prompt oder einen eigenen Validierungs-Prompt verwendet hat, gib die entsprechenden Dateien erneut mit --scan-prompt-file und --validation-prompt-file an.

Für die Wiederholung ist die im ursprünglichen Scan vermerkte Plugin-Version erforderlich. Weicht die installierte Version davon ab, bricht die CLI ab.

Gespeicherte Scan-Protokolle prüfen

Lies alle gespeicherten Sitzungsereignisse eines Scans und seiner Worker. Die Protokolle sind ungeschwärzt und können Quellcode oder Zugangsdaten enthalten. Prüfe sie, bevor du sie weitergibst:

npx @openai/codex-security scans logs SCAN_ID

Ergänze --json für eine strukturierte Ausgabe.

Befunde abgleichen und vergleichen

Vergleiche zwei Scans, um neue, fortbestehende, wieder geöffnete, nicht beobachtete, behobene und unbekannte Befunde zu ermitteln:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Beim Vergleich ordnet die CLI Befunde mit derselben Ursache automatisch einander zu und verwendet gespeicherte Zuordnungen erneut. Mit scans match speicherst du Zuordnungen ausdrücklich:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Ein Befund gilt als unbekannt, wenn sein Pfad ausgeschlossen oder seine Zuordnung unsicher ist. Findet der spätere Scan den Befund im geprüften Code nicht, gilt er als nicht beobachtet. Nur ein ausdrücklich als bereits behoben geschlossener Befund gilt als behoben. Ergänze --force bei match, wenn du eine vorhandene Zuordnung neu berechnen möchtest.

So gleichst du alle abgeschlossenen Scans für das aktuelle Repository ab, einschließlich Scans aus anderen Checkouts:

npx @openai/codex-security scans match --all

Scan-Ergebnisse können selbst bei wiederholten Scans mit derselben Konfiguration variieren. Mit Abgleich und Vergleich verfolgst du Veränderungen. Die Ergebnisse werden dadurch weder deterministisch noch lässt sich damit belegen, dass eine Schwachstelle nicht mehr besteht. Verwende validate, um einen sicherheitskritischen Befund anhand des aktuellen Codes erneut zu prüfen.

codex-security findings

Liste offene Befunde aus allen Scans des aktuellen Repositorys auf:

npx @openai/codex-security findings list

Gib einen Repository-Pfad an, um einen anderen Checkout zu untersuchen:

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

Ergänze --json für eine strukturierte Ausgabe. Die Liste kennzeichnet sowohl die im letzten Scan beobachteten Befunde als auch frühere Befunde, die dieser Scan nicht bestätigt hat.

Frühere Befunde bleiben offen, bis sie behoben oder verworfen werden. Wenn sie im letzten Scan fehlen, ist das kein Beleg für ihre Behebung.

So erfasst du einen geprüften Befund als Fehlalarm:

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Prüfe den gespeicherten Scan, um das konkrete Vorkommen des Befunds zu ermitteln:

npx @openai/codex-security scans show SCAN_ID

Gib konkret an, weshalb es sich um einen Fehlalarm handelt:

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

Die Begründung darf nicht leer sein. Codex Security speichert die Entscheidung für das Repository und stellt sie künftigen Scans als Kontext bereit. Jeder Scan prüft den aktuellen Quellcode, die Schutzmaßnahmen und die Erreichbarkeit erneut und unabhängig. Eine frühere Entscheidung unterdrückt weder Regeln noch Pfade oder Schwachstellenklassen.

codex-security export

Exportiere gespeicherte Befunde oder ein Bedrohungsmodell, ohne Codex zu starten oder Zugangsdaten zu laden. Befunde lassen sich nur aus einem abgeschlossenen, versiegelten Scan als CSV, JSON, SARIF oder ServiceNow-AVIT-CSV exportieren. Bedrohungsmodelle verwenden Markdown.

usage: codex-security export [scan_dir | --scan SCAN_ID]
                             [--artifact {findings,threat-model}]
                             [--export-format {csv,json,sarif,md,servicenow-avit}]
                             [--avit-template FILE]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH]

Lass scan_dir und --scan weg, um den letzten abgeschlossenen Scan des aktuellen Repositorys zu verwenden. Andernfalls gib ein gespeichertes Ergebnisverzeichnis an oder wähle mit --scan einen Scan anhand seiner ID oder eines eindeutigen Präfixes mit mindestens acht Zeichen aus. Beide Auswahlmethoden lassen sich nicht kombinieren.

Argument Beschreibung
--artifact {findings,threat-model} Wählt das gespeicherte Artefakt. Standardwert ist findings.
--scan SCAN_ID Wählt einen gespeicherten Scan anhand seiner ID, eines eindeutigen Präfixes mit mindestens acht Zeichen oder mit latest.
--export-format FORMAT Wählt csv, json, sarif, md oder servicenow-avit. Für Befunde ist sarif voreingestellt. Bedrohungsmodelle unterstützen nur md.
--avit-template FILE Gibt die für servicenow-avit erforderliche CSV-Vorlage an. Nur dieses Format akzeptiert die Vorlage.
--output FILE|- Schreibt das gewählte Format in eine Datei oder auf stdout. Standardziel ist eine Datei im aktuellen Verzeichnis.
--source-root PATH Fügt SARIF anhand eines Repository-Checkouts Fingerabdrücke der Quellcodezeilen hinzu.
--python PATH Wählt den Python-Interpreter für das mitgelieferte Exportprogramm.

--source-root funktioniert nur beim Export von Befunden als SARIF. Beim JSON-Export bleibt das versiegelte Befunddokument erhalten. CSV enthält übertragbare Befundspalten. Der lokale Bearbeitungsstand aus der Workbench ist darin nicht enthalten.

Ohne --output schreibt die CLI SARIF nach results.sarif, JSON nach findings.json, CSV nach findings.csv, ServiceNow-AVIT-CSV nach servicenow-avit.csv und Markdown nach threatmodel.md, jeweils im aktuellen Arbeitsverzeichnis. Exporte können Quellcodeauszüge und Einzelheiten zu Schwachstellen enthalten. Gib mit --output einen privaten Pfad außerhalb des Checkouts an. Wenn du den Befehl außerhalb des Repositorys ausführst, gib außerdem ein Ergebnisverzeichnis oder --scan an.

Befunde exportieren

Schreibe SARIF in eine Datei:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Gib SARIF auf stdout aus:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Exportiere Befunde als JSON:

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Exportiere Befunde als CSV:

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

Befunde für ServiceNow exportieren

Für ServiceNow benötigst du die Rolle Ethical Hacker (sn_vul.app_pen_tester). Öffne All > Manual AVIT Ingestion > Upload File UI und lade die CSV-Vorlage herunter. Behalte die ursprünglichen Spaltenüberschriften und genau eine Datenzeile bei. Verwende den exakten Anwendungsnamen aus ServiceNow. Gib Zweck, Arten sensibler Daten, Compliance-Programme, Technologie-Stack, Anwendungsteam und zu testende URLs an. Fülle Requested by, Assigned to und Assignment group aus. Lass die Befundfelder leer. Speichere die Vorlage als app.csv in einem privaten Verzeichnis außerhalb des gescannten Repositorys. Für weitere Scans derselben Anwendung kannst du sie erneut verwenden.

Exportiere im gescannten Repository die neuesten Befunde mit dieser Vorlage. Speichere auch die Ausgabe im privaten Verzeichnis:

npx @openai/codex-security export --scan latest \
  --export-format servicenow-avit \
  --avit-template /path/outside/repository/exports/app.csv \
  --output /path/outside/repository/exports/findings-avit.csv

Die CLI schreibt pro Befund eine Zeile. Liegt ein dokumentierter Angriffspfad vor, füllt sie damit Steps to reproduce aus. Prüfe diese Schritte und ergänze fehlende Angaben in der exportierten CSV-Datei. Öffne erneut Upload File UI, wähle Import File, lade die CSV-Datei hoch und wähle Submit. Bei jedem Upload entsteht ein neues Formular für einen Penetrationstest der Anwendung. Weitere Informationen findest du in der Upload-Anleitung von ServiceNow.

Ein gespeichertes Bedrohungsmodell exportieren

Gib das gespeicherte Bedrohungsmodell des letzten abgeschlossenen Scans ohne weiteren Modellaufruf auf stdout aus:

npx @openai/codex-security export --artifact threat-model --output -

Oder wähle einen Scan aus und speichere sein Modell in einer Datei:

npx @openai/codex-security export --scan SCAN_ID \
  --artifact threat-model \
  --output /path/outside/repository/exports/threatmodel.md

Wenn du einen Scan anhand seiner ID oder seines Verzeichnisses auswählst, kannst du auch aus einem nicht abgeschlossenen oder fehlgeschlagenen Scan ein gespeichertes Modell exportieren. Wurde kein Modell gespeichert, gibt der Befehl einen Fehler zurück. Prüfe Inhalte, die im Dokument als vorläufig oder wiederhergestellt gekennzeichnet sind, bevor du sie weiterverwendest.

Um das exportierte Modell als Kontext für einen weiteren Scan bereitzustellen, übergib seinen Pfad mit --knowledge-base.

codex-security publish scan

Veröffentliche ausgewählte Befunde eines abgeschlossenen Scans in Linear oder einem eigenen Dienst für Befunde. Die folgenden Optionen gelten für die Veröffentlichung in Linear:

usage: codex-security publish scan [SCAN_DIR] --to linear
                                   [--linear-team TEAM_ID]
                                   [--project PROJECT_ID]
                                   [--linear-api-key KEY]
                                   [--linear-assignee EMAIL_OR_USER_ID]
                                   [--dry-run] [--json]

SCAN_DIR muss einen abgeschlossenen, versiegelten Scan enthalten. Lass das Argument in einem interaktiven Terminal weg, um einen abgeschlossenen Scan aus dem lokalen Verlauf auszuwählen. Damit die CLI Issues erstellen kann, müssen der Scan und seine Befunde auch im lokalen Scan-Verlauf vorhanden sein. Ein Probelauf validiert die versiegelten Artefakte, ohne zu prüfen, ob sie im Verlauf gespeichert sind.

Verwende --scan SCAN_ID oder --scan latest anstelle eines Verzeichnisses, um einen gespeicherten Scan auszuwählen. Wiederhole --finding-id ID, um einzelne Befunde für Linear auszuwählen. Mit publish check SCAN_DIR und den Zieloptionen für Linear prüfst du Artefakte und dokumentierte Veröffentlichungen. Mit einem API-Schlüssel prüft der Befehl auch die Authentifizierung und den Zugriff auf das Ziel. Für den Zugriff über die verbundene App meldet er not-checked.

Argument Beschreibung
--to linear Veröffentlicht in Linear. Dieses Argument ist erforderlich.
--linear-team TEAM_ID Wählt das Linear-Team. Ohne Angabe verwendet die CLI CODEX_SECURITY_LINEAR_TEAM. Eine der beiden Angaben ist erforderlich.
--project PROJECT_ID Wählt ein Linear-Projekt. Ohne Angabe verwendet die CLI CODEX_SECURITY_LINEAR_PROJECT. Fehlen beide Angaben, erstellt sie die Issues direkt im Team.
--linear-api-key KEY Verwendet einen persönlichen Linear-API-Schlüssel für die direkte Veröffentlichung. Ohne Angabe verwendet die CLI CODEX_SECURITY_LINEAR_API_KEY.
--linear-assignee EMAIL_OR_USER_ID Weist erstellte Issues anhand der E-Mail-Adresse oder Linear-Benutzer-ID zu. Erfordert --linear-api-key oder CODEX_SECURITY_LINEAR_API_KEY. Ohne diese Zuweisungsoption bleiben die Issues unzugewiesen.
--dry-run Bereitet die Daten für die Issues vor, ohne Codex zu starten, Linear zu kontaktieren, Issues zu erstellen oder den Veröffentlichungsstatus zu speichern.
--skip-existing Überspringt Befunde, für deren konkretes Vorkommen im selben Linear-Team und Projekt bereits eine erfolgreiche Veröffentlichung dokumentiert ist. Erfordert den lokalen Verlauf.
--json Gibt strukturierte Veröffentlichungsergebnisse auf stdout aus. Fortschrittsmeldungen erscheinen weiterhin auf stderr.

Beschreibungen von Linear-Issues und die Ausgabe eines Probelaufs können Quellcodeauszüge und Einzelheiten zu Schwachstellen enthalten. Prüfe vor der Veröffentlichung, wer das Zielteam oder Zielprojekt einsehen kann.

Außer bei einem Probelauf versucht jeder Aufruf, für jeden ausgewählten Befund ein neues Issue zu erstellen. Eine Ausnahme gilt, wenn --skip-existing für das betreffende Vorkommen, Team und Projekt eine dokumentierte erfolgreiche Veröffentlichung findet. Die Option prüft keine Issues in Linear und erfasst weder undokumentierte noch gleichzeitige Veröffentlichungen. Schlägt die Veröffentlichung einzelner Befunde fehl, bleiben erfolgreich erstellte Issues erhalten und der Befehl gibt den Exitcode 2 zurück. Prüfe bei --json vor einem weiteren Versuch die Ergebnisse unter created und failed, um Duplikate zu vermeiden.

Sieh dir die Daten der Issues vor der Veröffentlichung an:

npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --dry-run \
  --json

Über die verbundene Linear-App veröffentlichen

Ohne Linear-API-Schlüssel startet der Befehl Codex mit deiner vorhandenen Konfiguration und der verbundenen Linear-App. Melde dich an und verbinde Linear mit deinem Codex-Konto, bevor du Befunde veröffentlichst:

npx @openai/codex-security login
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --project PROJECT_ID

Mit einem Linear-API-Schlüssel veröffentlichen

Wenn du --linear-api-key oder CODEX_SECURITY_LINEAR_API_KEY angibst, veröffentlicht die CLI direkt über die Linear-API, ohne Codex zu starten. Bei der direkten Veröffentlichung bleiben Issues unzugewiesen, sofern du keine zuständige Person angibst:

export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --linear-assignee teammate@example.com

Befehlszeilenwerte haben Vorrang vor den entsprechenden Umgebungsvariablen. Verwende für API-Schlüssel vorzugsweise CODEX_SECURITY_LINEAR_API_KEY anstelle von --linear-api-key, da Befehlszeilenargumente im Shell-Verlauf und in Prozesslisten sichtbar sein können.

In einem eigenen Dienst für Befunde veröffentlichen

Gib die URL deines vorhandenen Dienstes ausdrücklich an:

npx @openai/codex-security publish scan --scan latest \
  --to custom --findings-url http://localhost:3000

Bei der Veröffentlichung sendet die CLI die vollständigen versiegelten Befunde und die Ziel-ID des Repositorys. Befunde können Quellcodeauszüge, Belege und Einzelheiten zu Schwachstellen enthalten. Verwende HTTPS für Dienste außerhalb deines lokalen Rechners und ergänze --dry-run --json, um die Daten vor dem Senden zu prüfen.

Die CLI sendet keine Zugangsdaten für Modelle an eigene Dienste. Kümmere dich außerhalb der CLI um die gegebenenfalls erforderliche Authentifizierung. Einzelheiten zur Bereitstellung und zum Protokoll findest du im Leitfaden für Befunddienste.

codex-security publish findings

Du kannst die Befunde eines Scanners lokal speichern oder in Daybreak veröffentlichen.

Einen lokalen Bericht in der Vorschau prüfen und speichern

Exportiere beispielsweise Dependabot-Warnmeldungen in eine private Datei außerhalb des Checkouts. Gib mit --repository den zugehörigen Checkout an und verwende für --source-key einen gleichbleibenden Wert, damit spätere Importe dieselben Warnmeldungen aktualisieren. Hat der Checkout Git-Remotes mit Netzwerkadressen, muss mindestens eines davon auf das Repository verweisen, aus dem die Warnmeldungen stammen.

npx @openai/codex-security publish findings /path/to/dependabot.jsonl \
  --to local --repository ./project --provider github \
  --source-key github.com/OWNER/REPO/dependabot --dry-run --format json

npx @openai/codex-security publish findings /path/to/dependabot.jsonl \
  --to local --repository ./project --provider github \
  --source-key github.com/OWNER/REPO/dependabot

npx @openai/codex-security findings imported ./project --format json

Importierte Befunde erhalten zunächst den Bewertungsstatus not_assessed. Bei einem erneuten Import aktualisiert die CLI übereinstimmende Datensätze und behält vorhandene Befunde bei, die im neuen Bericht fehlen. Schließt die CLI nur einen Teil der Datensätze aus, endet die Vorschau mit 0. Der Import speichert in diesem Fall die angenommenen Datensätze und endet mit 1. Bei einem gültigen Bericht ohne Befunde lautet der Exitcode 0. Werden alle Datensätze ausgeschlossen, enden beide Befehle mit 2.

Einen Bericht in der Cloud veröffentlichen

Verwende dieselbe Datei, denselben Anbieter und denselben Quellschlüssel wie bei der lokalen Vorschau. Setze --to cloud, übergib mit --repository die URL des verbundenen Repositorys oder seine Cloud-ID und prüfe die Vorschau erneut mit --dry-run --format json. Führe den Befehl zur Veröffentlichung ohne --dry-run erneut aus und bestätige den Import.

Ziel in der Vorschau So prüfst du den Import
privateImport Die Befunde gehen an deine private Inbox. Das Repository ist als Ziel für die Bewertung vorgeschlagen. Prüfe, ob privateJob.status den Wert completed hat. Prüfe außerdem die Anzahl der Fehler und der unverarbeiteten Zeilen.
requests Prüfe für jede Anfrage die Zielumgebung. Sieh vor einem erneuten Versuch im Beleg nach, welche Datensätze verifiziert wurden, für welche die Empfangsbestätigung fehlt und bei welchen der Import fehlgeschlagen ist.

Gibt die CLI savedSubmission zurück, bewahre den Prüfpunkt auf und folge der Anleitung zum Fortsetzen eines unterbrochenen Cloud-Imports.

Befehle zur Prüfung von Befunden

Mit diesen Befehlen bearbeitest du vorhandene Befunde:

Befehl Beispiel Verhalten
classify-severity codex-security classify-severity --scan latest --rubric policy.md --json Bewertet den Schweregrad anhand des mitgelieferten Bewertungsschemas oder einer mit --rubric angegebenen Richtlinie neu. Die ursprünglichen Befunde bleiben erhalten.
suggest-owners codex-security suggest-owners findings.json --source-root /path/to/repository --json Liest den Quellcode aus Commits, CODEOWNERS, Git-Blame-Daten und den Git-Verlauf, um Zuständige vorzuschlagen. Weist keine Tickets zu.
dedupe codex-security dedupe --scan SCAN_ID --json Erkennt doppelte Befunde in der lokalen SQLite-Datenbank. Für fehlende oder veraltete Embeddings ist ein Embedding-API-Schlüssel erforderlich. Neue Prüfungen erfordern Modellzugriff.
verify-fix codex-security verify-fix --scan SCAN_ID --json Prüft vorhandene Korrekturen in einer Sandbox ohne Schreibzugriff. Akzeptiert Befund-IDs, Beschreibungen und Auswahlkriterien für Linear.

verify-fix gibt 2 zurück, wenn eine Prüfung kein eindeutiges Ergebnis liefert oder fehlschlägt. Andernfalls gibt der Befehl 1 zurück, wenn mindestens eine Schwachstelle fortbesteht, oder 0, wenn alle behoben sind. Mit --help beim jeweiligen Befehl findest du Auswahlkriterien, Modelleinstellungen und Ausgabeoptionen.

codex-security feedback

Sende eine Problembeschreibung an OpenAI. Du erhältst eine ID, die du dem Support mitteilen kannst:

npx @openai/codex-security feedback SCAN_ID \
  --reason "The scan stopped before it finished" --json

Ohne Scan-ID wählt der Befehl den zuletzt gestarteten Scan im aktuellen Repository, auch wenn dieser noch läuft oder fehlgeschlagen ist. Ist kein Scan vorhanden, sendet er einen allgemeinen Bericht. Berichte enthalten die Beschreibung, Versionsangaben sowie ausgewählte Scan- und Sitzungs-IDs. Protokolle sind standardmäßig ausgeschlossen. Ergänze --include-logs nur, wenn du den enthaltenen Quellcode, die Prompts, Befunde und Werkzeugausgaben mit OpenAI teilen kannst.

codex-security validate und codex-security patch

Bewerte mögliche Befunde anhand des Quellcodes im aktuellen Repository:

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

Erstelle mit dem mitgelieferten Skill zur Fehlerbehebung eine Korrektur:

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Jedes Positionsargument akzeptiert Text oder einen Dateipfad. Für diese Eingaben gilt das aktuelle Verzeichnis. validate bewertet Belege aus dem Quellcode in einer Sandbox ohne Schreibzugriff. Der Befehl erstellt keinen Build des Ziels, führt weder Anwendungscode noch Tests oder Machbarkeitsnachweise aus und kontaktiert keine Dienste. Standardscans, eingehende Scans und Diff-Scans behalten ihre eigenen Validierungsabläufe. patch behebt und überprüft Befunde weiterhin.

Verwende validate, um einen Befund nach einer Korrektur oder dann neu zu bewerten, wenn ein späterer Scan ihn nicht mehr meldet. Der Vergleich von Scans allein belegt nicht, dass eine Korrektur wirksam ist. Um Belege aus der Laufzeit zu erhalten, versuche separat, das Problem zu reproduzieren.

Der Befehl gibt seine Bewertung auf stdout aus, ohne einen Bericht zu speichern. Leite stdout um, um sie aufzubewahren:

npx @openai/codex-security validate findings.json > /path/outside/repository/assessment.md

Ergänze --context TEXT, --context-file FILE oder mehrfach --knowledge-base PATH, um Sicherheitskontext bereitzustellen. Für eine strukturierte Ausgabe verwende --output-schema FILE mit einem eigenständigen JSON-Schema, das dein Modell und dein Anbieter unterstützen. Die CLI prüft das erzeugte JSON anhand des Schemas, bevor sie es auf stdout ausgibt. Ist die Ausgabe ungültig, beendet sich die CLI mit 2 und gibt keine Bewertung aus. validate akzeptiert --json nicht.

Mit --effort wählst du für beide Befehle den Reasoning-Aufwand:

npx @openai/codex-security validate "Possible SQL injection" --effort high

Befunde nach einem Scan beheben

Mit scan --patch behebst du Befunde nach einem abgeschlossenen Scan. Der voreingestellte Mindestschweregrad ist low. Dieser Befehl wählt Befunde mit hohem und kritischem Schweregrad aus:

npx @openai/codex-security scan . --patch --patch-severity high --json

Befunde mit überprüfter Korrektur und bereits behobene Befunde lösen --fail-on-severity nicht aus.

Gespeicherte Befunde beheben

Gib die ID eines Befunds oder eines einzelnen Vorkommens an, um die Korrektur im ursprünglichen Repository vorzunehmen, oder wähle Befunde aus einem gespeicherten Scan aus:

npx @openai/codex-security patch OCCURRENCE_ID
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
npx @openai/codex-security patch --scan latest --severity medium

--scan latest wählt den letzten abgeschlossenen Scan des aktuellen Repositorys. patch unterstützt --json für gespeicherte Befunde, direkt angegebenen Text und Dateieingaben.

Ergänze --create-pr, um nur überprüfte Patch-Dateien in einen Commit aufzunehmen und mit der jeweiligen CLI einen Pull Request auf GitHub oder einen Merge Request auf GitLab als Entwurf zu öffnen:

npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr

Wenn der Push oder der Pull Request fehlschlägt, führe den ausgegebenen Befehl patch --resume-pr BRANCH im selben Repository aus, um es erneut zu versuchen.

Probleme aus Linear-Issues beheben

Setze CODEX_SECURITY_LINEAR_API_KEY oder LINEAR_API_KEY für einen persönlichen API-Schlüssel oder LINEAR_ACCESS_TOKEN für ein OAuth-Token. Verwende vorzugsweise eine Umgebungsvariable anstelle von --linear-api-key KEY, damit der Schlüssel nicht im Shell-Verlauf steht.

Importiere ein Issue anhand seiner ID oder URL. Wiederhole --linear-issue, um mehrere Issues auszuwählen:

npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124

Mit --linear-project wählst du die offenen Issues eines Projekts aus. Ergänze --linear-filter, um die Auswahl einzugrenzen:

npx @openai/codex-security patch --linear-project "Security backlog" \
  --linear-filter '{"labels":{"name":{"eq":"security"}}}'

Die CLI schließt abgeschlossene und abgebrochene Issues aus, sofern der Filter nicht state setzt. Sie ändert die Issues in Linear nicht.

codex-security login, logout und info

Melde dich interaktiv an:

npx @openai/codex-security login

Verwende auf einem entfernten Rechner oder einem Rechner ohne grafische Oberfläche die Geräteauthentifizierung:

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

Prüfe die aktuelle Anmeldung:

npx @openai/codex-security login status

Entferne die gespeicherte Anmeldung:

npx @openai/codex-security logout

Übergib einen API-Schlüssel über stdin, um ihn zu speichern:

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Speichere ein Zugriffstoken für Unternehmen:

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

Sieh dir die Metadaten des SDK und des mitgelieferten Plugins ohne Schreibzugriff an:

npx @openai/codex-security info --json

Scan-Ausgabe lesen

Standardmäßig geben Scans Fortschrittsmeldungen, Abschlussübersichten und Fehler auf stderr aus, ohne das vollständige Scan-Ergebnis auf stdout zu schreiben. Fordere mit --json, --format oder --full-output strukturierte Scan-Ergebnisse auf stdout an.

In interaktiven Terminals zeigt ein Live-Dashboard die aktuelle Scan-Phase, den Dateibestand, die Aktivität, den Tokenverbrauch und die geschätzten Kosten. In CI und bei umgeleiteter Ausgabe erscheinen Fortschrittsmeldungen als Klartext. Ergänze --headless, um den Fortschritt auch im interaktiven Terminal als Klartext anzuzeigen:

npx @openai/codex-security scan . --headless

Das Dashboard zeigt auch laufend Sitzungsdetails an. Sie sind ungeschwärzt und können Quellcode oder Zugangsdaten enthalten. Prüfe sie, bevor du sie weitergibst.

Ausführliche Diagnose

Ergänze --verbose, um Diagnoseinformationen zu Ablauf, Authentifizierung, Fortschritt und Kosten auf stderr auszugeben:

npx @openai/codex-security scan . --verbose

Setze CODEX_SECURITY_LOG_LEVEL=debug, um dieselbe Diagnose ohne das Flag zu aktivieren. LOG_LEVEL=debug aktiviert die Diagnose ebenfalls, wenn CODEX_SECURITY_LOG_LEVEL nicht gesetzt oder leer ist.

Codex Security gibt Diagnosetexte unverändert wieder. Sie können Quellcode oder Zugangsdaten enthalten. Prüfe sie, bevor du sie weitergibst.

Abschlussübersicht

Ein abgeschlossener Scan gibt auf stderr die Anzahl offener Befunde im Repository, ihre Verteilung nach Schweregrad, die Laufzeit, den Berichtspfad und das Ergebnisverzeichnis aus. Sofern verfügbar, zeigt er auch den Tokenverbrauch an. Wenn du --show-cost oder --max-cost setzt, zeigt er außerdem die geschätzten Kosten an. Beispiel:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  SCOPE     repository: .
  ELAPSED   1s
  RESULTS   /path/to/scan

Die Gesamtzahl in der Übersicht umfasst auch rein informative Befunde. Schweregradrichtlinien bewerten nur Befunde des aktuellen Scans mit den Stufen critical, high, medium und low. Frühere Befunde, die in der Gesamtzahl des Repositorys erscheinen, bleiben dabei unberücksichtigt.

JSON-Ausgabe

scan --json schreibt ein JSON-Dokument auf stdout. Unter manifest.scan findest du Status und Umfang, unter findings die Befunde des aktuellen Scans. Sofern vorhanden, enthält repositoryFindings sowohl diese Befunde als auch frühere offene Befunde. review.excludedPaths listet die Pfadmuster auf, die der Scan als von der Prüfung ausgeschlossen erfasst hat. scanDir, reportPath und artifactsDir verweisen auf die gespeicherten Ergebnisse.

threatModel enthält das gespeicherte Modell als strukturierte Daten oder Markdown. threatModelPath verweist auf das gespeicherte Dokument. Beide Felder können jeweils null sein. Auch wenn das Schreiben des Dokuments fehlgeschlagen ist, lässt sich das Modell weiterhin exportieren.

Beim Beheben von Befunden enthält die JSON-Ausgabe auch die Patch-Ergebnisse und gegebenenfalls den erstellten Pull Request.

Fortschrittsmeldungen, Abschlussübersichten, Archivierungshinweise und Diagnoseinformationen erscheinen weiterhin auf stderr. Ein abgeschlossener Scan gibt das JSON-Ergebnis auch dann aus, wenn eine Schweregradrichtlinie den Exitcode 1 auslöst.

Prüfe immer den Exitcode des Prozesses, auch wenn sich das JSON erfolgreich parsen lässt. Bei Ausführungsfehlern ohne Scan-Ergebnisse erhältst du einen strukturierten Fehler mit status, code und message, wenn du --json, --format json oder --format jsonl verwendest. Bleiben gültige Scan-Ergebnisse erhalten, kann die Ausgabe stattdessen das reguläre Scan-Ergebnis und warnings enthalten, etwa nach einer Änderung des Ziels. Ergänze bei --json, --format json oder --format jsonl die Option --full-output, um ein umschließendes Objekt mit ok: false zu erhalten. Der Fehler steht unter error, gegebenenfalls erhaltene gültige, versiegelte Ergebnisse unter data. Andere Formate melden Fehler ausschließlich auf stderr, auch mit --full-output. Diese Regeln gelten ebenfalls für scans rerun und scans resume.

codex-security scan --json gibt ein einzelnes JSON-Dokument aus. codex exec --json gibt einen Ereignisstrom im Format JSON Lines aus.

Scan-Artefakte

Ein abgeschlossener Scan speichert den lesbaren Bericht und die strukturierten Artefakte zusammen. Das versiegelte Manifest enthält Hashes der Artefakte. Damit lässt sich später prüfen, ob diese Dateien unverändert sind:

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── report.md
├── threatmodel.md          # when available
├── artifacts/
└── exports/
    └── results.sarif       # when produced

Die strukturierten Dateien erfüllen unterschiedliche Aufgaben:

Datei Inhalt
scan-manifest.json Kennung, Status, Ziel, Umfang und Erzeuger des Scans sowie versiegelte Artefakteinträge.
findings.json Befundkennungen, Schweregrad, Konfidenz, Taxonomie, Fundstellen, Belege, Validierung, Datenfluss, Erreichbarkeit und Maßnahmen zur Behebung.
report.md Lesbarer Scan-Bericht.
threatmodel.md Gespeichertes Bedrohungsmodell, sofern verfügbar.
artifacts/ Ergänzende Scan-Artefakte.
exports/results.sarif Während des Scans generierte SARIF-Ausgabe, sofern vorhanden.

Abschluss und Prüfabdeckung

Prüfe anhand von scan.status in scan-manifest.json, ob der Scan abgeschlossen ist. scan.scope enthält den konfigurierten Umfang, scan.review.excludedPaths die bei der Prüfung erfassten Ausschlüsse. Scan-Vergleiche berücksichtigen diese Ausschlüsse ebenfalls. Auch bei einem abgeschlossenen Scan können einzelne Dateien im vorgesehenen Umfang ungeprüft bleiben.

Prüfe bei noch ausstehenden Arbeiten die verfügbaren Belege mit scans show SCAN_ID und scans logs SCAN_ID. Einen unterbrochenen eingehenden Scan kannst du mit scans resume SCAN_ID fortsetzen, wenn er die Voraussetzungen dafür erfüllt. Um mit den gespeicherten Einstellungen eine neue Prüfung zu starten, verwende scans rerun SCAN_ID, sofern eine Startkonfiguration zur Wiederholung verfügbar ist. Bei Plugin-Scans kann diese fehlen. Starte in diesem Fall einen neuen Scan mit den vorgesehenen Pfaden und dem gewünschten Kontext.

Exitcodes und Signale

Die CLI verwendet folgende Exitcodes:

Exitcode Bedingung
0 Ein Scan oder eine Sammelscan-Kampagne wurde abgeschlossen und hat die Schweregradrichtlinie erfüllt, eine Veröffentlichung wurde ohne Fehler abgeschlossen oder ein anderer Befehl war erfolgreich.
1 Ein Scan oder eine Sammelscan-Kampagne meldet einen Befund ab dem konfigurierten Schweregrad. Auch verify-fix gibt diesen Code zurück, wenn mindestens eine Schwachstelle fortbesteht und alle Prüfergebnisse eindeutig sind. Bei einem bestätigten Import bedeutet er, dass der lokale Import Datensätze ausgeschlossen hat oder der Cloud-Import ein Teilergebnis zurückgibt.
2 Bei der Eingabe, der Ausführung, der Ergebnisintegrität, der erforderlichen Ausgabe oder dem Export ist ein Fehler aufgetreten. Dieser Code gilt auch, wenn publish scan mindestens einen Befund nicht veröffentlichen konnte oder verify-fix ein uneindeutiges Ergebnis meldet.
130 Strg+C hat einen Scan oder eine Veröffentlichung unterbrochen.
143 SIGTERM hat einen Scan oder eine Veröffentlichung beendet.

Lücken in der Prüfabdeckung ändern den Exitcode eines abgeschlossenen Scans nicht und setzen seine Schweregradrichtlinie nicht außer Kraft. Der Exitcode 0 bedeutet nicht, dass jede Datei geprüft wurde. Wenn du eine strukturierte Ausgabe anforderst, schreiben abgeschlossene Scans und teilweise erfolgreiche Veröffentlichungen die verfügbaren Ergebnisse weiterhin auf stdout. Nach einer Unterbrechung oder einem Laufzeitfehler gibt die CLI den Speicherort etwaiger Teilergebnisse aus.

Berechtigungen für lokale Scans

CLI- und SDK-Scans laufen mit deinen lokalen Betriebssystemberechtigungen. Das Scan-Profil erlaubt Lesezugriff auf das lokale Dateisystem und Schreibzugriff auf die Stammverzeichnisse des Workspace. Genehmigungsanfragen für die Ausführung werden automatisch geprüft. Dabei können für einen Vorgang zusätzliche Berechtigungen gewährt werden. Verwende --codex 'approval_policy="never"' oder setze im SDK codexOverrides.approval_policy: "never", um Berechtigungsanfragen abzulehnen. Host- und Netzwerkbeschränkungen gelten weiterhin.

Scan- und Workbench-Prozesse können deine Umgebung übernehmen, einschließlich API-Tokens und Cloud-Zugangsdaten, die für den Scan nicht benötigt werden. Entferne solche Zugangsdaten, bevor du einen Scan startest.

Authentifizierung und Voraussetzungen

Setze OPENAI_API_KEY oder CODEX_API_KEY, melde dich mit npx @openai/codex-security login an oder verwende eine vorhandene, in einer Datei gespeicherte Codex-Anmeldung. Setze für OpenRouter oder Fireworks den API-Schlüssel des Anbieters und wähle ein Modell aus. Verwende für Amazon Bedrock stattdessen einen Bedrock-API-Schlüssel oder die standardmäßige AWS-Anmeldeinformationskette.

Wie du Zugangsdaten auswählst, erfährst du unter Authentifizierung für Scans auswählen.

Beschränke den API-Schlüssel in CI auf den Scan-Schritt und verwende einen vertrauenswürdigen Workflow.

Die CLI erfordert Node.js 24 oder 26 oder Node.js 22 ab Version 22.13.0. Für Scans, Sammelscans, Exporte, den Scan-Verlauf und gespeicherte Befunde ist außerdem Python ab Version 3.10 erforderlich. Python 3.10 benötigt zusätzlich tomli. Verwende --python mit scan, bulk-scan oder export oder setze PYTHON für einen beliebigen Befehl, der Python verwendet.

Weiterführende Informationen findest du im CLI-Schnellstart, im Leitfaden zu Sammelscans, in den häufigen Fragen zur CLI, im CI-Leitfaden oder im Leitfaden zum TypeScript SDK.