Démarrage rapide
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 400 types de secrets.
ggshield est open source sur GitHub et accessible ici.
ggshield peut s'exécuter :
- dans votre environnement local pour scanner des fichiers et dépôts locaux ou en tant que pre-commit hook.
- dans un environnement CI,
- dans un pre-receive hook, si vous avez une instance VCS auto-gérée.
Note :
ggshield utilise notre API publique via py-gitguardian pour scanner les fichiers.
Seules les métadonnées telles que l'heure de l'appel, la taille de la requête et le mode de scan sont stockées lors du lancement d'un scan avec ggshield.
Par conséquent, les incidents de secrets ne seront pas affichés dans votre tableau de bord et vos fichiers et secrets ne seront pas stockés.
Étape 1 : Installer ggshield
Prérequis
ggshield fonctionne sur macOS, Linux et Windows.
Il nécessite Python 3.8 ou plus récent (sauf pour les paquets standalone) ainsi que git.
Certaines commandes nécessitent des programmes supplémentaires :
- docker : pour scanner les images docker.
- pip : pour scanner les paquets pypi.
macOS
Homebrew
Vous pouvez installer ggshield en utilisant Homebrew :
$ brew install gitguardian/tap/ggshield
La mise à jour est gérée par Homebrew.
Paquet .pkg standalone
Vous pouvez également télécharger et installer un paquet .pkg standalone depuis la page de release 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 à jour est gérée par le gestionnaire de paquets.
Windows
Archive .zip standalone
Nous fournissons une archive .zip standalone sur la page de release de ggshield.
Décompressez l'archive sur votre disque, puis ajoutez le répertoire contenant le fichier ggshield.exe au %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.
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 à jour votre installation, exécutez :
$ pipx upgrade ggshield
Avec pip
Vous pouvez également installer ggshield depuis PyPI en utilisant 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 manière peuvent affecter votre installation ggshield. Cette méthode ne fonctionnera pas non plus si votre installation Python est déclarée comme externally managed (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 à jour votre installation, exécutez :
$ pip install --user --upgrade ggshield
Étape 2 : Authentifier avec votre workspace GitGuardian
ggshield nécessite une clé API pour authentifier la CLI avec votre workspace GitGuardian.
Il existe 2 types différents de clés API :
- Comptes de service : un type spécial de token destiné à représenter un utilisateur non humain qui doit s'authentifier et être autorisé pour des scénarios tels que le scan de secrets dans les pipelines CI ou le traitement par lot d'incidents ouverts.
- Personal Access Tokens : un token destiné à l'utilisation de l'API GitGuardian et de l'application en ligne de commande ggshield par les développeurs individuels sur leurs postes de travail locaux (par exemple, les git hooks pre-commit ou pre-push).
Option 1 : Automatiquement
Si vous voulez configurer ggshield pour une utilisation sur votre poste de travail local (par exemple pour scanner des dépôts ou dans un git hook pre-commit ou pre-push), nous recommandons d'exécuter la commande suivante :
ggshield auth login
Cela ouvrira une nouvelle fenêtre dans votre navigateur web. Suivez simplement les étapes pour vous connecter à votre workspace (ou créer un nouveau compte) et GitGuardian provisionnera automatiquement un personal access token et le stockera dans votre configuration.
Vous trouverez plus de détails dans la section de référence de la commande login.
Option 2 : Manuellement
Vous pouvez également provisionner votre clé API manuellement. C'est utile lorsque vous voulez configurer ggshield dans votre environnement CI par exemple.
Créer votre clé API
Pour créer votre clé API manuellement, veuillez suivre les étapes décrites dans la section authentification API. Une fois votre clé API prête, suivez le reste du guide sur cette page.
Sourcer votre clé API dans votre environnement
Alternativement, vous pouvez créer votre personal access token manuellement et le stocker dans la variable d'environnement GITGUARDIAN_API_KEY pour terminer la configuration.
Si vous utilisez une version on-premise de GitGuardian, vous devez également définir la variable d'environnement GITGUARDIAN_INSTANCE avec l'URL de votre instance on-premise (ex : https://dashboard.gitguardian.mycorp.local).
Étape 3 : Scanner votre premier contenu avec ggshield
Vous pouvez scanner l'un de vos dépôts à la recherche de secrets avec la commande suivante :
ggshield secret scan repo /path/to/your/repo
Vous pouvez également exécuter ggshield -h pour obtenir de l'aide sur la CLI.
Aller plus loin avec ggshield
Si vous cherchez à configurer une intégration CI/CD, jetez un œil à notre page Intégrations CI/CD.
Si vous cherchez à utiliser GitGuardian au niveau des git hooks (pre-commit, pre-receive), jetez un œil à notre page de documentation Git hooks.
