FAQ sur la CLI Codex Security

Trouvez des réponses aux questions fréquentes sur l’analyse des dépôts et la gestion des constats de sécurité depuis le terminal. Pour l’installation et une première analyse, commencez par le guide de démarrage rapide de la CLI.

Analyses de dépôts

Pourquoi une analyse utilise-t-elle une API key après la connexion

Lorsque votre environnement contient OPENAI_API_KEY ou CODEX_API_KEY, les analyses sans terminal interactif ainsi que les analyses JSON et JSONL utilisent par défaut l’API key de l’environnement, même après une connexion réussie avec ChatGPT ou un jeton d’accès. Les analyses interactives avec une sortie texte vous demandent de choisir lorsqu’une connexion ChatGPT est également disponible. Les simulations ne demandent ni ne chargent d’identifiants.

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

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

Pour exiger une API key provenant de OPENAI_API_KEY ou CODEX_API_KEY :

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

Pour faire de vos identifiants enregistrés la valeur par défaut automatique, exécutez unset OPENAI_API_KEY CODEX_API_KEY. Pour tous les modes d’authentification pris en charge, consultez la référence de la CLI.

Une analyse groupée interrompue peut-elle reprendre

Oui. Exécutez la même commande bulk-scan avec le CSV et le répertoire de sortie d’origine. Codex Security ignore les dépôts déjà traités.

Ajoutez --max-attempts 3 pour réessayer après des erreurs temporaires de dépôt ou d’analyse :

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

Les analyses terminées conservent leurs résultats et ne sont pas relancées, même si des lacunes de couverture subsistent. Ces lacunes ne font pas terminer la campagne avec le code 2.

Constats et couverture

Où les équipes peuvent-elles trouver les résultats d’analyses antérieures

Répertoriez les analyses enregistrées pour votre dépôt :

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

Utilisez un identifiant d’analyse figurant dans les résultats pour examiner ses constats :

npx @openai/codex-security scans show SCAN_ID

Chaque analyse terminée conserve ensemble son rapport, ses constats, sa couverture et ses artefacts justificatifs. Consultez Artefacts d’analyse pour connaître la structure complète.

Pour inspecter les événements d’analyse et de worker enregistrés, exécutez scans logs SCAN_ID. Ces journaux ne sont pas expurgés et peuvent contenir du code source ou des identifiants d’accès.

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

Codex Security conserve l’historique des analyses dans une base de données de l’espace de travail. Si le répertoire d’état par défaut n’est pas accessible en écriture, choisissez un répertoire privé en dehors du dépôt :

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

Comment les analyses distinguent-elles les nouveaux constats des constats connus

Répertoriez les résultats ouverts issus de toutes les analyses d’un dépôt :

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

La liste identifie les résultats confirmés lors de la dernière analyse et les résultats ouverts antérieurs que l’analyse n’a pas confirmés.

Comparez les résultats des deux analyses :

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

La comparaison associe automatiquement les constats selon leur cause racine, réutilise les correspondances enregistrées et identifie les constats nouveaux, persistants, rouverts, non observés, résolus et indéterminés. Lorsqu’une analyse ultérieure ne retrouve pas un constat antérieur dans le code qu’elle a analysé, ce constat est considéré comme non observé. Il n’est considéré comme résolu qu’après avoir été explicitement clôturé comme déjà corrigé. Les chemins exclus et les correspondances incertaines restent indéterminés.

Comment fonctionne le retour sur les faux positifs

Examinez l’analyse enregistrée pour trouver l’identifiant de l’occurrence :

npx @openai/codex-security scans show SCAN_ID

Indiquez pourquoi ce constat 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 ultérieures du même dépôt reçoivent cette explication comme contexte. Elles vérifient toujours indépendamment le code source actuel, les contrôles et l’accessibilité. Un classement sans suite ne désactive ni une règle, ni un chemin, ni une catégorie de vulnérabilités.

Pour plus de détails sur les commandes, consultez la référence des constats.

