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 --helpAjoutez --help à une commande pour consulter ses arguments et ses options :
npx @openai/codex-security scan --helpcodex-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 --llmsExaminez le schéma JSON des arguments d’analyse :
npx @openai/codex-security scan --schema --format jsonGénérez les complétions de shell pour Bash :
npx @openai/codex-security completions bashRemplacez 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 addSynchronisez les skills Codex Security avec vos agents :
npx @openai/codex-security skills addLa 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.yamlinit 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 chatgptPour utiliser une API key d’environnement, transmettez --auth api-key :
npx @openai/codex-security scan . --auth api-keyPour 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.5Sé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-a22bLes 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 highPour 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 highVous 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 testsAnalysez les modifications validées :
npx @openai/codex-security scan . --diff origin/main --head HEADAnalysez les modifications indexées et non indexées :
npx @openai/codex-security scan . --working-tree --base HEADEffectuez un examen plus approfondi du dépôt :
npx @openai/codex-security scan . --mode deepConfigurer 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: 10Les 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-policiesLes 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.mdPar 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.mdPar 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-existingPar 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.jsonUne 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-runConfigurer 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 mediumPlacez 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,18Validez 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 jsonLa 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 jsonPour 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 jsonRemplacez 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/repositoryLe 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 mediumcodex-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 --jsonLa 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-componentsContrairement à 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-planExaminez 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/componentsOuvrez 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-resultsLe 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 mediumPour 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 4Le 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 scansRépertoriez les analyses d’un autre dépôt :
npx @openai/codex-security scans list /path/to/repositoryRecherchez les analyses stockées sous un répertoire de sortie donné :
npx @openai/codex-security scans list --scan-root /path/outside/repository/resultsExaminer 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_IDAjoutez --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_IDUne 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_IDAjoutez --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_IDLa 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_IDUn 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 --allLes 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 listTransmettez le chemin d’un dépôt pour examiner un autre checkout :
npx @openai/codex-security findings list /path/to/repositoryAjoutez --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 REASONExaminez l’analyse enregistrée pour identifier l’occurrence du constat :
npx @openai/codex-security scans show SCAN_IDEnregistrez 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.jsonExportez les constats au format CSV :
npx @openai/codex-security export /path/to/scan \
--export-format csv \
--output /path/outside/repository/exports/findings.csvExporter 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.csvLa 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.mdSi 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 \
--jsonPublier 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_IDPublier 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.comLes 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:3000La 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 jsonVé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 jsonLes 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" --jsonSans 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.mdAjoutez --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 highCorriger 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 --jsonLes 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-prSi 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-124Utilisez --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 loginUtilisez l’authentification par appareil sur une machine distante ou sans interface graphique :
npx @openai/codex-security login --device-authVérifiez la connexion actuelle :
npx @openai/codex-security login statusSupprimez la connexion enregistrée :
npx @openai/codex-security logoutStockez une API key en la transmettant via stdin :
printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-keyStockez un jeton d’accès d’entreprise :
printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-tokenExaminez les métadonnées en lecture seule du SDK et du plugin inclus :
npx @openai/codex-security info --jsonLire 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 . --headlessLe 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 . --verboseDé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/scanLes 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 producedLes 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|-