Référence de la CLI Codex Security

Arguments, formats de sortie, artefacts d’analyse et codes de sortie de la CLI Codex Security.

Consultez les commandes, les options, les formats de sortie et le comportement de sortie de codex-security. Pour une première analyse, suivez le guide de démarrage rapide de la CLI.

Exécutez la CLI avec npx @openai/codex-security. Le paquet installé fournit également l’alias cs.

Vue d’ensemble des commandes

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

La CLI fournit les commandes suivantes :

Commande Fonction
codex-security scan Exécuter une analyse Codex Security.
codex-security scan import Enregistrer des résultats CSV ou JSON sous forme d’analyse.
codex-security import github Lire les alertes d’analyse de code GitHub.
codex-security policy Rédiger ou mettre à jour la politique de sécurité d’un dépôt.
codex-security init Créer une configuration de projet YAML ou JSON.
codex-security install-hook Installer une analyse de sécurité Git avant commit.
codex-security bulk-scan Découvrir des dépôts et exécuter des analyses en masse pouvant être reprises.
codex-security scan-components Exécuter des analyses distinctes pour les composants du projet.
codex-security scans Lister, examiner, comparer et récupérer les journaux d’analyse enregistrés.
codex-security findings Examiner et mettre à jour les résultats de sécurité enregistrés.
codex-security export Exporter les résultats ou un modèle de menace conservé.
codex-security publish Vérifier ou publier une analyse enregistrée, ou importer des résultats externes.
codex-security classify-severity Appliquer une grille de gravité aux résultats enregistrés.
codex-security suggest-owners Suggérer des responsables pour les résultats à l’aide de CODEOWNERS et de l’historique Git.
codex-security dedupe Dédupliquer les résultats enregistrés.
codex-security validate Vérifier un ou plusieurs résultats de sécurité potentiels.
codex-security patch Corriger un ou plusieurs problèmes de sécurité.
codex-security verify-fix Vérifier si les problèmes signalés sont corrigés.
codex-security feedback Envoyer des commentaires à OpenAI et renvoyer un identifiant de retour.
codex-security login Se connecter, enregistrer des identifiants ou vérifier l’état de connexion.
codex-security logout Supprimer la connexion enregistrée.
codex-security info Afficher les métadonnées en lecture seule du SDK et du plugin inclus.

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

Commande Fonction
codex-security completions Générer des scripts de complétion du shell.
codex-security mcp Enregistrer la CLI comme MCP server.
codex-security skills Synchroniser les skills Codex Security avec les agents.

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 termine. codex-security info --json indique les versions du SDK et du plugin inclus. Aucune de ces commandes ne nécessite Python. Utilisez codex-security --update pour mettre à jour la CLI installée.

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. --export-format sélectionne quant à lui le format d’un artefact exporté depuis une analyse terminée. L’aide globale des commandes répertorie aussi 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

La CLI expose uniquement la commande de métadonnées en lecture seule info via son MCP server. Les analyses, les exportations, la publication, l’authentification, la validation et l’application de correctifs restent réservées à 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}]
                           [--config FILE]
                           [--cyber-access-program PROGRAM]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH] [--scan-prompt-file FILE]
                           [--validation-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 MINUTES]
                           [--model MODEL]
                           [--effort EFFORT]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--validate] [--patch] [--patch-severity {critical,high,medium,low}]
                           [--create-pr]
                           [--max-cost USD] [--show-cost] [--dry-run] [--mock]
                           [--workflow-id ID] [--safety-identifier ID]
                           [--headless] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

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

Charger la configuration du projet

Créez une configuration de départ et sélectionnez-la explicitement :

npx @openai/codex-security init codex-security.yaml
npx @openai/codex-security scan . --config codex-security.yaml

init n’écrase pas les fichiers existants. Utilisez -c FILE comme forme abrégée de --config FILE, ou définissez CODEX_SECURITY_PROJECT_CONFIG. Une option explicite est prioritaire sur la variable d’environnement. La CLI ne détecte pas automatiquement de fichier de projet.

Sélectionnez uniquement une configuration que vous contrôlez. Elle dispose des mêmes prérogatives que les options de la CLI : les paramètres natifs de Codex peuvent démarrer des processus de MCP server et choisir les destinations des services de modèles. Ne sélectionnez pas de fichier contrôlé par un dépôt ou une pull request non fiable. En CI, conservez la configuration du scanner en dehors de la copie de travail évaluée. Consultez le guide de configuration du projet pour connaître les paramètres et leur ordre de priorité.

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.

Utilisez --auth api-key avec --cyber-access-program standard|daybreak_blue|daybreak_red pour sélectionner un programme d’accès Cyber pour les requêtes aux modèles OpenAI. Si vous omettez cette option, les valeurs par défaut de Codex sont conservées ; standard sélectionne explicitement le programme standard. Sélectionner un programme ne vous en accorde pas l’accès ; votre projet API doit être approuvé pour le programme sélectionné. Consultez le guide des programmes d’accès pour connaître les exigences relatives aux identifiants.

Attribuer les analyses aux utilisateurs finaux

Lorsque vous effectuez des analyses pour le compte d’utilisateurs, --safety-identifier ID accepte un identifiant stable et haché avec une authentification par API key. Utilisez entre 1 et 64 caractères, sans caractère NUL ni données personnelles telles que des adresses e-mail.

Pour transmettre l’identifiant, utilisez CODEX_CLI_PATH afin de sélectionner une version de Codex qui prend en charge cette option et un plugin qui la transmet aux workers. L’environnement d’exécution Codex fourni ne la prend pas en charge.

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.

