Documentation ChatGPT
Français
Contact goolvyouyou@gmail.com

Démarrage rapide avec Codex Security CLI

Configurez Codex Security, exécutez une analyse locale et examinez le rapport, les résultats et la couverture.

Codex Security aide les équipes de sécurité et d'ingénierie à détecter, confirmer et corriger les vulnérabilités. Utilisez son interface de ligne de commande (CLI) pour analyser les dépôts dont vous êtes propriétaire ou que vous êtes autorisé à évaluer, suivre les résultats dans le temps et vérifier les modifications avant leur intégration.

Vérifier les prérequis

La CLI nécessite Node.js 22 (22.13.0 ou version ultérieure), 24 ou 26. Les analyses, analyses groupées, exportations, historiques d'analyse et résultats enregistrés nécessitent également Python 3.10 ou une version ultérieure. Pour en savoir plus, consultez Authentification et prérequis.

Configurer et vérifier la CLI

Exécutez la CLI avec npx et vérifiez sa version :

npx @openai/codex-security --version

Pour afficher à la fois la version du package et celle du plugin inclus, exécutez :

npx @openai/codex-security info --json

Consultez les versions de la CLI et du SDK pour connaître les modifications du package.

Répertoriez les commandes disponibles :

npx @openai/codex-security --help

Consultez également la référence de la CLI.

Se connecter

Pour une utilisation locale, connectez-vous avec votre compte ChatGPT :

npx @openai/codex-security login

Sur une machine distante ou sans interface graphique, utilisez l'authentification de l'appareil :

npx @openai/codex-security login --device-auth

Pour la CI et les autres workflows automatisés, définissez une OpenAI API key :

export OPENAI_API_KEY="<your-api-key>"

Pour les identifiants AWS, consultez la configuration d'Amazon Bedrock. Pour OpenRouter ou Fireworks, définissez l'API key du fournisseur et sélectionnez un modèle avec --provider et --model.

Pour utiliser votre connexion ChatGPT lorsqu'une API key est également définie, sélectionnez-la explicitement :

npx @openai/codex-security scan . --auth chatgpt

Pour imposer l'API key de l'environnement, sélectionnez l'authentification par API key :

npx @openai/codex-security scan . --auth api-key

Selon votre compte et votre dépôt, les analyses de l'ensemble du dépôt peuvent également nécessiter Trusted Access for Cyber.

Préparer une analyse

Choisissez un dépôt fiable que vous êtes autorisé à évaluer. Les analyses utilisent vos autorisations locales du système d'exploitation et ne s'interrompent pas pour demander une approbation. Les processus d'analyse peuvent hériter de votre environnement ; supprimez donc les identifiants sans rapport avec l'analyse avant de commencer. Consultez Autorisations des analyses locales.

Choisissez un répertoire situé hors du dépôt pour les résultats de l'analyse :

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Si vous omettez --output-dir, Codex Security enregistre les résultats dans son propre répertoire d'état persistant. Les résultats peuvent contenir des extraits de code source et des informations sur les vulnérabilités ; choisissez donc un emplacement privé et une politique de conservation appropriée.

Si le répertoire d'état par défaut n'est pas accessible en écriture, sélectionnez un répertoire accessible en écriture situé hors du dépôt analysé :

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Vérifiez le dépôt, la cible et le répertoire de sortie avant de lancer une analyse :

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

L'exécution à blanc vérifie les entrées locales, y compris les chemins --knowledge-base, sans démarrer Codex, charger les identifiants ni sonder l'interpréteur Python du plugin.

Exécuter votre première analyse

Exécutez une analyse standard et conservez ses résultats dans le répertoire sélectionné :

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

Les terminaux interactifs affichent un tableau de bord d'analyse en direct. Ajoutez --headless pour afficher à la place des lignes de progression en texte brut. La CI et les terminaux sans session interactive utilisent automatiquement ce mode de progression.

Le tableau de bord affiche également les détails de la session en direct. Ceux-ci peuvent contenir du code source ou des identifiants ; vérifiez-les donc avant de les partager.

Par défaut, la CLI écrit la progression de l'analyse et son récapitulatif final dans stderr. Elle n'affiche pas le résultat complet de l'analyse dans stdout. Une analyse terminée affiche un récapitulatif de ce type :

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  COVERAGE  complete
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

