Référence de la CLI Codex Security

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

Lancez 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 propose les commandes suivantes.

La CLI propose également les commandes d’intégration suivantes.

Listez toutes les commandes disponibles avec la commande suivante.

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 fourni. Aucune de ces commandes ne nécessite Python. Utilisez codex-security --update pour mettre à jour la CLI installée.

Découverte des commandes et connexion des agents

Affichez le manifeste des commandes dans un format lisible par les agents.

npx @openai/codex-security --llms

Consultez le schéma des arguments d’analyse au format JSON.

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

Générez le script d’autocomplétion pour Bash.

npx @openai/codex-security completions bash

Remplacez bash par zsh ou fish si vous utilisez l’un de ces shells.

Les résultats d’analyse prennent en charge --format toon|json|yaml|jsonl et --full-output. --export-format sélectionne le format d’un artefact exporté à partir d’une analyse terminée. L’aide générale des commandes mentionne aussi md, mais les résultats d’analyse ne prennent pas en charge la sortie Markdown.

Enregistrez la CLI comme serveur MCP.

npx @openai/codex-security mcp add

Synchronisez les skills Codex Security avec vos agents.

npx @openai/codex-security skills add

Le serveur MCP de la CLI expose uniquement la commande de métadonnées info, en lecture seule. Les analyses, les exports, la publication, l’authentification, la validation et l’application de correctifs restent accessibles uniquement via la CLI.

codex-security scan

Lancez une analyse sur un dépôt, des chemins sélectionnés, des modifications déjà intégrées à des commits ou l’arbre de travail.

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]

Par défaut, repository correspond au répertoire courant.

Chargement de la configuration du projet

Créez une configuration initiale 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. L’option explicite a priorité sur la variable d’environnement. La CLI ne recherche pas automatiquement de fichier de configuration du 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 lancer des processus de serveur MCP et choisir les services auxquels envoyer les requêtes de modèle. Ne sélectionnez pas un fichier contrôlé par un dépôt ou une pull request dont vous ne pouvez pas garantir la fiabilité. En CI, conservez la configuration de l’analyseur en dehors de la copie de travail à évaluer. Consultez le guide de configuration du projet pour connaître les paramètres et leur ordre de priorité.

Choix de l’authentification pour l’analyse

Utilisez --auth auto, l’option par défaut, pour sélectionner automatiquement les identifiants. Si une connexion ChatGPT est disponible en même temps que OPENAI_API_KEY ou CODEX_API_KEY, les analyses interactives avec sortie texte vous demandent quels identifiants utiliser. Les analyses en CI, les analyses avec sortie JSON ou JSONL et les autres analyses sans terminal interactif utilisent la clé API de l’environnement. Les simulations ne demandent ni ne chargent d’identifiants.

Pour utiliser vos identifiants enregistrés, passez --auth chatgpt.

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

Pour utiliser une clé API de l’environnement, passez --auth api-key.

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

Pour que la sélection automatique utilise par défaut les identifiants enregistrés, 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, Codex conserve ses paramètres par défaut. La valeur standard sélectionne explicitement le programme standard. La sélection d’un programme ne donne pas accès à celui-ci. Votre projet API doit avoir été approuvé pour le programme choisi. Consultez le guide des programmes d’accès pour connaître les identifiants requis.

Attribution des analyses aux utilisateurs finaux

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

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

Utilisation d’OpenRouter ou de Fireworks

Sélectionnez OpenRouter en indiquant sa clé API et un modèle explicite.

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

Sélectionnez Fireworks en indiquant sa clé API et un modèle explicite.

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

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

Utilisation d’Amazon Bedrock

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

Daybreak Blue et Daybreak Red

Daybreak Blue et Daybreak Red nécessitent l’approbation du programme Trusted Access for Cyber. Pour demander l’accès, envoyez le formulaire de demande d’accès pour les entreprises ou contactez l’équipe OpenAI chargée de votre compte. Après approbation, contactez l’équipe AWS chargée de votre compte pour activer l’accès au modèle sur Amazon Bedrock.

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

Pour vérifier la disponibilité, consultez les fiches modèles AWS de Daybreak Blue et de Daybreak Red.

Pour lancer une analyse avec Daybreak Blue, remplacez <aws-profile-name> par le nom d’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. Il 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 la chaîne standard d’identifiants AWS. Les clés d’accès temporaires nécessitent AWS_SESSION_TOKEN. Définissez les identifiants et AWS_REGION dans le shell ou la tâche de CI qui lance l’analyse.

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

