ggshield secret scan ai-hook

Description

Scanner les interactions avec les outils d'IA à la recherche de secrets.

ggshield secret scan ai-hook [OPTIONS]

Cette commande est invoquée automatiquement par les hooks IA de ggshield installés dans votre assistant de code ; elle n'est pas destinée à être exécutée manuellement. Elle lit un événement de hook depuis stdin au format JSON, le traite et renvoie une réponse JSON vers stdout qui bloque l'action si des secrets sont détectés.

Pour installer le hook pour vos assistants de code IA, exécutez ggshield machine setup.

Options

• --source-uuid TEXT : Identifiant de la source personnalisée dans GitGuardian. S'il est utilisé, les incidents seront créés et visibles sur le dashboard. Nécessite le scope « scan:create-incidents ».
• --filename-only : Envoyer uniquement le nom du fichier (et non le chemin complet) à GitGuardian, afin que les incidents n'enregistrent que le nom du fichier.
• --all-secrets : N'ignorer aucun secret. La raison possible de l'exclusion est également affichée.
• --instance URL : URL de l'instance à utiliser.
• --with-incident-details : Afficher tous les détails de l'incident du dashboard s'il en existe un (formats JSON et SARIF uniquement). Nécessite le scope « incidents:read ».
• -b, --banlist-detector DETECTOR : Exclure les résultats d'un détecteur.
• --ignore-known-secrets : Ignorer les secrets déjà connus par le dashboard GitGuardian.
• --exclude PATTERNS : Ne pas scanner les chemins qui correspondent aux motifs de type glob spécifiés.
• --exit-zero : Renvoyer un code de statut 0 (sans erreur), même si des incidents sont trouvés. Un code de statut d'erreur sera tout de même renvoyé pour d'autres erreurs, telles que des erreurs de connexion. Cette option peut également être définie avec la variable d'environnement GITGUARDIAN_EXIT_ZERO.
• --show-secrets : Afficher les secrets en clair au lieu de les masquer.
• -o, --output PATH : Rediriger la sortie de ggshield vers PATH.
• --format [text|json|sarif] : Format à utiliser pour la sortie.
• --json : Raccourci pour --format json.

Cette commande prend en charge toutes les options globales de ggshield.

Fonctionnement

Cette commande est appelée automatiquement par les outils de code IA (Cursor, Claude Code, Codex, Copilot CLI, VS Code et Mistral Vibe) lorsque ggshield est installé en tant que hook. Elle n'est pas destinée à être appelée manuellement. Utilisez ggshield machine setup pour configurer les hooks.

Codes de sortie

En fonctionnement normal, cette commande renvoie toujours le code de sortie 0. La décision de blocage ou d'autorisation est communiquée via une charge utile JSON dans stdout, que l'outil de code IA utilise pour afficher un retour dans son interface.

Si ggshield ne peut pas identifier l'outil de code IA appelant, il revient aux codes de sortie standard :

• 0 : Aucun secret trouvé.
• 1 : Une erreur s'est produite pendant le scan.
• 2 : Des secrets ont été trouvés.

Lorsque le scan ne peut pas s'exécuter

Si ggshield ne peut pas scanner une interaction — par exemple parce qu'il n'est pas authentifié, que l'API GitGuardian est inaccessible, ou que le token d'API stocké ne peut pas être lu — le hook ne bloque pas l'action. Il laisse l'interaction se poursuivre et fait apparaître un avertissement via l'outil de code IA indiquant que le contenu n'a pas été scanné à la recherche de secrets, ainsi que la manière de résoudre le problème (comme l'exécution de ggshield auth login).

Ce comportement « fail-open » maintient votre outil de code IA utilisable lorsque ggshield est mal configuré, au prix de ne pas détecter les secrets jusqu'à ce que le problème soit corrigé.

Voir aussi

• Scan de secrets pour les outils de code IA : Guide d'installation et détails d'utilisation.