ggshield secret scan ai-hook

Description

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

ggshield secret scan ai-hook [OPTIONS]

Lit un événement de hook depuis stdin au format JSON, le traite, et écrit une réponse sur stdout au format JSON qui bloque l'action si des secrets sont détectés.

Pour installer le hook pour votre outil de codage IA, exécutez :

ggshield install -t <your-code-assistant> -m [local|global]

Options

• --source-uuid TEXT : Identifiant de la source personnalisée dans GitGuardian. S'il est utilisé, des incidents seront créés et visibles sur le dashboard. Nécessite le scope 'scan:create-incidents'.
• --all-secrets : N'ignorer aucun secret. La raison possible d'ignorance 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 : Retourner un code de statut 0 (sans erreur), même si des incidents sont trouvés. Un code de statut d'erreur sera néanmoins retourné pour d'autres erreurs, telles que des erreurs de connexion. Cette option peut également être définie via 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 codage IA (Cursor, Claude Code, VS Code avec GitHub Copilot) lorsque ggshield est installé comme hook. Elle n'est pas destinée à être appelée manuellement — utilisez ggshield install avec le flag -t pour configurer les hooks.

Codes de sortie

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

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

• 0 : Aucun secret trouvé.
• 1 : Une erreur est survenue durant 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 API stocké ne peut pas être lu — le hook ne bloque pas l'action. Il autorise l'interaction à se poursuivre et fait apparaître un avertissement via l'outil de codage 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 exécuter ggshield auth login).

Ce comportement fail-open garde votre outil de codage IA utilisable lorsque ggshield est mal configuré, au prix de ne pas détecter les secrets tant que le problème n'est pas résolu.

Voir aussi

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