Referenz zur Codex Security CLI

In dieser Referenz können Sie die unterstützten codex-security-Befehle, Flags, Ausgabeformate und das Exit-Verhalten nachschlagen. Eine Anleitung für den ersten Scan finden Sie im CLI-Schnellstart.

Führen Sie die CLI mit npx @openai/codex-security aus.

Befehlsübersicht

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

Die CLI stellt folgende Befehle bereit:

Die CLI stellt außerdem folgende Integrationsbefehle bereit:

Alle verfügbaren Befehle auflisten:

npx @openai/codex-security --help

Fügen Sie einem Befehl --help hinzu, um dessen Argumente und Optionen anzuzeigen:

npx @openai/codex-security scan --help

codex-security --version gibt die installierte Version aus und wird dann beendet. codex-security info --json meldet die Versionen des SDK und des gebündelten Plugins. Keiner der beiden Befehle benötigt Python.

Befehle ermitteln und Agenten verbinden

Das für Agenten lesbare Befehlsmanifest ausgeben:

npx @openai/codex-security --llms

Das Schema der Scan-Argumente als JSON untersuchen:

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

Shell-Vervollständigungen für Bash generieren:

npx @openai/codex-security completions bash

Ersetzen Sie bash für diese Shells durch zsh oder fish.

Scan-Ergebnisse unterstützen --format toon|json|yaml|jsonl und --full-output. Dieses frameworkweite --format unterscheidet sich von --export-format, das das Format eines aus einem abgeschlossenen Scan exportierten Artefakts auswählt. Die globale Befehlshilfe führt auch md auf, Scan-Ergebnisse unterstützen jedoch keine Markdown-Ausgabe.

Die CLI als MCP server registrieren:

npx @openai/codex-security mcp add

Codex Security-Skills mit Ihren Agenten synchronisieren:

npx @openai/codex-security skills add

MCP stellt nur den schreibgeschützten Metadatenbefehl info bereit. Scans, Exporte, Authentifizierung, Validierung und Patching sind weiterhin ausschließlich über die CLI verfügbar.

codex-security scan

Führen Sie einen Scan für ein Repository, ausgewählte Pfade, committete Änderungen oder den Working Tree aus.

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

repository verwendet standardmäßig das aktuelle Verzeichnis.

Scan-Authentifizierung auswählen

Verwenden Sie --auth auto, die Standardeinstellung, um Anmeldedaten automatisch auszuwählen. Wenn sowohl eine ChatGPT-Anmeldung als auch OPENAI_API_KEY oder CODEX_API_KEY verfügbar sind, fragen interaktive Scans mit Textausgabe, welche Anmeldedaten verwendet werden sollen. CI-, JSON- und JSONL-Scans sowie andere Scans ohne interaktives Terminal verwenden den API key aus der Umgebung. Probeläufe fragen nicht nach Anmeldedaten und laden diese auch nicht.

Um Ihre gespeicherten Anmeldedaten zu verwenden, übergeben Sie --auth chatgpt:

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

Um einen API key aus der Umgebung zu verwenden, übergeben Sie --auth api-key:

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

Damit gespeicherte Anmeldedaten automatisch als Standard verwendet werden, führen Sie unset OPENAI_API_KEY CODEX_API_KEY aus.

OpenRouter oder Fireworks verwenden

Wählen Sie OpenRouter mit dessen API key und einem expliziten Modell aus:

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

Wählen Sie Fireworks mit dessen API key und einem expliziten Modell aus:

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 außerdem bulk-scan.

Amazon Bedrock verwenden

Verwenden Sie --provider amazon-bedrock und eine Bedrock-Modell-ID mit scan oder bulk-scan. Sobald AWS den Modellzugriff bereitgestellt hat, verwenden Scans AWS-Zugangsdaten ohne --auth, eine OpenAI-Anmeldung oder einen OpenAI API key.

Daybreak Blue und Daybreak Red

Daybreak Blue und Daybreak Red erfordern eine Genehmigung im Rahmen von Trusted Access for Cyber. Um Zugriff zu beantragen, reichen Sie den Antrag auf Unternehmenszugriff ein oder wenden Sie sich an Ihr OpenAI-Kundenbetreuungsteam. Arbeiten Sie nach der Genehmigung mit Ihrem AWS-Kundenbetreuungsteam zusammen, um den Modellzugriff auf Amazon Bedrock bereitzustellen.

