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 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 enregistré dans les logs, 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 avec l'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, lectures de fichiers et 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 exécution	Envoie une notification sur le 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.49.0 ou ultérieure (1.51.0 ou ultérieure pour Codex)
• Une clé d'API GitGuardian (voir Démarrer)
• L'un des outils de codage IA pris en charge : Cursor, Claude Code, Codex, ou VS Code avec GitHub Copilot

Installation

ggshield fournit un installateur en une seule commande qui écrit la configuration de hook correcte pour chaque outil.

Cursor

ggshield install -t cursor -m global

Cela écrit les hooks dans votre fichier global .cursor/hooks.json. Pour l'installer uniquement pour le projet actuel :

ggshield install -t cursor -m local

La configuration générée enregistre ggshield sur les trois étapes de hook (soumission du prompt, pre-tool use et post-tool use).

Claude Code

ggshield install -t claude-code -m global

Cela écrit les hooks dans votre fichier global .claude/settings.json. Pour l'installer uniquement pour le projet actuel :

ggshield install -t claude-code -m local

La configuration générée enregistre ggshield sur les trois étapes de hook (soumission du prompt, pre-tool use et post-tool use).

Codex

ggshield install -t codex -m global

Cela écrit les hooks dans votre fichier global ~/.codex/hooks.json. Pour l'installer uniquement pour le projet actuel :

ggshield install -t codex -m local

La configuration générée enregistre ggshield sur les trois étapes de hook (soumission du prompt, pre-tool use et post-tool use).

VS Code avec GitHub Copilot

ggshield install -t copilot -m global

Cela écrit les hooks dans vos paramètres VS Code globaux. Pour l'installer uniquement pour le projet actuel :

ggshield install -t copilot -m local

vscode est accepté comme alias de copilot (ggshield install -t vscode …).

La configuration générée enregistre ggshield sur les trois étapes de hook (soumission du prompt, pre-tool use et post-tool use).

astuce

Si vous avez déjà des configurations de hook pour l'outil cible, ggshield fusionne ses hooks dans le fichier existant sans toucher aux autres hooks. Utilisez --force pour écraser les propres hooks de ggshield (par exemple, s'ils ont été personnalisés et que vous souhaitez les réinitialiser).

remarque

Après l'installation des hooks, ggshield vérifie qu'il peut s'authentifier auprès de GitGuardian et indique si le hook est prêt à scanner. Si l'authentification échoue, il vous indique comment la corriger (par exemple, en exécutant ggshield auth login). 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.

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 sur le bureau pour alerter 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 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 le problème.

Cette conception « fail-open » permet de garder votre outil de codage IA utilisable lorsque ggshield est mal configuré. Pour restaurer le scan, suivez la remédiation indiquée dans l'avertissement (généralement en vous ré-authentifiant avec ggshield auth login), puis confirmez avec ggshield api-status.

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'exclusion .gitguardian.yaml. Les scans futurs (y compris les scans de hook IA) l'ignoreront.

Désinstallation

Pour supprimer les hooks, supprimez les entrées ggshield du fichier de configuration de l'outil :

• Cursor : .cursor/hooks.json
• Claude Code : .claude/settings.json
• Codex : .codex/hooks.json
• VS Code avec GitHub Copilot : paramètres VS Code

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