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 MCP server :

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 l’API key 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 API key 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 son API key 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 son API key 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

Utilisez --provider amazon-bedrock et un identifiant de modèle Bedrock avec scan ou bulk-scan. Une fois l’accès aux modèles activé par AWS, les analyses utilisent les identifiants AWS sans --auth, connexion OpenAI ni API key OpenAI.

Daybreak Blue et Daybreak Red

Daybreak Blue et Daybreak Red nécessitent une approbation Trusted Access for Cyber. Pour demander un accès, envoyez la demande d’accès entreprise ou contactez l’équipe OpenAI chargée de votre compte. Après approbation, collaborez avec l’équipe AWS chargée de votre compte pour activer l’accès aux modèles sur Amazon Bedrock.

L’approbation Daybreak Red n’inclut pas l’accès à GPT-5.6-Cyber. GPT-5.6-Cyber nécessite une approbation distincte du gouvernement des États-Unis (USG). Demandez à l’équipe OpenAI chargée de votre compte de solliciter cette approbation supplémentaire avant d’activer GPT-5.6-Cyber sur Amazon Bedrock. Consultez les conditions d’accès à Daybreak.

Pour connaître leur disponibilité, consultez les fiches de modèles AWS de Daybreak Blue et de Daybreak Red.

Pour lancer une analyse avec Daybreak Blue, remplacez <aws-profile-name> par un profil AWS ayant accès au modèle Daybreak Blue :

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-daybreak-blue-5.6-sol --effort high

Pour lancer une analyse avec Daybreak Red, choisissez un profil AWS ayant accès à GPT-5.6-Cyber. Ce profil peut être différent de celui que vous utilisez pour Daybreak Blue :

export AWS_PROFILE="<aws-profile-name>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-cyber --effort high

Vous pouvez aussi vous authentifier avec AWS_BEARER_TOKEN_BEDROCK ou avec la chaîne standard de fournisseurs d’identifiants AWS. Les clés d’accès temporaires nécessitent AWS_SESSION_TOKEN. Définissez les identifiants et AWS_REGION dans le même shell ou la même tâche CI que l’analyse.

Résultats locaux et vérification des accès

Les rapports enregistrés localement, scans show et export fonctionnent sans identifiants cloud. L’envoi des résultats à Codex Security Cloud nécessite une connexion distincte à ChatGPT et un accès à la destination.

info et scan --dry-run ne testent ni les identifiants AWS ni l’accès aux modèles. Lancez une analyse pour vérifier l’accès. En cas d’erreur d’authentification AWS ou d’accès refusé, vérifiez vos identifiants, votre région et vos autorisations d’accès aux modèles.

État de la prise en charge de Bedrock

@openai/codex-security@0.1.31 prend en charge les analyses sur Amazon Bedrock. Cette version ne fournit pas d’estimation des coûts et ne prend pas en charge --max-cost pour les ID des modèles Daybreak Blue et Daybreak Red ci-dessus.

Vérifiez la version du paquet installé et celle de Codex fournie avec celui-ci :

npx @openai/codex-security --version
npx @openai/codex-security info --json

Utilisez npx @openai/codex-security scan --help pour vérifier les options disponibles dans votre version installée.

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 est atteinte, l’analyse arrête les workers dont le travail est inachevé, conserve les résultats d’analyse terminés et les regroupe dans le rapport final. Consultez le rapport pour connaître les zones examinées et les travaux reportés. L’échéance seule ne détermine pas le code de sortie ; celui-ci dépend du statut d’exécution et de la politique de gravité.

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 erreurs d’analyse :

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, pas un plafond de dépenses strict. Les requêtes déjà en cours peuvent se terminer en dépassant légèrement la limite. Si une analyse approfondie atteint cette limite après que Codex Security a regroupé les résultats des workers ayant terminé, la CLI peut sceller un résultat complet et signaler l’avertissement budgétaire. Elle renvoie 0, ou 1 si des constats atteignent le seuil de gravité configuré. Si elle ne peut pas produire un résultat complet valide, elle renvoie 2 et laisse les sorties disponibles sur le disque.

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 autre modèle et un autre effort de raisonnement sans écrire de TOML, choisissez un modèle auquel vos identifiants donnent accès. Si vous vous connectez avec ChatGPT, vérifiez la disponibilité de GPT-6.1 Sol avant d’utiliser ces exemples :

