Référence de Codex Security CLI

Utilisez cette référence pour consulter les commandes codex-security prises en charge, leurs options, les formats de sortie et le comportement de sortie. Pour effectuer une première analyse guidée, commencez par le démarrage rapide de la CLI.

Installez le package publié dans votre projet :

npm install @openai/codex-security

Appelez le package installé avec npx @openai/codex-security. Vous pouvez utiliser codex-security directement lorsque l’exécutable est disponible dans votre PATH.

Vue d’ensemble des commandes

usage: codex-security [--version] <command> [options]

La CLI fournit les commandes suivantes :

La CLI fournit également les commandes d’intégration suivantes :

Répertoriez toutes les commandes disponibles :

npx @openai/codex-security --help

Ajoutez --help à une commande pour examiner ses arguments et ses options :

npx @openai/codex-security scan --help

codex-security --version affiche la version installée, puis se termine. codex-security info --json indique les versions du SDK et du plugin intégré. Aucune de ces commandes ne nécessite Python.

Découvrir les commandes et connecter des agents

Affichez le manifeste de commandes lisible par les agents :

npx @openai/codex-security --llms

Examinez le schéma des arguments d’analyse au format JSON :

npx @openai/codex-security scan --schema --format json

Générez les complétions shell pour Bash :

npx @openai/codex-security completions bash

Remplacez bash par zsh ou fish pour ces shells.

Les résultats d’analyse prennent en charge --format toon|json|yaml|jsonl et --full-output. Cette option --format au niveau du framework est distincte de --export-format, qui sélectionne le format d’un artefact exporté depuis une analyse terminée. L’aide globale des commandes répertorie également md, mais les résultats d’analyse ne prennent pas en charge la sortie Markdown.

Enregistrez la CLI comme serveur MCP :

npx @openai/codex-security mcp add

Synchronisez les skills Codex Security avec vos agents :

npx @openai/codex-security skills add

MCP expose uniquement la commande de métadonnées en lecture seule info. Les analyses, les exportations, l’authentification, la validation et les correctifs restent disponibles uniquement dans la CLI.

codex-security scan

Exécutez une analyse sur un dépôt, des chemins sélectionnés, des modifications validées ou le worktree.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository utilise par défaut le répertoire actuel.

Sélectionner l’authentification de l’analyse

Utilisez --auth auto, la valeur par défaut, pour sélectionner automatiquement les identifiants. Lorsqu’une connexion ChatGPT et OPENAI_API_KEY ou CODEX_API_KEY sont disponibles, les analyses interactives avec sortie texte vous demandent quel identifiant utiliser. La CI, les analyses JSON et JSONL, ainsi que les autres analyses sans terminal interactif utilisent l’API key de l’environnement. Les exécutions à blanc n’affichent aucune invite et ne chargent pas les identifiants.

Pour utiliser vos identifiants enregistrés, transmettez --auth chatgpt :

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

Pour utiliser une API key d’environnement, transmettez --auth api-key :

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

Pour faire des identifiants enregistrés le choix automatique par défaut, exécutez unset OPENAI_API_KEY CODEX_API_KEY.

Utiliser Amazon Bedrock

Sélectionnez Amazon Bedrock avec --provider amazon-bedrock et indiquez explicitement un modèle Bedrock avec --model :

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Définissez AWS_REGION et authentifiez-vous avec AWS_BEARER_TOKEN_BEDROCK, des clés d’accès AWS standard, un profil AWS, une identité web, des identifiants de conteneur ou la chaîne d’identifiants AWS par défaut. Les analyses Bedrock utilisent des identifiants AWS au lieu de --auth, d’une connexion ChatGPT ou d’une API key OpenAI. scan et bulk-scan prennent tous deux en charge --provider.

Sélectionner la cible de l’analyse

Choisissez un type de cible pour chaque analyse.

--path, --diff et --working-tree s’excluent mutuellement. --head nécessite --diff, et --base nécessite --working-tree. Le mode approfondi prend en charge les cibles de type dépôt et chemin.

Les analyses de diff et de worktree exigent que l’argument du dépôt désigne la racine du worktree Git. Les refs sélectionnées doivent exister dans cette version extraite.

Analysez l’ensemble du dépôt :

npx @openai/codex-security scan .

Analysez les chemins sélectionnés :

npx @openai/codex-security scan . --path src --path tests

Analysez les modifications validées :

