Scan de 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 involontairement exposer des secrets : un développeur peut coller des identifiants dans un prompt, ou l'agent IA peut lire un fichier ou exécuter une commande qui contient 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 demande 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
Pré-utilisation d'outil	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-utilisation d'outil	Scanne les sorties des outils après exécution	Retient la sortie du modèle lorsque l'outil le permet, sinon envoie une notification sur le bureau

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. Le hook de chaque assistant a sa propre version minimale, indiquée dans Ce que prend en charge chaque assistant.
• 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, Mistral Vibe, Kiro ou Junie CLI

Installation

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

ggshield machine setup

machine setup détecte quels agents vous avez installés et écrit la bonne configuration de hook pour chacun, en enregistrant ggshield sur les trois étapes de hook. Elle 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, junie, kiro, vibe et vscode :

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

Où les hooks sont écrits

machine setup écrit les hooks pour l'utilisateur actuel, 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
Kiro	~/.kiro/hooks/ggshield.json
Junie	~/.junie/config.json

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 ré-exécutée en toute sécurité : elle ajoute ce qui manque et laisse les entrées existantes intactes. Elle vérifie ensuite qu'elle 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.

Comportement spécifique à chaque outil

Deux outils nécessitent une remarque avant de vous y fier.

Junie est pris en charge uniquement en tant que Junie CLI : Junie au sein d'un IDE JetBrains fonctionne via ACP, qui n'invoque aucun hook.

Kiro CLI lit la configuration du hook uniquement lorsqu'il est démarré avec kiro-cli --v3. Les autres sessions prennent leurs hooks depuis la configuration de l'agent, donc le hook installé ne s'applique pas et rien ne l'indique.

Pour savoir ce que chaque outil peut faire à chaque étape, voir Ce que prend en charge chaque assistant.

Installer pour un seul projet

Pour limiter les hooks au dépôt actuel 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 ne charge les hooks du dépôt qu'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. Elle fonctionne toujours, et reste la manière d'installer les hooks git (-t pre-commit et -t pre-push), mais ggshield machine setup est désormais la méthode recommandée pour configurer les hooks IA.

attention

Mistral Vibe ne charge les hooks de projet que depuis les 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 bloquant. 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 en post-utilisation d'outil, l'action s'est déjà exécutée. Lorsque l'assistant le permet, ggshield retient la sortie et l'assistant lit le message bloquant à la place. Ailleurs, ggshield envoie une notification sur le bureau et le secret devrait être révoqué. Voir Ce que prend en charge chaque assistant.

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 inaccessible, ou que son token d'API ne peut pas être lu, il ne bloque pas l'action. Au lieu de cela, 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 garde 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 ré-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'y adhérer, voir Prévenir les fuites avec les AI Hooks.

Voir aussi

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