Getting started

ggshield is a CLI application that runs in your local environment or in a CI environment to help you detect more than 350+ types of secrets, as well as other potential security vulnerabilities or policy breaks affecting your codebase.

ggshield is open source on GitHub and accessible here .

ggshield can run:

• in your local environment to scan local files and repositories or as a pre-commit hook.
• in a CI environment ,
• in a pre-receive hook , if you have a self-managed VCS instance

Note :
ggshield uses our public API through py-gitguardian to scan files. Only metadata such as call time, request size and scan mode is stored when launching a scan with ggshield, therefore secrets and policy breaks incidents will not be displayed on your dashboard and your files and secrets won't be stored .

Step 1: Install ggshield ​

Requirements ​

ggshield works on macOS, Linux and Windows.

It requires Python 3.8 and newer (except for standalone packages) and git.

Some commands require additional programs:

• docker: to scan docker images.
• pip: to scan pypi packages.

macOS ​

Homebrew ​

You can install ggshield using Homebrew:

$ brew install gitguardian/tap/ggshield

Upgrading is handled by Homebrew.

Standalone .pkg package ​

Alternatively, you can download and install a standalone .pkg package from ggshield release page .

This package does not require installing Python, but you have to manually download new versions.

Linux ​

Deb and RPM packages ​

Deb and RPM packages are available on Cloudsmith .

Setup instructions:

• Deb packages
• RPM packages

Upgrading is handled by the package manager.

Windows ​

Standalone .zip archive ​

We provide a standalone .zip archive on ggshield release page .

Unpack the archive on your disk, then add the directory containing the ggshield.exe file to %PATH% .

This archive does not require installing Python, but you have to manually download new versions.

All operating systems ​

ggshield can be installed on all supported operating systems via its PyPI package .

Using pipx ​

The recommended way to install ggshield from PyPI is to use pipx , which will install it in an isolated environment:

$ pipx install ggshield

To upgrade your installation, run:

$ pipx upgrade ggshield

Using pip ​

You can also install ggshield from PyPI using pip, but this is not recommended because the installation is not isolated, so other applications or packages installed this way may affect your ggshield installation. This method will also not work if your Python installation is declared as externally managed (for example when using the system Python on operating systems like Debian 12):

$ pip install --user ggshield

To upgrade your installation, run:

$ pip install --user --upgrade ggshield

Step 2: Authenticate with your GitGuardian workspace ​

ggshield requires an API key to authenticate the CLI with your GitGuardian workspace.