npx @openai/codex-security scan . --diff origin/main --head HEAD

Analysez les modifications indexées et non indexées :

npx @openai/codex-security scan . --working-tree --base HEAD

Effectuez un examen plus approfondi du dépôt :

npx @openai/codex-security scan . --mode deep

Ajouter du contexte de sécurité

Utilisez --knowledge-base PATH pour fournir des documents d’architecture, des modèles de menace ou des politiques de sécurité. Répétez l’option pour ajouter d’autres fichiers ou répertoires :

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

Les documents pris en charge comprennent les fichiers .md, .markdown, .txt, .pdf et .docx. La CLI parcourt les répertoires de manière récursive, rejette les chemins d’entrée liés, ignore les entrées de répertoire liées et conserve le contenu extrait des documents en dehors des résultats d’analyse enregistrés.

Définir les options de sortie et de politique

Utilisez ces options pour conserver les artefacts et les résultats antérieurs, ou créer un résultat lisible par une machine.

La limite de coût est une estimation, et non un plafond de dépenses strict. Les requêtes déjà en cours peuvent se terminer au-delà de la limite, et les résultats d’analyse partiels restent disponibles.

Lorsque vous omettez --output-dir, les résultats sont conservés sous $CODEX_HOME/state/plugins/codex-security/scans/<repository>. CODEX_HOME utilise ~/.codex par défaut. Définissez CODEX_SECURITY_STATE_DIR pour conserver les résultats sous $CODEX_SECURITY_STATE_DIR/scans/<repository> à la place. Ces répertoires peuvent contenir des extraits de code source et des détails sur les vulnérabilités ; gérez donc leurs autorisations et leur conservation en conséquence.

Le workbench conserve l’historique des analyses dans $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. La définition de CODEX_SECURITY_STATE_DIR déplace également la base de données du workbench.

Le répertoire de sortie doit se trouver en dehors du répertoire analysé et de tout worktree Git englobant. Une analyse peut remplacer un répertoire de résultats existant avec --archive-existing.

Pour conserver les résultats antérieurs avant de réutiliser un répertoire de sortie :

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

Par défaut, les analyses produisent uniquement un rapport. Ajoutez --fail-on-severity pour évaluer une politique de sévérité dans la CI :

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

Une exécution à blanc vérifie les entrées locales sans charger les identifiants, démarrer Codex ni tester l’interpréteur Python du plugin :

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Configurer l’environnement d’exécution

Utilisez les options d’exécution lorsque vous devez indiquer explicitement un modèle, un interpréteur, un plugin ou une valeur de configuration Codex.

Pour sélectionner un autre modèle et un autre niveau de raisonnement sans écrire de TOML :

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

Placez entre guillemets les valeurs de chaîne transmises avec --codex afin que l’analyseur TOML reçoive une chaîne :

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

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

npx @openai/codex-security install-hook

Le contrôle analyse les modifications indexées et non indexées avant chaque commit et bloque les résultats de sévérité élevée ou les erreurs d’analyse. Il respecte core.hooksPath et ne remplace pas un script pre-commit existant. Définissez un autre seuil de sévérité si nécessaire :

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

Recherchez et analysez des dépôts GitHub, ou exécutez une analyse pouvant être reprise à partir d’un fichier CSV de dépôts :

Pour obtenir un guide complet sur la recherche de dépôts GitHub, les inventaires CSV, les résultats de campagne et les analyses conteneurisées, consultez Exécuter des analyses de sécurité en masse.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Exécutez npx @openai/codex-security bulk-scan sans argument pour sélectionner les dépôts de manière interactive. Ce parcours nécessite une connexion à GitHub CLI.

Pour choisir un modèle et un niveau de raisonnement pendant la recherche interactive :

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

Pour une liste de dépôts préparée, fournissez un fichier CSV et --output-dir :

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

Le fichier CSV nécessite les colonnes id, repository et revision. Les révisions doivent être des hachages de commit complets. Les colonnes facultatives scope et mode configurent les dépôts individuellement :

id,repository,revision,scope,mode
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard

--workers limite le nombre d’analyses simultanées et utilise 4 par défaut. --mode utilise standard par défaut, et --max-attempts utilise 1 par défaut. Définissez --max-attempts lorsque vous souhaitez réessayer un dépôt après une erreur. Exécutez de nouveau la même commande pour reprendre une analyse en masse depuis son répertoire de sortie existant. La CLI ignore les dépôts terminés uniquement lorsque leurs artefacts de résultats enregistrés sont toujours présents.