Les rapports locaux enregistrés, scans show et export sont utilisables sans identifiants cloud.

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

Estimation des coûts Bedrock

La CLI prend en charge les estimations de coût et --max-cost pour les identifiants de modèles Daybreak Blue et Daybreak Red indiqués ci-dessus. Les estimations utilisent les tarifs commerciaux standard d’AWS pour une utilisation dans la région, frais AWS compris. La limite de coût se fonde sur estimatedUsd, l’estimation de référence pour un contexte court. Les requêtes déjà en cours peuvent faire dépasser cette limite. La tarification des contextes longs peut porter estimatedUsdRange au-delà de cette limite. Celle-ci ne plafonne pas la facturation.

Choix de la cible d’analyse

Choisissez un seul type de cible par analyse.

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

Pour les analyses de différences ou d’arbres de travail, l’argument du dépôt doit désigner la racine de l’arbre de travail Git. Les références sélectionnées doivent exister dans cette copie de travail.

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 intégrées aux commits.

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

Lancez une analyse approfondie du dépôt.

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

Configuration des analyses approfondies

Utilisez les options suivantes avec --mode deep pour contrôler la recherche de problèmes.

Par exemple, utilisez deux processus, autorisez jusqu’à dix analyses et arrêtez la recherche 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 du délai, l’analyse arrête les processus encore actifs et regroupe les constats des analyses terminées dans son rapport. Pour une analyse standard, --max-time fixe une durée indicative pour l’investigation. La rédaction du rapport peut se terminer plus tard. Les instructions de validation personnalisées et les instructions de suivi 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 ont priorité sur la configuration du projet. Utilisez scan.deep.stop_after_consecutive_errors pour modifier le nombre d’erreurs consécutives des processus qui entraîne l’arrêt de la recherche. La valeur par défaut est 3. Pour bulk-scan, --workers contrôle le nombre de dépôts analysés en parallèle.

Ajout de 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 formats pris en charge comprennent les fichiers texte UTF-8 (dont JSON et SARIF), PDF et DOCX. La CLI parcourt les répertoires de manière récursive, refuse les chemins d’entrée qui passent par des liens et ignore les liens rencontrés dans les répertoires. Elle enregistre les documents extraits à côté des artefacts d’analyse dans le fichier privé .scan-knowledge.json, qui permet de reprendre l’analyse. Conservez ce fichier avec le répertoire d’analyse. Les rapports de référence ne contiennent pas le texte des documents.

Ajout d’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 une analyse réussie ou terminée avec 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 limites des autorisations et demandez, dans les instructions de suivi, la création d’un fichier post-scan-summary.md dans le répertoire d’analyse. Si le suivi échoue, la CLI émet un avertissement et conserve l’analyse terminée. Le suivi ne s’exécute pas après une annulation ou lorsque l’analyse atteint sa limite de coût. Lorsqu’il s’exécute, son coût échappe au suivi des coûts de l’analyse et à --max-cost.

Validation des constats 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 relève 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 pour les analyses standard de dépôts, de chemins, de différences ou d’arbres de travail. Pour les analyses standard de composants, définissez scan.validation_file dans la configuration du projet. Les analyses approfondies refusent la validation personnalisée.

Ajoutez --validate à une nouvelle commande d’analyse pour évaluer séparément chaque constat signalé à partir du seul code source. Si l’analyse relève des constats, la CLI consigne les évaluations dans un rapport dans le répertoire d’analyse. Ces évaluations ne modifient ni les constats ni la décision prise selon 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.

Options de sortie et de politique de gravité

Utilisez ces options pour conserver les artefacts, préserver les résultats précédents ou produire un résultat exploitable par un programme.

Le mode de simulation avec données synthétiques prend en charge les analyses standard de dépôts, de chemins et de différences. Vous ne pouvez pas le combiner avec --dry-run, --patch, le mode approfondi, une validation personnalisée ou des prompts de suivi. Les prompts d’analyse et les bases de connaissances ne modifient pas les constats synthétiques. Utilisez un CODEX_SECURITY_STATE_DIR distinct pour conserver les résultats synthétiques en dehors de votre historique d’analyse.

La limite de coût se fonde sur estimatedUsd, l’estimation de référence pour un contexte court. Les requêtes déjà en cours peuvent faire dépasser cette limite. La tarification des contextes longs peut porter estimatedUsdRange au-delà de cette limite. Celle-ci ne plafonne pas la facturation.

