Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Sicherheitsscans für mehrere Repositorys ausführen

Wähle GitHub-Repositorys interaktiv aus oder führe anhand einer CSV-Liste Sicherheitsscans aus, die du nach einer Unterbrechung fortsetzen kannst.

Mit npx @openai/codex-security bulk-scan kannst du mehrere Repositorys in einer Kampagne überprüfen. Wähle Repositorys aus deinem persönlichen GitHub-Konto oder aus einer Organisation aus. Alternativ kannst du eine CSV-Datei angeben, die für jedes Repository die genaue Git-Revision festlegt.

Das Paket @openai/codex-security ist öffentlich verfügbar. Für Scans mit Inferenz über OpenAI brauchst du Zugriff auf Codex Security. Installiere die CLI wie im CLI-Schnellstart beschrieben und wähle anschließend die Zugangsdaten für deinen Anbieter aus.

Quelle für die Repositorys auswählen

Quelle Wann du sie verwendest
Suche auf GitHub Wenn du Repositorys aus deinem persönlichen GitHub-Konto oder aus einer Organisation interaktiv auswählen möchtest.
CSV-Liste Wenn du eine automatisierte Kampagne mit genau festgelegten Repository-Revisionen ausführen und wiederholen möchtest.

Beide Verfahren speichern den Fortschritt und die Ergebnisse für jedes Repository. So kannst du die Kampagne nach einer Unterbrechung fortsetzen.

GitHub-Repositorys suchen und auswählen

Melde dich mit der GitHub CLI an:

gh auth login

Starte einen interaktiven Scan für mehrere Repositorys:

npx @openai/codex-security bulk-scan

Die CLI führt dich durch die folgenden Schritte:

  1. Wähle dein persönliches GitHub-Konto oder eine Organisation aus.
  2. Sieh dir die Repositorys an, die in den letzten 90 Tagen aktiv waren.
  3. Durchsuche die Liste und wähle die Repositorys aus, die du scannen möchtest.
  4. Wähle ein Verzeichnis für die Scanergebnisse aus.
  5. Überprüfe die ausgewählten Repositorys und bestätige die Kampagne.

Die Suche schließt archivierte Repositorys und Forks aus. Für jedes ausgewählte Repository hält die CLI den genauen Commit des Standard-Branchs in <output-directory>/repositories.csv fest. Die Scans starten erst, wenn du die Auswahl bestätigst.

Wenn du GitHub Enterprise Server verwendest, melde dich zuerst bei deinem GitHub-Host an:

gh auth login --hostname github.example.com

Setze GH_HOST, wenn du die Repository-Suche startest:

GH_HOST=github.example.com npx @openai/codex-security bulk-scan

Für die interaktive Suche brauchst du ein Terminal. Verwende für CI, für Container oder bei einer bereits vorbereiteten Repository-Liste eine CSV-Datei.

CSV-Datei für Repositorys erstellen

Erstelle eine CSV-Datei mit einer Zeile pro Repository und gib in jeder Zeile die genaue Revision an:

id,repository,revision,scope,mode,prompt
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard,Review payment authorization and refunds.
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep,Review session and identity boundaries.

Die CSV-Datei unterstützt folgende Spalten:

Spalte Erforderlich Beschreibung
id Ja Eindeutige Kennung des Repositorys. Verwende Buchstaben, Ziffern, Punkte, Bindestriche oder Unterstriche.
repository Ja HTTPS-URL, SSH-URL oder Pfad zu einem lokalen Repository. Relative Pfade beziehen sich auf das Verzeichnis der CSV-Datei.
revision Ja Vollständiger SHA-Hash des Git-Commits mit 40 oder 64 Zeichen. Die CLI unterstützt weder Branch-Namen noch Tags noch verkürzte Commit-Hashes.
scope Nein Pfad zum zu scannenden Verzeichnis, relativ zum Repository-Stammverzeichnis. Lass das Feld leer, um das gesamte Repository zu scannen.
mode Nein standard oder deep. Lass das Feld leer, um den beim Befehlsaufruf gewählten Modus zu verwenden.
prompt Nein Scan-Anweisungen für dieses Repository.

