Démarrage rapide avec Codex Security CLI

Exécutez une analyse standard d’un dépôt local avec la CLI autonome de Codex Security. Ce guide de démarrage rapide aboutit à un rapport enregistré que vous pouvez examiner et consulter à nouveau. Pour les analyses au sein d’une conversation Codex, utilisez le plugin Codex Security .

Vérifier les prérequis

Utilisez Node.js 24 ou 26, ou Node.js 22 à partir de la version 22.13.0. Vous avez également besoin de Python 3.10 ou version ultérieure. Python 3.10 nécessite aussi tomli. Les analyses utilisant l’inférence OpenAI nécessitent un accès à Codex Security. Selon votre compte et votre dépôt, les analyses de l’intégralité du dépôt peuvent également nécessiter Trusted Access for Cyber.

La CLI s’exécute avec les autorisations de votre système d’exploitation et ne s’interrompt pas pour demander une approbation. Les processus d’analyse peuvent hériter de votre environnement : supprimez donc les identifiants sans rapport avant de commencer. Consultez les autorisations des analyses locales.

Configurer et vérifier la CLI

Exécutez le package public avec npx :

npx @openai/codex-security --version

La commande affiche la version du package installé. Utilisez info --json pour vérifier la version du plugin inclus, ou --help pour lister les commandes. Les modifications du package sont répertoriées dans les versions de la CLI et du SDK.

Se connecter

Connectez-vous avec votre compte ChatGPT :

npx @openai/codex-security login

Sur une machine sans navigateur, ajoutez --device-auth et suivez les instructions de connexion affichées. Utilisez --auth chatgpt dans les commandes d’analyse ci-dessous pour sélectionner cette connexion même si votre environnement contient également une API key.

Pour les API keys et les autres fournisseurs, consultez Choisir l’authentification des analyses. Pour Amazon Bedrock, utilisez les identifiants AWS et l’accès aux modèles plutôt qu’une connexion ChatGPT ou une API key OpenAI.

Préparer une analyse

Remplacez ces chemins par celui de votre dépôt et celui d’un nouveau répertoire de résultats situé en dehors de son worktree Git :

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

Les résultats peuvent inclure des extraits du code source et des détails sur les vulnérabilités. Choisissez un emplacement privé. Si vous omettez --output-dir, la CLI utilise son répertoire d’état persistant.

Vérifiez la cible et l’emplacement de sortie :

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

Une simulation réussie confirme les données d’entrée locales. Elle ne lance pas d’analyse, ne charge pas d’identifiants et ne vérifie pas l’interpréteur Python du plugin ; elle ne garantit donc pas que l’authentification et la configuration de l’environnement d’exécution fonctionneront.

Exécuter votre première analyse

Supprimez --dry-run pour lancer l’analyse :

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

Un terminal interactif affiche un tableau de bord en temps réel. Les terminaux non interactifs affichent des lignes de progression. Ajoutez --headless pour afficher aussi des lignes de progression dans un terminal interactif. Le tableau de bord et les journaux enregistrés peuvent contenir du code source ou des identifiants. Examinez-les avant de les partager.

À la fin de l’analyse, stderr indique le chemin du rapport, le nombre de constats et le temps écoulé. Par exemple :

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

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

Par défaut, la gravité d’un constat ne fait pas échouer l’analyse. Pour obtenir une sortie stdout exploitable par une machine, ajoutez --json. Pour que les constats fassent échouer un contrôle CI, définissez une stratégie de gravité.

Examiner les résultats

Ouvrez report.md dans le répertoire indiqué. Confirmez la cible et la révision, puis consultez la couverture avant d’examiner chaque constat.

Vérifiez scan.status dans scan-manifest.json pour confirmer que l’analyse s’est terminée. Consultez coverage.json pour connaître les surfaces examinées, les chemins exclus, les travaux reportés et les questions en suspens.

Une analyse terminée renvoie le code de sortie 0, sauf si des constats atteignent un seuil de gravité configuré, auquel cas elle renvoie 1. Les lacunes de couverture ne modifient pas le code de sortie : un code de sortie 0 ne signifie donc pas que chaque fichier a été examiné. Les erreurs d’entrée, d’exécution, d’intégrité des résultats ou de production des sorties requises renvoient 2. La référence de la CLI explique les codes de sortie.

Pour chaque constat, vérifiez le code concerné, les conditions préalables nécessaires à l’attaquant, les éléments de validation et les incertitudes restantes. Un constat fondé sur le code source ne comprend pas nécessairement une reproduction réussie à l’exécution. Ne sélectionnez un constat à corriger que lorsque les éléments qui l’étayent confirment le problème signalé.

Conservez l’intégralité du répertoire d’analyse lorsque vous le partagez ou l’archivez. Il contient scan-manifest.json, findings.json et coverage.json, ainsi que le rapport et les artefacts justificatifs. Consultez Artefacts d’analyse pour connaître la structure complète.

Revenir sur une analyse enregistrée

Listez les analyses du dépôt :

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

Copiez un identifiant d’analyse depuis les résultats :

npx @openai/codex-security scans show SCAN_ID

Après une analyse interactive complète ayant produit des constats, la CLI propose également un outil de navigation parmi les constats. Examinez-y les éléments justificatifs avant de choisir une correction. Pour les constats enregistrés, utilisez les commandes de validation et de correction.

Choisir la prochaine analyse

Pour les problèmes d’authentification, les différences entre analyses successives ou les retours sur les faux positifs, consultez la FAQ de la CLI.