Exécuter des analyses de sécurité par lot

Utilisez npx @openai/codex-security bulk-scan pour analyser plusieurs dépôts au cours d’une même campagne. Sélectionnez des dépôts depuis votre compte GitHub personnel ou une organisation, ou fournissez un fichier CSV qui indique la révision Git exacte à analyser pour chaque dépôt.

Choisir la source des dépôts

Les deux méthodes 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 par lot en mode interactif :

npx @openai/codex-security bulk-scan

La CLI vous guide à chaque étape :

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

La découverte exclut les dépôts archivés et les forks. Pour chaque dépôt sélectionné, la CLI enregistre le commit exact de la branche par défaut dans <output-directory>/repositories.csv. Les analyses démarrent uniquement après confirmation de votre 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, pour une exécution dans un conteneur ou si vous disposez déjà d’une liste de dépôts, utilisez un inventaire CSV.

Créer un inventaire CSV des dépôts

Créez un fichier CSV avec une ligne par dépôt indiquant la révision exacte à analyser :

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 accepte les colonnes suivantes :

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

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

Lancer une campagne à partir d’un fichier CSV

Indiquez le fichier CSV et un répertoire de sortie privé situé en dehors des dépôts :

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

--workers définit le nombre de dépôts analysés en parallèle. Sa valeur par défaut est 4. Cette option ne détermine pas le nombre de processus indépendants qui exécutent des analyses standard au sein de chaque analyse approfondie. Configurez ces limites dans [deep_scan]. Utilisez --mode deep pour sélectionner l’analyse approfondie pour les lignes sans valeur mode. Vous pouvez toujours préciser le mode d’analyse et le périmètre du dépôt sur chaque ligne du fichier CSV.

Définissez [deep_scan].max_time_hours pour limiter la durée d’exécution des processus pour chaque analyse approfondie de la campagne. L’option --max-time-hours s’applique à scan, mais pas à bulk-scan.

Pour chaque dépôt, la CLI récupère la révision indiquée, analyse la cible sélectionnée, enregistre le résultat, puis supprime la copie de travail temporaire. La CLI considère l’analyse du dépôt comme terminée lorsque le manifeste indique le statut completed et que les artefacts de résultats requis sont présents et valides. Une couverture partielle ne fait pas échouer l’analyse.

Partager le contexte de sécurité et les instructions

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 communes ou exécuter des instructions de 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

Pour chaque dépôt, la CLI ajoute le contenu de la colonne prompt du fichier CSV à la suite des instructions d’analyse communes. Les instructions de suivi s’exécutent dans la même session authentifiée après une analyse réussie ou une erreur d’analyse. Elles ne s’exécutent pas si l’analyse est annulée ou atteint sa limite de coût. Les chemins des fichiers de prompt sont relatifs au répertoire courant.

Choisir un modèle et un niveau d’effort de raisonnement

Par défaut, les analyses par lot utilisent gpt-5.6-sol avec un effort de raisonnement de niveau xhigh. Pour choisir un autre modèle et un autre niveau d’effort pour une campagne lancée à partir d’un fichier CSV, utilisez un modèle auquel vos identifiants vous donnent accès. Si vous vous connectez avec ChatGPT, vérifiez la disponibilité de GPT-6.1 Sol avant d’utiliser cet exemple :

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

Les mêmes options s’appliquent à la découverte interactive des dépôts :

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

Pour --effort, utilisez une valeur prise en charge par votre modèle, votre fournisseur et votre version de Codex.

Pour utiliser OpenRouter ou Fireworks, définissez respectivement OPENROUTER_API_KEY ou FIREWORKS_API_KEY, puis indiquez --provider et --model. Pour en savoir plus sur les identifiants et consulter des exemples, reportez-vous à la configuration d’OpenRouter ou de Fireworks ou à la configuration d’Amazon Bedrock.

Consulter les résultats d’une campagne

Le répertoire de sortie contient la configuration de la campagne, un historique des tentatives et des résultats distincts pour chaque dépôt :

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 répertorie les dépôts, les révisions exactes, les périmètres, les modes d’analyse et les instructions de la campagne, qu’elles soient communes ou propres à un dépôt.
• results.jsonl consigne chaque tentative d’analyse d’un dépôt, son statut, le répertoire de ses artefacts et, le cas échéant, les détails disponibles sur le coût ou les erreurs.
• report.md présente un rapport lisible pour une tentative d’analyse d’un dépôt.
• Ouvrez findings.json pour consulter les problèmes détectés lors de cette tentative et scan-manifest.json pour connaître le périmètre configuré et les éléments exclus de l’analyse.

Pour obtenir un résultat portable, exportez l’analyse terminée d’un dépôt :

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é et en dehors des dépôts analysés. Définissez la durée de conservation des résultats.

Reprendre une campagne

Relancez la commande initiale 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 la campagne et lance une nouvelle tentative pour chaque dépôt dont l’analyse reste à terminer et peut être relancée. Elle ignore les analyses terminées, y compris celles dont la couverture est partielle. Leurs résultats restent disponibles.

Lorsque vous réutilisez un répertoire de sortie existant, ne modifiez ni l’inventaire des dépôts ni les instructions d’analyse ou de suivi. La CLI vérifie le manifeste enregistré et refuse d’exécuter une campagne différente. Utilisez un nouveau répertoire de sortie si vous modifiez les dépôts, les révisions, les périmètres, les modes d’analyse ou les instructions communes ou propres à un dépôt.

Relancer l’analyse d’un dépôt après une erreur

Utilisez --max-attempts pour réessayer après une erreur temporaire lors de la récupération ou de l’analyse d’un dépôt :

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

Par défaut, la CLI effectue une seule tentative par dépôt. Chaque tentative dispose de sa propre entrée dans le fichier de résultats et de son propre répertoire d’artefacts. La CLI peut réessayer si la récupération du dépôt ou l’analyse échoue, ou si un artefact requis est manquant ou invalide. Une couverture partielle ou le non-respect d’une règle de sévérité ne déclenche pas de nouvelle tentative pour une analyse terminée.

Les analyses par lot utilisent les codes de sortie suivants :

Exécuter des analyses par lot dans Docker

Le dépôt Codex Security inclut une configuration Compose durcie pour automatiser les campagnes à partir d’un fichier CSV sur un hôte Docker sous Linux. L’hôte doit permettre la création d’espaces de noms utilisateur sans privilèges.

Utilisez des répertoires persistants montés dans le conteneur pour le fichier CSV des dépôts, les résultats d’analyse et les données de session. Fournissez les identifiants OpenAI via des variables d’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.

Lancez l’image avec le fichier CSV et le répertoire de sortie montés dans le conteneur :

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

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

Pour connaître toutes les options disponibles, consultez la référence de la commande bulk-scan. Pour les questions courantes sur la couverture des analyses et les problèmes détectés, consultez la FAQ de la CLI.