Démarrer
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 hook pre-commit.
- dans un environnement CI,
- dans un hook pre-receive, si vous disposez d'une instance VCS auto-gérée
Note :
ggshield utilise notre API publique via py-gitguardian pour scanner les fichiers.
Seules des 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 sur votre dashboard 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 packages standalone) et git.
Certaines commandes nécessitent des programmes supplémentaires :
- docker : pour scanner les images docker.
- pip : pour scanner les packages pypi.
macOS
Homebrew
Vous pouvez installer ggshield à l'aide de Homebrew :
brew install ggshield
La mise à jour est gérée par Homebrew.
Package .pkg standalone
Alternativement, vous pouvez télécharger et installer un package .pkg standalone depuis la page de release de ggshield.
Ce package ne nécessite pas l'installation de Python, mais vous devez télécharger manuellement les nouvelles versions.
Linux
Packages Deb et RPM
Des packages Deb et RPM sont disponibles sur Cloudsmith.
Instructions de configuration :
La mise à jour est gérée par le gestionnaire de packages.
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 à %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 package PyPI.
Avec pipx
La manière recommandée d'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 à l'aide de pip, mais cela n'est pas recommandé car l'installation n'est pas isolée, et d'autres applications ou packages installés de cette manière peuvent affecter votre installation de ggshield. Cette méthode ne fonctionnera pas non plus si votre installation de Python est déclarée comme gérée en externe (par exemple lorsque vous utilisez le 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 : S'authentifier avec votre workspace GitGuardian
ggshield nécessite une clé API pour authentifier le CLI avec votre workspace GitGuardian.
Il existe 2 types différents de clés API :
- Service Accounts : un type particulier 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 lots 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 hooks git pre-commit ou pre-push).
Option 1 : Automatiquement
Si vous souhaitez configurer ggshield pour une utilisation sur votre poste de travail local (par exemple pour scanner des dépôts ou dans un hook git pre-commit ou pre-push), nous vous 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. Cela est utile lorsque vous souhaitez 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 de l'API. Une fois votre clé API prête, suivez la suite du guide sur cette page.
Charger 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 finaliser 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 (par exemple : 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 aussi exécuter ggshield -h pour obtenir de l'aide sur le CLI.
Aller plus loin avec ggshield
Si vous souhaitez configurer une intégration CI/CD, consultez notre page Intégrations CI/CD.
Si vous souhaitez utiliser GitGuardian au niveau des hooks git (pre-commit, pre-receive), consultez notre page de documentation des hooks Git.