L'utilisation des tokens et le coût estimé s'affichent lorsqu'ils sont disponibles. Pour afficher le résultat complet au format JSON lisible par une machine, demandez explicitement une sortie structurée :

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

Par défaut, les analyses génèrent uniquement un rapport, de sorte que les résultats restent disponibles pour un examen local. Vous pouvez ajouter un seuil de gravité lorsque vous êtes prêt à exécuter des analyses dans la CI.

Choisir un modèle et un niveau de raisonnement

Par défaut, les analyses utilisent gpt-5.6-sol avec le niveau de raisonnement xhigh. Sélectionnez un modèle et un niveau différents lorsque la tâche l'exige :

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

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

Examiner les résultats

Ouvrez report.md pour consulter le résultat lisible. Le répertoire de l'analyse contient également les fichiers structurés utilisés par les automatisations :

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json consigne la cible, la portée, le producteur et les artefacts scellés.
  • findings.json consigne la gravité, le niveau de confiance, les emplacements, les preuves et les mesures correctives de chaque résultat.
  • coverage.json consigne les surfaces examinées, les exclusions, les travaux reportés, les questions ouvertes et l'exhaustivité de la couverture.

La couverture peut être complete, partial ou unknown. Prenez connaissance de toutes les zones reportées et questions ouvertes avant de considérer l'analyse comme une preuve d'examen. La référence de la CLI décrit l'intégralité du contrat relatif aux artefacts et aux sorties.

Examiner et corriger les résultats

Après une analyse interactive complète ayant produit des résultats, la CLI propose un navigateur de résultats. Examinez les preuves et choisissez les résultats à corriger. Vous pouvez retrouver les tâches enregistrées dans l'application de bureau Codex.

Pour corriger les résultats de gravité élevée et critique sans utiliser le navigateur :

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

Ajoutez --create-pr pour valider dans un commit les correctifs vérifiés et ouvrir une pull request GitHub.

Vous pouvez également corriger des résultats enregistrés ou importer des issues Linear. Consultez la référence de validate et patch.

Choisir l'analyse suivante

Utilisez une analyse de chemin lorsqu'un dépôt contient des services ou packages distincts :

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Examinez les modifications validées entre la révision de base et HEAD :

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Examinez les modifications indexées et non indexées par rapport à HEAD :

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Les analyses de différences et de worktree attendent que l'argument du dépôt désigne la racine du worktree Git. Récupérez les révisions sélectionnées avant de lancer une analyse de différences.

Utilisez le mode approfondi lorsqu'un dépôt ou un chemin nécessite un examen plus vaste :

npx @openai/codex-security scan "$REPOSITORY" --mode deep

Pour contrôler les workers, les sous-agents et le moment où l'analyse s'arrête :

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

Ces options nécessitent le mode approfondi, qui prend en charge les cibles de type dépôt et chemin, mais pas les analyses de différences ni de worktree. Ici, --workers contrôle les workers d'analyse standard indépendants au sein d'une même analyse ; bulk-scan --workers contrôle les analyses de dépôts simultanées. --max-time-hours accepte un nombre positif allant jusqu'à 96, y compris un nombre fractionnaire d'heures. Lorsque la limite est atteinte, l'analyse arrête les workers inachevés, conserve les résultats terminés et les agrège dans le rapport final.

Ajouter du contexte architectural et de sécurité

Fournissez des documents d'architecture, des modèles de menaces ou des politiques de sécurité comme contexte de l'analyse. Codex Security pourra ainsi évaluer les résultats en fonction du fonctionnement réel de votre système :

npx @openai/codex-security scan "$REPOSITORY" \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Ajouter des instructions d'analyse personnalisées

Ajoutez des instructions qui concentrent l'analyse sur vos priorités de sécurité. Utilisez un second fichier pour les instructions de suivi :

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

Le suivi s'exécute dans la même session authentifiée après les analyses réussies et celles dont la couverture est incomplète ou qui comportent des erreurs. Si le suivi échoue, la CLI signale un avertissement et conserve l'analyse terminée. Il ne s'exécute pas après une annulation ni après une analyse ayant atteint sa limite de coût. Les deux options fonctionnent également avec bulk-scan ; une colonne CSV prompt ajoute des instructions propres au dépôt.

Définir un budget d'analyse

