Référence de la CLI Codex Security

Consultez cette référence pour connaître 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.

Exécutez la CLI avec npx @openai/codex-security.

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 consulter ses arguments et ses options :

npx @openai/codex-security scan --help

codex-security --version affiche la version installée, puis se ferme. codex-security info --json indique les versions du SDK et du plugin inclus. 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 JSON des arguments d’analyse :

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

Générez les complétions de 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é à partir d’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 corrections 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] [--scan-prompt-file FILE]
                           [--post-scan-prompt-file FILE]
                           [--mode {standard,deep}] [--workers N]
                           [--subagents N] [--stop-after-no-new N]
                           [--max-discovery-runs N] [--max-time-hours HOURS]
                           [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh,max}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--dry-run] [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

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

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 toutes deux disponibles, les analyses interactives avec sortie texte vous demandent quels identifiants utiliser. Les analyses CI, JSON et JSONL, ainsi que les autres analyses sans terminal interactif, utilisent la clé API de l’environnement. Les simulations ne demandent rien et ne chargent aucun identifiant.

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

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

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

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

Pour définir les identifiants enregistrés comme choix automatique par défaut, exécutez unset OPENAI_API_KEY CODEX_API_KEY.

Utiliser OpenRouter ou Fireworks

Sélectionnez OpenRouter avec sa clé API et un modèle explicite :

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
  --provider openrouter \
  --model anthropic/claude-sonnet-4.5

Sélectionnez Fireworks avec sa clé API et un modèle explicite :

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
  --provider fireworks \
  --model accounts/fireworks/models/qwen3-235b-a22b

Les deux fournisseurs prennent également en charge bulk-scan.

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 les identifiants AWS au lieu de --auth, d’une connexion ChatGPT ou d’une clé API OpenAI. scan et bulk-scan prennent tous deux en charge --provider.

Sélectionner la cible de l’analyse

Choisissez un seul type de cible par 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.

Pour les analyses de différences et de worktree, l’argument du dépôt doit désigner la racine du worktree Git. Les références sélectionnées doivent exister dans ce checkout.

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

Configurer les analyses approfondies

Utilisez ces options avec --mode deep pour contrôler la concurrence des workers et la durée d’exécution :

--subagents accepte zéro ou un entier positif. --max-time-hours accepte un nombre positif inférieur ou égal à 96. Les autres options nécessitent un entier positif. Ces options ne sont pas disponibles pour les analyses standard.

Par exemple, utilisez deux workers, autorisez jusqu’à dix exécutions et arrêtez l’exécution des workers après 1,5 heure :

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

Lorsque la limite de temps expire, l’analyse arrête les workers non terminés, conserve les résultats des analyses terminées et les agrège dans le rapport final. Si aucun worker ne termine l’examen des sources, l’analyse enregistre une couverture partielle et renvoie le code de sortie 2.

Définissez des valeurs par défaut persistantes dans ~/.codex/codex-security/config.toml, ou dans $CODEX_HOME/codex-security/config.toml lorsque vous définissez CODEX_HOME :

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
max_time_hours = 1.5

Les options de ligne de commande remplacent ces valeurs par défaut. scan --workers contrôle les workers indépendants d’analyse standard au sein d’une même analyse approfondie ; bulk-scan --workers contrôle les analyses simultanées de dépôts. Définissez stop_after_consecutive_errors uniquement dans le fichier TOML ; sa valeur par défaut est 3.

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 des fichiers ou des 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 récursivement, refuse 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.

Ajouter des instructions d’analyse

Pour ajouter des instructions d’analyse, fournissez un fichier texte ou Markdown avec --scan-prompt-file. Utilisez --post-scan-prompt-file pour exécuter des instructions de suivi dans la même session authentifiée après les analyses réussies et les analyses comportant une couverture incomplète ou des erreurs :

npx @openai/codex-security scan . \
  --scan-prompt-file security-focus.md \
  --post-scan-prompt-file follow-up.md

Par exemple, utilisez le prompt d’analyse pour vous concentrer sur les limites d’autorisation et demandez au suivi d’écrire un nouveau fichier post-scan-summary.md dans le répertoire d’analyse. Si le suivi échoue, la CLI signale un avertissement et conserve l’analyse terminée. Le suivi ne s’exécute pas après une annulation ni lorsque l’analyse atteint sa limite de coût.

Définir les options de sortie et de politique

Utilisez ces options pour conserver les artefacts, préserver 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 strict de dépenses. Les requêtes déjà en cours peuvent se terminer légèrement au-dessus de cette 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 scelle les résultats disponibles, marque la couverture comme partial et renvoie le code de sortie 2. Sinon, elle renvoie 2 et laisse sur le disque toute sortie partielle disponible.

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 des 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 préserver 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 gravité 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 simulation vérifie les entrées locales, notamment les documents de la base de connaissances, sans charger d’identifiants, démarrer Codex ni sonder 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 avez besoin d’un modèle, d’un interpréteur, d’un plugin ou d’une valeur de configuration Codex explicite.

Pour sélectionner un modèle et un effort de raisonnement différents sans écrire de TOML :

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

Placez les valeurs de chaîne transmises via --codex entre guillemets 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 avant commit pour le dépôt courant :

npx @openai/codex-security install-hook

Le contrôle analyse les modifications indexées et non indexées avant chaque commit et bloque les constats de gravité é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 gravité si nécessaire :

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

codex-security bulk-scan

Découvrez et analysez des dépôts GitHub, ou exécutez une analyse avec reprise à partir d’un fichier CSV de dépôts :

Pour un guide complet sur la découverte GitHub, les inventaires CSV, les résultats de campagnes 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}]
                                [--knowledge-base PATH]
                                [--scan-prompt-file FILE]
                                [--post-scan-prompt-file FILE]
                                [--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 flux nécessite une connexion à la CLI GitHub.

Pour choisir un modèle et un effort de raisonnement pendant la découverte 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 doit contenir les colonnes id, repository et revision. Les révisions doivent être des hachages de commit complets. Les colonnes facultatives scope, mode et prompt configurent les dépôts individuellement :

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

Utilisez --knowledge-base PATH pour partager des documents de sécurité entre tous les dépôts. Utilisez --scan-prompt-file FILE pour ajouter des instructions d’analyse communes ; la colonne CSV prompt ajoute des instructions propres au dépôt après ce prompt commun. --post-scan-prompt-file FILE exécute des instructions de suivi après chaque analyse, y compris celles qui présentent une couverture incomplète ou des erreurs. Elles ne s’exécutent pas après une annulation ni lorsqu’une analyse atteint sa limite de coût.

--workers limite le nombre d’analyses simultanées de dépôts et utilise 4 par défaut. --mode utilise standard par défaut, et --max-attempts utilise 1 par défaut. Définissez --max-attempts pour réessayer en cas d’erreur de dépôt ou d’analyse. Les analyses terminées avec une couverture incomplète ne font pas l’objet d’une nouvelle tentative. Leurs résultats restent disponibles et la commande renvoie le code de sortie 2.

Exécutez de nouveau la même commande pour reprendre à partir d’un répertoire de sortie existant. La CLI ignore les analyses terminées, y compris celles dont la couverture est incomplète.

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 courant :

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 sous un répertoire de sortie donné :

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

Ajoutez --show-linked-findings pour inclure les liens vers les constats d’analyses antérieures.

Relancez l’analyse sur le checkout courant avec sa configuration d’origine :

npx @openai/codex-security scans rerun SCAN_ID

La nouvelle exécution nécessite la version du plugin enregistrée par l’analyse d’origine. Si la version installée diffère, la commande s’arrête au lieu d’utiliser un autre plugin.

Examiner les journaux d’analyse enregistrés

Lisez l’ensemble des événements de session enregistrés pour une analyse et ses workers. Ces journaux ne sont pas expurgés et peuvent contenir du code source ou des identifiants ; examinez-les donc avant de les partager :

npx @openai/codex-security scans logs SCAN_ID

Ajoutez --json pour obtenir un résultat dans un format lisible par une machine contenant toutes les informations.

Faire correspondre et comparer les constats

Comparez deux analyses afin d’identifier les constats nouveaux, persistants, rouverts, résolus et inconnus :

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparaison fait automatiquement correspondre les constats qui partagent la même cause racine et réutilise les correspondances enregistrées. Pour enregistrer explicitement les correspondances, utilisez scans match :

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Un constat est inconnu lorsque l’analyse la plus récente présente une couverture incomplète ou ne couvre pas son emplacement d’origine. Ajoutez --force à match lorsque vous devez recalculer une correspondance existante.

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

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

Les résultats peuvent varier même si vous relancez 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 constat critique pour la sécurité par rapport au code actuel.

codex-security findings

Répertoriez les constats ouverts dans toutes les analyses du dépôt courant :

npx @openai/codex-security findings list

Transmettez le chemin d’un dépôt pour examiner un autre checkout :

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

Ajoutez --json pour obtenir une sortie structurée. La liste identifie les constats observés dans la dernière analyse et les constats antérieurs qui n’y ont pas été confirmés.

Notez que les constats antérieurs restent ouverts jusqu’à leur résolution ou leur rejet (leur absence de la dernière analyse n’est pas interprétée comme une preuve de correction).

Pour enregistrer un constat examiné comme faux positif :

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

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

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 futures. Chaque analyse revérifie indépendamment le code source actuel, les contrôles et l’accessibilité. Une décision antérieure ne désactive aucune règle, aucun chemin ni aucune catégorie de vulnérabilité.

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 de l’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 scellé des constats. CSV contient des colonnes de constats portables et n’inclut pas l’état de triage du workbench local.

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

Écrivez le fichier 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 fichier SARIF dans stdout :

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

Exportez les constats au format JSON :

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

Exportez les constats au format CSV :

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

codex-security publish scan

Publiez dans Linear chaque constat d’une analyse terminée :

usage: codex-security publish scan [SCAN_DIR] --to linear
                                   [--linear-team TEAM_ID]
                                   [--project PROJECT_ID]
                                   [--linear-api-key KEY]
                                   [--linear-assignee EMAIL_OR_USER_ID]
                                   [--dry-run] [--json]

SCAN_DIR doit contenir une analyse terminée et scellée. Omettez cet argument dans un terminal interactif pour sélectionner une analyse terminée dans l’historique local. La création de tickets nécessite également que l’analyse et ses constats existent dans l’historique local. Une simulation valide les artefacts scellés sans effectuer ce contrôle de persistance.

Chaque appel hors simulation tente de créer un nouveau ticket pour chaque constat. Publier de nouveau la même analyse ne recherche, ne met à jour et ne réutilise pas les tickets existants. Si certains constats échouent, la commande conserve les tickets créés avec succès et renvoie le code de sortie 2. Avec --json, examinez les résultats created et failed avant de réessayer afin d’éviter les doublons.

Prévisualisez les charges utiles des tickets avant la publication :

npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --dry-run \
  --json

Publier avec l’app Linear connectée

Sans clé API Linear, la commande démarre Codex avec votre configuration existante et l’app Linear connectée. Connectez-vous et associez Linear à votre compte Codex avant de publier :

npx @openai/codex-security login
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --project PROJECT_ID

Publier avec une clé API Linear

Fournir --linear-api-key ou CODEX_SECURITY_LINEAR_API_KEY publie directement via l’API Linear et ne démarre pas Codex. Lors d’une publication directe, les tickets ne sont attribués à personne, sauf si vous sélectionnez un responsable :

export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/completed-scan \
  --to linear \
  --linear-team TEAM_ID \
  --linear-assignee teammate@example.com

Les valeurs de ligne de commande remplacent les variables d’environnement correspondantes. Pour les clés API, préférez CODEX_SECURITY_LINEAR_API_KEY à --linear-api-key, car les arguments de ligne de commande peuvent apparaître dans l’historique du shell et la liste des processus.

codex-security validate et codex-security patch

Vérifiez si un constat potentiel est valide :

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

Générez une correction avec le skill de remédiation inclus :

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

Chaque argument positionnel accepte du texte littéral ou un chemin de fichier. Ces entrées utilisent le répertoire courant. Utilisez validate pour revérifier un constat après une correction ou lorsqu’une analyse ultérieure ne le signale plus. La seule comparaison des analyses ne prouve pas que la correction fonctionne.

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

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

Corriger les constats après une analyse

Utilisez scan --patch pour corriger les constats après une analyse complète. Cette opération nécessite @openai/codex-security 0.1.15 ou version ultérieure. Le seuil de gravité par défaut est low. Cette commande sélectionne les constats de gravité élevée et critique :

npx @openai/codex-security scan . --patch --patch-severity high --json

Les constats vérifiés et déjà corrigés ne déclenchent pas --fail-on-severity.

Corriger les constats enregistrés

Transmettez l’identifiant d’un constat ou d’une occurrence pour corriger son dépôt d’origine, ou sélectionnez des constats dans une analyse enregistrée :

npx @openai/codex-security patch OCCURRENCE_ID
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
npx @openai/codex-security patch --scan latest --severity medium

--scan latest sélectionne la dernière analyse terminée du dépôt courant. Les commandes relatives aux constats enregistrés prennent en charge --json ; ce n’est pas le cas des entrées sous forme de texte littéral ou de fichier.

Ajoutez --create-pr pour valider uniquement les fichiers de correction vérifiés et ouvrir une pull request avec la CLI GitHub :

npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr

Si le push ou la pull request échoue, exécutez la commande patch --resume-pr BRANCH affichée depuis le même dépôt pour réessayer.

Corriger les tickets Linear

Définissez CODEX_SECURITY_LINEAR_API_KEY ou LINEAR_API_KEY pour une clé API personnelle, ou LINEAR_ACCESS_TOKEN pour un jeton OAuth. Préférez une variable d’environnement à --linear-api-key KEY afin d’éviter d’enregistrer la clé dans l’historique du shell.

Importez un ticket à l’aide de son identifiant ou de son URL. Répétez --linear-issue pour sélectionner plusieurs tickets :

npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124

Utilisez --linear-project pour sélectionner les tickets ouverts d’un projet. Ajoutez --linear-filter pour affiner la sélection :

npx @openai/codex-security patch --linear-project "Security backlog" \
  --linear-filter '{"labels":{"name":{"eq":"security"}}}'

La CLI exclut les tickets terminés et annulés, sauf si le filtre définit state. Elle ne modifie pas les tickets Linear.

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 clé API en la transmettant via stdin :

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

Stockez un jeton 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 inclus :

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 publication, la connexion, la validation et les corrections restent disponibles uniquement dans la CLI.

Lire la sortie d’analyse

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

Les terminaux interactifs affichent un tableau de bord en direct avec la phase actuelle de l’analyse, les fichiers examinés, l’activité, l’utilisation des jetons et le coût estimé. La CI et les sorties redirigées utilisent une progression en texte brut. Ajoutez --headless pour utiliser la progression en texte brut dans un terminal interactif :

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

Le tableau de bord affiche également les détails de session en direct. Ils ne sont pas expurgés et peuvent contenir du code source ou des identifiants. Examinez-les avant de les partager.

Diagnostics détaillés

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

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

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

Résumé de fin

Une analyse terminée écrit dans stderr le nombre de constats ouverts du dépôt, leur répartition par gravité, la couverture, le temps écoulé, le chemin du rapport et le répertoire des résultats. Elle inclut l’utilisation des jetons et le coût estimé lorsqu’ils sont disponibles :

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  COVERAGE  complete
  ELAPSED   1s
  TOKENS    1,250 input, 200 cached, 30 output
  RESULTS   /path/to/scan

Les constats informatifs sont pris en compte dans le total du résumé. Les politiques de gravité évaluent uniquement les constats critical, high, medium et low de l’analyse actuelle, et non les constats antérieurs figurant dans le total du dépôt.

Sortie JSON

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

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

Lors d’une correction, la sortie JSON inclut également les résultats des corrections et toute pull request créée.

La progression, les résumés de fin, 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 gravité 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 ont des fonctions différentes :

L’exhaustivité de la couverture peut prendre trois valeurs :

• complete : l’analyse enregistre une couverture complète du périmètre sélectionné.
• partial : l’analyse enregistre 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 dans 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 gravité. Lorsque vous demandez une sortie structurée, les analyses terminées et les publications partielles écrivent tout de même 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.

Autorisations des analyses locales

Les analyses de la CLI et du SDK s’exécutent avec vos autorisations locales du système d’exploitation. Chaque analyse utilise le profil de système de fichiers codex_security_scan et définit approvalPolicy sur "never". Ce profil autorise la lecture du système de fichiers local et l’écriture dans les racines de l’espace de travail et le répertoire d’état d’analyse sélectionné. Les analyses ne s’interrompent pas pour demander une approbation interactive.

Les paramètres fournis via --codex dans la CLI ou codexOverrides dans le SDK, notamment approval_policy, sandbox_mode et les autorisations du système de fichiers, ne peuvent ni remplacer ni restreindre ces contrôles d’analyse. Les restrictions de l’hôte et du réseau continuent de s’appliquer.

Les processus d’analyse et du workbench peuvent hériter de votre environnement, y compris de jetons API et d’identifiants cloud sans rapport avec l’analyse. Analysez uniquement des dépôts auxquels vous faites confiance et que vous êtes autorisé à évaluer, et ne fournissez que les identifiants nécessaires à l’analyse.

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 OpenRouter ou Fireworks, définissez la clé API du fournisseur et sélectionnez un modèle. Pour Amazon Bedrock, utilisez une clé API Bedrock ou la chaîne d’identifiants AWS standard.

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

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

La CLI nécessite Node.js 22 (22.13.0 ou version ultérieure), 24 ou 26. Les analyses, les analyses en masse, les exportations, l’historique des analyses et les constats enregistrés nécessitent également Python 3.10 ou version ultérieure. Python 3.10 nécessite aussi tomli. Utilisez --python avec scan, bulk-scan ou export, ou définissez PYTHON pour toute commande reposant sur Python.

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|-