Accès ID du modèle Bedrock Région AWS
Daybreak Blue openai.gpt-daybreak-blue-5.6-sol us-east-2
Daybreak Red openai.gpt-5.6-cyber us-east-2

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 locaux enregistrés, scans show et export fonctionnent sans identifiants cloud.

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.

Estimations des coûts Bedrock

La CLI prend en charge les estimations de coûts et --max-cost pour les identifiants de modèles Daybreak Blue et Daybreak Red ci-dessus. Les estimations utilisent les tarifs commerciaux AWS Standard au sein d’une même région, frais AWS compris. La limite de coût utilise estimatedUsd, l’estimation de référence pour les contextes courts. Les requêtes déjà en cours peuvent faire dépasser la limite à cette estimation. La tarification des contextes longs peut porter la valeur indiquée de estimatedUsdRange au-delà de cette limite. Cette limite ne constitue pas un plafond de facturation.

Sélectionner la cible de l’analyse

Choisissez un seul type de cible par analyse.

Argument Description
--path PATH Analyser un chemin relatif au dépôt. Répétez l’option pour ajouter des chemins.
--diff BASE Analyser les modifications validées de BASE à --head. La révision de tête utilise HEAD par défaut.
--head HEAD Définir la révision de tête pour --diff.
--working-tree Analyser les modifications indexées et non indexées par rapport à --base. La base utilise HEAD par défaut.
--base BASE Définir la révision de base pour --working-tree.
--mode {standard,deep} Sélectionner le mode d’analyse. La valeur par défaut est standard.

--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 découverte :

Argument Description
--workers N Nombre maximal de workers indépendants exécutant des analyses standard simultanément. Valeur par défaut : 4.
--subagents N Sous-agents disponibles pour chaque worker. Valeur par défaut : 3. Utilisez 0 pour les désactiver.
--stop-after-no-new N Arrêter après N analyses de worker terminées consécutives ne détectant aucun nouveau problème. Valeur par défaut : 4.
--max-discovery-runs N Nombre total maximal d’exécutions indépendantes d’analyses standard. Valeur par défaut : 40.
--max-time MINUTES Durée limite de découverte. Accepte des fractions de minute positives. La valeur par défaut et le maximum sont de 5 760 minutes.

Par exemple, utilisez deux workers, autorisez jusqu’à dix exécutions et arrêtez la découverte après 90 minutes :

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

À l’expiration de la durée limite, l’analyse arrête les workers qui n’ont pas terminé et regroupe les résultats finalisés dans son rapport. Pour une analyse standard, --max-time définit une durée d’investigation indicative. La génération du rapport peut se terminer plus tard. La validation personnalisée et les instructions après analyse s’exécutent en dehors de ce délai.

Pour réutiliser ces limites, enregistrez-les dans un fichier de configuration du projet :

scan:
  mode: deep
  max_time_minutes: 90
  deep:
    workers: 2
    subagents_per_worker: 0
    stop_after_no_new: 3
    max_discovery_runs: 10

Les options de ligne de commande sont prioritaires sur la configuration du projet. Utilisez scan.deep.stop_after_consecutive_errors pour modifier le nombre d’erreurs consécutives de worker qui arrêtent la découverte. La valeur par défaut est 3. Pour bulk-scan, --workers contrôle les analyses simultanées de dépôts.

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 texte UTF-8 (y compris JSON et SARIF), les fichiers PDF et DOCX. La CLI parcourt les répertoires de manière récursive, rejette les chemins d’entrée qui sont des liens et ignore les entrées de répertoire qui sont des liens. Elle enregistre les documents extraits dans le fichier privé de reprise .scan-knowledge.json, à côté des artefacts d’analyse, afin de permettre la reprise de l’analyse. Conservez ce fichier avec le répertoire d’analyse. Les rapports canoniques n’incluent pas le texte des documents.

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 qui réussissent ou renvoient 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 cibler les frontières d’autorisation et demandez au suivi de créer un fichier post-scan-summary.md dans le répertoire d’analyse. Si le suivi échoue, la CLI affiche 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. Lorsqu’il s’exécute, le suivi n’est soumis ni au suivi des coûts d’analyse ni à --max-cost.

Valider les résultats dans votre environnement

Utilisez --validation-prompt-file FILE pour remplacer l’étape finale de validation par votre propre procédure de test. Codex examine d’abord le code source et ignore la validation s’il ne trouve aucun problème potentiel. Conservez le prompt et le script de test dans un répertoire que vous contrôlez, en dehors de la copie de travail :

npx @openai/codex-security scan . \
  --validation-prompt-file /path/to/security-tests/validation.md

Par exemple, si votre serveur de test local est en cours d’exécution, placez ces instructions dans validation.md :

Run /path/to/security-tests/validate.sh against http://localhost:3000.
Report which findings reproduce and include the relevant test output.

Utilisez cette option avec les analyses standard de dépôt, de chemin, de diff ou de worktree. Pour les analyses standard de composants, définissez scan.validation_file dans la configuration du projet. Les analyses approfondies n’acceptent pas la validation personnalisée.

Ajoutez --validate à une nouvelle commande d’analyse pour obtenir une évaluation distincte, fondée uniquement sur le code source, de chaque résultat signalé. Si l’analyse signale des résultats, la CLI écrit les évaluations dans un rapport dans le répertoire d’analyse. Elles ne modifient ni les résultats ni la décision liée à la politique de gravité. Vous ne pouvez pas combiner --validate avec --dry-run, --mock ou une limite de coût d’analyse définie en ligne de commande ou dans la configuration du projet.

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.

