ggshield: protect your code with GitGuardian
ggshield is a CLI application that runs in your local environment or in a CI environment to help you detect more than 500+ types of secrets.
ggshield uses our public API through py-gitguardian to scan and detect potential vulnerabilities in files and other text content.
Only metadata such as call time, request size and scan mode is stored from scans using ggshield, therefore secrets will not be displayed on your dashboard and your files and secrets won't be stored.
Table of Contents
- Installation
- Initial setup
- Getting started
- Integrations
- Learn more
- Output
- Related open source projects
- License
Installation
Install script (Recommended)
The quickest way to install ggshield.
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
Or, if you prefer curl (bundled with Windows 10+):
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
The script accepts options such as --instance and --plugin (install a
plugin). For the EU workspace or a self-hosted instance, set the
GITGUARDIAN_INSTANCE environment variable (or pass --instance <URL>)
before running.
See scripts/install/README.md for the full list
of options, the other install methods, and how to uninstall.
The methods below install the CLI manually instead.
macOS
Homebrew
You can install ggshield using Homebrew:
brew install 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:
Upgrading is handled by the package manager.
Windows
Chocolatey
ggshield is available via the Chocolatey package manager:
choco install ggshield
MSI installer
Download the MSI installer from the ggshield release page and install it:
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
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.
It requires a supported version of Python (not EOL) (except for standalone packages) and git.
If you don't use our packaged versions of ggshield, please be aware that we follow the Python release cycle and do not support versions that have reached EOL.
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
Initial setup
Using ggshield auth login
To use ggshield you need to authenticate against GitGuardian servers. To do so, use the ggshield auth login command. This command automates the provisioning of a personal access token and its configuration on the local workstation.
You can learn more about it from ggshield auth login documentation.
Manual setup
You can also create your personal access token manually and store it in the GITGUARDIAN_API_KEY environment variable to complete the setup.
Getting started
Secrets
You can now use ggshield to search for secrets:
- in files:
ggshield secret scan path -r . - in repositories:
ggshield secret scan repo . - in Docker images (
dockercommand must be available):ggshield secret scan docker ubuntu:22.04 - in Pypi packages (
pipcommand must be available):ggshield secret scan pypi flask - and more, have a look at
ggshield secret scan --helpoutput for details.
Migrating a legacy configuration file
If ggshield reports that your .gitguardian.yaml (or .gitguardian.yml) config file uses a deprecated format, migrate it to the latest version with:
ggshield config migrate
By default, this looks for the configuration file in the current directory, so run it from the directory containing the file. To run it from anywhere, point ggshield to the file explicitly:
ggshield --config-path path/to/.gitguardian.yaml config migrate
The previous version of the file is kept as a .old backup next to it.
Integrations
You can integrate ggshield in your CI/CD workflow.
To catch errors earlier, use ggshield as a pre-commit, pre-push or pre-receive Git hook.
AI coding assistants
ggshield can scan interactions between you and your AI coding assistant in real time, blocking actions that contain secrets before they are executed.
You can install the hooks with the ggshield install command.
Supported tools: Cursor, Claude Code, Copilot Chat, Codex, and Mistral Vibe 2.21+.
Learn more
For more information, have a look at the documentation
Output
If no secrets have been found, the exit code will be 0:
ggshield secret scan pre-commit
If a secret is found in your staged code or in your CI, you will have an alert giving you the filename where the secret has been found and a patch giving you the position of the secret in the file:
ggshield secret scan pre-commit
2 incidents have been found in file production.rb
11 | config.paperclip_defaults = {
12 | :s3_credentials => {
13 | :bucket => "XXX",
14 | :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
|_____AWS Keys_____|
15 | :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|_______________AWS Keys_______________|
16 | }
17 | }
Lines that are too long are truncated to match the size of the terminal, unless the verbose mode is used (-v or --verbose).
Related open source projects
License
ggshield is MIT licensed.
1 maintainer
Release files for ggshield 1.54.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ggshield-1.54.0.tar.gz | 1.0 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| ggshield-1.54.0-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| ggshield-1.54.0-py3-none-musllinux_1_2_x86_64.whl | Python 3 | none | Linux musl 1.2+ x86-64 | Details |
| ggshield-1.54.0-py3-none-musllinux_1_2_aarch64.whl | Python 3 | none | Linux musl 1.2+ ARM64 | Details |
| ggshield-1.54.0-py3-none-manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| ggshield-1.54.0-py3-none-manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| ggshield-1.54.0-py3-none-macosx_11_0_universal2.whl | Python 3 | none | macOS 11.0+ universal2 (ARM64, x86-64) | Details |
| ggshield-1.54.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 20.1 MB
Release files / ggshield-1.54.0.tar.gz
| Download URL | ggshield-1.54.0.tar.gz |
|---|---|
| Size | 1.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2861919706bb5fae2cffa8b1a26ac2643534388fb286818f9e6dace61692d65a
|
|
BLAKE2b-256 checksum How to use checksums |
d83bf78b04da02a8d7389fc9d13c154351cafdca34aa005559db3873029b6002
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ggshield-1.54.0-py3-none-win_amd64.whl
| Download URL | ggshield-1.54.0-py3-none-win_amd64.whl |
|---|---|
| Size | 2.4 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
2965ab00128560ba3f15b4f36cedd2f4458f768fc08095e4334198d911e74a03
|
|
BLAKE2b-256 checksum How to use checksums |
85f2ad67ae754a0e84a365f1749531c50da093231bae01ce007bfcd94faa6572
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ggshield-1.54.0-py3-none-musllinux_1_2_x86_64.whl
| Download URL | ggshield-1.54.0-py3-none-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | Linux musl 1.2+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
bb144dd0055d641d04562560528b2fdc38517cfd5e7418deabf4c22f515aed78
|
|
BLAKE2b-256 checksum How to use checksums |
cbee47dc12c6b277e47cddffa90f3aeea900584278911a9154b3e8af294b0dd8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ggshield-1.54.0-py3-none-musllinux_1_2_aarch64.whl
| Download URL | ggshield-1.54.0-py3-none-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | Linux musl 1.2+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
de298354df3b9dccbe39b3126c205b36277872aea4679480d3ef8ae7dee6d61c
|
|
BLAKE2b-256 checksum How to use checksums |
b4b3b2ab1ea41a952e5458f46f80e2beffe0e1288a23da060733507399619d7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ggshield-1.54.0-py3-none-manylinux2014_x86_64.whl
| Download URL | ggshield-1.54.0-py3-none-manylinux2014_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
bde2685bd67c1b766918e9050cb5eff0c1e145629a4fc8d974200d039151266b
|
|
BLAKE2b-256 checksum How to use checksums |
649db2d43d4a45f04a99e0da69df4ca8acd80c3c549264fdabcf66b4d9054848
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ggshield-1.54.0-py3-none-manylinux2014_aarch64.whl
| Download URL | ggshield-1.54.0-py3-none-manylinux2014_aarch64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
42e0658ecd20d7d709931b5632aca8932b7c91a780f00f2e6b17061937f22a6e
|
|
BLAKE2b-256 checksum How to use checksums |
820fb4a8b7a107f84388ced2e414ec9f4dc01652b2082d7690010bab9aca873e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ggshield-1.54.0-py3-none-macosx_11_0_universal2.whl
| Download URL | ggshield-1.54.0-py3-none-macosx_11_0_universal2.whl |
|---|---|
| Size | 4.1 MB |
| Tags | Python 3 macOS 11.0+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
07c3c090cb2d8195a2ae40d9c8f420901cfa2146223b5ac14b0245ec5af2270e
|
|
BLAKE2b-256 checksum How to use checksums |
5ba6eb1e9dd4d54816ecaf41114f5bc2d31801a837dac19bcd644972737df607
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ggshield-1.54.0-py3-none-any.whl
| Download URL | ggshield-1.54.0-py3-none-any.whl |
|---|---|
| Size | 372.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
774bc5b707c9babcc88e2981e3da3742127bcd0bf462af63f151af4a771ad6b5
|
|
BLAKE2b-256 checksum How to use checksums |
771e15187c3da46bfbd4bb370ed465fd72494058443759fbae7c2f933de470b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
