Scan des secrets pour les outils de codage IA

Les développeurs s'appuient de plus en plus sur des outils de codage IA comme Cursor, Claude Code et Codex pour écrire et modifier du code. Ces outils peuvent exposer des secrets par inadvertance : un développeur peut coller des identifiants dans un prompt, ou l'agent IA peut lire un fichier ou exécuter une commande contenant des clés d'API ou des tokens. Une fois qu'un secret atteint le modèle IA, il peut être journalisé, mis en cache ou envoyé à des services tiers.

ggshield s'intègre aux outils de codage IA via leurs systèmes de hooks pour scanner les interactions en temps réel. Lorsqu'un secret est détecté, ggshield bloque l'action avant qu'elle n'atteigne le modèle et indique au développeur de supprimer le secret.

Fonctionnement

Les outils de codage IA prennent en charge les hooks : des commandes personnalisées qui s'exécutent à des moments précis d'une interaction IA. ggshield s'enregistre comme un hook et scanne le contenu à trois étapes :

Étape	Ce qu'elle fait	Comportement
Soumission du prompt	Scanne le prompt de l'utilisateur avant qu'il ne soit envoyé au modèle IA	Bloque le prompt si des secrets sont trouvés
Pre-tool use	Scanne les commandes, les lectures de fichiers et les appels MCP avant que l'IA ne les exécute	Bloque l'action si des secrets sont trouvés
Post-tool use	Scanne les sorties des outils après leur exécution	Envoie une notification bureau si des secrets sont trouvés

ggshield utilise le même moteur de détection que toutes les autres commandes de scan, couvrant plus de 600 types de secrets.

Prérequis

• ggshield version 1.53.0 ou ultérieure pour ggshield machine setup (les hooks eux-mêmes fonctionnent à partir de la 1.49.0, de la 1.51.0 pour Codex et de la 1.54.0 pour Mistral Vibe)
• Une clé d'API GitGuardian (voir Démarrer)
• L'un des outils de codage IA pris en charge : Cursor, Claude Code, Codex, Copilot CLI, VS Code ou Mistral Vibe

Installation

Une seule commande configure le hook pour chaque outil de codage IA de votre machine :

ggshield machine setup

machine setup détecte les agents que vous avez installés et écrit la configuration de hook correcte pour chacun d'eux, en enregistrant ggshield sur les trois étapes de hook. Il ignore les agents qui ne sont pas présents, donc rien n'est écrit pour les outils que vous n'utilisez pas.

La commande installe également les hooks git pre-commit et pre-push et plante un honeytoken. Pour configurer uniquement les hooks IA :

ggshield machine setup --no-git-hooks --no-honeytokens

Pour cibler des assistants spécifiques, utilisez --agent ou --exclude-agent, qui acceptent claude-code, codex, copilot, cursor, vibe et vscode :

ggshield machine setup --agent cursor --agent claude-code

Où les hooks sont écrits

machine setup écrit les hooks pour l'utilisateur courant, dans les fichiers suivants :

Outil	Configuration du hook
Cursor	~/.cursor/hooks.json
Claude Code	~/.claude/settings.json
Codex	~/.codex/hooks.json
Copilot CLI et VS Code	~/.copilot/hooks/hooks.json
Mistral Vibe	~/.vibe/hooks.toml

Ce sont les propres fichiers de hooks de Copilot plutôt que les paramètres d'un éditeur, donc une seule installation couvre Copilot partout où il s'exécute : le Copilot CLI dans un terminal, VS Code, et tout autre IDE dont l'extension Copilot exécute le Copilot CLI.

astuce

ggshield fusionne ses hooks dans une configuration existante sans toucher aux autres hooks, donc machine setup peut être relancé sans risque : il ajoute ce qui manque et laisse les entrées existantes intactes. Il vérifie ensuite qu'il peut s'authentifier auprès de GitGuardian, indique si le hook est prêt à scanner, et vous explique comment le corriger si ce n'est pas le cas. Sur macOS, cela déclenche également l'invite d'autorisation du trousseau système pendant que vous pouvez encore l'approuver de manière interactive.

Installer pour un seul projet

Pour limiter les hooks au dépôt courant plutôt qu'à l'ensemble de votre compte utilisateur, installez par outil avec le mode local :

ggshield install -t cursor -m local

Utilisez --force pour écraser les propres hooks de ggshield, par exemple s'ils ont été personnalisés et que vous souhaitez les réinitialiser.

Pour GitHub Copilot, une installation local écrit dans .github/hooks/hooks.json dans le dépôt. Préférez l'installation globale : Copilot charge les hooks du dépôt uniquement après que vous ayez confirmé la confiance du dossier, et les ignore en mode prompt (copilot -p) sauf si vous l'activez via une variable d'environnement.

remarque

ggshield install -t <assistant> est déprécié pour les installations globales à partir de ggshield 1.53.0. Cela fonctionne toujours, et cela reste la manière d'installer les hooks git (-t pre-commit et -t pre-push), mais ggshield machine setup est désormais la manière recommandée de configurer les hooks IA.

attention

Mistral Vibe ne charge les hooks de projet qu'à partir des dossiers que vous avez marqués comme approuvés, donc une installation local y prend effet une fois le dossier approuvé.

Ce que voit le développeur

Lorsque ggshield détecte un secret, l'outil de codage IA affiche un message de blocage. Par exemple, dans Cursor :

Detected 1 secret

• Google API Key (valid) : AIzaSyC****************-*********d5oii7Y

Please remove the secrets from the content before proceeding.

Le prompt ou l'action est bloqué jusqu'à ce que le développeur supprime le secret et réessaie.

Pour les détections post-tool-use (où l'action a déjà été exécutée), ggshield envoie une notification bureau alertant le développeur.

Lorsque ggshield ne peut pas scanner

Si ggshield ne peut pas scanner une interaction — par exemple parce qu'il n'est pas authentifié, que l'API GitGuardian est injoignable ou que son token d'API ne peut pas être lu — il ne bloque pas l'action. À la place, il autorise l'interaction et affiche un avertissement dans l'outil de codage IA indiquant que le contenu n'a pas été scanné à la recherche de secrets, ainsi que la manière de corriger cela.

Cette conception fail-open maintient votre outil de codage IA utilisable lorsque ggshield est mal configuré. Pour rétablir le scan, suivez la remédiation indiquée dans l'avertissement (généralement une nouvelle authentification avec ggshield auth login), puis confirmez avec ggshield machine doctor, qui indique si le hook de chaque agent est installé et si votre token peut atteindre GitGuardian.

Gérer les faux positifs

Si ggshield bloque une action sur un secret qui est un faux positif connu, vous pouvez demander à ggshield de l'ignorer :

ggshield secret ignore --last-found

Cela ajoute le secret détecté à votre liste d'ignorés .gitguardian.yaml. Les scans futurs (y compris les scans de hooks IA) l'ignoreront.

Désinstallation

Pour supprimer les hooks, supprimez les entrées ggshield du fichier de configuration de l'outil, en utilisant les chemins listés dans Où les hooks sont écrits.

Déployer à l'échelle d'une flotte

Les commandes ci-dessus configurent les hooks sur une seule machine. Pour les déployer sur chaque poste de travail de développeur via votre MDM, sans demander à chaque développeur d'activer l'option, consultez Prévenir les fuites avec les AI Hooks.

Voir aussi

• Référence de ggshield secret scan ai-hook : référence CLI pour la commande de scan sous-jacente
• Démarrer avec ggshield : installation et authentification