Argument Description
--output-dir DIR Écrire les artefacts d’analyse dans un répertoire privé en dehors du worktree Git englobant. Par défaut, utiliser l’état persistant de Codex Security.
--archive-existing Déplacer les résultats existants vers DIR.previous-<timestamp>-<id> et démarrer avec un répertoire de sortie vide. Nécessite --output-dir.
--fail-on-severity LEVEL Renvoyer le code de sortie 1 lorsqu’une analyse terminée signale un résultat de gravité égale ou supérieure à critical, high, medium ou low.
--patch Corriger et vérifier les résultats sélectionnés après une analyse complète.
--patch-severity LEVEL Corriger les résultats de gravité égale ou supérieure à critical, high, medium ou low. Valeur par défaut : low.
--create-pr Créer un commit des fichiers de correctifs vérifiés et ouvrir une pull request GitHub ou une merge request GitLab en brouillon. Nécessite --patch.
--max-cost USD Arrêter une analyse lorsque le coût estimé du modèle dépasse le montant spécifié en USD.
--show-cost Afficher le coût estimé dans les sorties de progression et de fin d’exécution.
--mock Enregistrer des résultats synthétiques d’analyse Standard sans appeler de modèle.
--workflow-id ID Réutiliser le travail terminé dans le workflow local de résultats nommé.
--dry-run Vérifier le dépôt, la cible, la base de connaissances, le répertoire de sortie et la configuration de Codex sans lancer d’analyse.
--headless Afficher la progression en texte brut au lieu du tableau de bord d’analyse interactif.
--verbose Afficher sur stderr des diagnostics supplémentaires sur le cycle de vie, l’authentification, la progression et les coûts.
--json Afficher le manifeste, les résultats, les exclusions de revue, les chemins et les métadonnées des tours dans un seul document JSON.
--format FORMAT Afficher le résultat complet de l’analyse au format toon, json, yaml ou jsonl.
--full-output Afficher le résultat complet avec le format de sortie structuré par défaut.

Le mode de simulation prend en charge les analyses Standard de dépôt, de chemin et de diff. Vous ne pouvez pas le combiner avec --dry-run, --patch, le mode Deep, la validation personnalisée ou les prompts après analyse. Les prompts d’analyse et les bases de connaissances ne modifient pas ses résultats synthétiques. Utilisez un CODEX_SECURITY_STATE_DIR distinct pour exclure les résultats simulés de votre historique d’analyses.

La limite de coût utilise estimatedUsd, l’estimation de référence pour les contextes courts. Les requêtes déjà en cours peuvent faire dépasser la limite à cette estimation. La tarification des contextes longs peut porter estimatedUsdRange au-delà de cette limite. Cette limite ne constitue pas un plafond de facturation.

Si une analyse approfondie atteint la limite après que Codex Security a regroupé les résultats des workers ayant terminé, la CLI peut finaliser un résultat complet et signaler l’avertissement relatif au budget. Elle renvoie 0, ou 1 si les résultats atteignent le seuil de gravité configuré. Si elle ne peut pas produire de résultat complet valide, elle renvoie 2 et laisse toute sortie disponible 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. Utilisez --archive-existing pour conserver les résultats précédents 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 pour sélectionner un modèle, un interpréteur, un plugin ou une valeur de configuration de Codex.

Argument Description
--auth {auto,chatgpt,api-key} Sélectionnez les identifiants d’authentification de l’analyse. La valeur par défaut est auto.
--provider {openai,openrouter,fireworks,amazon-bedrock} Sélectionnez le fournisseur d’inférence. La valeur par défaut est openai.
--model MODEL Sélectionnez le modèle. La valeur par défaut est gpt-5.6-sol. Obligatoire pour OpenRouter, Fireworks et Amazon Bedrock.
--effort EFFORT Sélectionnez l’effort de raisonnement du modèle. La valeur par défaut est xhigh ; les valeurs prises en charge dépendent du modèle et du fournisseur.
--plugin-path PATH Utilisez un répertoire ou un fichier ZIP de plugin Codex Security pour remplacer le plugin fourni.
--python PATH Sélectionnez l’interpréteur Python pour l’environnement d’exécution du plugin.
--codex KEY=VALUE Remplacez une valeur de la configuration Codex isolée. Les valeurs utilisent la syntaxe TOML. Répétez l’option pour définir plusieurs valeurs.

Codex Security accepte les identifiants de modèle et les valeurs d’effort de raisonnement sous forme de chaînes. Les combinaisons prises en charge dépendent du modèle, du fournisseur, de la version de Codex et de vos identifiants d’authentification.

Si la configuration Codex isolée de l’analyse sélectionne un profil, les valeurs model et model_reasoning_effort de ce profil ont priorité sur --model et --effort. Votre configuration Codex habituelle n’est pas chargée. Ajoutez --dry-run --verbose à votre commande d’analyse pour examiner le modèle et l’effort effectivement retenus avant de lancer une analyse.

Pour choisir un modèle et un effort de raisonnement, sélectionnez un modèle Codex accessible avec votre compte :

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

Les valeurs du modèle et de l’effort sont transmises à Codex sans modification. Les combinaisons non prises en charge renvoient des erreurs de Codex ou du fournisseur, sans substitution d’un autre modèle ou effort.

codex-security scan import

Enregistrez des résultats existants en tant qu’analyse terminée dans l’historique local sans effectuer d’analyse de sécurité ni d’appels au modèle. L’importation ne nécessite pas d’authentification auprès du modèle.

usage: codex-security scan import (--csv FILE | --json FILE)
                                  [--output-dir DIR] [--archive-existing]
                                  [--dry-run] [--format json]

Fournissez exactement une entrée. Le format CSV utilise les colonnes d’exportation de Codex Security. Le format JSON accepte un document codex-security.findings complet ou un objet contenant un tableau findings conforme au schéma des résultats. Les données JSON d’autres outils d’analyse et les tableaux bruts d’alertes GitHub ne sont pas acceptés comme résultats enregistrés.

Enregistrez cet exemple fictif sous le nom findings.csv :