Den vollständigen SHA-Hash des aktuellen Commits eines lokalen Repositorys erhältst du mit diesem Befehl:

git -C /path/to/repository rev-parse HEAD

Kampagne mit einer CSV-Datei ausführen

Gib die CSV-Datei und ein privates Ausgabeverzeichnis außerhalb der Repositorys an:

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

--workers legt fest, wie viele Repositorys die CLI innerhalb der Kampagne gleichzeitig scannt. Der Standardwert ist 4.

Die CLI checkt jede festgelegte Revision aus, scannt den ausgewählten Bereich, speichert das Ergebnis und entfernt die temporäre Arbeitskopie des Repositorys. Der Scan eines Repositorys gilt als abgeschlossen, wenn im Manifest der Status completed steht und alle erforderlichen Ergebnisartefakte vorliegen und gültig sind. Lücken in der Scanabdeckung führen nicht dazu, dass der Scan fehlschlägt.

Sicherheitskontext und Anweisungen für alle Scans bereitstellen

Mit --knowledge-base kannst du jedem Scan Architekturdokumente, Bedrohungsmodelle oder Sicherheitsrichtlinien mitgeben. Gib die Option mehrfach an, um weitere Dateien oder Verzeichnisse hinzuzufügen:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Wenn du gemeinsame Scan-Anweisungen hinzufügen oder nach jedem Scan weitere Anweisungen ausführen möchtest, gib Prompt-Dateien an:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --scan-prompt-file scan-instructions.md \
  --post-scan-prompt-file follow-up.md

Für jedes Repository hängt die CLI den Inhalt des CSV-Felds prompt an die gemeinsamen Scan-Anweisungen an. Nach einem erfolgreichen Scan oder einem Scanfehler führt die CLI die Folgeanweisungen in derselben authentifizierten Sitzung aus. Bei einem Abbruch oder wenn der Scan sein Kostenlimit erreicht, entfallen die Folgeanweisungen. Relative Pfade zu Prompt-Dateien beziehen sich auf dein aktuelles Verzeichnis.

Modell und Reasoning-Aufwand auswählen

Scans für mehrere Repositorys verwenden standardmäßig gpt-5.6-sol mit dem Reasoning-Aufwand xhigh. Wenn du für eine CSV-Kampagne ein anderes Modell und einen anderen Reasoning-Aufwand wählen möchtest, verwende ein Modell, auf das du mit deinen Zugangsdaten zugreifen kannst. Wenn du dich über ChatGPT anmeldest, prüfe vor dem Ausführen dieses Beispiels die Verfügbarkeit von GPT-6.1 Sol:

npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4 \
--model gpt-6.1-sol \
--effort medium

Dieselben Optionen kannst du bei der interaktiven Repository-Suche verwenden:

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

Wähle für --effort einen Wert, den dein Modell, dein Anbieter und deine Codex-Version unterstützen.

Für OpenRouter oder Fireworks setzt du OPENROUTER_API_KEY bzw. FIREWORKS_API_KEY und gibst --provider und --model an. Informationen zu Zugangsdaten und Beispiele findest du im Setup für OpenRouter oder Fireworks oder im Setup für Amazon Bedrock.

Kampagnenergebnisse prüfen

Im Ausgabeverzeichnis findest du die Kampagnenkonfiguration, ein Protokoll aller Versuche und die Ergebnisse für jedes einzelne Repository:

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            └── report.md
  • manifest.json enthält die Repositorys der Kampagne, die festgelegten Revisionen, die Scanbereiche und Scanmodi sowie die gemeinsamen oder Repository-spezifischen Anweisungen.
  • results.jsonl enthält für jeden Scanversuch eines Repositorys den Status, das Artefaktverzeichnis und alle verfügbaren Angaben zu Kosten oder Fehlern.
  • report.md enthält einen lesbaren Bericht zu einem einzelnen Scanversuch für ein Repository.
  • Öffne findings.json, um die Befunde des Scanversuchs anzusehen. In scan-manifest.json siehst du, welcher Scanbereich für diesen Versuch konfiguriert war und was von der Überprüfung ausgeschlossen war.

