gitguardian/ggshieldDétectez et validez plus de 500 types de secrets codés en dur avec des vérifications avancées. Utilisez-le comme hook pre-commit, GitHub Action ou CLI pour une détection proactive des secrets et la sécurité.
# [ggshield](https://github.com/GitGuardian/ggshield) : protégez votre code avec GitGuardian
[](https://pypi.org/project/ggshield/)
[](https://hub.docker.com/r/gitguardian/ggshield)
[](LICENSE)
[](https://github.com/GitGuardian/ggshield/stargazers)
[](https://github.com/GitGuardian/ggshield/actions)
[](https://codecov.io/gh/GitGuardian/ggshield/)
> [!IMPORTANT]
> **macOS : la mise à niveau vers la version 1.54.0 déclenche une invite Keychain pour `ggshield-py`**, un second binaire qui lit désormais votre jeton enregistré dans le cadre de nos améliorations de performance. Cliquez sur **Toujours autoriser** ; il ne le demandera plus.
`ggshield` est une application CLI qui s'exécute dans votre environnement local ou dans un environnement CI pour vous aider à détecter plus de 500 types de secrets.
`ggshield` utilise notre [API publique](https://api.gitguardian.com/docs) via [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) pour analyser et détecter les vulnérabilités potentielles dans les fichiers et autres contenus textuels.
Seules les métadonnées telles que l'heure d'appel, la taille de la requête et le mode d'analyse sont conservées lors des analyses effectuées avec `ggshield`. Par conséquent, les secrets ne seront pas affichés sur votre tableau de bord et **vos fichiers et secrets ne seront pas stockés**.
# Table des matières
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Installation](#installation)
- [Script d'installation (recommandé)](#script-dinstallation-recommandé)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Paquet .pkg autonome](#paquet-pkg-autonome)
- [Linux](#linux)
- [Paquets Deb et RPM](#paquets-deb-et-rpm)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [Programme d'installation MSI](#programme-dinstallation-msi)
- [Archive .zip autonome](#archive-zip-autonome)
- [Tous les systèmes d'exploitation](#tous-les-systèmes-dexploitation)
- [Avec pipx](#avec-pipx)
- [Avec pip](#avec-pip)
- [Configuration initiale](#configuration-initiale)
- [Avec `ggshield auth login`](#avec-ggshield-auth-login)
- [Configuration manuelle](#configuration-manuelle)
- [Premiers pas](#premiers-pas)
- [Secrets](#secrets)
- [Migration d'un fichier de configuration hérité](#migration-dun-fichier-de-configuration-hérité)
- [Intégrations](#intégrations)
- [Assistants de codage IA](#assistants-de-codage-ia)
- [En savoir plus](#en-savoir-plus)
- [Sortie](#sortie)
- [Projets open source connexes](#projets-open-source-connexes)
- [Licence](#licence)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Installation
<!--
Any change made in this section must be replicated in the "Step 1: Install
ggshield" section of the "Getting started" page of ggshield public
documentation.
-->
## Script d'installation (recommandé)
La façon la plus rapide d'installer `ggshield`.
Linux / macOS :
```shell
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
```
Windows (PowerShell) :
```powershell
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
```
Ou, si vous préférez `curl` (fourni avec Windows 10+) :
```powershell
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
```
Le script accepte des options telles que `--instance` et `--plugin` (installer un
plugin). Pour l'espace de travail UE ou une instance auto-hébergée, définissez la
variable d'environnement `GITGUARDIAN_INSTANCE` (ou passez `--instance <URL>`)
avant de l'exécuter.
Consultez [`scripts/install/README.md`](https://github.com/gitguardian/ggshield/blob/main/scripts/install/README.md) pour la liste complète
des options, les autres méthodes d'installation et la procédure de désinstallation.
Les méthodes ci-dessous installent la CLI manuellement à la place.
## macOS
### Homebrew
Vous pouvez installer `ggshield` avec Homebrew :
```shell
brew install ggshield
```
La mise à niveau est gérée par Homebrew.
### Paquet .pkg autonome
Vous pouvez également télécharger et installer un paquet .pkg autonome depuis la [page des versions de `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Ce paquet _ne nécessite pas_ l'installation de Python, mais vous devez télécharger manuellement les nouvelles versions.
## Linux
### Paquets Deb et RPM
Les paquets Deb et RPM sont disponibles sur [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/).
Instructions d'installation :
- [Paquets Deb](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [Paquets RPM](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)
La mise à niveau est gérée par le gestionnaire de paquets.
## Windows
### Chocolatey
`ggshield` est disponible via le [gestionnaire de paquets Chocolatey](https://chocolatey.org/packages/ggshield) :
```shell
choco install ggshield
```
### Programme d'installation MSI
Téléchargez le programme d'installation MSI depuis la [page des versions de `ggshield`](https://github.com/GitGuardian/ggshield/releases) et installez-le :
```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```
### Archive .zip autonome
Nous fournissons une archive .zip autonome sur la [page des versions de `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Décompressez l'archive sur votre disque, puis ajoutez le répertoire contenant le fichier `ggshield.exe` à `%PATH%`.
Cette archive _ne nécessite pas_ l'installation de Python, mais vous devez télécharger manuellement les nouvelles versions.
## Tous les systèmes d'exploitation
`ggshield` peut être installé sur tous les systèmes d'exploitation pris en charge via son [paquet PyPI](https://pypi.org/project/ggshield).
Il nécessite **une version prise en charge de Python (non EOL)** (sauf pour les paquets autonomes) et git.
Si vous n'utilisez pas nos versions packagées de `ggshield`, veuillez noter que nous suivons le [cycle de publication de Python](https://devguide.python.org/versions/) et ne prenons pas en charge les versions ayant atteint leur fin de vie (EOL).
### Avec pipx
La méthode recommandée pour installer `ggshield` depuis PyPI est d'utiliser [pipx](https://pypa.github.io/pipx/), qui l'installera dans un environnement isolé :
```shell
pipx install ggshield
```
Pour mettre à niveau votre installation, exécutez :
```shell
pipx upgrade ggshield
```
### Avec pip
Vous pouvez également installer `ggshield` depuis PyPI avec pip, mais ce n'est pas recommandé car l'installation n'est pas isolée, donc d'autres applications ou paquets installés de cette façon peuvent affecter votre installation de `ggshield`. Cette méthode ne fonctionnera pas non plus si votre installation Python est déclarée comme gérée en externe (par exemple lors de l'utilisation du Python système sur des systèmes d'exploitation comme Debian 12) :
```shell
pip install --user ggshield
```
Pour mettre à niveau votre installation, exécutez :
```shell
pip install --user --upgrade ggshield
```
# Configuration initiale
## Avec `ggshield auth login`
Pour utiliser `ggshield`, vous devez vous authentifier auprès des serveurs GitGuardian. Pour ce faire, utilisez la commande `ggshield auth login`. Cette commande automatise la création d'un jeton d'accès personnel et sa configuration sur le poste de travail local.
Vous pouvez en savoir plus dans la [documentation de `ggshield auth login`](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login).
Après l'authentification, exécutez `ggshield machine setup` pour configurer les hooks IA et git,
planter des honeytokens et enregistrer la machine sur la page Endpoints avant sa première
analyse. L'enregistrement inclut l'utilisateur actuel, ou tous les utilisateurs cibles des honeytokens lorsque
exécuté en tant que root. Il est effectué au mieux, prend au maximum cinq secondes et n'affecte pas
le code de sortie de la commande.
Les analyses de `ggshield secret scan pre-commit`, `pre-push` et `ai-hook` envoient également
le nom d'hôte de la machine, à partir duquel GitGuardian enregistre les utilisateurs de ces hooks.
Les autres commandes d'analyse ne l'envoient pas, pas plus que le hook IA natif que les installations autonomes et
spécifiques à la plateforme via `pip` exécutent.
En CI, ggshield n'enregistre pas la machine et n'envoie pas le nom d'hôte. Pour désactiver les deux
ailleurs, définissez `endpoint_registration: false` dans `.gitguardian.yaml`, ou définissez
`GGSHIELD_NO_ENDPOINT_REGISTRATION` sur une valeur non vide.
## Configuration manuelle
Vous pouvez également créer votre jeton d'accès personnel manuellement et le stocker dans la variable d'environnement `GITGUARDIAN_API_KEY` pour terminer la configuration.
# Premiers pas
## Secrets
Vous pouvez maintenant utiliser `ggshield` pour rechercher des secrets :
- dans les fichiers : `ggshield secret scan path -r .`
- dans les dépôts : `ggshield secret scan repo .`
- dans les images Docker (la commande `docker` doit être disponible) : `ggshield secret scan docker ubuntu:22.04`
- dans les paquets Pypi (la commande `pip` doit être disponible) : `ggshield secret scan pypi flask`
- et plus encore, consultez la sortie de `ggshield secret scan --help` pour plus de détails.
## Migration d'un fichier de configuration hérité
Si `ggshield` signale que votre fichier de configuration `.gitguardian.yaml` (ou `.gitguardian.yml`) utilise un format obsolète, migrez-le vers la dernière version avec :
```shell
ggshield config migrate
```
Par défaut, cette commande recherche le fichier de configuration dans le répertoire courant, donc exécutez-la depuis le répertoire contenant le fichier. Pour l'exécuter depuis n'importe où, indiquez explicitement le fichier à `ggshield` :
```shell
ggshield --config-path path/to/.gitguardian.yaml config migrate
```
La version précédente du fichier est conservée sous forme de sauvegarde `.old` à côté de celui-ci.
# Intégrations
Vous pouvez intégrer `ggshield` dans votre [workflow CI/CD](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow).
Pour détecter les erreurs plus tôt, utilisez `ggshield` comme [hook Git pre-commit, pre-push ou pre-receive](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).
## Assistants de codage IA
`ggshield` peut [analyser les interactions](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools) entre vous et votre assistant de codage IA en temps réel, en bloquant les actions contenant des secrets avant qu'elles ne soient exécutées.
Vous pouvez installer les hooks avec la commande `ggshield install`.
Outils pris en charge : **Cursor**, **Claude Code**, **Copilot Chat**, **Codex**, et
**Mistral Vibe 2.21+**.
# En savoir plus
Pour plus d'informations, consultez [la documentation](https://docs.gitguardian.com/ggshield-docs/getting-started)
# Sortie
Si aucun secret n'a été trouvé, le code de sortie sera 0 :
```bash
ggshield secret scan pre-commit
```
Si un secret est trouvé dans votre code indexé ou dans votre CI, vous recevrez une alerte vous indiquant le nom du fichier où le secret a été trouvé et un patch vous donnant la position du secret dans le fichier :
```shell
ggshield secret scan pre-commit
```
```
2 incidents have been found in file production.rb
11 | config.paperclip_defaults = {
12 | :s3_credentials => {
13 | :bucket => "XXX",
14 | :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
|_____AWS Keys_____|
15 | :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|_______________AWS Keys_______________|
16 | }
17 | }
```
Les lignes trop longues sont tronquées pour correspondre à la taille du terminal, sauf si le mode verbeux est utilisé (`-v` ou `--verbose`).
# Projets open source connexes
- [truffleHog](https://github.com/dxa4481/truffleHog)
- [gitleaks](https://github.com/zricethezav/gitleaks)
- [gitrob](https://github.com/michenriksen/gitrob)
- [git-hound](https://github.com/tillson/git-hound)
- [AWS git-secrets](https://github.com/awslabs/git-secrets)
- [detect-secrets](https://github.com/Yelp/detect-secrets)
# Licence
`ggshield` est sous licence MIT.