Sicherheitsscans in großem Umfang ausführen

Verwenden Sie npx @openai/codex-security bulk-scan, um Repositorys in einer einzigen Kampagne zu überprüfen. Ermitteln Sie Repositorys aus Ihrem persönlichen GitHub-Konto oder einer Organisation, oder stellen Sie eine CSV-Datei bereit, die jedes Repository auf eine exakte Git-Revision festlegt.

Repository-Quelle auswählen

Beide Workflows speichern den Fortschritt, bewahren die Ergebnisse der einzelnen Repositorys auf und ermöglichen es Ihnen, eine Kampagne nach einer Unterbrechung fortzusetzen.

GitHub-Repositorys ermitteln

Melden Sie sich mit der GitHub CLI an:

gh auth login

Starten Sie einen interaktiven Scan in großen Mengen:

npx @openai/codex-security bulk-scan

Die CLI führt Sie durch diese Schritte:

1. Wählen Sie Ihr persönliches GitHub-Konto oder eine Organisation aus.
2. Prüfen Sie die Repositorys, die innerhalb der letzten 90 Tage aktiv waren.
3. Durchsuchen Sie die Repository-Liste und wählen Sie die zu scannenden Repositorys aus.
4. Wählen Sie ein Verzeichnis für die Scan-Ergebnisse aus.
5. Prüfen Sie die ausgewählten Repositorys und bestätigen Sie die Kampagne.

Bei der Ermittlung werden archivierte Repositorys und Forks ausgeschlossen. Die CLI zeichnet den exakten Commit des Standard-Branches für jedes ausgewählte Repository in <output-directory>/repositories.csv auf. Es werden keine Scans gestartet, bevor Sie die Auswahl bestätigen.

Um GitHub Enterprise Server zu verwenden, melden Sie sich zunächst bei Ihrem GitHub-Host an:

gh auth login --hostname github.example.com

Legen Sie GH_HOST fest, wenn Sie die Repository-Ermittlung starten:

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

Die interaktive Ermittlung erfordert ein Terminal. Verwenden Sie für CI, Container oder eine vorbereitete Repository-Liste stattdessen ein CSV-Inventar.

Repository-CSV erstellen

Erstellen Sie eine CSV-Datei mit einer Zeile für jedes Repository und jede festgelegte Revision:

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 unterstützt folgende Spalten:

Führen Sie folgenden Befehl aus, um die vollständige Commit-SHA eines lokalen Repositorys zu ermitteln:

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

Kampagne anhand einer CSV ausführen

Übergeben Sie die CSV-Datei und ein privates Ausgabeverzeichnis außerhalb der Repositorys:

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

--workers steuert die Anzahl paralleler Repository-Scans und verwendet standardmäßig 4. Dies legt nicht die Anzahl der unabhängigen Standard-Scan-Worker innerhalb der einzelnen Tiefenscans fest; konfigurieren Sie diese Grenzwerte über [deep_scan]. Verwenden Sie --mode deep, um für Zeilen ohne eigenen Wert für mode den Tiefenscan auszuwählen. Jede CSV-Zeile kann weiterhin einen eigenen Scan-Modus und Repository-Umfang festlegen.

Legen Sie [deep_scan].max_time_hours fest, um die Worker-Ausführung für jeden Tiefenscan in der Kampagne zu begrenzen. Das Flag --max-time-hours funktioniert mit scan, nicht mit bulk-scan.

Die CLI checkt jede festgelegte Revision aus, scannt das ausgewählte Ziel, zeichnet das Ergebnis auf und entfernt den temporären Repository-Checkout. Ein Repository gilt als abgeschlossen, wenn sein Scan den Manifeststatus completed und gültige erforderliche Ergebnisartefakte aufweist. Abdeckungslücken führen nicht dazu, dass der Scan fehlschlägt.

Sicherheitskontext und Anweisungen bereitstellen

Fügen Sie mit --knowledge-base jedem Scan Architekturdokumente, Bedrohungsmodelle oder Sicherheitsrichtlinien hinzu. Wiederholen Sie das Flag für weitere Dateien oder Verzeichnisse:

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

Um gemeinsame Scan-Anweisungen hinzuzufügen oder nach jedem Scan eine Folgeaktion auszuführen, stellen Sie Prompt-Dateien bereit:

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

Die CLI hängt den CSV-Wert prompt jedes Repositorys an die gemeinsamen Scan- Anweisungen an. Folgeanweisungen werden in derselben authentifizierten Sitzung nach erfolgreichen Scans und Scanfehlern ausgeführt, jedoch nicht nach einem Abbruch oder einem Scan, der sein Kostenlimit erreicht. Pfade zu Prompt-Dateien werden relativ zu Ihrem aktuellen Verzeichnis aufgelöst.

Modell und Reasoning-Aufwand auswählen

