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, enregistre le résultat, puis supprime la copie de travail temporaire du dépôt. Un dépôt est considéré comme terminé lorsque son analyse présente le statut completed dans le manifeste et que les artefacts de résultat requis sont valides. Les lacunes de couverture ne font pas échouer l’analyse.

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 le champ CSV prompt de chaque dépôt après les instructions d’analyse communes. Les instructions de suivi s’exécutent dans la même session authentifiée après les analyses réussies et les erreurs d’analyse, mais pas après une annulation ou une analyse qui atteint sa limite de coût. Les chemins des fichiers d’instructions sont résolus à partir de votre répertoire courant.

Choisir un modèle et un niveau de raisonnement

Les analyses en masse utilisent par défaut gpt-5.6-sol avec un effort de raisonnement xhigh. Pour choisir un autre modèle et un autre effort pour une campagne CSV, utilisez un modèle auquel vos identifiants donnent accès. Si vous vous connectez avec ChatGPT, vérifiez la disponibilité de GPT-6.1 Sol avec cette connexion avant d’utiliser cet exemple :

npx @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 fonctionnent pendant la découverte interactive des dépôts :

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

Les niveaux d’effort disponibles dépendent du modèle sélectionné. Les analyses en masse prennent en charge minimal, low, medium, high, xhigh et max ; GPT-6.1 Sol exige au minimum low.

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 conserve la configuration de la campagne, un enregistrement de chaque tentative 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
    │       ├── 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é et en dehors des dépôts analysés. Définissez la durée de conservation des résultats.

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 la campagne, lance de nouvelles tentatives pour les dépôts non terminés éligibles et ignore les analyses terminées, y compris celles présentant des lacunes de couverture. Leurs résultats restent disponibles.

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 enregistrement de résultat et de son propre répertoire d’artefacts. Les nouvelles tentatives couvrent les erreurs d’extraction, les échecs d’analyse et les artefacts requis manquants ou invalides. Les analyses terminées ne sont pas relancées en raison de lacunes de couverture ou de violations de la politique de gravité.

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. Cet hôte doit permettre la création d’espaces de noms utilisateur sans privilèges.

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.