Utilisez --max-cost pour arrêter une analyse lorsque le coût estimé du modèle dépasse une limite en USD :

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Les requêtes déjà en cours peuvent se terminer légèrement au-dessus de la limite. Si une analyse approfondie atteint la limite après que Codex Security a agrégé les résultats des workers terminés, la CLI enregistre le rapport terminé, marque sa couverture comme partial et renvoie le code de sortie 2. Si l'analyse ne peut pas produire de rapport terminé, toute sortie partielle disponible reste sur le disque.

Analyser les modifications avant chaque commit

Installez un contrôle de sécurité Git pre-commit pour votre dépôt :

npx @openai/codex-security install-hook

Ce contrôle analyse les modifications indexées et non indexées avant chaque commit. Il bloque les résultats de gravité élevée et les erreurs d'analyse sans remplacer un éventuel script pre-commit existant.

Analyser des dépôts en masse

Connectez-vous à GitHub avant de rechercher des dépôts :

gh auth login

Recherchez et sélectionnez des dépôts dans votre compte ou votre organisation GitHub :

npx @openai/codex-security bulk-scan

Le flux interactif exclut les dépôts archivés et les forks. Il vous demande de confirmer les dépôts sélectionnés avant l'analyse.

Pour analyser une liste de dépôts préparée, fournissez un fichier CSV et un répertoire de sortie :

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

Exécutez de nouveau la même commande pour reprendre une analyse groupée existante. Codex Security ignore les dépôts terminés. Ajoutez --max-attempts 3 si vous souhaitez réessayer après des erreurs temporaires de dépôt ou d'analyse.

Pour en savoir plus sur la recherche GitHub, la préparation du fichier CSV, les résultats de campagne et la configuration de Docker, consultez Exécuter des analyses de sécurité groupées.

Exécuter des analyses groupées dans Docker

Si votre accès comprend l'image Docker de Codex Security, utilisez la configuration Compose renforcée et le profil de sécurité fournis sur un hôte Docker Linux. L'hôte doit prendre en charge la création d'espaces de noms d'utilisateurs sans privilèges. Fournissez un fichier CSV de dépôts, conservez les résultats et l'état de connexion dans des répertoires montés persistants et fournissez les identifiants par l'intermédiaire de votre environnement ou d'un gestionnaire de secrets :

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

Le conteneur exécute des analyses groupées sans prompts interactifs. Utilisez la CLI hors de Docker lorsque vous souhaitez rechercher des dépôts de manière interactive. Pour les dépôts privés, fournissez GH_TOKEN ou GITHUB_TOKEN par l'intermédiaire de votre environnement ou d'un gestionnaire de secrets. Les exigences de connexion, notamment celles relatives au compte et à l'accès au dépôt, s'appliquent également aux analyses conteneurisées.

Revenir sur une analyse enregistrée

Répertoriez les analyses enregistrées pour votre dépôt :

npx @openai/codex-security scans list "$REPOSITORY"

Copiez un ID d'analyse depuis les résultats afin d'examiner ses résultats et sa configuration :

npx @openai/codex-security scans show SCAN_ID

Pour examiner les événements enregistrés d'une analyse et de ses workers :

npx @openai/codex-security scans logs SCAN_ID

Les journaux enregistrés ne sont pas expurgés et peuvent contenir du code source ou des identifiants. Vérifiez-les avant de les partager.

Répertoriez les résultats ouverts parmi les analyses du dépôt :

npx @openai/codex-security findings list "$REPOSITORY"

Un résultat antérieur reste ouvert si la dernière analyse ne le confirme pas.

Pour marquer un résultat examiné comme faux positif, expliquez pourquoi il ne s'applique pas :

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Les analyses ultérieures prennent en compte cette explication, mais vérifient tout de même à nouveau le code actuel.

Exécutez la même analyse sur la version actuellement extraite en utilisant sa configuration d'origine :

npx @openai/codex-security scans rerun SCAN_ID

Comparez deux analyses pour identifier les résultats nouveaux, persistants, rouverts, résolus ou inconnus :

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparaison rapproche automatiquement les résultats selon leur cause racine et réutilise les correspondances enregistrées.

Pour connaître le format CSV des analyses groupées, les filtres de l'historique d'analyse et les options de commande, consultez la référence de la CLI.

Poursuivez avec le workflow adapté à votre objectif :