Die Genehmigung für Daybreak Red umfasst keinen Zugriff auf GPT-5.6-Cyber. GPT-5.6-Cyber erfordert eine gesonderte Genehmigung der US-Regierung (USG). Bitten Sie Ihr OpenAI-Kundenbetreuungsteam, diese zusätzliche Genehmigung zu beantragen, bevor GPT-5.6-Cyber auf Amazon Bedrock bereitgestellt wird. Siehe die Zugriffsvoraussetzungen für Daybreak.

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

Um mit Daybreak Blue zu scannen, ersetzen Sie <aws-profile-name> durch ein AWS-Profil, das Zugriff auf das Daybreak Blue-Modell hat:

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

Um mit Daybreak Red zu scannen, wählen Sie ein AWS-Profil mit Zugriff auf GPT-5.6-Cyber. Dieses kann sich von dem Profil unterscheiden, das Sie für Daybreak Blue verwenden:

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

Sie können sich auch mit AWS_BEARER_TOKEN_BEDROCK oder über die standardmäßige AWS-Anmeldeinformationskette authentifizieren. Temporäre Zugriffsschlüssel erfordern AWS_SESSION_TOKEN. Legen Sie die Anmeldeinformationen und AWS_REGION in derselben Shell oder demselben CI-Job fest, in der bzw. dem der Scan ausgeführt wird.

Lokale Ergebnisse und Zugriffsprüfungen

Gespeicherte lokale Berichte, scans show und export funktionieren ohne Cloud-Anmeldeinformationen. Das Hochladen von Befunden in Codex Security Cloud erfordert eine separate ChatGPT-Anmeldung und Zugriff auf das Ziel.

info und scan --dry-run prüfen weder AWS-Anmeldeinformationen noch den Modellzugriff. Führen Sie einen Scan aus, um den Zugriff zu prüfen. Prüfen Sie bei AWS-Authentifizierungsfehlern oder verweigertem Zugriff Ihre Anmeldeinformationen, die Region und die Modellberechtigungen.

Bedrock-Versionsstatus

@openai/codex-security@0.1.31 unterstützt Scans über Amazon Bedrock. Diese Version bietet weder Kostenschätzungen noch Unterstützung für --max-cost für die oben genannten Modell-IDs von Daybreak Blue und Daybreak Red.

Prüfen Sie die Versionen Ihres installierten Pakets und der mitgelieferten Codex-Version:

npx @openai/codex-security --version
npx @openai/codex-security info --json

Verwenden Sie npx @openai/codex-security scan --help, um die verfügbaren Optionen Ihrer installierten Version zu prüfen.

Scanziel auswählen

Wählen Sie für jeden Scan genau einen Zieltyp aus.

--path, --diff und --working-tree schließen sich gegenseitig aus. --head erfordert --diff und --base erfordert --working-tree. Der Deep-Modus unterstützt Repository- und Pfadziele.

Für Diff- und Working-Tree-Scans muss als Repository-Argument das Stammverzeichnis des Git-Working-Trees angegeben werden. Die ausgewählten Refs müssen in diesem Checkout vorhanden sein.

Das gesamte Repository scannen:

npx @openai/codex-security scan .

Ausgewählte Pfade scannen:

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

Committete Änderungen scannen:

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

Änderungen im Staging-Bereich und nicht vorgemerkte Änderungen scannen:

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

Eine eingehendere Prüfung des Repositorys ausführen:

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

Tiefenscans konfigurieren

Verwenden Sie diese Optionen mit --mode deep, um die Worker-Parallelität und Laufzeit zu steuern:

--subagents akzeptiert null oder eine positive Ganzzahl. --max-time-hours akzeptiert eine positive Zahl, die nicht größer als 96 ist. Die übrigen Optionen erfordern eine positive Ganzzahl. Diese Optionen sind für Standardscans nicht verfügbar.

Verwenden Sie beispielsweise zwei Worker, lassen Sie bis zu zehn Durchläufe zu und beenden Sie die Worker-Ausführung nach 1,5 Stunden:

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

Wenn das Zeitlimit abläuft, stoppt der Scan noch nicht abgeschlossene Worker, behält abgeschlossene Scanergebnisse bei und führt sie im Abschlussbericht zusammen. Prüfen Sie den Bericht auf untersuchte Bereiche und zurückgestellte Arbeiten. Das Zeitlimit allein bestimmt nicht den Exit- Code; maßgeblich sind der Ausführungsstatus und die Schweregradrichtlinie.

