Documentation ChatGPT
Français
Contact goolvyouyou@gmail.com

Démarrage rapide avec Codex Security CLI

Configurez Codex Security, exécutez une analyse locale, puis examinez le rapport, les résultats et la couverture.

Codex Security aide les équipes de sécurité et d’ingénierie à détecter, confirmer et corriger les vulnérabilités. Utilisez son interface de ligne de commande (CLI) pour analyser les dépôts que vous possédez ou que vous êtes autorisé à évaluer, suivre les résultats dans le temps et vérifier les modifications avant leur intégration.

Vérifier les prérequis

La CLI nécessite Node.js 22 ou version ultérieure. L’exécution d’une analyse ou l’exportation des résultats nécessite également Python 3.10 ou version ultérieure. Pour en savoir plus, consultez Authentification et prérequis.

Configurer et vérifier la CLI

Installez le package publié :

npm install @openai/codex-security

Répertoriez les commandes disponibles :

npx @openai/codex-security --help

Consultez également la référence de la CLI.

Se connecter

Pour une utilisation locale, connectez-vous avec votre compte ChatGPT :

npx @openai/codex-security login

Sur une machine distante ou sans interface graphique, utilisez l’authentification par appareil :

npx @openai/codex-security login --device-auth

Pour la CI et les autres workflows automatisés, définissez une API key OpenAI :

export OPENAI_API_KEY="<your-api-key>"

Pour les identifiants AWS, consultez la configuration d’Amazon Bedrock.

Pour utiliser votre connexion ChatGPT lorsqu’une API key est également définie, sélectionnez-la explicitement :

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

Pour imposer l’utilisation de l’API key de l’environnement, sélectionnez l’authentification par API key :

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

Selon votre compte et votre dépôt, les analyses de l’ensemble du dépôt peuvent également nécessiter Trusted Access for Cyber.

Préparer une analyse

Choisissez un dépôt à analyser et un répertoire dans lequel écrire les résultats.

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Si vous omettez --output-dir, Codex Security enregistre les résultats dans son propre répertoire d’état persistant. Les résultats peuvent inclure des extraits de code source et des détails sur les vulnérabilités ; choisissez donc un emplacement privé et une politique de conservation appropriée.

Si le répertoire d’état par défaut n’est pas accessible en écriture, sélectionnez un répertoire accessible en écriture situé en dehors du dépôt analysé :

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

Vérifiez le dépôt, la cible et le répertoire de sortie avant de démarrer une analyse :

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

L’exécution à blanc vérifie les entrées locales sans démarrer Codex, charger les identifiants ni tester l’interpréteur Python du plugin.

Exécuter votre première analyse

Exécutez une analyse standard et conservez ses résultats dans le répertoire sélectionné :

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

Par défaut, la CLI écrit la progression de l’analyse et son résumé final dans stderr. Elle n’écrit pas le résultat complet de l’analyse dans stdout. Une analyse terminée affiche un résumé semblable à celui-ci :

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

L’utilisation des tokens et le coût estimé s’affichent lorsqu’ils sont disponibles. Pour afficher le résultat complet au format JSON lisible par une machine, demandez explicitement une sortie structurée :

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

Par défaut, les analyses produisent uniquement un rapport, de sorte que les résultats restent disponibles pour un examen local. Vous pouvez ajouter un seuil de sévérité lorsque vous êtes prêt à exécuter des analyses dans la CI.

Choisir un modèle et un niveau de raisonnement

Par défaut, les analyses utilisent gpt-5.6-sol avec un niveau de raisonnement xhigh. Sélectionnez un modèle et un niveau différents lorsque la tâche l’exige :

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

Les niveaux pris en charge sont minimal, low, medium, high et xhigh.

Examiner les résultats

Ouvrez report.md pour consulter le résultat lisible. Le répertoire de l’analyse contient également les fichiers structurés utilisés par l’automatisation :

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json consigne la cible, la portée, le producteur et les artefacts scellés.
  • findings.json consigne la sévérité, le niveau de confiance, les emplacements, les preuves et les mesures correctives de chaque résultat.
  • coverage.json consigne les surfaces examinées, les exclusions, le travail différé, les questions ouvertes et l’exhaustivité de la couverture.

La couverture peut être complete, partial ou unknown. Examinez toutes les zones différées ou questions ouvertes avant de considérer l’analyse comme une preuve de vérification. La référence de la CLI décrit le contrat complet des artefacts et de la sortie.

Choisir l’analyse suivante