occurrence_id,finding_id,title,summary,severity,confidence,status,close_reason,note,remediation,path,start_line,end_line
occ_000000000000000000000001,csf_000000000000000000000001,Missing authorization check,The route reads a record without checking ownership,high,high,open,,,Check record ownership before returning data,src/routes.ts,18,18

Validez le fichier, puis importez-le :

npx @openai/codex-security scan import --csv findings.csv --dry-run --format json
npx @openai/codex-security scan import --csv findings.csv --format json

La simulation indique dryRun: true et findingCount: 1 sans enregistrer d’analyse. L’importation renvoie l’identifiant de l’analyse enregistrée et les chemins des résultats. Pour importer du JSON à la place :

npx @openai/codex-security scan import --json findings.json --format json

Pour cette commande, --json FILE sélectionne le fichier d’entrée. Utilisez --format json pour obtenir une sortie JSON.

Option Comportement
--csv FILE Lisez les résultats au format d’exportation CSV de Codex Security.
--json FILE Lisez un document de résultats ou un objet contenant un tableau findings.
--dry-run Validez l’entrée sans enregistrer d’analyse.
--output-dir DIR Choisissez le répertoire des artefacts. Par défaut, il s’agit du répertoire d’état persistant de Codex Security.
--archive-existing Archivez les résultats existants avant l’importation. Cette option nécessite --output-dir.

Utilisez un fichier d’entrée ordinaire dont le chemin ne contient ni liens symboliques ni jonctions de répertoires. Chaque importation conserve les occurrences des résultats, y compris les doublons, et conserve l’entrée sous artifacts/import/. Les identifiants d’origine sont stockés dans extensions.import. L’état terminé signifie que l’importation est achevée ; il ne signifie pas que la source a été examinée. scans rerun SCAN_ID importe à nouveau l’entrée conservée.

Pour analyser un dépôt nommé import, utilisez scan ./import.

codex-security import github

Lisez les alertes d’analyse de code GitHub sans modifier GitHub ni extraire le code :

npx @openai/codex-security import github example/repository --format json > /path/outside/repository/alerts.json
npx @openai/codex-security import github example/repository \
  --github-alert 12 --github-alert 18 --format json

Remplacez example/repository par votre dépôt. Authentifiez-vous avec des identifiants GitHub CLI disposant d’un accès en lecture aux alertes d’analyse de code. Par défaut, l’importation lit les alertes ouvertes de la branche par défaut, y compris celles issues de fichiers SARIF téléversés par des tiers.

Option Comportement
--github-alert NUMBER Sélectionnez une alerte précise, quel que soit son état ; répétez l’option pour plusieurs alertes.
--github-ref REF Sélectionnez une référence Git à la place de la branche par défaut.
--github-state STATE Répertoriez les alertes à l’état open, closed, dismissed, fixed ou all ; la valeur par défaut est open.

Ne combinez pas des numéros d’alerte précis avec un état autre que open. La commande renvoie un tableau d’alertes provenant de la source, et non une analyse enregistrée. Depuis le dépôt local correspondant, exécutez codex-security validate /path/outside/repository/alerts.json pour les évaluer. Conservez l’intégralité du JSON, sans filtres de sortie ni limites de jetons, lorsque vous enregistrez les entrées de validation. Utilisez scan import pour les résultats déjà conformes au schéma de Codex Security. Pour importer des alertes Dependabot, utilisez publish findings.

codex-security install-hook

Installez la CLI en dehors du dépôt, examinez le hook pre-commit existant du dépôt, puis exécutez la CLI installée depuis l’extérieur de la copie de travail :

git -C /path/to/repository rev-parse --git-path hooks/pre-commit
codex-security install-hook /path/to/repository

Le contrôle analyse les modifications indexées et non indexées avant chaque commit et bloque les commits en cas de résultats de gravité élevée ou critique, ou d’erreurs d’analyse. Les hooks locaux sont facultatifs ; utilisez un contrôle CI obligatoire pour imposer cette règle. Laissez la gestion des hooks personnalisés, liés ou partagés et de leurs répertoires à leur propriétaire. Le programme d’installation ne remplace pas un script pre-commit sans rapport avec Codex Security. Définissez un autre seuil de gravité si nécessaire :

codex-security install-hook /path/to/repository --fail-on-severity medium

codex-security policy

Rédigez une ébauche de politique SECURITY.md décrivant les limites de sécurité du projet et ce qui doit être considéré comme un résultat à signaler :

npx @openai/codex-security policy .
npx @openai/codex-security policy . --headless --json

La commande enregistre une ébauche en dehors du dépôt et laisse les fichiers existants inchangés. Examinez l’ébauche, le diff et les notes de révision, puis copiez uniquement le fichier SECURITY.md révisé vers l’emplacement cible de la politique indiqué. En mode sans interface, les questions sans réponse restent dans les notes de révision. La génération de politique est facultative ; les analyses peuvent utiliser une politique existante ou s’exécuter sans politique. Consultez le guide des politiques pour connaître les portées des chemins et les options.

codex-security scan-components

Utilisez scan-components pour analyser séparément les services ou les packages d’un même dépôt. Chaque exécution, y compris une exécution limitée à la planification, nécessite un répertoire de sortie nouveau ou vide situé en dehors du worktree Git qui englobe le dépôt. Définissez-le avec --output-dir ou avec output.directory dans la configuration du projet.

Par exemple, analysez deux services en parallèle :

npx @openai/codex-security scan-components . \
  --component apps/api --component apps/web \
  --output-dir /path/outside/repository/manual-components

