FAQ sur la CLI de Codex Security

Comment analyser des dépôts et gérer les problèmes de sécurité détectés depuis le terminal ? Cette FAQ répond aux questions les plus fréquentes. Pour installer la CLI et lancer une première analyse, consultez le guide de démarrage rapide de la CLI.

Analyse des dépôts

Pourquoi une analyse utilise-t-elle une clé API après la connexion ?

Si votre environnement contient OPENAI_API_KEY ou CODEX_API_KEY, les analyses sans terminal interactif et celles dont la sortie est au format JSON ou JSONL utilisent par défaut la clé API de l’environnement, même après une connexion réussie via ChatGPT ou avec un jeton d’accès. Lors d’une analyse interactive avec sortie texte, la CLI vous demande de choisir le mode d’authentification si une connexion via ChatGPT est également disponible. Les simulations ne vous demandent rien et ne chargent aucun identifiant.

Pour utiliser vos identifiants enregistrés lors d’une analyse, sélectionnez-les explicitement :

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

Pour exiger une clé API provenant de OPENAI_API_KEY ou de CODEX_API_KEY, utilisez la commande suivante :

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

Pour utiliser automatiquement vos identifiants enregistrés par défaut, exécutez unset OPENAI_API_KEY CODEX_API_KEY. Consultez la référence de la CLI pour connaître tous les modes d’authentification pris en charge.

Peut-on reprendre une analyse par lots interrompue ?

Oui. Relancez la même commande d’analyse par lots avec le fichier CSV et le répertoire de sortie d’origine. Codex Security ignore les dépôts dont l’analyse est terminée.

Ajoutez --max-attempts 3 pour réessayer en cas d’erreur temporaire liée au dépôt ou à l’analyse :

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

Codex Security conserve les résultats des analyses terminées et ne les relance pas, même si certaines parties du dépôt n’ont pas été couvertes. Une couverture incomplète n’entraîne pas le code de sortie 2 pour la campagne.

Problèmes détectés et couverture

Où retrouver les résultats des analyses précédentes ?

Affichez la liste des analyses enregistrées pour votre dépôt :

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

Utilisez l’identifiant d’une analyse figurant dans la liste pour examiner les problèmes qu’elle a détectés :

npx @openai/codex-security scans show SCAN_ID

Chaque analyse terminée conserve au même endroit son rapport, les problèmes détectés, son manifeste et les artefacts associés. Consultez la section Artefacts d’analyse pour voir comment l’ensemble est organisé.

Pour consulter les événements enregistrés pour l’analyse et ses processus de travail, exécutez scans logs SCAN_ID. Ces journaux ne masquent pas les données sensibles et peuvent contenir du code source ou des identifiants.

Que faire si la CLI ne peut pas enregistrer l’historique des analyses ?

Codex Security conserve l’historique des analyses dans la base de données de son environnement de travail. Si vous ne pouvez pas écrire dans le répertoire d’état par défaut, choisissez un répertoire privé en dehors du dépôt :

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Comment distinguer les nouveaux problèmes des problèmes connus ?

Affichez la liste des problèmes encore ouverts pour l’ensemble des analyses d’un dépôt :

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

La liste distingue les problèmes confirmés lors de la dernière analyse de ceux qui restent ouverts depuis une analyse précédente et que la dernière analyse n’a pas confirmés.

Comparez les problèmes détectés lors des deux analyses :

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparaison rapproche automatiquement les problèmes selon leur cause première et réutilise les correspondances enregistrées. Elle distingue les problèmes nouveaux, persistants, rouverts, non observés, résolus et ceux dont le statut reste inconnu. Si une analyse ultérieure ne retrouve pas un problème antérieur dans le code qu’elle a examiné, ce problème est considéré comme non observé. Il ne compte comme résolu qu’une fois explicitement clôturé au motif qu’il a déjà été corrigé. Le statut reste inconnu si le chemin a été exclu ou si la correspondance est incertaine.

Comment les analyses tiennent-elles compte des faux positifs signalés ?

Consultez l’analyse enregistrée pour retrouver l’identifiant de l’occurrence :

npx @openai/codex-security scans show SCAN_ID

Indiquez pourquoi le problème signalé ne s’applique pas :

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

Les analyses suivantes du même dépôt reçoivent cette explication comme élément de contexte. Chacune vérifie indépendamment le code source actuel, les protections en place et la possibilité d’atteindre le code concerné. Écarter un faux positif n’exclut aucune règle, aucun chemin ni aucune catégorie de vulnérabilités.

Pour plus de détails sur les commandes, consultez la référence des commandes de gestion des problèmes détectés.