Utilisez une analyse de chemin lorsqu’un dépôt contient des services ou des packages distincts :

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Examinez les modifications validées entre la révision de base et HEAD :

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Examinez les modifications indexées et non indexées par rapport à HEAD :

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Les analyses de diff et de worktree exigent que l’argument du dépôt désigne la racine du worktree Git. Récupérez les révisions sélectionnées avant de démarrer une analyse de diff.

Utilisez le mode approfondi lorsqu’un dépôt ou un chemin nécessite un examen plus étendu :

npx @openai/codex-security scan "$REPOSITORY" --mode deep

Le mode approfondi prend en charge les cibles de type dépôt et chemin, mais pas les analyses de diff ou de worktree.

Ajouter du contexte sur l’architecture et la sécurité

Fournissez des documents d’architecture, des modèles de menace ou des politiques de sécurité comme contexte de l’analyse. Cela aide Codex Security à évaluer les résultats en fonction du fonctionnement réel de votre système :

npx @openai/codex-security scan "$REPOSITORY" \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Définir un budget d’analyse

Utilisez --max-cost pour arrêter une analyse lorsque le coût estimé du modèle dépasse une limite en USD :

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Les requêtes déjà en cours peuvent se terminer au-delà de cette limite. Codex Security conserve les résultats disponibles lorsqu’une analyse s’arrête.

Analyser les modifications avant chaque commit

Installez un contrôle de sécurité Git pre-commit pour votre dépôt :

npx @openai/codex-security install-hook

Le contrôle analyse les modifications indexées et non indexées avant chaque commit. Il bloque les résultats de sévérité élevée et les erreurs d’analyse sans remplacer un script pre-commit existant.

Analyser des dépôts en masse

Connectez-vous à GitHub avant de rechercher les dépôts :

gh auth login

Recherchez et sélectionnez des dépôts depuis votre compte ou votre organisation GitHub :

npx @openai/codex-security bulk-scan

Le parcours interactif exclut les dépôts archivés et les forks. Il vous demande de confirmer les dépôts sélectionnés avant l’analyse.

Pour analyser une liste de dépôts préparée, fournissez un fichier CSV et un répertoire de sortie :

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

Exécutez de nouveau la même commande pour reprendre une analyse en masse existante. Les dépôts terminés dont les artefacts de résultats sont intacts ne sont pas analysés de nouveau. Ajoutez --max-attempts 3 lorsque vous souhaitez réessayer après des erreurs temporaires de dépôt ou d’analyse.

Pour la recherche de dépôts GitHub, la préparation du CSV, les résultats de campagne et la configuration de Docker, consultez Exécuter des analyses de sécurité en masse.

Exécuter des analyses en masse dans Docker

Si votre accès inclut l’image Docker de Codex Security, utilisez la configuration Compose renforcée et le profil de sécurité fournis sur un hôte Docker Linux. L’hôte doit prendre en charge la création d’espaces de noms utilisateur non privilégiés. Fournissez un fichier CSV de dépôts, conservez les résultats et l’état de connexion dans des répertoires montés persistants et fournissez les identifiants par l’intermédiaire de votre environnement ou d’un gestionnaire de secrets :

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Le conteneur exécute les analyses en masse sans invite. Utilisez la CLI en dehors de Docker lorsque vous souhaitez rechercher des dépôts de manière interactive. Pour les dépôts privés, fournissez GH_TOKEN ou GITHUB_TOKEN par l’intermédiaire de votre environnement ou de votre gestionnaire de secrets. Les exigences de connexion, notamment l’accès au compte et au dépôt, s’appliquent également aux analyses conteneurisées.

Revenir sur une analyse enregistrée

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

npx @openai/codex-security scans list "$REPOSITORY"

Copiez un ID d’analyse depuis les résultats pour examiner ses résultats et sa configuration :

npx @openai/codex-security scans show SCAN_ID

Pour marquer un résultat examiné comme faux positif, expliquez pourquoi il ne s’applique pas :

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Les analyses ultérieures prennent cette explication en compte, mais revérifient tout de même le code actuel.

Exécutez la même analyse sur la version actuellement extraite en utilisant sa configuration d’origine :

npx @openai/codex-security scans rerun SCAN_ID

Pour comparer deux analyses, commencez par faire correspondre les résultats qui partagent la même cause racine :

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Vérifiez ensuite quels résultats sont nouveaux, persistants, rouverts, résolus ou inconnus :

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Pour le format CSV des analyses en masse, les filtres de l’historique des analyses et les options des commandes, consultez la référence de la CLI.

Poursuivez avec le workflow adapté à votre objectif :