Si une analyse approfondie atteint la limite après que Codex Security a regroupé les résultats des processus terminés, la CLI peut sceller un résultat complet et émettre un avertissement budgétaire. Elle renvoie 0, ou 1 si des constats atteignent le seuil de gravité configuré. Si elle ne peut pas produire de résultat complet valide, elle renvoie 2 et laisse les sorties disponibles sur disque.

Si vous omettez --output-dir, les résultats sont conservés sous $CODEX_HOME/state/plugins/codex-security/scans/<repository>. La valeur par défaut de CODEX_HOME est ~/.codex. Définissez CODEX_SECURITY_STATE_DIR pour conserver les résultats sous $CODEX_SECURITY_STATE_DIR/scans/<repository>. Ces répertoires peuvent contenir des extraits de code source et des détails sur les vulnérabilités. Gérez leurs permissions et leur durée de conservation en conséquence.

L’environnement de travail conserve l’historique des analyses dans $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Définir CODEX_SECURITY_STATE_DIR déplace également la base de données de cet environnement.

Le répertoire de sortie doit se trouver en dehors du répertoire analysé et de tout arbre de travail Git qui l’englobe. 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 se limitent à produire un rapport. Ajoutez --fail-on-severity pour évaluer une politique de gravité en 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, y compris les documents de la base de connaissances, sans charger d’identifiants, lancer Codex ni tester l’interpréteur Python du plugin.

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

Configuration de l’environnement d’exécution

Utilisez les options d’exécution pour choisir un modèle, un interpréteur, un plugin ou une valeur de configuration Codex.

Codex Security accepte les identifiants de modèles 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.

Si la configuration isolée de Codex utilisée pour 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 vérifier le modèle et l’effort effectivement sélectionnés avant de lancer l’analyse.

Pour choisir un modèle et un effort de raisonnement, sélectionnez un modèle Codex auquel votre compte a accès.

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

Entourez de guillemets les valeurs de type chaîne passées via --codex afin que l’analyseur TOML reçoive bien une chaîne.

npx @openai/codex-security scan . --codex 'model="gpt-6.1-sol"'

Codex reçoit les valeurs de modèle et d’effort telles quelles. Si la combinaison n’est pas prise en charge, Codex ou le fournisseur renvoie une erreur sans substituer un autre modèle ou niveau d’effort.

codex-security scan import

Enregistrez des constats existants dans l’historique local sous forme d’analyse terminée, sans lancer d’analyse de sécurité ni appeler de modèle. L’import ne nécessite pas d’authentification auprès d’un 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’export 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 constats. Les fichiers JSON quelconques d’autres analyseurs et les tableaux bruts d’alertes GitHub ne sont pas acceptés comme constats enregistrés.

Enregistrez cet exemple synthétique dans 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’import renvoie l’identifiant de l’analyse enregistrée et les chemins des résultats. Pour importer du JSON, exécutez la commande suivante.

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.

Utilisez un fichier d’entrée ordinaire dont le chemin ne contient ni lien symbolique ni jonction de répertoires. Chaque import conserve les occurrences des constats, y compris les doublons, et stocke l’entrée sous artifacts/import/. Les identifiants d’origine sont conservés dans extensions.import. L’état terminé indique que l’import a abouti, sans attester d’un examen du code source. 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 de copie du 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 de la CLI GitHub disposant d’un accès en lecture aux alertes d’analyse de code. Par défaut, l’import lit les alertes ouvertes de la branche par défaut, y compris celles issues de fichiers SARIF envoyés par des tiers.

Ne combinez pas des numéros d’alerte précis avec un état autre que open. La commande renvoie un tableau des alertes provenant de GitHub sans enregistrer d’analyse. Depuis le dépôt local correspondant, exécutez codex-security validate /path/outside/repository/alerts.json pour les évaluer. Lorsque vous enregistrez les entrées de validation, conservez le JSON complet sans filtre de sortie ni limite de tokens. Utilisez scan import pour les constats déjà conformes au schéma Codex Security. Pour importer des alertes Dependabot, utilisez publish findings.

codex-security install-hook

Installez la CLI en dehors du dépôt, inspectez 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

Avant chaque commit, le contrôle analyse les modifications indexées et non indexées. Il bloque le commit en cas de constat de gravité élevée ou critique, ou d’erreur d’analyse. Les hooks locaux sont facultatifs. Utilisez un contrôle obligatoire en CI pour imposer la vérification. Laissez les propriétaires gérer les hooks et répertoires de hooks personnalisés, partagés ou accessibles via des liens. L’installateur ne remplace pas un script pre-commit sans rapport avec l’analyse. Si nécessaire, définissez un autre seuil de gravité.

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