Contrairement à scan --path, cette commande effectue une analyse par composant, puis regroupe et rapproche les résultats. Par défaut, quatre analyses de composants peuvent s’exécuter simultanément. Définissez --workers N pour modifier cette limite. --max-cost USD limite chaque analyse de composant. Cette limite exclut la planification automatique et le rapprochement entre composants.

Pour que Codex propose un découpage, enregistrez un plan à examiner avant de lancer l’analyse :

npx @openai/codex-security scan-components . --auto --plan-only \
  --output-dir /path/outside/repository/component-plan

Examinez les noms et les chemins des composants dans components.json, puis exécutez le plan enregistré dans un nouveau répertoire de sortie :

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/component-plan/components.json \
  --output-dir /path/outside/repository/components

Ouvrez report.md dans le répertoire de sortie pour examiner les résultats regroupés. Si un composant échoue, utilisez le plan de relance enregistré pour relancer uniquement les composants en échec :

npx @openai/codex-security scan-components . \
  --components-file /path/outside/repository/components/retry-components.json \
  --output-dir /path/outside/repository/retry-results

Le rapport de relance couvre uniquement les composants relancés. Conservez le rapport d’origine pour examiner les résultats des composants dont l’analyse s’est terminée lors de la première exécution.

Les échecs d’analyse ou de rapprochement renvoient 2. Les violations de la politique de gravité renvoient 1. Consultez le guide d’analyse des composants pour connaître la syntaxe des plans et les modalités de relance.

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 la découverte de dépôts GitHub, les inventaires CSV, les résultats de campagne et les analyses en conteneur, 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 EFFORT]
                                [--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 la découverte interactive, sélectionnez un modèle Codex accessible avec votre compte :

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 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 renvoient des erreurs. Ces instructions ne sont pas exécutées 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’erreurs de dépôt ou d’analyse. Les exclusions et les notes de suivi ne déclenchent pas de nouvelle tentative pour les analyses terminées. Les échecs d’exécution restants renvoient 2 ; les violations de la politique de gravité constatées à l’issue des analyses renvoient 1.

Exécutez à nouveau la même commande pour reprendre à partir d’un répertoire de sortie existant. La CLI ignore les analyses terminées. Utilisez --recover pour relancer les tentatives échouées ou interrompues dans une campagne correspondante.

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 une analyse enregistrée :

npx @openai/codex-security scans rerun SCAN_ID

Une relance crée une nouvelle analyse à partir des paramètres et du choix d’authentification enregistrés, de la copie de travail actuelle et des fichiers de contexte actuels. Elle ne recharge pas les fichiers de configuration du projet et ne réutilise pas les identifiants enregistrés. Si l’analyse initiale utilisait des prompts d’analyse ou de validation personnalisée, fournissez à nouveau ces fichiers avec --scan-prompt-file et --validation-prompt-file.

Les relances nécessitent la version du plugin enregistrée lors de l’analyse initiale et s’arrêtent si la version installée est différente.

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 les résultats enregistrés ou un modèle de menaces sans démarrer Codex ni charger d’identifiants. Vous pouvez exporter les résultats au format CSV, JSON, SARIF ou CSV ServiceNow AVIT uniquement à partir d’une analyse terminée et scellée. Les modèles de menaces utilisent Markdown.

usage: codex-security export [scan_dir | --scan SCAN_ID]
                             [--artifact {findings,threat-model}]
                             [--export-format {csv,json,sarif,md,servicenow-avit}]
                             [--avit-template FILE]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH]

Omettez scan_dir et --scan pour utiliser la dernière analyse terminée du dépôt actuel. Sinon, fournissez un répertoire de résultats enregistrés ou sélectionnez une analyse par son ID ou un préfixe unique d’au moins huit caractères avec --scan. Vous ne pouvez pas combiner ces sélecteurs.

Argument Description
--artifact {findings,threat-model} Sélectionnez l’artefact enregistré. La valeur par défaut est findings.
--scan SCAN_ID Sélectionnez une analyse enregistrée par son ID, un préfixe unique d’au moins huit caractères ou latest.
--export-format FORMAT Sélectionnez csv, json, sarif, md ou servicenow-avit. Les résultats utilisent sarif par défaut ; les modèles de menaces prennent uniquement en charge md.
--avit-template FILE Fournissez le modèle CSV requis par servicenow-avit. Seul ce format l’accepte.
--output FILE|- Écrivez le format sélectionné dans un fichier ou sur la sortie standard. Par défaut, utilise un fichier dans le répertoire actuel.
--source-root PATH Ajoutez des empreintes de lignes de code source au format SARIF à l’aide d’une copie de travail du dépôt.
--python PATH Sélectionnez l’interpréteur Python pour l’exportateur fourni.

--source-root fonctionne uniquement avec les exports de résultats SARIF. JSON préserve le document de résultats scellé. CSV contient des colonnes de résultats portables et n’inclut pas l’état de triage de l’espace de travail local.

Sans --output, la CLI écrit le contenu SARIF dans results.sarif, JSON dans findings.json, CSV dans findings.csv, CSV ServiceNow AVIT dans servicenow-avit.csv et Markdown dans threatmodel.md, dans le répertoire de travail actuel. Les exports peuvent contenir des extraits de code source et des détails sur les vulnérabilités. Passez --output avec un chemin privé situé hors de la copie de travail. Si vous exécutez la commande hors du dépôt, spécifiez également un répertoire de résultats ou --scan.

Exporter les résultats

É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

Exporter les résultats pour ServiceNow

ServiceNow nécessite le rôle Ethical Hacker (sn_vul.app_pen_tester). Ouvrez All > Manual AVIT Ingestion > Upload File UI et téléchargez le modèle CSV. Conservez les en-têtes d’origine et exactement une ligne de données. Utilisez le nom exact de l’application ServiceNow. Renseignez l’objectif, les types de données sensibles, les programmes de conformité, la pile technologique, l’équipe de l’application et les URL à tester. Définissez Requested by, Assigned to et Assignment group. Laissez les champs de résultats vides. Enregistrez le modèle sous app.csv dans un répertoire privé hors du dépôt analysé. Réutilisez-le pour les analyses de la même application.

