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

Wählen Sie Amazon Bedrock mit --provider amazon-bedrock aus und geben Sie mit --model ein explizites Bedrock-Modell an:

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Legen Sie AWS_REGION fest und authentifizieren Sie sich mit AWS_BEARER_TOKEN_BEDROCK, standardmäßigen AWS- Zugriffsschlüsseln, einem AWS-Profil, einer Webidentität, Container-Anmeldedaten oder der standardmäßigen AWS-Anmeldedatenkette. Bedrock-Scans verwenden AWS-Anmeldedaten anstelle von --auth, einer ChatGPT-Anmeldung oder einem OpenAI API key. Sowohl scan als auch bulk-scan unterstützen --provider.

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 bereitgestellte Ä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, beendet der Scan nicht abgeschlossene Worker, behält die Ergebnisse abgeschlossener Scans bei und fasst sie im Abschlussbericht zusammen. Wenn kein Worker die Quellcodeprüfung abschließt, zeichnet der Scan eine unvollständige Abdeckung auf und gibt den Exit-Code 2 zurück.

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, stellen Sie mit --scan-prompt-file eine Text- oder Markdown-Datei bereit. Verwenden Sie --post-scan-prompt-file, um nach erfolgreichen Scans sowie Scans mit unvollständiger Abdeckung oder Fehlern Folgeanweisungen in derselben authentifizierten Sitzung 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 knapp oberhalb des Limits abgeschlossen werden. Wenn ein Tiefenscan das Limit erreicht, nachdem Codex Security die Ergebnisse abgeschlossener Worker zusammengefasst hat, versiegelt die CLI die verfügbaren Ergebnisse, markiert die Abdeckung als partial und gibt den Exit-Code 2 zurück. Andernfalls gibt sie 2 zurück und belässt alle verfügbaren Teilergebnisse 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.

So wählen Sie ein anderes Modell und einen anderen Reasoning-Aufwand aus, ohne TOML zu schreiben:

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

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-5.6-terra"'

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 bereitgestellte Ä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-Repositorys oder führen Sie einen fortsetzbaren Scan anhand einer Repository-CSV 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.

So wählen Sie während der interaktiven Ermittlung ein Modell und den Reasoning-Aufwand aus:

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

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 Repositorys gemeinsam zu nutzen. Verwenden Sie --scan-prompt-file FILE, um gemeinsame Scan-Anweisungen hinzuzufügen; die CSV-Spalte prompt fügt nach diesem gemeinsamen Prompt Repository-spezifische Anweisungen hinzu. --post-scan-prompt-file FILE führt nach jedem Scan Folgeanweisungen aus, einschließlich Scans mit unvollständiger Abdeckung oder Fehlern. Nach einem Abbruch oder wenn ein Scan sein Kostenlimit erreicht, wird sie nicht ausgeführt.

--workers begrenzt die Anzahl gleichzeitiger Repository-Scans und verwendet standardmäßig 4. --mode verwendet standardmäßig standard und --max-attempts standardmäßig 1. Legen Sie --max-attempts fest, um Repository- oder Scan-Fehler erneut zu versuchen. Abgeschlossene Scans mit unvollständiger Abdeckung werden nicht erneut versucht. Ihre Ergebnisse bleiben verfügbar und der Befehl gibt den Exit-Code 2 zurück.

Führen Sie denselben Befehl erneut aus, um aus einem vorhandenen Ausgabeverzeichnis fortzufahren. Die CLI überspringt abgeschlossene Scans, einschließlich Scans mit unvollständiger Abdeckung.

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 hinzu, um ein maschinenformatiertes Ergebnis mit vollständigen Informationen zu erhalten.

Befunde zuordnen und vergleichen

Vergleichen Sie zwei Scans, um neue, fortbestehende, erneut aufgetretene, 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 ist unbekannt, wenn der spätere Scan eine unvollständige Abdeckung aufweist oder den ursprünglichen Fundort nicht abdeckt. 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.

Beachten Sie, dass frühere Befunde offen bleiben, bis sie behoben oder verworfen werden (das Fehlen im neuesten Scan gilt nicht als Beleg für eine Behebung).

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 Repository-Befunde, die Aufschlüsselung nach Schweregrad, die Abdeckung, die verstrichene Zeit, den Berichtspfad und das Ergebnisverzeichnis nach stderr. Sofern verfügbar, werden Token-Nutzung und geschätzte Kosten einbezogen:

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  COVERAGE  complete
  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, Archivhinweise und Fehler verbleiben auf stderr. Ein abgeschlossener Scan gibt auch dann das vollständige JSON-Ergebnis aus, wenn eine Schweregradrichtlinie den Exit-Code 1 oder eine unvollständige Abdeckung den Exit-Code 2 zurückgibt.

Scan-Artefakte

Bei einem abgeschlossenen Scan werden der lesbare Bericht und die strukturierten Artefakte zusammen aufbewahrt:

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

Die strukturierten Dateien erfüllen unterschiedliche Aufgaben:

Die Vollständigkeit der Abdeckung hat drei Werte:

• complete: Der Scan zeichnet für den ausgewählten Umfang eine vollständige Abdeckung auf.
• partial: Der Scan zeichnet zurückgestellte Arbeiten oder andere Einschränkungen der Abdeckung auf.
• unknown: Der Scan meldet die Vollständigkeit der Abdeckung als unbekannt.

Prüfen Sie zurückgestellte Bereiche, explizite Ausschlüsse und offene Fragen, bevor Sie die Abdeckung als Nachweis für eine Sicherheitsentscheidung verwenden.

Exit-Codes und Signale

Die CLI verwendet folgende Exit-Codes:

Jeder Scan mit einer Abdeckung vom Typ partial oder unknown gibt 2 zurück, auch ohne eine Schweregradrichtlinie. Wenn Sie eine strukturierte Ausgabe anfordern, schreiben abgeschlossene Scans und teilweise abgeschlossene Veröffentlichungen weiterhin die verfügbaren Ergebnisse nach stdout. Die CLI gibt nach einer Unterbrechung oder einem Laufzeitfehler den Speicherort etwaiger Teilergebnisse aus.

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-Statusverzeichnis. 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 einschließlich nicht zugehöriger API-Token und Cloud-Anmeldedaten übernehmen. Scannen Sie nur Repositorys, denen Sie vertrauen und zu deren Prüfung Sie berechtigt sind, und stellen Sie nur die für den Scan erforderlichen Anmeldedaten bereit.

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 22 (22.13.0 oder höher), 24 oder 26. Scans, Massenscans, Exporte, Scan-Verlauf und gespeicherte Befunde erfordern außerdem Python 3.10 oder höher. Python 3.10 erfordert außerdem tomli. Verwenden Sie --python mit scan, bulk-scan oder export oder legen Sie PYTHON für jeden Python-basierten Befehl fest.

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|-