npx @openai/codex-security scan . --model gpt-6.1-sol --effort medium

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-6.1-sol"'

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 lancez une analyse pouvant être 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, utilisez un modèle auquel vos identifiants donnent accès. Consultez la disponibilité de GPT-6.1 Sol avec la connexion ChatGPT :

npx @openai/codex-security bulk-scan --model gpt-6.1-sol --effort medium

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 à chaque dépôt après ces instructions communes. --post-scan-prompt-file FILE exécute des instructions de suivi après chaque analyse, y compris en cas d’erreur d’analyse. Ces instructions ne s’exécutent pas après une annulation ou lorsqu’une analyse atteint sa limite de coût.

--workers limite le nombre d’analyses de dépôts simultanées et vaut 4 par défaut. --mode vaut standard par défaut, et --max-attempts vaut 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 ne sont pas relancées en raison de lacunes de couverture ou de violations de la politique de gravité. Leurs résultats restent disponibles.

Exécutez à 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 présentant des lacunes de couverture.

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 une sortie structurée.

Faire correspondre et comparer les constats

Comparez deux analyses pour identifier les constats nouveaux, persistants, rouverts, non observés, résolus ou de statut inconnu :

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 de statut inconnu lorsque son chemin est exclu ou que sa correspondance est incertaine. Si l’analyse ultérieure ne le retrouve pas dans le code qu’elle a analysé, il est non observé. Seul un constat explicitement clôturé comme déjà corrigé est résolu. 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.

Les constats antérieurs restent ouverts jusqu’à leur résolution ou leur rejet. Leur absence de la dernière analyse ne prouve pas qu’ils ont été corrigés.

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 API key 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 API key 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 API keys, 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 API key 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 API key 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 MCP server, 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 sur stderr le nombre de constats ouverts du dépôt, leur répartition par gravité, 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. Par exemple :

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  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 d’exécution, les avis d’archivage et les erreurs restent sur stderr. Une analyse terminée affiche tout de même le résultat JSON complet lorsqu’une politique de gravité entraîne le code de sortie 1.

Artefacts d’analyse

Une analyse terminée conserve ensemble le rapport lisible et les artefacts structurés. Le manifeste scellé enregistre les empreintes des artefacts afin que les lecteurs ultérieurs puissent vérifier que ces fichiers n’ont pas été modifié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 :

Consultez scan.status dans scan-manifest.json pour connaître l’état d’exécution : completed, failed, canceled ou interrupted. Les nouveaux résultats n’incluent pas coverage.completeness. Examinez les surfaces dont l’examen a été reporté, les exclusions explicites et les questions en suspens dans coverage.json pour comprendre ce que l’analyse a examiné.

Codes de sortie et signaux

La CLI utilise les codes de sortie suivants :

Les lacunes de couverture ne modifient pas le code de sortie d’une analyse terminée et ne contournent pas sa politique de sévérité. Le code de sortie 0 ne signifie pas que chaque fichier a été examiné. Lorsque vous demandez une sortie structurée, les analyses terminées et les publications partielles écrivent tout de même les résultats disponibles sur 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 de workbench peuvent hériter de votre environnement, y compris de jetons API et d’identifiants cloud sans rapport avec l’analyse. Supprimez les identifiants sans rapport avec l’analyse avant de la lancer.

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 l’API key du fournisseur et sélectionnez un modèle. Pour Amazon Bedrock, utilisez une API key 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 l’API key à l’étape d’analyse et utilisez un workflow de confiance.

La CLI nécessite Node.js 24 ou 26, ou Node.js 22 à partir de la version 22.13.0. Les analyses, les analyses en masse, les exports, 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 s’appuyant 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|-