ggshield secret scan ai-hook

Description

Scan les interactions avec les 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 renvoie 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é, les incidents seront créés et visibles sur le dashboard. Nécessite le scope 'scan:create-incidents'.
• --all-secrets : N'ignore aucun secret. La raison d'ignorance éventuelle est également affichée.
• --instance URL : URL de l'instance à utiliser.
• --with-incident-details : Affiche tous les détails concernant l'incident du dashboard s'il en existe un (formats JSON et SARIF uniquement). Nécessite le scope 'incidents:read'.
• -b, --banlist-detector DETECTOR : Exclut les résultats d'un détecteur.
• --ignore-known-secrets : Ignore les secrets déjà connus par le dashboard GitGuardian.
• --exclude PATTERNS : Ne scanne pas les chemins qui correspondent aux motifs de type glob spécifiés.
• --exit-zero : Renvoie 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 les erreurs de connexion. Cette option peut également être définie avec la variable d'environnement GITGUARDIAN_EXIT_ZERO.
• --show-secrets : Affiche les secrets en clair au lieu de les masquer.
• -o, --output PATH : Redirige 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, 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 sur stdout, que l'outil de codage IA utilise pour afficher un retour dans son interface.

Si ggshield ne parvient pas à identifier l'outil de codage IA appelant, il se rabat sur des codes de sortie standard :

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

Lorsque le scan ne peut pas s'exécuter

Si ggshield ne parvient pas à scanner une interaction — par exemple parce qu'il n'est pas authentifié, que l'API GitGuardian est injoignable, 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 remonter un avertissement via l'outil de codage IA indiquant que le contenu n'a pas été scanné à la recherche de secrets, accompagné de la marche à suivre pour résoudre le problème (par exemple en exécutant ggshield auth login).

Ce comportement fail-open permet de garder 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.