Legen Sie dauerhafte Standardwerte in ~/.codex/codex-security/config.toml fest oder in $CODEX_HOME/codex-security/config.toml, wenn Sie CODEX_HOME festlegen:

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5

Befehlszeilenoptionen überschreiben diese Standardwerte. scan --workers steuert unabhängige Standardscan-Worker innerhalb eines einzelnen Tiefenscans; bulk-scan --workers steuert gleichzeitig ausgeführte Repository-Scans. Legen Sie stop_after_consecutive_errors nur in der TOML-Datei fest; der Standardwert ist 3.

Sicherheitskontext hinzufügen

Verwenden Sie --knowledge-base PATH, um Architekturdokumente, Bedrohungsmodelle oder Sicherheitsrichtlinien bereitzustellen. Wiederholen Sie 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

Zu den unterstützten Dokumenten gehören .md-, .markdown-, .txt-, .pdf- und .docx- Dateien. Die CLI durchsucht Verzeichnisse rekursiv, lehnt verknüpfte Eingabepfade ab, überspringt verknüpfte Verzeichniseinträge und hält extrahierte Dokumentinhalte aus den gespeicherten Scan-Ergebnissen heraus.

Scan-Anweisungen hinzufügen

Um Scan-Anweisungen hinzuzufügen, geben Sie mit --scan-prompt-file eine Text- oder Markdown-Datei an. Verwenden Sie --post-scan-prompt-file, um Folgeanweisungen in derselben authentifizierten Sitzung nach erfolgreichen Scans und Scanfehlern auszuführen:

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

Verwenden Sie beispielsweise den Scan-Prompt, um den Schwerpunkt auf Autorisierungsgrenzen zu legen, und lassen Sie durch die Folgeanweisung eine neue post-scan-summary.md im Scan-Verzeichnis erstellen. Wenn die Folgeanweisung fehlschlägt, meldet die CLI eine Warnung und behält den abgeschlossenen Scan bei. Nach einem Abbruch oder wenn der Scan sein Kostenlimit erreicht, wird die Folgeanweisung nicht ausgeführt.

Ausgabe- und Richtlinienoptionen festlegen

Verwenden Sie diese Optionen, um Artefakte aufzubewahren, frühere Ergebnisse zu erhalten oder ein maschinenlesbares Ergebnis zu erstellen.

Das Kostenlimit ist eine Schätzung und keine feste Ausgabenobergrenze. Bereits laufende Anfragen können das Limit bei ihrem Abschluss geringfügig überschreiten. Wenn ein Tiefenscan das Limit erreicht, nachdem Codex Security die Ergebnisse abgeschlossener Worker zusammengeführt hat, kann die CLI ein abgeschlossenes Ergebnis versiegeln und die Budgetwarnung melden. Sie gibt 0 zurück oder 1, wenn Befunde den konfigurierten Schweregradschwellenwert erreichen. Kann sie kein gültiges abgeschlossenes Ergebnis erzeugen, gibt sie 2 zurück und belässt alle verfügbaren Ausgaben auf dem Datenträger.

Wenn Sie --output-dir weglassen, werden die Ergebnisse unter $CODEX_HOME/state/plugins/codex-security/scans/<repository> gespeichert. CODEX_HOME verwendet standardmäßig ~/.codex. Legen Sie CODEX_SECURITY_STATE_DIR fest, um die Ergebnisse stattdessen unter $CODEX_SECURITY_STATE_DIR/scans/<repository> zu speichern. Diese Verzeichnisse können Quellcodeauszüge und Details zu Schwachstellen enthalten. Verwalten Sie daher ihre Berechtigungen und Aufbewahrung entsprechend.

Die Workbench speichert den Scan-Verlauf in $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Durch Festlegen von CODEX_SECURITY_STATE_DIR wird auch die Workbench-Datenbank verschoben.

Das Ausgabeverzeichnis muss außerhalb des gescannten Verzeichnisses und jedes umgebenden Git-Working-Trees liegen. Ein Scan kann mit --archive-existing ein vorhandenes Ergebnisverzeichnis ersetzen.

So bewahren Sie frühere Ergebnisse auf, bevor Sie ein Ausgabeverzeichnis erneut verwenden:

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