Pour les campagnes conteneurisées, consultez Exécuter des analyses en masse dans Docker.

codex-security scans

Rechercher les analyses enregistrées

Répertoriez les analyses enregistrées pour le répertoire actuel :

npx @openai/codex-security scans

Répertoriez les analyses d’un autre dépôt :

npx @openai/codex-security scans list /path/to/repository

Recherchez les analyses stockées dans un répertoire de sortie spécifique :

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Examiner ou répéter une analyse

Affichez les résultats et la configuration d’une analyse enregistrée :

npx @openai/codex-security scans show SCAN_ID

Réexécutez l’analyse sur la version actuellement extraite en utilisant sa configuration d’origine :

npx @openai/codex-security scans rerun SCAN_ID

Faire correspondre et comparer les résultats

Faites correspondre les résultats qui partagent la même cause racine entre deux analyses :

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Comparez les analyses mises en correspondance afin de repérer les résultats nouveaux, persistants, rouverts, résolus et inconnus :

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Un résultat est inconnu lorsque l’analyse ultérieure présente une couverture incomplète ou ne couvre pas l’emplacement d’origine du résultat. Ajoutez --force à match lorsque vous devez recalculer une correspondance existante.

Pour faire correspondre toutes les analyses terminées du dépôt actuel, y compris celles provenant d’autres versions extraites :

npx @openai/codex-security scans match --all

Les résultats d’analyse peuvent varier même lorsque vous réexécutez la même configuration. La mise en correspondance et la comparaison suivent les changements ; elles ne rendent pas les résultats déterministes et ne prouvent pas qu’une vulnérabilité n’existe plus. Utilisez validate pour revérifier un résultat critique pour la sécurité dans le code actuel.

codex-security findings

Enregistrez un résultat examiné comme faux positif :

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Examinez l’analyse enregistrée pour identifier l’occurrence du résultat :

npx @openai/codex-security scans show SCAN_ID

Enregistrez une explication précise du faux positif :

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

Le motif ne doit pas être vide. Codex Security enregistre la décision pour le dépôt et la fournit comme contexte aux analyses ultérieures. Chaque analyse revérifie indépendamment la source actuelle, les contrôles et l’accessibilité. Une décision antérieure ne désactive pas une règle, un chemin ou une classe de vulnérabilités.

codex-security export

Exportez des données CSV, JSON ou SARIF à partir d’une analyse terminée et scellée. L’exportation valide les artefacts d’analyse avant d’écrire la sortie et n’utilise ni l’environnement d’exécution Codex ni les identifiants.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir est le répertoire de l’analyse terminée.

--source-root fonctionne uniquement avec --export-format sarif. JSON conserve le document de résultats scellé. CSV contient des colonnes de résultats portables et n’inclut pas l’état de triage local du workbench.

Sans --output, la CLI écrit le SARIF dans results.sarif, le JSON dans findings.json et le CSV dans findings.csv, dans le répertoire de travail actuel. Les exportations peuvent contenir des extraits de code source et des détails sur les vulnérabilités. Exécutez la commande en dehors du dépôt ou transmettez --output avec un chemin privé situé en dehors de la version extraite analysée.

Écrivez le SARIF dans un fichier :

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Écrivez le SARIF dans stdout :

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Exportez les résultats au format JSON :

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Exportez les résultats au format CSV :

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

codex-security validate et codex-security patch

Vérifiez si un résultat potentiel est valide :

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

Générez un correctif avec le skill de remédiation intégré :

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Chaque argument peut contenir du texte littéral ou pointer vers un fichier. Les deux commandes fonctionnent dans le répertoire actuel. Utilisez validate pour revérifier directement un résultat d’origine après un correctif ou lorsqu’une analyse ultérieure ne le signale plus. Une comparaison d’analyses ne suffit pas à prouver qu’un correctif fonctionne. Les outils externes peuvent utiliser ces commandes sans reconstruire le scanner.

Utilisez --effort pour sélectionner le niveau de raisonnement de l’une ou l’autre commande :

npx @openai/codex-security validate "Possible SQL injection" --effort high

codex-security login, logout et info

Connectez-vous de manière interactive :

npx @openai/codex-security login

Utilisez l’authentification par appareil sur une machine distante ou sans interface graphique :

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