codex-security policy

Rédigez une politique SECURITY.md qui décrit les limites de sécurité du projet et précise les problèmes à signaler comme constats.

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

La commande enregistre un brouillon en dehors du dépôt et laisse les fichiers existants intacts. Examinez le brouillon, les différences et les notes de revue, puis copiez uniquement le fichier SECURITY.md vérifié à l’emplacement indiqué pour la politique. En mode sans interface, les questions restées sans réponse figurent dans les notes de revue. La génération de la politique est facultative. Les analyses peuvent utiliser une politique existante ou s’exécuter sans politique. Consultez le guide des politiques de sécurité pour connaître les chemins concernés et les options disponibles.

codex-security scan-components

Utilisez scan-components pour analyser séparément les services ou les paquets d’un même dépôt. Chaque exécution, même limitée à la planification, nécessite un répertoire de sortie nouveau ou vide en dehors de l’arbre de travail Git englobant. 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 produit une analyse par composant, puis regroupe les constats et établit leurs correspondances. Par défaut, quatre analyses de composants peuvent s’exécuter en parallèle. Définissez --workers N pour modifier cette limite. --max-cost USD limite le coût de chaque analyse de composant. Cette limite exclut la planification automatique et la mise en correspondance entre composants.

Pour que Codex propose un découpage, enregistrez un plan et examinez-le avant de lancer l’analyse.

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

Vérifiez 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 constats regroupés. En cas d’échec d’un composant, utilisez le plan de relance enregistré pour analyser à nouveau 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 analysés à nouveau. Conservez le rapport initial pour examiner les constats des composants dont l’analyse a abouti dès la première exécution.

Les échecs d’analyse ou de mise en correspondance 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

Recherchez et analysez des dépôts GitHub, ou lancez une analyse pouvant être reprise à partir d’un inventaire de dépôts au format CSV.

Pour la recherche sur GitHub, les inventaires CSV, les résultats des campagnes et les analyses en conteneur, consultez le guide des analyses de sécurité par lots.

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. Cette procédure nécessite une connexion via la CLI GitHub.

Pour la recherche interactive, sélectionnez un modèle Codex auquel votre compte a accès.

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

Si vous avez préparé une liste de dépôts, fournissez un fichier CSV et indiquez --output-dir.

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

Le CSV doit contenir les colonnes id, repository et revision. Les révisions doivent être des empreintes complètes de commits. Les colonnes facultatives scope, mode et prompt permettent de configurer chaque dépôt 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 les instructions propres au dépôt à la suite du prompt commun. --post-scan-prompt-file FILE exécute des instructions de suivi après chaque analyse, y compris celles qui renvoient des erreurs. Le suivi ne s’exécute pas après une annulation ou lorsqu’une analyse atteint sa limite de coût.

--workers limite le nombre de dépôts analysés simultanément et vaut 4 par défaut. --mode vaut standard par défaut et --max-attempts vaut 1 par défaut. Définissez --max-attempts pour réessayer en cas d’erreur liée au dépôt ou à l’analyse. Les exclusions et les notes de suivi ne déclenchent pas la relance d’analyses terminées. Les échecs d’exécution qui persistent renvoient 2. Les analyses terminées qui enfreignent la politique de gravité 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 d’une campagne correspondante.

Pour les campagnes en conteneur, consultez la section Exécution d’analyses par lots dans Docker.

codex-security scans

Recherche des analyses enregistrées

Listez les analyses enregistrées pour le répertoire courant.

npx @openai/codex-security scans

Listez 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 précis.

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

Consultation ou relance d’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 des analyses précédentes.

Relancez une analyse enregistrée.

npx @openai/codex-security scans rerun SCAN_ID

La relance crée une nouvelle analyse avec les paramètres et le mode d’authentification enregistrés, la copie de travail actuelle et les 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.

La relance nécessite la version du plugin consignée lors de l’analyse initiale et s’arrête si la version installée est différente.

Consultation des journaux d’analyse enregistrés

Consultez l’ensemble des événements de session enregistrés pour une analyse et ses processus. Ces journaux ne sont pas expurgés et peuvent contenir du code source ou des identifiants. Examinez-les avant de les partager.

npx @openai/codex-security scans logs SCAN_ID

Ajoutez --json pour obtenir une sortie structurée.

Mise en correspondance et comparaison des constats

