Deutsch

Referenz für die Codex Security CLI

Argumente, Ausgabeformate, Scanartefakte, Anbieter und Exit-Codes für die Codex Security CLI.

Verwenden Sie diese Referenz, um die unterstützten codex-security-Befehle, Flags, Ausgabeformate und das Beendigungsverhalten nachzuschlagen. Beginnen Sie für einen angeleiteten ersten Scan mit dem CLI-Schnellstart.

Installieren Sie das veröffentlichte Paket in Ihrem Projekt:

npm install @openai/codex-security

Rufen Sie das installierte Paket als npx @openai/codex-security auf. Sie können codex-security direkt verwenden, wenn die ausführbare Datei in Ihrem PATH verfügbar ist.

Befehlsübersicht

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

Die CLI stellt folgende Befehle bereit:

Befehl Zweck
codex-security scan Einen Codex Security-Scan ausführen.
codex-security install-hook Einen Git-Pre-Commit-Sicherheitsscan installieren.
codex-security bulk-scan Repositorys suchen und fortsetzbare Sammelscans ausführen.
codex-security scans Gespeicherte Scans auflisten, untersuchen, zuordnen, erneut ausführen und vergleichen.
codex-security findings Gespeicherte Sicherheitsbefunde prüfen und aktualisieren.
codex-security export Abgeschlossene Befunde als CSV, JSON oder SARIF exportieren.
codex-security validate Einen oder mehrere potenzielle Sicherheitsbefunde prüfen.
codex-security patch Ein oder mehrere Sicherheitsprobleme korrigieren.
codex-security login Anmelden, Anmeldedaten speichern oder Anmeldestatus prüfen.
codex-security logout Die gespeicherte Anmeldung entfernen.
codex-security info Schreibgeschützte SDK- und gebündelte Plugin-Metadaten anzeigen.

Die CLI stellt außerdem folgende Integrationsbefehle bereit:

Befehl Zweck
codex-security completions Skripte zur Shell-Vervollständigung erzeugen.
codex-security mcp Die CLI als MCP-Server registrieren.
codex-security skills Codex Security-Skills mit Agenten synchronisieren.

Listen Sie alle verfügbaren Befehle auf:

npx @openai/codex-security --help

Fügen Sie einem Befehl --help hinzu, um seine Argumente und Optionen zu untersuchen:

npx @openai/codex-security scan --help

codex-security --version gibt die installierte Version aus und wird beendet. codex-security info --json meldet die SDK- und gebündelten Plugin-Versionen. Keiner der Befehle erfordert Python.

Befehle ermitteln und Agenten verbinden

Geben Sie das für Agenten lesbare Befehlsmanifest aus:

npx @openai/codex-security --llms

Untersuchen Sie das Schema der Scanargumente als JSON:

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

Erzeugen Sie Shell-Vervollständigungen für Bash:

npx @openai/codex-security completions bash

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

Scanergebnisse unterstützen --format toon|json|yaml|jsonl und --full-output. Dieses --format auf Framework-Ebene ist von --export-format getrennt, das das Format eines aus einem abgeschlossenen Scan exportierten Artefakts auswählt. Die globale Befehlshilfe führt außerdem md auf, Scanergebnisse unterstützen jedoch keine Markdown-Ausgabe.

Registrieren Sie die CLI als MCP-Server:

npx @openai/codex-security mcp add

Synchronisieren Sie Codex Security-Skills mit Ihren Agenten:

npx @openai/codex-security skills add

MCP stellt nur den schreibgeschützten Metadatenbefehl info bereit. Scans, Exporte, Authentifizierung, Validierung und Korrekturen sind weiterhin nur über die CLI möglich.

codex-security scan

Führen Sie einen Scan für ein Repository, ausgewählte Pfade, committete Änderungen oder den Arbeitsbaum 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]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository verwendet standardmäßig das aktuelle Verzeichnis.

Scanauthentifizierung 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 zeigen keine Eingabeaufforderung an und laden keine Anmeldedaten.

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

Führen Sie unset OPENAI_API_KEY CODEX_API_KEY aus, um gespeicherte Anmeldedaten zum automatischen Standard zu machen.

Amazon Bedrock verwenden

Wählen Sie Amazon Bedrock mit --provider amazon-bedrock aus und geben Sie mit --model ausdrücklich ein 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, Web Identity, 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 einen Zieltyp aus.

Argument Beschreibung
--path PATH Einen relativ zum Repository angegebenen Pfad scannen. Wiederholen Sie das Flag für weitere Pfade.
--diff BASE Committete Änderungen von BASE bis --head scannen. Der Head verwendet standardmäßig HEAD.
--head HEAD Die Head-Revision für --diff festlegen.
--working-tree Bereitgestellte und nicht bereitgestellte Änderungen gegenüber --base scannen. Die Basis verwendet standardmäßig HEAD.
--base BASE Die Basisrevision für --working-tree festlegen.
--mode {standard,deep} Den Scanmodus auswählen. Standardmäßig wird standard verwendet.

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