Scans erstellen standardmäßig nur Berichte. Fügen Sie --fail-on-severity hinzu, 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 Wissensdatenbank, ohne Anmeldedaten zu laden, Codex zu starten oder den Python-Interpreter des Plugins zu prüfen:

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

Laufzeit konfigurieren

Verwenden Sie Laufzeitoptionen, wenn Sie ein bestimmtes Modell, einen Interpreter, ein Plugin oder einen Codex-Konfigurationswert benötigen.

Um ein anderes Modell und einen anderen Reasoning-Aufwand ohne TOML-Konfiguration auszuwählen, wählen Sie ein Modell, auf das Sie mit Ihren Anmeldedaten zugreifen können. Wenn Sie die ChatGPT-Anmeldung verwenden, prüfen Sie die Verfügbarkeit von GPT-6.1 Sol, bevor Sie diese Beispiele verwenden:

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

Setzen Sie Zeichenfolgenwerte, die über --codex übergeben werden, in Anführungszeichen, damit der TOML-Parser eine Zeichenfolge erhält:

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

codex-security install-hook

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

npx @openai/codex-security install-hook

Die Prüfung scannt vor jedem Commit Änderungen im Staging-Bereich sowie nicht vorgemerkte Änderungen und blockiert Befunde mit hohem Schweregrad oder Scan-Fehler. Sie berücksichtigt core.hooksPath und ersetzt kein vorhandenes Pre-Commit-Skript. Legen Sie bei Bedarf einen anderen Schweregrad-Schwellenwert fest:

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

Ermitteln und scannen Sie GitHub-Repositories oder führen Sie einen fortsetzbaren Scan anhand einer Repository-CSV-Datei aus.

Eine vollständige Anleitung zur GitHub-Ermittlung, zu CSV-Inventaren, Kampagnenergebnissen und containerisierten Scans finden Sie unter Massensicherheitsscans 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 {minimal,low,medium,high,xhigh,max}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Führen Sie npx @openai/codex-security bulk-scan ohne Argumente aus, um Repositorys interaktiv auszuwählen. Dieser Ablauf erfordert eine Anmeldung bei der GitHub CLI.

Um während der interaktiven Erkennung ein Modell und einen Reasoning-Aufwand auszuwählen, verwenden Sie ein Modell, auf das Sie mit Ihren Anmeldedaten zugreifen können. Siehe Verfügbarkeit von GPT-6.1 Sol bei der ChatGPT-Anmeldung:

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

Geben Sie für eine vorbereitete Repository-Liste eine CSV und --output-dir an:

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

Die CSV erfordert die Spalten id, repository und revision. Revisionen müssen vollständige Commit-Hashes sein. Mit den optionalen Spalten scope, mode und prompt lassen sich einzelne Repositorys konfigurieren:

id,repository,revision,scope,mode,prompt
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Review authorization boundaries.

Verwenden Sie --knowledge-base PATH, um Sicherheitsdokumente für alle Repositories bereitzustellen. Verwenden Sie --scan-prompt-file FILE, um gemeinsame Scan-Anweisungen hinzuzufügen; die CSV-Spalte prompt ergänzt repositoryspezifische Anweisungen nach diesem gemeinsamen Prompt. --post-scan-prompt-file FILE führt Folgeanweisungen nach jedem Scan aus, auch bei Scanfehlern. Sie werden nicht nach einem Abbruch oder beim Erreichen des Kostenlimits eines Scans ausgeführt.

--workers begrenzt die Anzahl gleichzeitiger Repository-Scans und hat den Standardwert 4. --mode hat den Standardwert standard und --max-attempts den Standardwert 1. Legen Sie --max-attempts fest, um bei Repository- oder Scanfehlern Wiederholungsversuche durchzuführen. Abgeschlossene Scans werden aufgrund von Abdeckungslücken oder Verstößen gegen Schweregradrichtlinien nicht wiederholt. Ihre Ergebnisse bleiben verfügbar.

Führen Sie denselben Befehl erneut aus, um die Kampagne aus einem vorhandenen Ausgabeverzeichnis fortzusetzen. Die CLI überspringt abgeschlossene Scans, einschließlich Scans mit Abdeckungslücken.

Informationen zu containerisierten Kampagnen finden Sie unter Massenscans in Docker ausführen.

codex-security scans