Comparez deux analyses pour repérer 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 rapproche automatiquement les constats qui ont la même cause profonde 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 a un statut inconnu si son chemin est exclu ou si sa correspondance est incertaine. Si l’analyse la plus récente ne le retrouve pas dans le code examiné, il est considéré comme non observé. Seul un constat explicitement clos au motif qu’il a déjà été corrigé est considéré comme résolu. Ajoutez --force à match pour recalculer une correspondance existante.

Pour rapprocher les constats de toutes les analyses terminées du dépôt courant, y compris celles provenant d’autres copies de travail, exécutez la commande suivante.

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

Les résultats peuvent varier même si vous relancez une analyse avec la même configuration. La mise en correspondance et la comparaison permettent de suivre les changements, sans rendre les résultats déterministes ni prouver qu’une vulnérabilité a disparu. Utilisez validate pour revérifier un constat critique pour la sécurité dans le code actuel.

codex-security findings

Listez les constats ouverts de l’ensemble des analyses du dépôt courant.

npx @openai/codex-security findings list

Passez le chemin d’un dépôt pour examiner une autre copie de travail.

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

Ajoutez --json pour obtenir une sortie structurée. La liste distingue les constats observés lors de la dernière analyse des constats antérieurs qu’elle n’a pas confirmés.

Les constats antérieurs restent ouverts tant qu’ils n’ont pas été résolus ou écartés. Leur absence dans la dernière analyse ne prouve pas qu’ils ont été corrigés.

Pour consigner un constat examiné comme faux positif, utilisez la syntaxe suivante.

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

Inspectez l’analyse enregistrée pour identifier l’occurrence du constat.

npx @openai/codex-security scans show SCAN_ID

Consignez 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 peut pas être vide. Codex Security enregistre la décision pour le dépôt et la fournit comme contexte aux analyses futures. Chaque analyse vérifie à nouveau et de façon indépendante le code source actuel, les contrôles et la possibilité d’atteindre le code concerné. Une décision antérieure n’exclut aucune règle, aucun chemin ni aucune catégorie de vulnérabilités.

codex-security export

Exportez des constats enregistrés ou un modèle de menace sans lancer Codex ni charger d’identifiants. Seule une analyse terminée et scellée permet d’exporter des constats au format CSV, JSON, SARIF ou CSV ServiceNow AVIT. Les modèles de menace 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 courant. Sinon, fournissez un répertoire de résultats enregistrés ou sélectionnez une analyse par son identifiant ou un préfixe unique d’au moins huit caractères avec --scan. Ces deux modes de sélection ne peuvent pas être combinés.

--source-root fonctionne uniquement pour les exports de constats en SARIF. Le format JSON conserve le document de constats scellé. Le CSV contient des colonnes de constats portables et n’inclut pas l’état de triage de l’environnement de travail local.

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

Export des constats

Écrivez le SARIF dans un fichier.

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

Écrivez le SARIF sur 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

Export des constats 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 dans ServiceNow. Renseignez sa finalité, les types de données sensibles, les programmes de conformité, la pile technologique, l’équipe responsable de l’application et les URL à tester. Renseignez les champs Requested by, Assigned to et Assignment group. Laissez vides les champs relatifs aux constats. Enregistrez le modèle sous le nom app.csv dans un répertoire privé en dehors 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 constats 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 constat et remplit Steps to reproduce à partir du chemin d’attaque consigné, s’il est disponible. Vérifiez ces étapes et complétez les champs vides du CSV exporté. Revenez à Upload File UI, sélectionnez Import File, importez le CSV et sélectionnez Submit. Chaque import crée un nouveau formulaire de test d’intrusion pour l’application. Consultez les instructions d’import de ServiceNow.

Export d’un modèle de menace enregistré

Exportez sur stdout le modèle de menace enregistré lors de la dernière analyse terminée sans effectuer de nouvel appel au modèle.

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

Vous pouvez également sélectionner une analyse et enregistrer son modèle de menace 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 identifiant ou par répertoire, vous pouvez aussi exporter un modèle enregistré lors d’une analyse inachevée ou échouée. Si aucun modèle n’a été enregistré, la commande renvoie une erreur. Examinez tout contenu signalé comme provisoire ou récupéré 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 des constats sélectionnés d’une analyse terminée dans Linear ou auprès d’un service personnalisé de gestion des constats. Les options suivantes concernent 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. Dans un terminal interactif, omettez cet argument pour sélectionner une analyse terminée dans l’historique local. Pour créer des tickets, l’analyse et ses constats doivent également figurer dans cet historique. Une simulation valide les artefacts scellés sans vérifier leur présence dans l’historique.

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 de constats à publier dans Linear. Utilisez publish check SCAN_DIR avec les options de destination Linear pour vérifier les artefacts et les publications enregistrées. Avec une clé API, la commande vérifie également l’authentification et l’accès à la destination. Pour une application connectée, l’état de vérification de l’accès est not-checked.