Massenscans verwenden standardmäßig gpt-5.6-sol mit dem Reasoning-Aufwand xhigh. Wenn Sie für eine CSV-Kampagne ein anderes Modell und einen anderen Aufwand wählen, verwenden Sie ein Modell, auf das Sie mit Ihren Anmeldedaten zugreifen können. Wenn Sie die ChatGPT-Anmeldung verwenden, prüfen Sie die Verfügbarkeit von GPT-6.1 Sol bei der ChatGPT-Anmeldung, bevor Sie dieses Beispiel verwenden:

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 funktionieren während der interaktiven Repository-Ermittlung:

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

Die verfügbaren Aufwandsstufen hängen vom ausgewählten Modell ab. Massenscans unterstützen minimal, low, medium, high, xhigh und max; GPT-6.1 Sol erfordert mindestens low.

Um OpenRouter oder Fireworks zu verwenden, legen Sie OPENROUTER_API_KEY beziehungsweise FIREWORKS_API_KEY fest und geben Sie --provider und --model an. Anmeldedaten und Beispiele finden Sie unter Einrichtung von OpenRouter oder Fireworks oder Einrichtung von Amazon Bedrock.

Kampagnenergebnisse prüfen

Das Ausgabeverzeichnis enthält die Kampagnenkonfiguration, einen Datensatz für jeden Versuch und separate Ergebnisse für jedes Repository:

security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    ├── payments/
    │   └── attempt-1/
    │       ├── scan-manifest.json
    │       ├── findings.json
    │       ├── coverage.json
    │       └── report.md
    └── identity/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            ├── coverage.json
            └── report.md

• manifest.json zeichnet die Repositorys, festgelegten Revisionen, Umfänge, Scan- Modi sowie die gemeinsamen oder Repository-spezifischen Anweisungen der Kampagne auf.
• results.jsonl zeichnet jeden Repository-Versuch, dessen Status, das Artefakt- Verzeichnis und alle verfügbaren Kosten- oder Fehlerdetails auf.
• report.md stellt einen lesbaren Bericht für einen Repository-Versuch bereit.
• findings.json und coverage.json zeichnen die Befunde und den überprüften Umfang dieses Versuchs auf.

Exportieren Sie einen abgeschlossenen Repository-Scan, wenn Sie ein portables Ergebnis benötigen:

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

Ergebnisse können Quellcodeauszüge und Details zu Schwachstellen enthalten. Halten Sie das Ausgabeverzeichnis privat und außerhalb der gescannten Repositories. Legen Sie fest, wie lange Sie die Ergebnisse aufbewahren.

Kampagne fortsetzen

Führen Sie 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, startet neue Versuche für infrage kommende, noch nicht abgeschlossene Repositories und überspringt abgeschlossene Scans, einschließlich Scans mit Abdeckungslücken. Deren Ergebnisse bleiben verfügbar.

Ändern Sie für ein bestehendes Ausgabeverzeichnis weder das Repository-Inventar noch die Scan- und Folgeanweisungen. Die CLI prüft das festgelegte Manifest und weist eine abweichende Kampagne zurück. Verwenden Sie ein neues Ausgabeverzeichnis, wenn Sie Repositorys, Revisionen, Umfänge, Scan-Modi oder gemeinsame beziehungsweise Repository-spezifische Anweisungen ändern.

Repository-Fehler erneut versuchen

Verwenden Sie --max-attempts, um einen Repository-Scan nach einem vorübergehenden Checkout- oder Scan- Fehler erneut zu versuchen:

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 verfügt über einen eigenen Ergebnisdatensatz und ein eigenes Artefaktverzeichnis. Wiederholungsversuche erfolgen bei Checkout-Fehlern, Scanfehlern und fehlenden oder ungültigen erforderlichen Artefakten. Abgeschlossene Scans werden aufgrund von Abdeckungslücken oder Verstößen gegen Schweregradrichtlinien nicht wiederholt.

Massenscans verwenden folgende Exit-Codes:

Massenscans in Docker ausführen

Das Codex Security-Repository enthält eine gehärtete Compose-Konfiguration für automatisierte CSV-Kampagnen auf einem Linux-Docker-Host. Der Host muss die Erstellung unprivilegierter Benutzernamensräume unterstützen.

Binden Sie die Repository-CSV, die Scan-Ergebnisse und den Anmeldestatus in persistente Verzeichnisse ein. Stellen Sie OpenAI-Anmeldedaten über die Umgebung oder einen Secret-Manager bereit. Stellen Sie für private GitHub-Repositorys auf dieselbe Weise GH_TOKEN oder GITHUB_TOKEN bereit.

Führen Sie das Image mit der eingebundenen CSV-Datei und dem eingebundenen Ausgabeverzeichnis aus:

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

Verwenden Sie dieselbe eingebundene CSV-Datei und dasselbe Ausgabeverzeichnis, um die Kampagne fortzusetzen. Legen Sie für GitHub Enterprise Server CODEX_SECURITY_GIT_HOST auf Ihren GitHub-Host fest.

Eine Übersicht aller verfügbaren Flags finden Sie in der Referenz zum bulk-scan-Befehl . Antworten auf häufige Fragen zur Scan-Abdeckung und zu Befunden finden Sie in den CLI-FAQ.