Gespeicherte Scans finden

Gespeicherte Scans für das aktuelle Verzeichnis auflisten:

npx @openai/codex-security scans

Scans für ein anderes Repository auflisten:

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

Scans finden, die unter einem bestimmten Ausgabeverzeichnis gespeichert sind:

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

Einen Scan untersuchen oder wiederholen

Ergebnisse und Konfiguration eines gespeicherten Scans anzeigen:

npx @openai/codex-security scans show SCAN_ID

Fügen Sie --show-linked-findings hinzu, um Links zu Befunden aus früheren Scans einzubeziehen.

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

npx @openai/codex-security scans rerun SCAN_ID

Für die erneute Ausführung ist die vom ursprünglichen Scan aufgezeichnete Plugin-Version erforderlich. Wenn die installierte Version abweicht, wird der Befehl beendet, statt mit einem anderen Plugin ausgeführt zu werden.

Gespeicherte Scan-Protokolle untersuchen

Lesen Sie die vollständigen gespeicherten Sitzungsereignisse für einen Scan und seine Worker. Diese Protokolle sind nicht bereinigt und können Quellcode oder Anmeldedaten enthalten. Prüfen Sie sie daher vor der Weitergabe:

npx @openai/codex-security scans logs SCAN_ID

Fügen Sie --json für eine strukturierte Ausgabe hinzu.

Befunde zuordnen und vergleichen

Vergleichen Sie zwei Scans, um neue, weiterhin bestehende, erneut geöffnete, nicht beobachtete, behobene und unbekannte Befunde zu ermitteln:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Der Vergleich ordnet Befunde mit derselben Grundursache automatisch einander zu und verwendet gespeicherte Zuordnungen erneut. Um Zuordnungen explizit zu speichern, verwenden Sie scans match:

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. Wenn der spätere Scan ihn im gescannten Code nicht findet, gilt er als nicht beobachtet. Nur ein Befund, der ausdrücklich als bereits behoben geschlossen wurde, gilt als behoben. Fügen Sie --force zu match hinzu, wenn Sie eine vorhandene Zuordnung neu berechnen müssen.

So ordnen Sie alle abgeschlossenen Scans für das aktuelle Repository einander zu, einschließlich Scans aus anderen Checkouts:

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

Scan-Ergebnisse können variieren, selbst wenn Sie dieselbe Konfiguration erneut ausführen. Zuordnung und Vergleich verfolgen Änderungen; sie machen Ergebnisse weder deterministisch noch beweisen sie, dass eine Schwachstelle nicht mehr vorhanden ist. Verwenden Sie validate, um einen sicherheitskritischen Befund anhand des aktuellen Codes erneut zu prüfen.

codex-security findings

Offene Befunde aus allen Scans des aktuellen Repositorys auflisten:

npx @openai/codex-security findings list

Übergeben Sie einen Repository-Pfad, um einen anderen Checkout zu untersuchen:

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

Fügen Sie --json hinzu, um eine strukturierte Ausgabe zu erhalten. Die Liste kennzeichnet Befunde aus dem neuesten Scan sowie frühere Befunde, die in diesem Scan nicht bestätigt wurden.

Frühere Befunde bleiben offen, bis sie behoben oder verworfen werden. Dass sie im neuesten Scan fehlen, belegt nicht, dass sie behoben wurden.

So erfassen Sie einen geprüften Befund als falsch-positiv:

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

Untersuchen Sie den gespeicherten Scan, um das Vorkommen des Befunds zu identifizieren:

npx @openai/codex-security scans show SCAN_ID

Erfassen Sie eine konkrete Begründung für das falsch-positive Ergebnis:

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 die aktuelle Quelle, die Kontrollen und die Erreichbarkeit unabhängig erneut. Eine frühere Entscheidung unterdrückt weder eine Regel noch einen Pfad oder eine Schwachstellenklasse.

codex-security export

Exportieren Sie CSV, JSON oder SARIF aus einem abgeschlossenen, versiegelten Scan. Der Export validiert die Scan-Artefakte vor dem Schreiben der Ausgabe und lässt die Codex-Laufzeit sowie die Anmeldedaten unverändert.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir ist das Verzeichnis des abgeschlossenen Scans.

--source-root funktioniert nur mit --export-format sarif. JSON bewahrt das versiegelte Befunddokument. CSV enthält übertragbare Befundspalten und keinen lokalen Workbench-Triage-Status.

