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 locaux et des dépôts ou en tant que hook pre-commit.
• dans un environnement CI,
• dans un hook pre-receive, si vous avez une instance VCS auto-hébergée.

Note : ggshield utilise notre API publique via py-gitguardian pour scanner les fichiers. Seules des métadonnées telles que l'heure d'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 autonomes) et git.

Certaines commandes nécessitent des programmes supplémentaires :

• docker : pour scanner les images docker.
• pip : pour scanner les packages pypi.

Script d'installation (Recommandé)

Le moyen le plus rapide d'installer ggshield.

Le script exécute également la commande ggshield auth login, afin que l'installation et l'authentification se fassent en une seule étape.

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 (fourni 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 le workspace EU 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 comment désinstaller.

Les méthodes ci-dessous installent la CLI manuellement.

macOS

Homebrew

Vous pouvez installer ggshield en utilisant Homebrew :

brew install ggshield

La mise à jour est gérée par Homebrew.

Package autonome .pkg

Alternativement, vous pouvez télécharger et installer un package autonome .pkg depuis la page de release de ggshield.

Ce package ne nécessite pas d'installer Python, mais vous devez télécharger manuellement les nouvelles versions de ggshield.

Le package sera installé dans le répertoire /usr/bin/ggshield ou /usr/local/bin/ggshield.

Linux

Packages Deb et RPM

Les packages Deb et RPM sont disponibles sur Cloudsmith.

Instructions de configuration :

• Packages Deb
• Packages RPM

La mise à jour est gérée par le gestionnaire de packages.

Windows

Chocolatey

ggshield est disponible via le gestionnaire de packages Chocolatey :

choco install ggshield

La mise à jour est gérée par Chocolatey.

Installateur MSI

Téléchargez l'installateur MSI depuis la page de release de ggshield et installez-le :

msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi

Archive autonome .zip

Nous fournissons une archive autonome .zip 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 d'installer 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 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 packages installés de cette manière pourraient 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 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 :

• 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 des 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, les hooks git pre-commit ou pre-push).

remarque

Si vous avez installé ggshield avec le script d'installation, il vous a déjà authentifié — vous pouvez sauter cette étape.

Option 1 : Automatiquement

Si vous souhaitez configurer ggshield pour l'utiliser 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 pouvez trouver 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éez votre clé API

Pour créer votre clé API manuellement, veuillez suivre les étapes décrites dans la section d'authentification de l'API. Une fois votre clé API prête, suivez le reste du guide sur cette page.

Utilisez 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 hooks git (pre-commit, pre-receive), jetez un œil à notre page de documentation Git hooks.

Si vous souhaitez scanner un poste de travail ou un serveur entier (secrets qui vivent en dehors de Git, comme les identifiants ~/.aws, les clés SSH et les fichiers .env), jetez un œil à Endpoint Protection : Machine Scan, le plugin ggshield machine que vous pouvez configurer en deux étapes. Limité aux comptes Business.