Vérifiez la connexion actuelle :

npx @openai/codex-security login status

Supprimez la connexion enregistrée :

npx @openai/codex-security logout

Stockez une API key en la transmettant dans stdin :

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Stockez un token d’accès d’entreprise :

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

Examinez les métadonnées en lecture seule du SDK et du plugin intégré :

npx @openai/codex-security info --json

Lorsque vous exposez la CLI comme serveur MCP, info est la seule commande disponible. Les analyses, les exportations, la connexion, la validation et les correctifs restent disponibles uniquement dans la CLI.

Lire la sortie de l’analyse

Par défaut, les analyses envoient la progression, les résumés finaux et les erreurs dans stderr sans écrire le résultat complet de l’analyse dans stdout. Demandez --json, --format ou --full-output pour envoyer les résultats structurés de l’analyse dans stdout.

Diagnostics détaillés

Ajoutez --verbose pour afficher dans stderr des diagnostics expurgés sur le cycle de vie, l’authentification, la progression et le coût :

npx @openai/codex-security scan . --verbose

Définissez CODEX_SECURITY_LOG_LEVEL=debug pour activer les mêmes diagnostics sans l’option. LOG_LEVEL=debug active également les diagnostics lorsque CODEX_SECURITY_LOG_LEVEL n’est pas défini.

Ces contrôles de journalisation s’appliquent uniquement à la CLI. Les identifiants et les identifiants de fournisseur restent expurgés, et les résultats structurés de l’analyse restent dans stdout.

Résumé final

Une analyse terminée écrit dans stderr le nombre de résultats, leur répartition par sévérité, la couverture, le temps écoulé, le chemin du rapport et le répertoire des résultats. Elle inclut l’utilisation des tokens et le coût estimé lorsqu’ils sont disponibles :

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

Les résultats informatifs sont inclus dans le total du résumé. Les politiques de sévérité évaluent uniquement les résultats critical, high, medium et low.

Sortie JSON

scan --json écrit un document JSON complet dans stdout. Sa structure de premier niveau est la suivante :

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

La progression, les résumés finaux, les avis d’archivage et les erreurs restent dans stderr. Une analyse terminée affiche toujours le résultat JSON complet lorsqu’une politique de sévérité renvoie le code de sortie 1 ou qu’une couverture incomplète renvoie le code de sortie 2.

Artefacts d’analyse

Une analyse terminée conserve ensemble le rapport lisible et les artefacts structurés :

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

Les fichiers structurés remplissent des fonctions différentes :

L’exhaustivité de la couverture possède trois valeurs :

• complete : l’analyse consigne une couverture complète de la portée sélectionnée.
• partial : l’analyse consigne du travail différé ou d’autres limites de couverture.
• unknown : l’analyse indique que l’exhaustivité de la couverture est inconnue.

Examinez les surfaces différées, les exclusions explicites et les questions ouvertes avant d’utiliser la couverture comme preuve pour une décision de sécurité.

Codes de sortie et signaux

La CLI utilise les codes de sortie suivants :

Toute analyse avec une couverture partial ou unknown renvoie 2, même sans politique de sévérité. Lorsque vous demandez une sortie structurée, les analyses terminées écrivent toujours les résultats disponibles dans stdout. La CLI affiche l’emplacement de toute sortie partielle après une interruption ou une erreur d’exécution.

Authentification et prérequis

Définissez OPENAI_API_KEY ou CODEX_API_KEY, connectez-vous avec npx @openai/codex-security login ou utilisez une connexion Codex existante stockée dans un fichier. Pour Amazon Bedrock, utilisez une API key Bedrock ou la chaîne d’identifiants AWS standard à la place.

Pour la sélection des identifiants, consultez Sélectionner l’authentification de l’analyse.

Pour la CI, limitez la portée de l’API key à l’étape d’analyse et utilisez un workflow de confiance.

La CLI nécessite Node.js 22 ou version ultérieure. L’exécution d’une analyse ou l’exportation des résultats nécessite également Python 3.10 ou version ultérieure. Python 3.10 nécessite aussi tomli. Utilisez --python ou PYTHON pour sélectionner un interpréteur lorsque la détection automatique ne convient pas.

Poursuivez avec le démarrage rapide de la CLI, le guide des analyses en masse, la FAQ de la CLI, le guide de la CI ou le guide du SDK TypeScript.

Alias en texte brut

• --output FILE|-