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 600 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 de pre-commit.
• dans un environnement CI,
• dans un hook de 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 sous macOS, Linux et Windows.

Il nécessite une version supportée de Python (non EOL) (sauf pour les packages autonomes) et git. ggshield suit le cycle de publication de Python et ne prend pas en charge les versions ayant atteint leur fin de vie (EOL).

Certaines commandes nécessitent des programmes supplémentaires :

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

Script d'installation (recommandé)

La façon la plus rapide d'installer ggshield.

Le script exécute également la commande ggshield auth login, de sorte que l'installation et l'authentification se font 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 à la place.

macOS

Homebrew

Vous pouvez installer ggshield avec Homebrew :

brew install ggshield

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

Package .pkg autonome

Vous pouvez également télécharger et installer un package .pkg autonome 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 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 .zip autonome

Nous fournissons une archive .zip autonome 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 supportés via son package PyPI.

Avec pipx

La façon 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 avec pip, mais ce n'est pas recommandé car l'installation n'est pas isolée, de sorte que 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 des 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 de pre-commit ou pre-push).

remarque

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

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 de 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. Ceci 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 le reste du guide sur cette page.

Sourcer 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 (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 é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 des hooks Git.

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