Pourquoi des analyses répétées peuvent-elles produire des constats différents

Les analyses assistées par l’IA peuvent varier, même avec la même configuration d’analyse. Commencez par réexécuter votre analyse de référence :

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

La nouvelle exécution conserve la configuration de l’analyse d’origine et nécessite la même version du plugin. Si le 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

Fournissez des orientations communes sur l’architecture et la sécurité lorsqu’un manque de contexte peut contribuer à cette variation. La mise en correspondance peut identifier le même constat sous-jacent d’une exécution à l’autre, mais elle ne rend pas les analyses déterministes. Revérifiez directement tout constat important qui disparaît.

Comment une équipe peut-elle confirmer qu’un correctif a fonctionné

Vérifiez à nouveau le constat initial dans la copie de travail modifiée. Depuis cette copie de travail, fournissez le rapport correspondant et le problème dont vous souhaitez valider la correction :

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 prouvant que le chemin vulnérable est bloqué et que le fonctionnement légitime reste opérationnel. Exécutez le scénario de reproduction initial ou le test de non-régression, s’il est disponible. Si la vérification ne peut pas être exécutée, signalez l’incertitude restante dans le résultat.

Une comparaison d’analyses peut montrer l’évolution des constats, mais l’absence d’un constat ne suffit pas à vérifier une correction.

Que signifie une couverture incomplète

Consultez coverage.json pour connaître les chemins exclus, les périmètres différés et les questions en suspens. Les nouveaux résultats ne comportent pas de champ indiquant l’exhaustivité de la couverture. Consultez scan.status dans scan-manifest.json pour connaître l’état d’exécution.

Les lacunes de couverture ne modifient pas le code de sortie d’une analyse terminée. Le code de sortie 0 ne signifie pas que chaque fichier a été examiné. Une analyse ultérieure ne peut pas établir qu’un constat antérieur n’existe plus si elle ne couvre pas le chemin d’origine de ce constat.

Automatisation et coûts

Fonctionnement des limites de durée des analyses approfondies

Définissez une échéance pour les workers au démarrage d’une analyse approfondie :

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

La valeur par défaut est de 96 heures. Utilisez toute valeur positive jusqu’à 96, y compris des fractions d’heure. À l’échéance, Codex Security arrête les workers qui n’ont pas terminé, conserve les résultats des analyses standard terminées et les regroupe dans le rapport final. Consultez le rapport pour connaître les zones examinées et les travaux différés. L’échéance seule ne détermine pas le code de sortie ; celui-ci dépend de l’état d’exécution et de la politique de sévérité.

Pour des paramètres persistants ou des campagnes groupées, définissez max_time_hours sous [deep_scan] dans la configuration des analyses approfondies.

Comment fonctionnent les limites de coût des analyses

Définissez une limite de coût estimée en USD avant de lancer l’analyse :

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

La limite est une estimation, et non un plafond de dépenses strict. Les requêtes déjà en cours peuvent se terminer au-delà de cette limite. Si une analyse approfondie atteint la limite après que Codex Security a regroupé les résultats des workers ayant terminé, la CLI peut enregistrer un rapport terminé avec un avertissement budgétaire. Elle renvoie 0, ou 1 si des constats atteignent le seuil de sévérité configuré. Si elle ne peut pas produire de résultat terminé valide, elle renvoie 2 et conserve toute sortie disponible.

Pour les vérifications des pull requests GitHub et les analyses planifiées des dépôts, utilisez l’action GitHub Codex Security. Avec action-v0.3.0, une analyse terminée signifie que l’analyse configurée a produit un résultat valide. Les exclusions de périmètre et les investigations différées ne contournent pas la politique de sévérité. Examinez coverage.json pour évaluer le périmètre et les limites de l’analyse. Pour rejeter également les diffs vides et les simulations, exigez que la sortie scan-status de l’action soit completed ; consultez Choisir une politique de sévérité.

Pour les autres fournisseurs, consultez la présentation de CI/CD. Pour effectuer une vérification avant chaque commit, utilisez install-hook.