Depuis le dépôt analysé, exportez les derniers résultats avec ce modèle. Conservez également la sortie dans le répertoire privé :

npx @openai/codex-security export --scan latest \
  --export-format servicenow-avit \
  --avit-template /path/outside/repository/exports/app.csv \
  --output /path/outside/repository/exports/findings-avit.csv

La CLI écrit une ligne par résultat et remplit Steps to reproduce à partir du chemin d’attaque enregistré, lorsqu’il est disponible. Vérifiez ces étapes et complétez les champs vides dans le CSV exporté. Revenez à Upload File UI, sélectionnez Import File, importez le CSV, puis sélectionnez Submit. Chaque import crée un nouveau formulaire de test d’intrusion pour l’application. Consultez les instructions d’import de ServiceNow.

Exporter un modèle de menaces enregistré

Exportez le modèle de menaces enregistré de la dernière analyse terminée vers la sortie standard sans effectuer de nouvel appel au modèle :

npx @openai/codex-security export --artifact threat-model --output -

Ou sélectionnez une analyse et enregistrez son modèle dans un fichier :

npx @openai/codex-security export --scan SCAN_ID \
  --artifact threat-model \
  --output /path/outside/repository/exports/threatmodel.md

Si vous sélectionnez une analyse par son ID ou son répertoire, vous pouvez également exporter un modèle enregistré à partir d’une analyse inachevée ou échouée. Si aucun modèle n’a été enregistré, la commande renvoie une erreur. Examinez tout contenu provisoire ou récupéré signalé dans le document avant de le réutiliser.

Pour fournir le modèle exporté comme contexte à une autre analyse, passez son chemin à --knowledge-base.

codex-security publish scan

Publiez les résultats sélectionnés d’une analyse terminée dans Linear ou un service de résultats personnalisé. Les options suivantes décrivent la publication dans Linear :

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.

Utilisez --scan SCAN_ID ou --scan latest à la place d’un répertoire pour sélectionner une analyse enregistrée. Répétez --finding-id ID pour sélectionner un sous-ensemble destiné à Linear. Utilisez publish check SCAN_DIR avec les options de destination Linear pour vérifier les artefacts et les publications enregistrées. Avec une API key, cette commande vérifie également l’authentification et l’accès à la destination ; l’accès via une application connectée est indiqué comme not-checked.

Argument Description
--to linear Publiez dans Linear. Cet argument est obligatoire.
--linear-team TEAM_ID Sélectionnez l’équipe Linear. Utilise CODEX_SECURITY_LINEAR_TEAM si l’argument est omis ; l’un des deux est obligatoire.
--project PROJECT_ID Sélectionnez un projet Linear. Utilise CODEX_SECURITY_LINEAR_PROJECT si l’argument est omis. Si aucun des deux n’est défini, les tickets sont créés directement dans l’équipe.
--linear-api-key KEY Utilisez une API key personnelle Linear pour une publication directe. Utilise CODEX_SECURITY_LINEAR_API_KEY si l’argument est omis.
--linear-assignee EMAIL_OR_USER_ID Attribuez les tickets créés par adresse e-mail ou ID utilisateur Linear. Nécessite --linear-api-key ou CODEX_SECURITY_LINEAR_API_KEY. Les tickets restent non attribués si l’argument est omis.
--dry-run Préparez les données des tickets sans démarrer Codex, contacter Linear, créer de tickets ni écrire l’état de publication.
--skip-existing Ignorez les résultats dont une publication réussie est enregistrée pour la même occurrence, la même équipe Linear et le même projet. Nécessite l’historique local.
--json Écrivez les résultats structurés de publication sur la sortie standard. La progression reste sur la sortie d’erreur standard.

Chaque invocation sans simulation tente de créer un nouveau ticket pour chaque résultat sélectionné, sauf si --skip-existing trouve une réussite enregistrée pour cette occurrence, cette équipe et ce projet. Cette option n’examine pas les tickets distants et ne couvre pas les publications non enregistrées ou simultanées. Si la publication de certains résultats échoue, 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 pour é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.

Publier dans un service de résultats personnalisé

Pour un service de résultats existant, sélectionnez explicitement son URL :

npx @openai/codex-security publish scan --scan latest \
  --to custom --findings-url http://localhost:3000

La publication envoie l’intégralité des résultats scellés et l’ID de la cible du dépôt. Les résultats peuvent inclure des extraits de code source, des preuves et des détails sur les vulnérabilités. Utilisez HTTPS pour les services situés hors de votre machine locale et ajoutez --dry-run --json pour examiner les données avant de les envoyer.

La CLI n’envoie pas les identifiants du modèle à un service personnalisé. Gérez toute authentification requise en dehors de la CLI. Consultez le guide du service de résultats pour en savoir plus sur le déploiement et le protocole.

codex-security publish findings

Utilisez --to local pour enregistrer les résultats importés sur votre machine. Avec --to cloud, même un aperçu contacte le service. Une connexion ChatGPT enregistrée dans un fichier et un ID ou une URL de dépôt autorisé disposant d’un environnement Cloud existant sont nécessaires. Un import Cloud peut renvoyer un résultat partiel si le service rejette certains enregistrements. Consultez le guide d’import GitHub pour les deux procédures.

Pour importer des alertes Dependabot pour une copie de travail locale, vous devez disposer d’un export enregistré provenant du même dépôt GitHub. Suivez le guide d’export Dependabot pour enregistrer toutes les pages hors de la copie de travail à l’aide d’un jeton disposant d’un accès en lecture aux alertes Dependabot.

