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 comme hook pre-commit.
- dans un environnement CI,
- dans un hook pre-receive, si vous disposez d'une instance VCS auto-gérée
Remarque :
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 en utilisant Homebrew :
$ brew install ggshield
La mise à jour est gérée par Homebrew.
Package .pkg standalone
Vous pouvez également 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
Les 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 supportés via son package PyPI.
Utilisation de 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
Utilisation de pip
Vous pouvez également installer ggshield depuis PyPI en utilisant pip, mais cela n'est pas recommandé car l'installation n'est pas isolée, donc 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 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) :
$ pip install --user ggshield
Pour mettre à jour votre installation, exécutez :
$ pip install --user --upgrade ggshield
Étape 2 : S'authentifier auprès de votre workspace GitGuardian
ggshield nécessite une clé API pour authentifier la CLI auprès de votre workspace GitGuardian.
Il existe 2 types différents de clés API :
- Service Accounts : 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 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 des développeurs individuels sur leurs postes de travail locaux (par exemple, 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 sur l'authentification API. Une fois votre clé API prête, suivez le reste du guide sur cette page.
Charger votre clé API dans votre environnement
Vous pouvez également 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, consultez notre page Intégrations CI/CD.
Si vous cherchez à utiliser GitGuardian au niveau des hooks git (pre-commit, pre-receive), consultez notre page de documentation sur les hooks Git.
