Scan de secrets pour les outils de coding IA

Les développeurs s'appuient de plus en plus sur des outils de coding IA comme Cursor, Claude Code et Codex pour écrire et modifier du code. Ces outils peuvent exposer involontairement des secrets : un développeur pourrait coller des identifiants dans un prompt, ou l'agent IA pourrait lire un fichier ou exécuter une commande contenant des clés 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 coding 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 coding IA prennent en charge les hooks : des commandes personnalisées qui s'exécutent à des moments précis lors d'une interaction avec l'IA. ggshield s'enregistre comme un hook et scanne le contenu à trois étapes :

Étape	Ce qu'il 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 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 500 types de secrets.

Prérequis

• ggshield version 1.49.0 ou ultérieure (1.51.0 ou ultérieure pour Codex)
• Une clé API GitGuardian (voir Démarrer)
• L'un des outils de coding 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 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 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 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 globaux VS Code. Pour installer uniquement pour le projet actuel :

ggshield install -t copilot -m local

vscode est accepté comme alias pour 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 hooks propres à 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 signale si le hook est prêt à scanner. Si l'authentification échoue, il vous indique comment y remédier (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 coding 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 inaccessible ou que son token 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 coding IA indiquant que le contenu n'a pas été scanné pour détecter des secrets, ainsi que la manière d'y remédier.

Cette conception fail-open maintient votre outil de coding 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 indiquer à 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 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 ggshield secret scan ai-hook : référence CLI pour la commande de scan sous-jacente
• Démarrer avec ggshield : installation et authentification