Ohne --output schreibt die CLI SARIF nach results.sarif, JSON nach findings.json und CSV nach findings.csv im aktuellen Arbeitsverzeichnis. Exporte können Quellcodeauszüge und Details zu Schwachstellen enthalten. Führen Sie den Befehl außerhalb des Repositorys aus oder übergeben Sie --output mit einem privaten Pfad außerhalb des gescannten Checkouts.

SARIF in eine Datei schreiben:

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

SARIF nach stdout schreiben:

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

Befunde als JSON exportieren:

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

Befunde als CSV exportieren:

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

codex-security publish scan

Alle Befunde aus einem abgeschlossenen Scan in Linear veröffentlichen:

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. Lassen Sie die Angabe in einem interaktiven Terminal weg, um einen abgeschlossenen Scan aus dem lokalen Scan-Verlauf auszuwählen. Zum Erstellen von Issues müssen der Scan und seine Befunde außerdem im lokalen Scan-Verlauf vorhanden sein. Ein Probelauf validiert die versiegelten Artefakte ohne diese Persistenzprüfung.

Jeder Aufruf, der kein Probelauf ist, versucht, für jeden Befund ein neues Issue zu erstellen. Bei erneuter Veröffentlichung desselben Scans werden vorhandene Issues weder zugeordnet noch aktualisiert oder wiederverwendet. Wenn einige Befunde fehlschlagen, behält der Befehl erfolgreich erstellte Issues bei und gibt den Exit-Code 2 zurück. Prüfen Sie bei --json vor einem erneuten Versuch die Ergebnisse created und failed, um Duplikate zu vermeiden.

Vorschau der Issue-Nutzlasten vor der Veröffentlichung anzeigen:

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

Mit der verbundenen Linear-App veröffentlichen

Ohne Linear API key startet der Befehl Codex mit Ihrer vorhandenen Konfiguration und der verbundenen Linear-App. Melden Sie sich an und verbinden Sie Linear mit Ihrem Codex-Konto, bevor Sie veröffentlichen:

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 key veröffentlichen

Bei Angabe von --linear-api-key oder CODEX_SECURITY_LINEAR_API_KEY erfolgt die Veröffentlichung direkt über die Linear API, ohne Codex zu starten. Bei der direkten Veröffentlichung bleiben Issues nicht zugewiesen, sofern Sie keinen Bearbeiter auswählen:

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 überschreiben die entsprechenden Umgebungsvariablen. Bevorzugen Sie für API keys CODEX_SECURITY_LINEAR_API_KEY gegenüber --linear-api-key, da Befehlszeilenargumente im Shell-Verlauf und in Prozesslisten erscheinen können.

codex-security validate und codex-security patch

Prüfen Sie, ob ein potenzieller Befund gültig ist:

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

Erstellen Sie mit dem gebündelten Behebungs-Skill einen Fix:

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

Jedes Positionsargument akzeptiert Literaltext oder einen Dateipfad. Diese Eingaben verwenden das aktuelle Verzeichnis. Verwenden Sie validate, um einen Befund nach einem Fix oder dann erneut zu prüfen, wenn ein späterer Scan ihn nicht mehr meldet. Der bloße Vergleich von Scans beweist nicht, dass ein Fix funktioniert hat.

Verwenden Sie --effort, um den Reasoning-Aufwand für einen der beiden Befehle auszuwählen:

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

Befunde nach einem Scan patchen

Verwenden Sie scan --patch, um Befunde nach einem vollständigen Scan zu beheben. Dies erfordert @openai/codex-security 0.1.15 oder höher. Der standardmäßige Schweregrad-Schwellenwert ist low. Dieser Befehl wählt Befunde mit hohem und kritischem Schweregrad aus:

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

Verifizierte und bereits behobene Befunde lösen --fail-on-severity nicht aus.

Gespeicherte Befunde patchen

Übergeben Sie eine Befund- oder Vorkommnis-ID, um das ursprüngliche Repository zu patchen, oder wählen Sie 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 neuesten abgeschlossenen Scan für das aktuelle Repository aus. Befehle für gespeicherte Befunde unterstützen --json; Literaltext- und Dateieingaben nicht.

Fügen Sie --create-pr hinzu, um nur verifizierte Patch-Dateien zu committen und mit der GitHub CLI einen Pull-Request zu öffnen:

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