Ajoutez echo "$out/dependabot.jsonl" à la fin du script d’export avant de l’exécuter. Dans un nouveau shell, utilisez le chemin affiché pour prévisualiser le fichier. Remplacez ./project et OWNER/REPO par votre copie de travail et votre dépôt. Si la copie de travail possède des dépôts distants réseau, l’un d’eux doit correspondre au dépôt des alertes. Sinon, vérifiez que l’export appartient à la copie de travail.

export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
npx @openai/codex-security publish findings /path/to/dependabot.jsonl \
  --to local --repository ./project --provider github \
  --source-key github.com/OWNER/REPO/dependabot --dry-run --format json

Vérifiez la destination et les exclusions dans l’aperçu. Une simulation se termine avec le code 0 même si elle répertorie des alertes exclues. Pour enregistrer les alertes acceptées, relancez la commande sans --dry-run et confirmez, ou remplacez --dry-run par --yes. Si l’import exclut des alertes, il enregistre celles qui sont acceptées et se termine avec le code 1. Consultez les alertes enregistrées dans le même shell.

npx @openai/codex-security findings imported ./project --format json

Les alertes importées ont initialement le statut d’évaluation not_assessed. Avec la même clé source, un import ultérieur met à jour les enregistrements des alertes présentes dans le fichier. Les alertes omises conservent leur dernier état importé. Les alertes liées au même avis de sécurité restent des enregistrements distincts.

Commandes de révision des résultats

Ces commandes s’appliquent aux résultats existants :

Commande Exemple Comportement
classify-severity codex-security classify-severity --scan latest --rubric policy.md --json Applique une grille d’évaluation sans relancer la détection ni réécrire les résultats d’origine. Omettez --rubric pour reprendre une gravité existante sans appel au modèle. Les résultats sans gravité nécessitent une grille d’évaluation.
suggest-owners codex-security suggest-owners findings.json --source-root /path/to/repository --json Consulte le code source commité, CODEOWNERS, les informations blame et l’historique Git pour suggérer des responsables. N’attribue pas de tickets.
dedupe codex-security dedupe --scan SCAN_ID --json Repère les résultats en double dans la base SQLite locale. Les représentations vectorielles absentes ou obsolètes nécessitent une API key de vectorisation ; les nouvelles révisions nécessitent un accès au modèle.
verify-fix codex-security verify-fix --scan SCAN_ID --json Vérifie les correctifs existants dans un bac à sable en lecture seule. Accepte les ID de résultats, les descriptions et les sélecteurs Linear.

verify-fix renvoie 2 si une vérification n’est pas concluante ou échoue. Sinon, la commande renvoie 1 si un résultat reste vulnérable, ou 0 si tous les résultats sont corrigés. Utilisez --help pour chaque commande afin de consulter les sélecteurs, les paramètres du modèle et les options de sortie.

codex-security feedback

Envoyez une description du problème à OpenAI et recevez un ID à communiquer à l’assistance :

npx @openai/codex-security feedback SCAN_ID \
  --reason "The scan stopped before it finished" --json

Sans ID d’analyse, la commande sélectionne l’analyse démarrée le plus récemment dans le dépôt actuel, y compris les analyses actives ou ayant échoué, ou envoie un rapport général si aucune analyse n’existe. Les rapports comprennent la description, les versions et les ID d’analyse/session sélectionnés. Les journaux sont exclus par défaut. Ajoutez --include-logs uniquement si vous pouvez partager le code source, les prompts, les résultats et les sorties d’outils inclus avec OpenAI.

codex-security validate et codex-security patch

Évaluez les résultats potentiels à partir du code source du dépôt actuel :

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 actuel. validate utilise un bac à sable en lecture seule pour évaluer les éléments probants du code source. La commande ne compile pas la cible, n’exécute pas le code de l’application, ne lance ni tests ni preuves de concept et ne contacte aucun service. Les analyses Standard, Deep et diff conservent leurs propres procédures de validation ; patch continue de corriger et de vérifier les résultats.

Utilisez validate pour réévaluer un résultat après un correctif ou lorsqu’une analyse ultérieure ne le signale plus. La seule comparaison des analyses ne prouve pas qu’un correctif a fonctionné. Pour obtenir des éléments probants à l’exécution, lancez une étape de reproduction distincte.

La commande affiche son évaluation sur stdout sans enregistrer de rapport. Redirigez stdout pour la conserver :

npx @openai/codex-security validate findings.json > /path/outside/repository/assessment.md

Ajoutez --context TEXT, --context-file FILE ou plusieurs options --knowledge-base PATH pour fournir le contexte de sécurité. Pour une sortie structurée, utilisez --output-schema FILE avec un schéma JSON Schema autonome pris en charge par votre modèle et votre fournisseur. La CLI vérifie le JSON généré par rapport au schéma avant de l’écrire sur stdout. Si la sortie est invalide, la CLI se termine avec le code 2 et n’écrit aucune évaluation. validate n’accepte pas --json.

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 résultats après une analyse terminée. Le seuil de gravité par défaut est low. Cette commande sélectionne les résultats 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 pour le dépôt actuel. patch prend en charge --json pour les résultats enregistrés, le texte littéral et les fichiers en entrée.

Ajoutez --create-pr pour commiter uniquement les fichiers de correctifs vérifiés et ouvrir une pull request GitHub ou une merge request GitLab à l’état de brouillon avec la CLI correspondante :

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

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 indiquant la phase d’analyse actuelle, l’inventaire des fichiers, l’activité, l’utilisation des jetons et le coût estimé. La CI et les sorties redirigées affichent la progression en texte brut. Ajoutez --headless pour afficher 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 les diagnostics du cycle de vie, de l’authentification, de la progression et des coûts sur stderr :

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éfinie ou est vide.

