ChatGPT-Dokumentation
Deutsch
Kontakt goolvyouyou@gmail.com

Schnellstart für die Codex Security CLI

Richten Sie Codex Security ein, führen Sie einen lokalen Scan aus und prüfen Sie den Bericht, die Befunde und die Abdeckung.

Codex Security unterstützt Sicherheits- und Entwicklungsteams dabei, Schwachstellen zu finden, zu bestätigen und zu beheben. Verwenden Sie die Befehlszeilenschnittstelle (CLI), um Repositorys zu scannen, die Ihnen gehören oder für deren Prüfung Sie eine Berechtigung besitzen, Befunde im zeitlichen Verlauf zu prüfen und Änderungen zu kontrollieren, bevor sie übernommen werden.

Voraussetzungen prüfen

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. Weitere Einzelheiten finden Sie unter Authentifizierung und Voraussetzungen.

CLI einrichten und überprüfen

Installieren Sie das veröffentlichte Paket:

npm install @openai/codex-security

Listen Sie die verfügbaren Befehle auf:

npx @openai/codex-security --help

Siehe auch CLI-Referenz.

Anmelden

Melden Sie sich für die lokale Verwendung mit Ihrem ChatGPT-Konto an:

npx @openai/codex-security login

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

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

Legen Sie für CI und andere automatisierte Workflows einen OpenAI API key fest:

export OPENAI_API_KEY="<your-api-key>"

Informationen zu AWS-Anmeldedaten finden Sie unter Einrichtung von Amazon Bedrock.

Um Ihre ChatGPT-Anmeldung zu verwenden, wenn zugleich ein API key festgelegt ist, wählen Sie sie ausdrücklich aus:

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

Um die Verwendung des API key aus der Umgebung zu erzwingen, wählen Sie die API-key-Authentifizierung aus:

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

Abhängig von Ihrem Konto und Repository können Scans des gesamten Repositorys außerdem Trusted Access for Cyber erfordern.

Scan vorbereiten

Wählen Sie ein zu scannendes Repository und ein Verzeichnis aus, in das die Ergebnisse geschrieben werden sollen.

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Wenn Sie --output-dir weglassen, speichert Codex Security die Ergebnisse in seinem eigenen persistenten Statusverzeichnis. Ergebnisse können Quelltextauszüge und Einzelheiten zu Schwachstellen enthalten. Wählen Sie daher einen privaten Speicherort und eine geeignete Aufbewahrungsrichtlinie.

Wenn das standardmäßige Statusverzeichnis nicht beschreibbar ist, wählen Sie ein beschreibbares Verzeichnis außerhalb des gescannten Repositorys aus:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Prüfen Sie das Repository, das Ziel und das Ausgabeverzeichnis, bevor Sie einen Scan starten:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

Der Probelauf prüft lokale Eingaben, ohne Codex zu starten, Anmeldedaten zu laden oder den Python-Interpreter des Plugins zu untersuchen.

Ersten Scan ausführen

Führen Sie einen Standardscan aus und bewahren Sie seine Ergebnisse im ausgewählten Verzeichnis auf:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

Standardmäßig schreibt die CLI den Scanfortschritt und die Abschlusszusammenfassung nach stderr. Das vollständige Scanergebnis wird nicht nach stdout ausgegeben. Ein abgeschlossener Scan gibt eine Zusammenfassung wie diese aus:

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

Token-Nutzung und geschätzte Kosten werden angezeigt, sofern sie verfügbar sind. Fordern Sie ausdrücklich eine strukturierte Ausgabe an, um das vollständige Ergebnis als maschinenlesbares JSON auszugeben:

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

Scans dienen standardmäßig nur zur Berichterstellung, sodass Befunde für die lokale Prüfung verfügbar bleiben. Sobald Sie bereit sind, Scans in CI auszuführen, empfiehlt es sich, einen Schweregrad-Schwellenwert hinzuzufügen.

Modell und Reasoning-Aufwand auswählen

Scans verwenden standardmäßig gpt-5.6-sol mit dem Reasoning-Aufwand xhigh. Wählen Sie ein anderes Modell und einen anderen Aufwand aus, wenn die Aufgabe dies erfordert:

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Unterstützte Aufwandsstufen sind minimal, low, medium, high und xhigh.

Ergebnisse prüfen

Öffnen Sie report.md, um das lesbare Ergebnis anzuzeigen. Das Scanverzeichnis enthält außerdem die von der Automatisierung verwendeten strukturierten Dateien:

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json erfasst das Ziel, den Umfang, den Ersteller und die versiegelten Artefakte.
  • findings.json erfasst für jeden Befund Schweregrad, Konfidenz, Fundorte, Belege und Abhilfemaßnahmen.
  • coverage.json erfasst geprüfte Bereiche, Ausschlüsse, zurückgestellte Arbeiten, offene Fragen und die Vollständigkeit der Abdeckung.

Die Abdeckung kann complete, partial oder unknown sein. Lesen Sie alle Angaben zu zurückgestellten Bereichen oder offenen Fragen, bevor Sie den Scan als Nachweis einer Prüfung behandeln. Die CLI-Referenz beschreibt den vollständigen Vertrag für Artefakte und Ausgaben.

Nächsten Scan auswählen

Verwenden Sie einen Pfadscan, wenn ein Repository getrennte Dienste oder Pakete enthält:

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Prüfen Sie committete Änderungen zwischen der Basisrevision und HEAD:

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Prüfen Sie bereitgestellte und nicht bereitgestellte Änderungen gegenüber HEAD:

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Diff- und Arbeitsbaum-Scans erwarten als Repository-Argument das Stammverzeichnis des Git- Arbeitsbaums. Rufen Sie die ausgewählten Revisionen ab, bevor Sie einen Diff-Scan starten.

