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-securityRufen 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 --helpFügen Sie einem Befehl --help hinzu, um seine Argumente und Optionen zu untersuchen:
npx @openai/codex-security scan --helpcodex-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 --llmsUntersuchen Sie das Schema der Scanargumente als JSON:
npx @openai/codex-security scan --schema --format jsonErzeugen Sie Shell-Vervollständigungen für Bash:
npx @openai/codex-security completions bashErsetzen 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 addSynchronisieren Sie Codex Security-Skills mit Ihren Agenten:
npx @openai/codex-security skills addMCP 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 chatgptUm einen API key aus der Umgebung zu verwenden, übergeben Sie --auth api-key:
npx @openai/codex-security scan . --auth api-keyFü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-solLegen 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 testsScannen Sie committete Änderungen:
npx @openai/codex-security scan . --diff origin/main --head HEADScannen Sie bereitgestellte und nicht bereitgestellte Änderungen:
npx @openai/codex-security scan . --working-tree --base HEADFühren Sie eine tiefgehendere Prüfung des Repositorys aus:
npx @openai/codex-security scan . --mode deepSicherheitskontext 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-policiesUnterstü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-existingScans 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.jsonEin 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-runLaufzeit 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 highSetzen 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-hookDie 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 mediumcodex-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 highStellen 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 4Die 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 scansListen Sie Scans für ein anderes Repository auf:
npx @openai/codex-security scans list /path/to/repositorySuchen Sie Scans, die unter einem bestimmten Ausgabeverzeichnis gespeichert sind:
npx @openai/codex-security scans list --scan-root /path/outside/repository/resultsScan untersuchen oder wiederholen
Zeigen Sie die Ergebnisse und Konfiguration eines gespeicherten Scans an:
npx @openai/codex-security scans show SCAN_IDFühren Sie den Scan mit seiner ursprünglichen Konfiguration für den aktuellen Checkout erneut aus:
npx @openai/codex-security scans rerun SCAN_IDBefunde 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_IDVergleichen 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_IDEin 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 --allScanergebnisse 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 REASONUntersuchen Sie den gespeicherten Scan, um das Auftreten des Befunds zu ermitteln:
npx @openai/codex-security scans show SCAN_IDErfassen 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_dirscan_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.sarifSchreiben 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.jsonExportieren Sie Befunde als CSV:
npx @openai/codex-security export /path/to/scan \
--export-format csv \
--output /path/outside/repository/exports/findings.csvcodex-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 highcodex-security login, logout und info
Melden Sie sich interaktiv an:
npx @openai/codex-security loginVerwenden Sie auf einem entfernten oder monitorlosen Computer die Geräteauthentifizierung:
npx @openai/codex-security login --device-authPrüfen Sie die aktuelle Anmeldung:
npx @openai/codex-security login statusEntfernen Sie die gespeicherte Anmeldung:
npx @openai/codex-security logoutSpeichern Sie einen API key, indem Sie ihn über stdin übergeben:
printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-keySpeichern Sie ein Enterprise-Zugriffstoken:
printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-tokenUntersuchen Sie schreibgeschützte SDK- und gebündelte Plugin-Metadaten:
npx @openai/codex-security info --jsonWenn 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 . --verboseLegen 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/scanInformative 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
usageFortschritt, 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 producedDie 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|-