Wenn der Push oder Pull-Request fehlschlägt, führen Sie den ausgegebenen patch --resume-pr BRANCH- Befehl aus demselben Repository erneut aus.

Linear-Issues patchen

Legen Sie CODEX_SECURITY_LINEAR_API_KEY oder LINEAR_API_KEY für einen persönlichen API key oder LINEAR_ACCESS_TOKEN für ein OAuth-Token fest. Bevorzugen Sie eine Umgebungsvariable gegenüber --linear-api-key KEY, damit der Schlüssel nicht im Shell-Verlauf erscheint.

Importieren Sie ein Issue anhand seiner ID oder URL. Wiederholen Sie --linear-issue, um mehrere Issues auszuwählen:

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

Verwenden Sie --linear-project, um die offenen Issues eines Projekts auszuwählen. Fügen Sie --linear-filter hinzu, 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 festlegt. Sie verändert die Linear-Issues nicht.

codex-security login, logout und info

Interaktiv anmelden:

npx @openai/codex-security login

Geräteauthentifizierung auf einem entfernten oder monitorlosen Rechner verwenden:

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

Aktuelle Anmeldung prüfen:

npx @openai/codex-security login status

Gespeicherte Anmeldung entfernen:

npx @openai/codex-security logout

Einen API key speichern, indem Sie ihn über stdin übergeben:

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

Ein Enterprise-Zugriffstoken speichern:

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

Schreibgeschützte SDK- und Metadaten des gebündelten Plugins untersuchen:

npx @openai/codex-security info --json

Wenn Sie die CLI als MCP server bereitstellen, ist info der einzige verfügbare Befehl. Scans, Exporte, Veröffentlichungen, Anmeldung, Validierung und Patching sind weiterhin ausschließlich über die CLI verfügbar.

Scan-Ausgabe lesen

Standardmäßig senden Scans Fortschrittsmeldungen, Abschlusszusammenfassungen und Fehler an stderr, ohne das vollständige Scan-Ergebnis nach stdout zu schreiben. Fordern Sie --json, --format oder --full-output an, um strukturierte Scan-Ergebnisse nach stdout zu senden.

Interaktive Terminals zeigen ein Live-Dashboard mit der aktuellen Scanphase, geprüften Dateien, Aktivitäten, Token-Nutzung und geschätzten Kosten. CI und umgeleitete Ausgaben verwenden Klartext-Fortschrittsmeldungen. Fügen Sie --headless hinzu, um in einem interaktiven Terminal Klartext-Fortschrittsmeldungen zu verwenden:

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

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

Ausführliche Diagnoseinformationen

Fügen Sie --verbose hinzu, um bereinigte Diagnoseinformationen zu Lebenszyklus, Authentifizierung, Fortschritt und Kosten auf stderr auszugeben:

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

Legen Sie CODEX_SECURITY_LOG_LEVEL=debug fest, um dieselben Diagnoseinformationen ohne das Flag zu aktivieren. LOG_LEVEL=debug aktiviert Diagnoseinformationen ebenfalls, wenn CODEX_SECURITY_LOG_LEVEL nicht festgelegt ist.

Abschlusszusammenfassung

Ein abgeschlossener Scan schreibt die Anzahl offener Befunde im Repository, die Aufschlüsselung nach Schweregrad, die verstrichene Zeit, den Berichtspfad und das Ergebnisverzeichnis nach stderr. Er enthält auch den Tokenverbrauch und die geschätzten Kosten, sofern verfügbar. Beispiel:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  ELAPSED   1s
  TOKENS    1,250 input, 200 cached, 30 output
  RESULTS   /path/to/scan

Informative Befunde werden in der Gesamtsumme der Zusammenfassung berücksichtigt. Schweregradrichtlinien werten nur Befunde der Stufen critical, high, medium und low aus dem aktuellen Scan aus, nicht frühere Befunde, die in der Repository-Gesamtsumme angezeigt werden.

JSON-Ausgabe

scan --json schreibt ein vollständiges JSON-Dokument nach stdout. Seine Struktur auf oberster Ebene lautet:

manifest
repositoryFindings
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
cost
turn
  id
  status
  durationMs
  finalResponse
  usage

Beim Patchen enthält die JSON-Ausgabe außerdem Patch-Ergebnisse und alle erstellten Pull-Requests.