Verwenden Sie den tiefgehenden Modus, wenn für ein Repository oder einen Pfad eine umfassendere Prüfung erforderlich ist:

npx @openai/codex-security scan "$REPOSITORY" --mode deep

Der tiefgehende Modus unterstützt Repository- und Pfadziele, jedoch keine Diff- oder Arbeitsbaum-Scans.

Architektur- und Sicherheitskontext hinzufügen

Stellen Sie Architekturdokumente, Bedrohungsmodelle oder Sicherheitsrichtlinien als Scan- Kontext bereit. Dadurch kann Codex Security Befunde danach bewerten, wie Ihr System tatsächlich funktioniert:

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

Scanbudget festlegen

Verwenden Sie --max-cost, um einen Scan zu beenden, wenn seine geschätzten Modellkosten einen Grenzwert in USD überschreiten:

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Bereits laufende Anfragen können oberhalb des Grenzwerts abgeschlossen werden. Codex Security behält die verfügbaren Ergebnisse bei, wenn ein Scan beendet wird.

Änderungen vor jedem Commit scannen

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

npx @openai/codex-security install-hook

Die Prüfung scannt bereitgestellte und nicht bereitgestellte Änderungen vor jedem Commit. Sie blockiert Befunde mit hohem Schweregrad und Scanfehler, ohne ein vorhandenes Pre-Commit-Skript zu ersetzen.

Repositorys gesammelt scannen

Melden Sie sich bei GitHub an, bevor Sie nach Repositorys suchen:

gh auth login

Suchen Sie Repositorys in Ihrem GitHub-Konto oder Ihrer Organisation und wählen Sie sie aus:

npx @openai/codex-security bulk-scan

Der interaktive Ablauf schließt archivierte Repositorys und Forks aus. Sie werden aufgefordert, die ausgewählten Repositorys vor dem Scannen zu bestätigen.

Um eine vorbereitete Repository-Liste zu scannen, stellen Sie eine CSV-Datei und ein Ausgabeverzeichnis bereit:

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

Führen Sie denselben Befehl erneut aus, um einen vorhandenen Sammelscan fortzusetzen. Abgeschlossene Repositorys mit intakten Ergebnisartefakten werden nicht erneut gescannt. Fügen Sie --max-attempts 3 hinzu, wenn Sie vorübergehende Repository- oder Scanfehler erneut versuchen möchten.

Informationen zur GitHub-Suche, CSV-Vorbereitung, zu Kampagnenergebnissen und zur Docker-Einrichtung finden Sie unter Sicherheitssammelscans ausführen.

Sammelscans in Docker ausführen

Wenn Ihr Zugriff das Codex Security-Docker-Image umfasst, verwenden Sie die bereitgestellte gehärtete Compose-Konfiguration und das Sicherheitsprofil auf einem Linux-Docker-Host. Der Host muss die Erstellung nicht privilegierter Benutzer-Namespaces unterstützen. Stellen Sie eine Repository- CSV-Datei bereit, bewahren Sie Ergebnisse und Anmeldestatus in persistent eingebundenen Verzeichnissen auf und stellen Sie Anmeldedaten über Ihre Umgebung oder einen Secret Manager bereit:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Der Container führt Sammelscans ohne Eingabeaufforderungen aus. Verwenden Sie die CLI außerhalb von Docker, wenn Sie Repositorys interaktiv suchen möchten. Stellen Sie für private Repositorys GH_TOKEN oder GITHUB_TOKEN über Ihre Umgebung oder einen Secret Manager bereit. Die Anmeldeanforderungen, einschließlich des Konto- und Repository- Zugriffs, gelten auch für containerisierte Scans.

Gespeicherten Scan erneut aufrufen

Listen Sie die für Ihr Repository gespeicherten Scans auf:

npx @openai/codex-security scans list "$REPOSITORY"

Kopieren Sie eine Scan-ID aus den Ergebnissen, um die Befunde und Konfiguration des Scans zu untersuchen:

npx @openai/codex-security scans show SCAN_ID

Um einen geprüften Befund als falsch positiv zu markieren, erläutern Sie, warum der Befund nicht zutrifft:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Spätere Scans berücksichtigen diese Erklärung, prüfen den aktuellen Code jedoch weiterhin erneut.

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

npx @openai/codex-security scans rerun SCAN_ID

Um zwei Scans zu vergleichen, ordnen Sie zunächst Befunde zu, die dieselbe Grundursache haben:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Prüfen Sie anschließend, welche Befunde neu, weiterhin vorhanden, erneut aufgetreten, behoben oder unbekannt sind:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Informationen zum CSV-Format für Sammelscans, zu Filtern für den Scanverlauf und zu Befehlsoptionen finden Sie in der CLI-Referenz.

Fahren Sie mit dem Workflow fort, der zu Ihrem Ziel passt:

  • Sicherheitssammelscans ausführen, um GitHub- Repositorys zu suchen oder einen fixierten CSV-Bestand zu scannen.
  • CLI-FAQ lesen, um Antworten zu Scanverlauf, Rückmeldungen zu falsch positiven Befunden, Abdeckung und Überprüfung von Korrekturen zu erhalten.
  • Scans in CI ausführen, um Pull Requests zu prüfen, Ergebnisse aufzubewahren und eine Schweregradrichtlinie festzulegen.
  • CLI-Referenz verwenden, um jedes Flag, Ausgabeformat, Artefakt und jeden Exit-Code nachzuschlagen.
  • TypeScript SDK integrieren, um Scans aus einer Anwendung oder einem Entwicklerwerkzeug heraus auszuführen.