Exécuter des analyses de sécurité en masse

Utilisez npx @openai/codex-security bulk-scan pour examiner plusieurs dépôts dans une même campagne. Découvrez les dépôts de votre compte GitHub personnel ou d’une organisation, ou fournissez un fichier CSV qui associe chaque dépôt à une révision Git précise.

Choisir une source de dépôts

Les deux workflows enregistrent la progression, conservent les résultats de chaque dépôt et vous permettent de reprendre une campagne après une interruption.

Découvrir des dépôts GitHub

Connectez-vous avec GitHub CLI :

gh auth login

Lancez une analyse en masse interactive :

npx @openai/codex-security bulk-scan

La CLI vous guide à travers les étapes suivantes :

1. Choisissez votre compte GitHub personnel ou une organisation.
2. Examinez les dépôts actifs au cours des 90 derniers jours.
3. Recherchez des dépôts dans la liste et sélectionnez ceux à analyser.
4. Choisissez un répertoire pour les résultats des analyses.
5. Examinez les dépôts sélectionnés et confirmez la campagne.

La découverte exclut les dépôts archivés et les forks. La CLI consigne le commit exact de la branche par défaut pour chaque dépôt sélectionné dans <output-directory>/repositories.csv. Aucune analyse ne démarre avant que vous confirmiez la sélection.

Pour utiliser GitHub Enterprise Server, connectez-vous d’abord à votre hôte GitHub :

gh auth login --hostname github.example.com

Définissez GH_HOST lorsque vous lancez la découverte des dépôts :

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

La découverte interactive nécessite un terminal. Pour la CI, les conteneurs ou une liste de dépôts préparée, utilisez plutôt un inventaire CSV.

Créer un fichier CSV de dépôts

Créez un fichier CSV contenant une ligne pour chaque dépôt et sa révision épinglée :

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.

Le fichier CSV prend en charge les colonnes suivantes :

Pour trouver le SHA complet du commit d’un dépôt local, exécutez :

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

Exécuter une campagne à partir d’un fichier CSV

Transmettez le fichier CSV et un répertoire de sortie privé situé hors des dépôts :

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

--workers contrôle le nombre d’analyses de dépôts simultanées et sa valeur par défaut est 4. Il ne définit pas le nombre de workers indépendants d’analyse standard au sein de chaque analyse approfondie ; configurez ces limites avec [deep_scan]. Utilisez --mode deep pour sélectionner l’analyse approfondie pour les lignes qui ne disposent pas de leur propre mode. Chaque ligne du fichier CSV peut toujours choisir son propre mode d’analyse et son propre périmètre de dépôt.

Définissez [deep_scan].max_time_hours pour limiter l’exécution des workers de chaque analyse approfondie de la campagne. L’option --max-time-hours fonctionne avec scan, et non avec bulk-scan.

La CLI extrait chaque révision épinglée, analyse la cible sélectionnée, consigne le résultat, puis supprime l’extraction temporaire du dépôt. Un dépôt n’est considéré comme terminé que si son analyse offre une couverture complète et que tous les artefacts de résultats requis existent.

Partager le contexte et les instructions de sécurité

Ajoutez des documents d’architecture, des modèles de menaces ou des politiques de sécurité à chaque analyse avec --knowledge-base. Répétez l’option pour ajouter d’autres fichiers ou répertoires :

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

Pour ajouter des instructions d’analyse partagées ou exécuter un suivi après chaque analyse, fournissez des fichiers de prompt :

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

La CLI ajoute les prompt de chaque dépôt provenant du fichier CSV après les instructions d’analyse partagées. Les instructions de suivi s’exécutent dans la même session authentifiée après les analyses réussies ainsi qu’après celles présentant une couverture incomplète ou des erreurs, mais pas après une annulation ni après une analyse ayant atteint sa limite de coût. Les chemins des fichiers de prompt sont résolus à partir de votre répertoire actuel.

Choisir un modèle et un niveau de raisonnement