Codex Security conserve le texte des diagnostics. Les diagnostics peuvent contenir du code source ou des identifiants d’accès ; examinez-les avant de les partager.

Résumé de fin

Une analyse terminée écrit sur stderr le nombre de résultats 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 indique aussi l’utilisation des jetons lorsque cette information est disponible et le coût estimé lorsque vous définissez --show-cost ou --max-cost. Par exemple :

  REPORT    /path/to/scan/report.md

  FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
  SCOPE     repository: .
  ELAPSED   1s
  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 sur stdout. Utilisez manifest.scan pour le statut et le périmètre, et findings pour les résultats de l’analyse actuelle. Lorsque cette donnée est disponible, repositoryFindings inclut ces résultats ainsi que les résultats antérieurs encore ouverts. review.excludedPaths répertorie les motifs de chemins que l’analyse a enregistrés comme exclus de la révision. scanDir, reportPath et artifactsDir pointent vers les résultats enregistrés.

threatModel contient le modèle enregistré sous forme de données structurées ou de Markdown. threatModelPath pointe vers le document enregistré. L’un comme l’autre peut valoir null ; le modèle peut toujours être exporté si l’écriture du document a échoué.

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’analyse, les avis d’archivage et les diagnostics restent sur stderr. Une analyse terminée affiche toujours le résultat JSON lorsqu’une politique de gravité renvoie le code de sortie 1.

Vérifiez toujours le code de sortie du processus, même lorsque le JSON est analysé correctement. Les échecs d’exécution sans résultats d’analyse renvoyés produisent une erreur structurée avec status, code et message lorsque vous utilisez --json, --format json ou --format jsonl. Lorsque des résultats d’analyse valides sont conservés, la sortie peut à la place contenir le résultat d’analyse habituel et warnings, par exemple après un changement de cible. Avec --json, --format json ou --format jsonl, ajoutez --full-output pour recevoir une enveloppe ok: false contenant l’erreur sous error et les éventuels résultats valides scellés et conservés sous data. Les autres formats signalent les échecs uniquement sur stderr, même avec --full-output. Ces règles s’appliquent aussi à scans rerun et scans resume.

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
├── report.md
├── threatmodel.md          # when available
├── artifacts/
└── exports/
    └── results.sarif       # when produced

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

Fichier Contenu
scan-manifest.json Identité, statut, cible, périmètre et producteur de l’analyse, ainsi qu’enregistrements des artefacts scellés.
findings.json Identifiants, gravité, confiance, taxonomie, emplacements, éléments probants, validation, flux de données, accessibilité et mesures correctives des résultats.
report.md Rapport d’analyse lisible.
threatmodel.md Modèle de menace enregistré, lorsqu’il est disponible.
artifacts/ Artefacts complémentaires de l’analyse.
exports/results.sarif SARIF généré pendant l’analyse, lorsqu’il est présent.

Achèvement et couverture de la révision

Consultez scan.status dans scan-manifest.json pour vérifier si l’analyse est terminée. Consultez scan.scope pour connaître le périmètre configuré et scan.review.excludedPaths pour connaître les exclusions enregistrées par l’analyse pendant la révision. Les comparaisons d’analyses utilisent également ces exclusions. Une analyse terminée peut encore laisser certains fichiers du périmètre sans révision.

Pour les travaux restant à traiter, examinez les éléments disponibles avec scans show SCAN_ID et scans logs SCAN_ID. Un Deep Scan interrompu et éligible peut reprendre avec scans resume SCAN_ID. Pour lancer une nouvelle analyse avec les paramètres enregistrés, utilisez scans rerun SCAN_ID lorsqu’une recette de lancement est disponible. Les scans lancés par un plugin peuvent ne pas disposer d’une recette réutilisable ; lancez alors un nouveau scan avec les chemins et le contexte souhaités.

Codes de sortie et signaux

La CLI utilise les codes de sortie suivants :

Code de sortie Condition
0 Un scan ou une campagne en masse s’est terminé et respecte sa politique de sévérité, une publication s’est terminée sans échec, ou une autre commande a réussi.
1 Un scan ou une campagne en masse atteint son seuil de sévérité, verify-fix signale un problème non corrigé sans résultat non concluant, ou un import confirmé exclut des enregistrements locaux ou renvoie un résultat Cloud partiel.
2 Une erreur d’entrée, d’exécution, d’intégrité des résultats, de sortie requise ou d’export s’est produite, publish scan présente un ou plusieurs problèmes en échec, ou verify-fix signale un résultat non concluant.
130 Ctrl-C a interrompu un scan ou une publication.
143 SIGTERM a arrêté un scan ou une publication.

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 scans CLI et SDK s’exécutent avec les autorisations de votre système d’exploitation local. Le profil de scan permet de lire le système de fichiers local et d’écrire dans les racines des espaces de travail. Les demandes d’approbation d’exécution sont examinées automatiquement et peuvent accorder des autorisations supplémentaires pour une opération. Utilisez --codex 'approval_policy="never"', ou définissez codexOverrides.approval_policy: "never" dans le SDK, pour refuser les demandes d’autorisation. Les restrictions de l’hôte et du réseau restent applicables.

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 scans, les scans en masse, les exports, l’historique des scans et les problèmes enregistrés nécessitent également Python 3.10 ou une 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.

Pour lire ou reprendre des sessions Codex compressées (.jsonl.zst), utilisez Node.js 22.15.0 ou une version ultérieure de la branche 22.x, ou Node.js 24 ou 26. Les sessions .jsonl non compressées fonctionnent sur toutes les versions de Node.js prises en charge.

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