Diff- und Arbeitsbaum-Scans erfordern als Repository-Argument das Stammverzeichnis des Git- Arbeitsbaums. Die ausgewählten Refs müssen in diesem Checkout vorhanden sein.

Scannen Sie das gesamte Repository:

npx @openai/codex-security scan .

Scannen Sie ausgewählte Pfade:

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

Scannen Sie committete Änderungen:

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

Scannen Sie bereitgestellte und nicht bereitgestellte Änderungen:

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

Führen Sie eine tiefgehendere Prüfung des Repositorys aus:

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

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

Unterstützte Dokumente umfassen .md-, .markdown-, .txt-, .pdf- und .docx- Dateien. Die CLI durchsucht Verzeichnisse rekursiv, lehnt verknüpfte Eingabepfade ab, überspringt verknüpfte Verzeichniseinträge und bewahrt extrahierte Dokumentinhalte außerhalb der gespeicherten Scanergebnisse auf.

Ausgabe- und Richtlinienoptionen festlegen

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

Argument Beschreibung
--output-dir DIR Scanartefakte in ein privates Verzeichnis außerhalb des umgebenden Git-Arbeitsbaums schreiben. Standardmäßig wird der persistente Status von Codex Security verwendet.
--archive-existing Vorhandene Ergebnisse nach DIR.previous-<timestamp>-<id> verschieben und mit einem leeren Ausgabeverzeichnis beginnen. Erfordert --output-dir.
--fail-on-severity LEVEL Exit-Code 1 zurückgeben, wenn ein abgeschlossener Scan einen Befund mit mindestens dem Schweregrad critical, high, medium oder low meldet.
--max-cost USD Einen Scan beenden, wenn seine geschätzten Modellkosten den angegebenen USD-Betrag überschreiten.
--dry-run Repository, Ziel, Ausgabeverzeichnis und Codex-Konfiguration prüfen, ohne einen Scan zu starten.
--verbose Bereinigte Diagnoseinformationen zu Lebenszyklus, Authentifizierung, Fortschritt und Kosten nach stderr ausgeben.
--json Manifest, Befunde, Abdeckung, Pfade und Turn-Metadaten als ein JSON-Dokument ausgeben.
--format FORMAT Das vollständige Scanergebnis als toon, json, yaml oder jsonl ausgeben.
--full-output Das vollständige Ergebnis im standardmäßigen strukturierten Ausgabeformat ausgeben.

Der Kostengrenzwert ist eine Schätzung und keine feste Ausgabenobergrenze. Bereits laufende Anfragen können oberhalb des Grenzwerts abgeschlossen werden, und Teilergebnisse des Scans bleiben verfügbar.

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

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

Das Ausgabeverzeichnis muss außerhalb des gescannten Verzeichnisses und aller umgebenden Git-Arbeitsbäume liegen. Ein Scan kann ein vorhandenes Ergebnisverzeichnis mit --archive-existing 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 dienen standardmäßig nur zur Berichterstellung. Fügen Sie --fail-on-severity hinzu, um eine Schweregradrichtlinie in CI 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, ohne Anmeldedaten zu laden, Codex zu starten oder den Python-Interpreter des Plugins zu untersuchen:

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.

Argument Beschreibung
--auth {auto,chatgpt,api-key} Die Scan-Anmeldedaten auswählen. Standardmäßig wird auto verwendet.
--provider {openai,openrouter,fireworks,amazon-bedrock} Den Inferenzanbieter auswählen. Standardmäßig wird openai verwendet.
--model MODEL Das Modell auswählen. Standardmäßig wird gpt-5.6-sol verwendet. Bei --provider amazon-bedrock erforderlich.
--effort {minimal,low,medium,high,xhigh} Den Reasoning-Aufwand des Modells auswählen. Standardmäßig wird xhigh verwendet.
--plugin-path PATH Ein Codex Security-Plugin-Verzeichnis oder eine ZIP-Datei verwenden, um das gebündelte Plugin zu überschreiben.
--python PATH Den Python-Interpreter für die Plugin-Laufzeit auswählen.
--codex KEY=VALUE Einen isolierten Codex-Konfigurationswert überschreiben. Werte verwenden TOML-Syntax. Wiederholen Sie das Flag für weitere Werte.

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 bereitgestellte und nicht bereitgestellte Änderungen vor jedem Commit und blockiert Befunde mit hohem Schweregrad oder Scanfehler. 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

Suchen und scannen Sie GitHub-Repositorys oder führen Sie einen fortsetzbaren Scan anhand einer Repository-CSV-Datei aus:

Eine vollständige Anleitung zur GitHub-Suche, zu CSV-Beständen, Kampagnenergebnissen und containerisierten Scans finden Sie unter Sicherheitssammelscans 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-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 GitHub CLI.

So wählen Sie bei der interaktiven Suche ein Modell und einen Reasoning-Aufwand aus:

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

Stellen Sie für eine vorbereitete Repository-Liste eine CSV-Datei und --output-dir bereit:

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

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

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

--workers begrenzt gleichzeitige Scans und verwendet standardmäßig 4. --mode verwendet standardmäßig standard und --max-attempts verwendet standardmäßig 1. Legen Sie --max-attempts fest, wenn Sie einen Scan für ein Repository nach einem Fehler erneut versuchen möchten. Führen Sie denselben Befehl erneut aus, um einen Sammelscan aus seinem vorhandenen Ausgabeverzeichnis fortzusetzen. Die CLI überspringt abgeschlossene Repositorys nur, wenn die erfassten Ergebnisartefakte weiterhin vorhanden sind.

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

codex-security scans

Gespeicherte Scans suchen

Listen Sie gespeicherte Scans für das aktuelle Verzeichnis auf:

npx @openai/codex-security scans

Listen Sie Scans für ein anderes Repository auf:

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

Suchen Sie Scans, die unter einem bestimmten Ausgabeverzeichnis gespeichert sind:

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

Scan untersuchen oder wiederholen

Zeigen Sie die Ergebnisse und Konfiguration eines gespeicherten Scans an:

npx @openai/codex-security scans show SCAN_ID

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

npx @openai/codex-security scans rerun SCAN_ID

Befunde zuordnen und vergleichen

Ordnen Sie Befunde mit derselben Grundursache über zwei Scans hinweg zu:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Vergleichen Sie die zugeordneten Scans, um neue, weiterhin vorhandene, erneut aufgetretene, behobene und unbekannte Befunde zu ermitteln:

npx @openai/codex-security scans compare 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 des Befunds 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 zu, einschließlich Scans aus anderen Checkouts:

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

Scanergebnisse können selbst dann variieren, wenn Sie dieselbe Konfiguration erneut ausführen. Zuordnung und Vergleich verfolgen Änderungen; sie machen Ergebnisse weder deterministisch noch belegen 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

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 Auftreten des Befunds zu ermitteln:

npx @openai/codex-security scans show SCAN_ID

Erfassen Sie eine konkrete Begründung für den falsch positiven Befund:

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 keine Regel, keinen Pfad und keine Schwachstellenklasse.

codex-security export

Exportieren Sie CSV, JSON oder SARIF aus einem abgeschlossenen, versiegelten Scan. Der Export validiert die Scanartefakte 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.

Argument Beschreibung
--export-format {csv,json,sarif} Das Exportformat auswählen. Standardmäßig wird sarif verwendet.
--output FILE|- Das ausgewählte Format in eine Datei oder nach stdout schreiben. Standardmäßig wird eine Datei im aktuellen Verzeichnis verwendet.
--source-root PATH SARIF mithilfe eines Repository-Checkouts Quellzeilen-Fingerabdrücke hinzufügen.
--python PATH Den Python-Interpreter für den gebündelten Exporter auswählen.

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

Ohne --output schreibt die CLI SARIF nach results.sarif, JSON nach findings.json und CSV nach findings.csv im aktuellen Arbeitsverzeichnis. Exporte können Quelltextauszüge und Einzelheiten 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.

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

Schreiben Sie SARIF nach stdout:

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

Exportieren Sie Befunde als JSON:

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

Exportieren Sie Befunde als CSV:

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

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"

Erzeugen Sie mit dem gebündelten Skill zur Abhilfe eine Korrektur:

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

Jedes Argument kann wörtlichen Text enthalten oder auf eine Datei verweisen. Beide Befehle arbeiten mit dem aktuellen Verzeichnis. Verwenden Sie validate, um einen ursprünglichen Befund nach einer Korrektur oder dann direkt erneut zu prüfen, wenn ein späterer Scan ihn nicht mehr meldet. Ein Scanvergleich allein belegt nicht, dass eine Korrektur funktioniert hat. Externe Werkzeuge können diese Befehle verwenden, ohne den Scanner neu zu erstellen.

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

codex-security login, logout und info

Melden Sie sich interaktiv an:

npx @openai/codex-security login

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

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

Prüfen Sie die aktuelle Anmeldung:

npx @openai/codex-security login status

Entfernen Sie die gespeicherte Anmeldung:

npx @openai/codex-security logout

Speichern Sie einen API key, indem Sie ihn über stdin übergeben:

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

Speichern Sie ein Enterprise-Zugriffstoken:

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

Untersuchen Sie schreibgeschützte SDK- und gebündelte Plugin-Metadaten:

npx @openai/codex-security info --json

Wenn Sie die CLI als MCP-Server bereitstellen, ist info der einzige verfügbare Befehl. Scans, Exporte, Anmeldung, Validierung und Korrekturen sind weiterhin nur über die CLI möglich.

Scanausgabe lesen

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

Ausführliche Diagnoseinformationen

Fügen Sie --verbose hinzu, um bereinigte Diagnoseinformationen zu Lebenszyklus, Authentifizierung, Fortschritt und Kosten nach 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.

Diese Protokollierungsoptionen gelten nur für die CLI. Anmeldedaten und Anbieterkennungen bleiben unkenntlich gemacht, und strukturierte Scanergebnisse verbleiben auf stdout.

Abschlusszusammenfassung

Ein abgeschlossener Scan schreibt die Anzahl seiner Befunde, die Aufschlüsselung nach Schweregrad, die Abdeckung, die verstrichene Zeit, den Berichtspfad und das Ergebnisverzeichnis nach stderr. Sofern verfügbar, enthält sie die Token- Nutzung und die geschätzten Kosten:

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

Informative Befunde werden in der Gesamtzahl der Zusammenfassung berücksichtigt. Schweregradrichtlinien werten nur Befunde der Stufen critical, high, medium und low aus.

JSON-Ausgabe

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

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

Fortschritt, Abschlusszusammenfassungen, Archivhinweise und Fehler verbleiben auf stderr. Ein abgeschlossener Scan gibt das vollständige JSON-Ergebnis auch dann aus, wenn eine Schweregradrichtlinie den Exit-Code 1 oder eine unvollständige Abdeckung den Exit-Code 2 zurückgibt.

Scanartefakte

Ein abgeschlossener Scan bewahrt den lesbaren Bericht und die strukturierten Artefakte gemeinsam auf:

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

Die strukturierten Dateien erfüllen unterschiedliche Aufgaben:

Datei Inhalt
scan-manifest.json Scanidentität, Status, Ziel, Umfang, Ersteller und versiegelte Artefaktdatensätze.
findings.json Befundkennungen, Schweregrad, Konfidenz, Taxonomie, Fundorte, Belege, Validierung, Datenfluss, Erreichbarkeit und Abhilfemaßnahmen.
coverage.json Geprüfte Bereiche, Ausschlüsse, zurückgestellte Arbeiten, offene Fragen und Vollständigkeit der Abdeckung.
report.md Lesbarer Scanbericht.
artifacts/ Unterstützende Scanartefakte.
exports/results.sarif Während des Scans erzeugtes SARIF, sofern vorhanden.

Die Vollständigkeit der Abdeckung hat drei Werte:

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

Prüfen Sie zurückgestellte Bereiche, ausdrückliche 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:

Exit Bedingung
0 Ein Scan wurde mit vollständiger Abdeckung abgeschlossen und hat seine Schweregradrichtlinie bestanden, ein Sammelscan wurde ohne Fehler abgeschlossen oder ein anderer Befehl war erfolgreich.
1 Ein abgeschlossener Scan meldet einen Befund mit mindestens dem konfigurierten Schweregrad.
2 Die CLI hat einen Eingabe-, Laufzeit- oder Exportfehler festgestellt, ein Scan weist eine unvollständige Abdeckung auf oder ein Sammelscan enthält Repositorys mit Fehlern.
130 Strg-C hat einen Scan unterbrochen.
143 SIGTERM hat einen Scan beendet.

Jeder Scan mit der Abdeckung partial oder unknown gibt 2 zurück, auch ohne eine Schweregradrichtlinie. Wenn Sie eine strukturierte Ausgabe anfordern, schreiben abgeschlossene Scans weiterhin die verfügbaren Ergebnisse nach stdout. Die CLI gibt nach einer Unterbrechung oder einem Laufzeitfehler den Speicherort einer vorhandenen Teilausgabe aus.

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. Verwenden Sie für Amazon Bedrock stattdessen einen Bedrock API key oder die standardmäßige AWS- Anmeldedatenkette.

Informationen zur Auswahl von Anmeldedaten finden Sie unter Scanauthentifizierung auswählen.

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

Die CLI erfordert Node.js 22 oder höher. Für die Ausführung eines Scans oder den Export von Befunden ist außerdem Python 3.10 oder höher erforderlich. Python 3.10 erfordert außerdem tomli. Verwenden Sie --python oder PYTHON, um einen Interpreter auszuwählen, wenn die automatische Erkennung ungeeignet ist.

Fahren Sie mit dem CLI-Schnellstart, der Anleitung für Sammelscans, den CLI-FAQ, der CI- Anleitung oder der Anleitung zum TypeScript SDK fort.

Klartext-Aliasse

  • --output FILE|-