Pourquoi des analyses successives peuvent-elles détecter des problèmes différents ?

Les résultats des analyses assistées par IA peuvent varier, même avec une configuration identique. Commencez par relancer votre analyse de référence :

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

La nouvelle analyse reprend la configuration d’origine et exige la même version du plugin. Si la version du plugin installé a changé, la commande s’arrête.

Comparez l’analyse de référence à la nouvelle analyse :

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Si un manque de contexte peut expliquer les écarts, fournissez aux analyses les mêmes consignes sur l’architecture et la sécurité. La mise en correspondance peut reconnaître un même problème de fond d’une analyse à l’autre, mais elle ne rend pas les analyses déterministes. Vérifiez directement tout problème important qui n’apparaît plus.

Comment vérifier qu’un correctif fonctionne ?

Vérifiez à nouveau le problème initial sur la copie de travail modifiée. Depuis cette copie, indiquez le rapport de l’analyse d’origine et le problème à vérifier :

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

Examinez les éléments montrant que le chemin vulnérable n’est plus exploitable et que les usages légitimes fonctionnent toujours. Si vous disposez du scénario de reproduction initial ou d’un test de régression, exécutez-le. Si la vérification ne peut pas être exécutée, précisez dans le résultat ce qui reste incertain.

Une comparaison des analyses peut montrer comment les problèmes détectés ont évolué, mais la seule absence d’un problème ne suffit pas à confirmer sa correction.

Que signifie une couverture incomplète ?

Dans scan-manifest.json, consultez scan.status pour savoir si l’analyse est terminée. Le champ scan.scope indique le périmètre configuré. Le champ scan.review.excludedPaths répertorie les motifs de chemin que l’analyse a exclus de son examen. Si un ancien manifeste contient le champ scan.coverageRef, ouvrez le fichier qu’il désigne pour obtenir les détails de la couverture.

Une couverture incomplète ne change pas le code de sortie d’une analyse terminée. Le code 0 ne signifie pas que tous les fichiers ont été examinés. Une analyse ultérieure ne peut pas établir qu’un problème antérieur a disparu si elle ne couvre pas le chemin où il avait été détecté.

Automatisation et coûts

Comment limiter la durée d’une analyse approfondie ?

Fixez une durée maximale pour les processus de travail au lancement de l’analyse approfondie :

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

La durée par défaut est de 96 heures. Vous pouvez indiquer toute valeur strictement positive jusqu’à 96 inclus, y compris une valeur fractionnaire. À l’échéance, Codex Security arrête les processus de travail encore en cours, conserve les résultats des analyses standard terminées et les regroupe dans le rapport final. Consultez le rapport pour savoir quelles parties ont été examinées et quels travaux ont été reportés. Le code de sortie dépend de l’état d’exécution et de la politique de sévérité. Le seul fait d’atteindre l’échéance ne le détermine pas.

Pour conserver ce réglage ou l’appliquer aux campagnes d’analyse par lots, définissez max_time_hours dans la section [deep_scan] de la configuration des analyses approfondies.

Comment fonctionnent les limites de coût des analyses ?

Avant de lancer l’analyse, fixez une limite pour le coût estimé en dollars américains :

npx @openai/codex-security scan . --max-cost 5

Cette limite repose sur une estimation. Les requêtes déjà en cours peuvent aller à leur terme et porter la dépense au-delà du montant fixé. Si une analyse approfondie atteint la limite après que Codex Security a regroupé les résultats des processus de travail terminés, la CLI peut enregistrer un rapport complet assorti d’un avertissement budgétaire. Elle renvoie 0, ou 1 si des problèmes détectés atteignent le seuil de sévérité configuré. Si elle ne peut pas produire de résultat final valide, elle renvoie 2 et conserve les données de sortie disponibles.

Pour vérifier les pull requests sur GitHub et planifier des analyses de dépôts, utilisez la GitHub Action de Codex Security. Avec action-v0.3.0, une analyse est considérée comme terminée lorsque l’analyse configurée a produit un résultat valide. La politique de sévérité s’applique même si certaines parties du dépôt sont exclues ou si des investigations sont reportées. Consultez coverage.json pour évaluer le périmètre de l’analyse et ses limites. Pour rejeter également les diffs vides et les simulations, exigez que la sortie scan-status de la GitHub Action ait la valeur completed. Consultez la section Choisir une politique de sévérité.

Pour les autres fournisseurs, consultez la présentation de l’intégration et de la livraison continues (CI/CD). Pour lancer une vérification avant chaque commit, utilisez install-hook.