Guide de démarrage rapide de la CLI Codex Security

Lancez une analyse standard d’un dépôt local avec la CLI autonome de Codex Security. À la fin de ce guide, vous disposerez d’un rapport enregistré que vous pourrez consulter à tout moment. Pour lancer une analyse dans une conversation Codex, utilisez le plugin Codex Security.

Vérifiez 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 d’une version ultérieure. Si vous utilisez Python 3.10, installez tomli. Certaines requêtes de cybersécurité et certains résultats protégés nécessitent Trusted Access for Cyber.

La CLI s’exécute avec les permissions que vous accorde le système d’exploitation, sans s’interrompre pour demander votre approbation. Les processus d’analyse peuvent hériter de vos variables d’environnement. Avant de lancer l’analyse, retirez de l’environnement les identifiants dont elle n’a pas besoin. Consultez les permissions des analyses locales.

Installez et vérifiez la CLI

Installez le paquet public globalement, puis vérifiez sa version :

npm install -g @openai/codex-security
codex-security --version

Le paquet fournit la commande codex-security et son alias cs. Vérifiez que le répertoire des exécutables installés globalement par npm figure dans votre PATH.

Pour exécuter la CLI sans installation globale, utilisez npx :

npx @openai/codex-security --version

Les exemples ci-dessous utilisent npx @openai/codex-security. Après une installation globale, vous pouvez utiliser codex-security à la place.

La commande affiche la version du paquet installé. Utilisez info --json pour vérifier la version du plugin inclus, ou --help pour afficher la liste des commandes.

Connectez-vous

Connectez-vous avec votre compte ChatGPT :

npx @openai/codex-security login

Sur une machine sans navigateur, ajoutez --device-auth si votre espace de travail le permet, puis suivez les instructions de connexion qui s’affichent. Si l’authentification par appareil est désactivée, suivez les instructions de connexion via SSH. Utilisez --auth chatgpt dans les commandes d’analyse ci-dessous pour sélectionner cette connexion même si votre environnement contient aussi une clé API.

Pour les clés API et les autres fournisseurs, consultez la section Choisissez le mode d’authentification de l’analyse. Pour Amazon Bedrock, utilisez les identifiants AWS et les autorisations d’accès aux modèles à la place d’une connexion ChatGPT ou d’une clé API OpenAI.

Préparez une analyse

Remplacez ces deux chemins par celui de votre dépôt et celui d’un nouveau répertoire de résultats situé en dehors de l’arbre de travail Git du dépôt :

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

Les résultats peuvent contenir des extraits de code source et des détails sur les vulnérabilités. Choisissez un emplacement privé. Si vous omettez --output-dir, la CLI utilise le répertoire où elle conserve son état.

Vérifiez la cible et le répertoire de sortie :

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

Si la simulation réussit, les paramètres locaux sont valides. La simulation ne lance aucune analyse, ne charge pas les identifiants et ne vérifie pas l’interpréteur Python du plugin. Elle ne garantit donc pas que l’authentification fonctionnera ni que l’environnement d’exécution est correctement configuré.

Lancez votre première analyse

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

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

Dans un terminal interactif, un tableau de bord affiche la progression en temps réel. Dans un terminal non interactif, la progression s’affiche ligne par ligne. Ajoutez --headless pour obtenir cet affichage ligne par ligne dans un terminal interactif. Le tableau de bord et les journaux enregistrés peuvent contenir du code source ou des identifiants. Vérifiez leur contenu avant de le partager.

À la fin de l’analyse, stderr indique le chemin du rapport, le nombre de problèmes détectés et le temps écoulé. Exemple :

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

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

Par défaut, la gravité d’un problème détecté ne fait pas échouer l’analyse. Pour obtenir un format exploitable par un programme sur stdout, ajoutez --json. Pour qu’un problème détecté fasse échouer un contrôle de CI selon sa gravité, définissez une règle de gravité.

Examinez les résultats

Ouvrez report.md dans le répertoire des résultats. Vérifiez la cible et la révision, puis examinez les problèmes détectés. Pour connaître l’état et le périmètre enregistrés, consultez scan.status et scan.scope dans scan-manifest.json.

Une analyse menée à terme renvoie le code 0, sauf si un problème détecté atteint le seuil de gravité configuré, auquel cas elle renvoie 1. Le code 0 ne garantit pas que l’analyse a couvert tous les fichiers. Une erreur liée aux données d’entrée, à l’exécution, à l’intégrité des résultats ou à la production d’une sortie requise entraîne le code 2. La référence de la CLI explique les codes de sortie.

Pour chaque problème signalé, examinez le code concerné, les conditions qu’un attaquant devrait réunir, les éléments qui valident le signalement et les incertitudes qui subsistent. Un signalement fondé sur le code source ne s’accompagne pas nécessairement d’une reproduction réussie à l’exécution. N’engagez une correction que si les éléments disponibles étayent le problème signalé.

Lorsque vous partagez ou archivez le répertoire de l’analyse, conservez tout son contenu. Il contient scan-manifest.json et findings.json, ainsi que le rapport et les artefacts associés. Consultez la section Artefacts d’analyse pour connaître la structure complète du répertoire.

Exportez le modèle de menaces enregistré

Les analyses standard, les analyses approfondies et les analyses de diff enregistrent leur modèle de menaces avec les résultats. Exportez-le au format Markdown sans vous connecter ni effectuer de nouvel appel au modèle :

npx @openai/codex-security export "$SCAN_DIR" \
  --artifact threat-model --output "$SCAN_DIR/exports/threatmodel.md"

Si aucun modèle de menaces n’a été enregistré, export renvoie une erreur. Consultez la référence de la commande d’export pour choisir l’analyse enregistrée à exporter et, si besoin, un autre format de sortie.

Consultez une analyse enregistrée

Affichez la liste des analyses du dépôt :

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

Copiez l’identifiant d’une analyse dans les résultats et utilisez-le dans la commande suivante :

npx @openai/codex-security scans show SCAN_ID

Lorsqu’une analyse interactive se termine et signale des problèmes, la CLI propose également de les parcourir. Examinez les éléments à l’appui de chaque signalement avant de choisir un correctif. Pour les problèmes déjà enregistrés, utilisez les commandes de validation et de correction.

Choisissez la prochaine analyse

Si vous rencontrez un problème d’authentification, constatez des différences entre plusieurs exécutions d’une même analyse ou souhaitez signaler un faux positif, consultez la FAQ de la CLI.