En dehors des simulations, chaque exécution tente de créer un ticket pour chaque constat sélectionné, sauf si --skip-existing trouve une publication réussie enregistrée pour cette occurrence, cette équipe et ce projet. Cette option ne consulte pas les tickets distants et ne couvre pas les publications non enregistrées ou simultanées. Si certains constats ne peuvent pas être publiés, la commande conserve les tickets créé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 données des tickets avant de publier.

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

Publication avec l’application Linear connectée

Sans clé API Linear, la commande lance Codex avec votre configuration existante et votre application 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

Publication avec une clé API Linear

Si vous fournissez --linear-api-key ou CODEX_SECURITY_LINEAR_API_KEY, la commande publie directement via l’API Linear sans lancer Codex. En publication directe, les tickets restent sans responsable sauf si vous en désignez un.

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 la ligne de commande ont priorité sur les variables d’environnement correspondantes. Pour les clés API, privilégiez 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.

Publication auprès d’un service personnalisé de gestion des constats

Pour utiliser un service existant de gestion des constats, indiquez 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 constats scellés et l’identifiant du dépôt cible. Les constats peuvent inclure des extraits de code source, des éléments de preuve et des détails sur les vulnérabilités. Utilisez HTTPS pour les services hébergés en dehors de votre machine et ajoutez --dry-run --json pour inspecter les données avant leur envoi.

La CLI ne transmet pas les identifiants d’accès au modèle à un service personnalisé. Gérez toute authentification requise en dehors de la CLI. Consultez le guide du service de gestion des constats pour les détails du déploiement et du protocole.

codex-security publish findings

Utilisez --to local pour enregistrer les constats importés sur votre machine. Avec --to cloud, la CLI contacte le service même pour un aperçu. Vous devez disposer d’une connexion ChatGPT enregistrée dans un fichier et fournir l’identifiant ou l’URL d’un dépôt autorisé disposant déjà d’un environnement Cloud. Un import dans le Cloud peut renvoyer un résultat partiel si le service rejette certains enregistrements. Consultez le guide d’import depuis GitHub pour les deux procédures.

Pour importer des alertes Dependabot dans 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 des alertes Dependabot pour enregistrer toutes les pages en dehors 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é par le script pour prévisualiser le fichier. Remplacez ./project par le chemin de votre copie de travail et OWNER/REPO par le propriétaire et le nom de votre dépôt. Si la copie de travail possède des dépôts distants accessibles via le réseau, l’un d’eux doit correspondre au dépôt d’origine des alertes. Sinon, vérifiez que l’export provient bien du dépôt correspondant à 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. La simulation renvoie le code 0 même si elle liste 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 renvoie le code 1. Consultez les alertes enregistrées dans le même shell.

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

À l’import, les alertes ont pour statut d’évaluation not_assessed. Si vous réutilisez la même clé de source, un import ultérieur met à jour les enregistrements des alertes présentes dans le fichier. Les alertes absentes du fichier conservent leur dernier état importé. Les alertes qui se rapportent au même avis de sécurité conservent chacune leur propre enregistrement.

Commandes d’examen des constats

Ces commandes s’appliquent aux constats existants.

verify-fix renvoie 2 si une vérification échoue ou ne permet pas de conclure. Sinon, la commande renvoie 1 si au moins une vulnérabilité subsiste, ou 0 si tous les problèmes ont été corrigés. Consultez --help pour chaque commande afin de connaître les sélecteurs, les paramètres du modèle et les options de sortie.

codex-security feedback

Envoyez la description d’un problème à OpenAI pour recevoir un identifiant à communiquer à l’assistance.

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

Sans identifiant d’analyse, la commande sélectionne l’analyse démarrée le plus récemment dans le dépôt courant, y compris si elle est en cours ou a échoué. En l’absence d’analyse, elle envoie un rapport général. Les rapports contiennent la description, les versions et les identifiants d’analyse et de session sélectionnés. Par défaut, ils excluent les journaux. Ajoutez --include-logs uniquement si vous pouvez partager avec OpenAI le code source, les prompts, les constats et les sorties d’outils qu’ils contiennent.