Fortschrittsmeldungen, Abschlusszusammenfassungen, Archivierungshinweise und Fehler werden weiterhin nach stderr ausgegeben. Ein abgeschlossener Scan gibt auch dann das vollständige JSON-Ergebnis aus, wenn eine Schweregradrichtlinie den Exit-Code 1 zurückgibt.

Scan-Artefakte

Ein abgeschlossener Scan bewahrt den lesbaren Bericht und die strukturierten Artefakte gemeinsam auf. Das versiegelte Manifest zeichnet die Hashwerte der Artefakte auf, damit spätere Leser prüfen können, dass diese Dateien nicht verändert wurden:

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

Die strukturierten Dateien erfüllen unterschiedliche Aufgaben:

Lesen Sie scan.status in scan-manifest.json, um den Ausführungsstatus zu ermitteln: completed, failed, canceled oder interrupted. Neue Ergebnisse enthalten kein coverage.completeness. Prüfen Sie zurückgestellte Bereiche, ausdrückliche Ausschlüsse und offene Fragen in coverage.json, um nachzuvollziehen, was der Scan geprüft hat.

Exit-Codes und Signale

Die CLI verwendet folgende Exit-Codes:

Abdeckungslücken ändern weder den Exitcode eines abgeschlossenen Scans noch umgehen sie dessen Schweregrad- richtlinie. Exitcode 0 bedeutet nicht, dass jede Datei geprüft wurde. Wenn Sie strukturierte Ausgaben anfordern, schreiben abgeschlossene Scans und teilweise abgeschlossene Veröffentlichungen die verfügbaren Ergebnisse weiterhin nach stdout. Die CLI gibt nach einer Unterbrechung oder einem Laufzeitfehler den Speicherort einer etwaigen Teilausgabe an.

Berechtigungen für lokale Scans

CLI- und SDK-Scans werden mit den Berechtigungen Ihres lokalen Betriebssystems ausgeführt. Jeder Scan verwendet das Dateisystemprofil codex_security_scan und setzt approvalPolicy auf "never". Das Profil erlaubt das Lesen des lokalen Dateisystems und das Schreiben in Workspace-Stammverzeichnisse sowie das ausgewählte Scan-Zustandsverzeichnis. Scans werden nicht angehalten, um eine interaktive Genehmigung anzufordern.

Über CLI --codex oder SDK codexOverrides bereitgestellte Einstellungen, einschließlich approval_policy, sandbox_mode und Dateisystemberechtigungen, können diese Scan-Kontrollen weder ersetzen noch einschränken. Host- und Netzwerkeinschränkungen gelten weiterhin.

Scan- und Workbench-Prozesse können Ihre Umgebung übernehmen, einschließlich nicht benötigter API-Tokens und Cloud-Zugangsdaten. Entfernen Sie nicht benötigte Zugangsdaten, bevor Sie einen Scan starten.

Authentifizierung und Voraussetzungen

Legen Sie OPENAI_API_KEY oder CODEX_API_KEY fest, melden Sie sich mit npx @openai/codex-security login an oder verwenden Sie eine vorhandene dateibasierte Codex-Anmeldung. Legen Sie für OpenRouter oder Fireworks den API key des Anbieters fest und wählen Sie ein Modell aus. Verwenden Sie für Amazon Bedrock stattdessen einen Bedrock API key oder die standardmäßige AWS- Anmeldedatenkette.

Informationen zur Auswahl der Anmeldedaten finden Sie unter Scan-Authentifizierung auswählen.

Beschränken Sie den API key in CI auf den Scan-Schritt und verwenden Sie einen vertrauenswürdigen Workflow.

Die CLI erfordert Node.js 24 oder 26 oder Node.js 22 ab 22.13.0. Scans, Massenscans, Exporte, Scanverlauf und gespeicherte Befunde erfordern außerdem Python 3.10 oder neuer. Python 3.10 erfordert zusätzlich tomli. Verwenden Sie --python mit scan, bulk-scan oder export, oder setzen Sie PYTHON für jeden Python-basierten Befehl.

Fahren Sie mit dem CLI-Schnellstart, dem Leitfaden zu Massenscans, den häufig gestellten Fragen zur CLI, dem CI-Leitfaden oder dem Leitfaden zum TypeScript SDK fort.

Klartext-Aliasse

• --output FILE|-