Par défaut, les analyses en masse utilisent gpt-5.6-sol avec un niveau de raisonnement xhigh. Pour choisir un autre modèle et un autre niveau pour une campagne CSV :

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --model gpt-5.6-terra \
  --effort high

Les mêmes options fonctionnent pendant la découverte interactive des dépôts :

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

Les niveaux pris en charge sont minimal, low, medium, high et xhigh.

Pour utiliser OpenRouter ou Fireworks, définissez respectivement OPENROUTER_API_KEY ou FIREWORKS_API_KEY, puis spécifiez --provider et --model. Pour les identifiants et des exemples, consultez la configuration d’OpenRouter ou de Fireworks ou la configuration d’Amazon Bedrock.

Examiner les résultats de la campagne

Le répertoire de sortie contient la campagne épinglée, un registre de résultats en ajout seul et des artefacts distincts pour chaque dépôt et chaque tentative :

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 consigne les dépôts, les révisions épinglées, les périmètres, les modes d’analyse et les instructions partagées ou propres à chaque dépôt de la campagne.
• results.jsonl consigne chaque tentative d’analyse d’un dépôt, son statut, son répertoire d’artefacts ainsi que tous les détails disponibles sur les coûts ou les erreurs.
• report.md fournit un rapport lisible pour une tentative d’analyse d’un dépôt.
• findings.json et coverage.json consignent les résultats de cette tentative et le périmètre examiné.

Exportez une analyse de dépôt terminée lorsque vous avez besoin d’un résultat portable :

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

Les résultats peuvent contenir des extraits de code source et des détails sur les vulnérabilités. Gardez le répertoire de sortie privé, hors des dépôts analysés, et soumettez-le à une politique de conservation appropriée.

Reprendre une campagne

Exécutez la commande d’origine avec le même fichier CSV et le même répertoire de sortie :

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

La CLI reprend les analyses de dépôts inachevées et ignore celles qui sont terminées. Les analyses présentant une couverture incomplète ne sont pas relancées. Leurs résultats restent disponibles et la commande se termine avec le code 2.

Ne modifiez pas l’inventaire des dépôts ni les instructions d’analyse et de suivi pour un répertoire de sortie existant. La CLI vérifie le manifeste épinglé et rejette toute campagne différente. Utilisez un nouveau répertoire de sortie lorsque vous modifiez les dépôts, les révisions, les périmètres, les modes d’analyse ou les instructions partagées ou propres à chaque dépôt.

Réessayer après des erreurs de dépôt

Utilisez --max-attempts pour réessayer d’analyser un dépôt après une erreur temporaire d’extraction ou d’analyse :

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

Par défaut, une seule tentative est effectuée par dépôt. Chaque tentative dispose de son propre reçu et de son propre répertoire d’artefacts. Les nouvelles tentatives couvrent les erreurs d’extraction, les échecs d’analyse et l’absence d’artefacts requis. Les analyses terminées avec une couverture incomplète ne sont pas relancées.

Les analyses en masse utilisent les codes de sortie suivants :

Exécuter des analyses en masse dans Docker

Le dépôt Codex Security comprend une configuration Compose renforcée pour les campagnes CSV automatisées sur un hôte Docker Linux. L’hôte doit prendre en charge la création d’espaces de noms utilisateur non privilégiés.

Conservez le fichier CSV des dépôts, les résultats d’analyse et l’état de connexion dans des répertoires persistants montés. Fournissez les identifiants OpenAI via l’environnement ou un gestionnaire de secrets. Pour les dépôts GitHub privés, fournissez GH_TOKEN ou GITHUB_TOKEN de la même manière.

Exécutez l’image avec le fichier CSV et le répertoire de sortie montés :

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

Utilisez le même fichier CSV et le même répertoire de sortie montés pour reprendre la campagne. Pour GitHub Enterprise Server, définissez CODEX_SECURITY_GIT_HOST sur votre hôte GitHub.

Pour consulter toutes les options disponibles, reportez-vous à la référence de la commande bulk-scan . Pour les questions fréquentes sur la couverture des analyses et les résultats, consultez la FAQ de la CLI.