codex-security validate et codex-security patch

Évaluez les constats potentiels à partir du code source actuel du dépôt.

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

Générez un correctif avec le skill de correction fourni.

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

Chaque argument positionnel accepte du texte littéral ou un chemin de fichier. Ces entrées utilisent le répertoire courant. validate utilise un bac à sable en lecture seule pour évaluer les éléments de preuve dans le code source. La commande ne compile pas la cible, n’exécute ni code applicatif, ni tests, ni démonstrations de faisabilité, et ne contacte aucun service. Les analyses standard, approfondies et de différences conservent leurs propres workflows de validation. patch continue de corriger et de vérifier les problèmes signalés.

Utilisez validate pour réévaluer un constat après un correctif ou lorsqu’une analyse ultérieure ne le signale plus. La seule comparaison des analyses ne prouve pas l’efficacité du correctif. Pour recueillir des preuves à l’exécution, reproduisez le problème dans une étape distincte.

La commande écrit 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 du 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 la conformité du JSON généré au schéma avant d’écrire sur stdout. Si la sortie n’est pas valide, la CLI se termine avec le code 2 sans écrire d’évaluation. validate n’accepte pas --json.

Utilisez --effort pour choisir l’effort de raisonnement de l’une ou l’autre commande.

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

Correction des problèmes après une analyse

Utilisez scan --patch pour corriger les problèmes après une analyse terminée. Le seuil de gravité par défaut est low. La commande suivante sélectionne les constats de gravité élevée ou critique.

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

Les constats dont le correctif a été vérifié et ceux qui étaient déjà corrigés ne déclenchent pas --fail-on-severity.

Correction des problèmes enregistrés

Passez un identifiant de constat ou d’occurrence pour corriger le problème dans son dépôt d’origine, ou sélectionnez des constats d’une analyse enregistrée.

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

--scan latest sélectionne la dernière analyse terminée du dépôt courant. patch prend en charge --json pour les constats enregistrés, le texte littéral et les fichiers d’entrée.

Ajoutez --create-pr pour créer un commit contenant uniquement les fichiers des 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.

Correction des problèmes signalés dans Linear

Définissez CODEX_SECURITY_LINEAR_API_KEY ou LINEAR_API_KEY pour une clé API personnelle, ou LINEAR_ACCESS_TOKEN pour un jeton OAuth. Privilégiez une variable d’environnement à --linear-api-key KEY pour que la clé ne figure pas dans l’historique du shell.

Importez un ticket par identifiant ou par 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.

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

Enregistrez une clé API en la passant sur stdin.

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

Enregistrez un jeton d’accès d’entreprise.

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

Consultez en lecture seule les métadonnées du SDK et du plugin fourni.

npx @openai/codex-security info --json

Lecture de la sortie d’analyse

Par défaut, les analyses écrivent la progression, les bilans de fin d’analyse et les erreurs sur stderr sans écrire le résultat complet sur stdout. Utilisez --json, --format ou --full-output pour écrire les résultats structurés sur stdout.

Les terminaux interactifs affichent un tableau de bord en temps réel indiquant la phase d’analyse en cours, l’inventaire des fichiers, l’activité, la consommation de tokens et le coût estimé. En CI ou lorsque la sortie est redirigée, la progression s’affiche 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 aussi les détails de la session en temps réel. 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 écrire sur stderr les diagnostics relatifs au cycle d’exécution, à l’authentification, à la progression et aux coûts.

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

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

Codex Security conserve le texte des diagnostics. Celui-ci peut contenir du code source ou des identifiants. Examinez les diagnostics avant de les partager.

Bilan de fin d’analyse

Une analyse terminée écrit sur stderr le nombre de constats ouverts du dépôt, leur répartition par gravité, le temps écoulé, le chemin du rapport et le répertoire des résultats. Elle indique également la consommation de tokens si elle est disponible, et le coût estimé si vous avez défini --show-cost ou --max-cost. Exemple de sortie :

  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 à titre informatif sont inclus dans le total du bilan. Les politiques de gravité évaluent uniquement les constats critical, high, medium et low de l’analyse en cours. Les constats antérieurs inclus dans le total du dépôt ne participent pas à cette évaluation.

Sortie JSON