Exportiere einen einzelnen abgeschlossenen Repository-Scan, wenn du das Ergebnis in einem übertragbaren Format brauchst:

npx @openai/codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif

Die Ergebnisse können Quellcodeauszüge und Details zu Schwachstellen enthalten. Halte das Ausgabeverzeichnis privat und lege es außerhalb der gescannten Repositorys an. Lege fest, wie lange du die Ergebnisse aufbewahrst.

Kampagne fortsetzen

Führe den ursprünglichen Befehl mit derselben CSV-Datei und demselben Ausgabeverzeichnis aus:

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

Die CLI setzt die Kampagne fort. Für Repositorys mit unvollständigen Scans startet sie einen neuen Versuch, sofern ein weiterer Versuch zulässig ist. Abgeschlossene Scans überspringt sie, auch wenn die Scanabdeckung Lücken aufweist. Die Ergebnisse dieser Scans bleiben verfügbar.

Wenn du ein bestehendes Ausgabeverzeichnis verwendest, lass die Repository-Liste sowie die Scan- und Folgeanweisungen unverändert. Die CLI prüft das für die Kampagne festgeschriebene Manifest und lehnt abweichende Kampagnen ab. Verwende ein neues Ausgabeverzeichnis, wenn du Repositorys, Revisionen, Scanbereiche, Scanmodi oder gemeinsame bzw. Repository-spezifische Anweisungen änderst.

Scanversuche nach Repository-Fehlern wiederholen

Mit --max-attempts kannst du nach einem vorübergehenden Fehler beim Checkout oder beim Scan einen neuen Versuch für das Repository zulassen:

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

Standardmäßig gibt es einen Versuch pro Repository. Jeder Versuch hat einen eigenen Ergebniseintrag und ein eigenes Artefaktverzeichnis. Die CLI kann einen Versuch wiederholen, wenn der Checkout oder der Scan fehlschlägt oder erforderliche Artefakte fehlen oder ungültig sind. Bei abgeschlossenen Scans lösen weder Lücken in der Scanabdeckung noch Verstöße gegen eine Richtlinie zum Schweregrad einen weiteren Versuch aus.

Für Scans mehrerer Repositorys gelten folgende Exitcodes:

Exitcode Bedeutung
0 Die Scans aller Repositorys sind abgeschlossen. Alle konfigurierten Richtlinien zum Schweregrad sind erfüllt.
1 Die Scans sind abgeschlossen, aber Befunde haben einen konfigurierten Schwellenwert für den Schweregrad erreicht.
2 Der Scan eines Repositorys ist fehlgeschlagen. Die Ursache war ein Fehler bei der Eingabe oder Ausführung, bei der Integrität der Ergebnisse oder bei einer erforderlichen Ausgabe.
130 Strg+C hat die Kampagne unterbrochen.
143 SIGTERM hat die Kampagne beendet.

Mehrere Repositorys in Docker scannen

Das Repository von Codex Security enthält eine gehärtete Compose-Konfiguration für automatisierte CSV-Kampagnen auf einem Docker-Host unter Linux. Der Host muss das Erstellen von Benutzer-Namespaces ohne erhöhte Rechte unterstützen.

Binde persistente Verzeichnisse für die Repository-CSV-Datei, die Scanergebnisse und den Anmeldestatus ein. Stelle die OpenAI-Zugangsdaten über Umgebungsvariablen oder einen Secret-Manager bereit. Für private GitHub-Repositorys stellst du GH_TOKEN oder GITHUB_TOKEN auf demselben Weg bereit.

Starte das Image mit der eingebundenen CSV-Datei und dem eingebundenen Ausgabeverzeichnis:

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

Verwende dieselbe eingebundene CSV-Datei und dasselbe eingebundene Ausgabeverzeichnis, um die Kampagne fortzusetzen. Für GitHub Enterprise Server setzt du CODEX_SECURITY_GIT_HOST auf deinen GitHub-Host.

Alle verfügbaren Optionen findest du in der Befehlsreferenz für bulk-scan. Antworten auf häufige Fragen zur Scanabdeckung und zu Befunden findest du in den FAQ zur CLI.