Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
February 23, 2023 10:55
February 20, 2023 16:49
March 21, 2023 16:01
March 21, 2023 16:01

ggshield: protect your code with GitGuardian

PyPI Docker Image Version (latest semver) License GitHub stars GitHub Workflow Status Codecov

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 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 and policy breaks incidents will not be displayed on your dashboard and your files and secrets won't be stored.

Table of Contents


macOS - Using Homebrew

You can install ggshield using Homebrew by running the following command:

$ brew install gitguardian/tap/ggshield

Linux packages

Deb and RPM packages are available on Cloudsmith.

Setup instructions:

Other Operating Systems - Using pip


$ pip install ggshield

ggshield supports Python 3.7 and newer.

The package should run on MacOS, Linux and Windows.


To update ggshield you can add the option -U/--upgrade to the pip install command.

$ pip install -U ggshield

Initial setup

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.

Alternatively, you can create your personal access token manually and you can store it in the GITGUARDIAN_API_KEY environment variable to complete the setup.

Getting started

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: ggshield secret scan docker ubuntu:22.04
  • in Pypi packages: ggshield secret scan pypi flask
  • and more, have a look at ggshield secret scan --help output for details.

You can also search for vulnerabilities in your IaC files using the following command:

ggshield iac scan .


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.

Learn more

For more information, have a look at the documentation


If no secrets or policy breaks have been found, the exit code will be 0:

$ ggshield secret scan pre-commit

If a secret or other issue is found in your staged code or in your CI, you will have an alert giving you the type of policy break, the filename where the policy break has been found and a patch giving you the position of the policy break in the file:

$ ggshield secret scan pre-commit

🛡️  ⚔️  🛡️  2 policy breaks have been found in file production.rb

11 | config.paperclip_defaults = {
12 |     :s3_credentials => {
13 |     :bucket => "XXX",
14 |     :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
                            |_____AWS Keys_____|

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


ggshield is MIT licensed.