scan --json écrit un seul document JSON sur stdout. Consultez manifest.scan pour connaître l’état et le périmètre de l’analyse, et findings pour les constats de l’analyse en cours. Lorsqu’il est disponible, repositoryFindings comprend ces constats ainsi que les constats antérieurs encore ouverts. review.excludedPaths liste les motifs de chemins consignés comme exclus de l’examen. scanDir, reportPath et artifactsDir indiquent l’emplacement des résultats enregistrés.

threatModel contient le modèle de menace enregistré sous forme de données structurées ou de Markdown. threatModelPath indique le chemin du document enregistré. Chacun de ces champs peut valoir null. Le modèle reste exportable si l’écriture du document a échoué.

Lors de l’application de correctifs, la sortie JSON inclut également les résultats des corrections et toute pull request créée.

La progression, les bilans de fin d’analyse, les notifications d’archivage et les diagnostics restent sur stderr. Une analyse terminée écrit le résultat JSON même si la politique de gravité entraîne le code de sortie 1.

Vérifiez toujours le code de sortie du processus, même si le JSON est syntaxiquement valide. En cas d’échec d’exécution sans résultat d’analyse renvoyé, la CLI produit une erreur structurée avec status, code et message si vous utilisez --json, --format json ou --format jsonl. Si des résultats valides ont été conservés, la sortie peut 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 scellés valides 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é consigne les empreintes des artefacts pour permettre de vérifier ultérieurement que les fichiers n’ont pas changé.

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

Les fichiers structurés remplissent des fonctions distinctes.

État d’achèvement et périmètre examiné

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 les exclusions consignées pendant l’examen. La comparaison des analyses utilise également ces exclusions. Même une analyse terminée peut laisser certains fichiers du périmètre sans examen.

Pour les tâches non résolues, examinez les éléments disponibles avec scans show SCAN_ID et scans logs SCAN_ID. Une analyse approfondie interrompue peut se poursuivre avec scans resume SCAN_ID si elle remplit les conditions de reprise. Pour lancer un nouvel examen avec les paramètres enregistrés, utilisez scans rerun SCAN_ID si une procédure de lancement est disponible. Les analyses effectuées par un plugin ne disposent pas toujours d’une procédure réexécutable. Dans ce cas, lancez une nouvelle analyse avec les chemins et le contexte voulus.

Codes de sortie et signaux

La CLI utilise les codes de sortie suivants.

Les lacunes de couverture ne modifient pas le code de sortie d’une analyse terminée et ne contournent pas sa politique de gravité. Le code de sortie 0 ne garantit pas que tous les fichiers ont été examinés. Si vous demandez une sortie structurée, les analyses terminées et les publications partielles écrivent les résultats disponibles sur stdout. Après une interruption ou une erreur d’exécution, la CLI indique l’emplacement des éventuelles sorties partielles.

Permissions des analyses locales

Les analyses de la CLI et du SDK s’exécutent avec les permissions dont vous disposez sur le système d’exploitation local. Le profil d’analyse autorise la lecture du système de fichiers local et l’écriture dans les répertoires racines de l’espace de travail. Les demandes d’approbation d’exécution sont examinées automatiquement et peuvent aboutir à l’octroi de permissions 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 de permission. Les restrictions de l’hôte et du réseau restent applicables.

Les processus d’analyse et de l’environnement de travail peuvent hériter de vos variables d’environnement, y compris de jetons API et d’identifiants cloud sans rapport avec l’analyse. Supprimez les identifiants inutiles avant de lancer une analyse.

Authentification et prérequis

Définissez OPENAI_API_KEY ou CODEX_API_KEY, connectez-vous avec npx @openai/codex-security login ou utilisez une connexion Codex existante enregistrée dans un fichier. Pour OpenRouter ou Fireworks, définissez la clé API du fournisseur et sélectionnez un modèle. Pour Amazon Bedrock, utilisez une clé API Bedrock ou la chaîne standard d’identifiants AWS.

Pour choisir les identifiants, consultez la section Choix de l’authentification pour l’analyse.

En CI, limitez l’accès à la clé API à l’étape d’analyse et utilisez un workflow de confiance.

La CLI nécessite Node.js 24 ou 26, ou Node.js 22 à partir de la version 22.13.0. Les analyses, les analyses par lots, les exports, l’historique des analyses et les constats enregistrés nécessitent aussi Python 3.10 ou version ultérieure. Python 3.10 nécessite également tomli. Utilisez --python avec scan, bulk-scan ou export, ou définissez PYTHON pour toute commande qui repose 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 encore Node.js 24 ou 26. Les sessions .jsonl non compressées fonctionnent avec toutes les versions prises en charge de Node.js.

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