ggshield v1.53.0
Dé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 : protégez votre code avec GitGuardian
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 via 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 stockées lors des analyses 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
- Installation
- Configuration initiale
- Premiers pas
- Intégrations
- Pour en savoir plus
- Sortie
- Projets open source connexes
- Licence
Installation
Script d'installation (recommandé)
Le moyen le plus rapide d'installer ggshield.
Linux / macOS :
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
Windows (PowerShell) :
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
Ou, si vous préférez curl (inclus avec Windows 10+) :
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 l'exécution.
Consultez scripts/install/README.md pour la liste complète
des options, les autres méthodes d'installation et la désinstallation.
Les méthodes ci-dessous installent manuellement la CLI à la place.
macOS
Homebrew
Vous pouvez installer ggshield avec Homebrew :
brew install ggshield
La mise à niveau est gérée par Homebrew.
Paquet .pkg autonome
Alternativement, vous pouvez télécharger et installer un paquet .pkg autonome depuis la page des versions de ggshield.
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.
Instructions de configuration :
La mise à niveau est gérée par le gestionnaire de paquets.
Windows
Chocolatey
ggshield est disponible via le gestionnaire de paquets Chocolatey :
choco install ggshield
Installateur MSI
Téléchargez l'installateur MSI depuis la page des versions de ggshield et installez-le :
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.
Extrayez 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.
Il nécessite une version prise en charge de Python (non en fin de vie) (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 et ne supportons pas les versions ayant atteint leur fin de vie.
Avec pipx
La méthode recommandée pour installer ggshield depuis PyPI est d'utiliser pipx, qui l'installera dans un environnement isolé :
pipx install ggshield
Pour mettre à niveau votre installation, exécutez :
pipx upgrade ggshield
Avec pip
Vous pouvez également installer ggshield depuis PyPI avec pip, mais cela n'est pas recommandé car l'installation n'est pas isolée, donc d'autres applications ou paquets installés de cette manière peuvent affecter votre installation ggshield. Cette méthode ne fonctionnera pas non plus si votre installation Python est déclarée comme étant gérée en externe (par exemple lors de l'utilisation du Python système sur des systèmes d'exploitation comme Debian 12) :
pip install --user ggshield
Pour mettre à niveau votre installation, exécutez :
pip install --user --upgrade ggshield
Configuration initiale
Utilisation de 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 fourniture d'un jeton d'accès personnel et sa configuration sur la station de travail locale.
Vous pouvez en savoir plus dans la documentation de ggshield auth login.
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 finaliser 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
dockerdoit être disponible) :ggshield secret scan docker ubuntu:22.04 - dans les paquets Pypi (la commande
pipdoit être disponible) :ggshield secret scan pypi flask - et plus encore, consultez la sortie de
ggshield secret scan --helppour 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 :
ggshield config migrate
Par défaut, cette commande recherche le fichier de configuration dans le répertoire courant, alors exécutez-la depuis le répertoire contenant le fichier. Pour l'exécuter depuis n'importe où, indiquez explicitement le fichier à ggshield :
ggshield --config-path chemin/vers/.gitguardian.yaml config migrate
La version précédente du fichier est conservée sous forme de sauvegarde .old à côté de lui.
Intégrations
Vous pouvez intégrer ggshield dans votre flux CI/CD.
Pour détecter les erreurs plus tôt, utilisez ggshield comme hook Git pre-commit, pre-push ou pre-receive.
Assistants de codage IA
ggshield peut analyser les interactions entre vous et votre assistant de codage IA en temps réel, bloquant les actions contenant des secrets avant leur exécution.
Vous pouvez installer les hooks avec la commande ggshield install.
Outils pris en charge : Cursor, Claude Code, Copilot Chat, et Codex.
Pour en savoir plus
Pour plus d'informations, consultez la documentation.
Sortie
Si aucun secret n'a été trouvé, le code de sortie sera 0 :
ggshield secret scan pre-commit
Si un secret est trouvé dans votre code stagé ou dans votre CI, vous recevrez une alerte indiquant le nom du fichier où le secret a été trouvé ainsi qu'un patch donnant la position du secret dans le fichier :
ggshield secret scan pre-commit
2 incidents ont été trouvés dans le fichier 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
Licence
ggshield est sous licence MIT.