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 500 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

Remarque : 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 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 une version supportée de Python (non EOL) (sauf pour les paquets autonomes) et git. ggshield suit le cycle de publication de Python et ne prend pas en charge les versions ayant atteint la fin de vie (EOL).

Certaines commandes nécessitent des programmes supplémentaires :

• docker : pour scanner des images Docker.
• pip : pour scanner des paquets 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 UE ou une instance Self-Hosted, 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.

Paquet .pkg autonome

Vous pouvez également télécharger et installer un paquet .pkg autonome depuis la page des releases de ggshield.

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

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

Linux

Paquets Deb et RPM

Les paquets Deb et RPM sont disponibles sur Cloudsmith.

Instructions de configuration :

• Paquets Deb
• Paquets RPM

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

Windows

Chocolatey

ggshield est disponible via le gestionnaire de paquets Chocolatey :

choco install ggshield

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

Installeur MSI

Téléchargez l'installeur MSI depuis la page des releases 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 des releases 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 d'installer Python, mais vous devrez 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 cela n'est pas recommandé car l'installation n'est pas isolée, de sorte que d'autres applications ou paquets 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 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 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, 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 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 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 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 d'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 des 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 tout un poste de travail ou serveur (secrets qui existent 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.