GitGuardian Shield: protect your secrets with GitGuardian

The GitGuardian shield (gg-shield) is a CLI application that runs in your local environment or in a CI environment to help you detect more than 200 types of secrets, as well as other potential security vulnerabilities or policy breaks.

GitGuardian shield uses our public API through py-gitguardian to scan your files and detect potential secrets in your code. The /v1/scan endpoint of the public API is stateless. We will not store any files you are sending or any secrets we have detected.

You can also use gg-shield via the pre-commit framework on your repositories, or as a standalone pre-commit either globally or locally.

You'll need an API Key from GitGuardian to use gg-shield.

Add the API Key to your environment variables:

GITGUARDIAN_API_KEY=<GitGuardian API Key>

Currently supported integrations

• Pre-commit hooks
• Pre-receive hooks
• GitLab
• GitHub Actions
• Bitbucket Pipelines
• Circle CI Orbs
• Travis CI
• Jenkins

Table of Contents

1. Introduction

2. Installation

3. Configuration

   1. Environment Variables
   2. On-premises
   3. Ignoring a secret

4. Commands

   • Scan
   • Install
   • Ignore

5. Pre-commit

   • The pre-commit framework
   • The global and local pre-commit hook

1. Pre-receive hook
2. GitLab
3. GitHub Actions
4. Circle CI
5. Travis CI
6. Jenkins
7. Output
8. Contributing
9. License

Installation

Install and update using pip:

$ pip install ggshield

gg-shield supports Python 3.6 and newer.

The package should run on MacOS, Linux and Windows.

You'll need an API Key from the GitGuardian dashboard to use ggshield.

Add the API Key to your environment variables:

GITGUARDIAN_API_KEY=<GitGuardian API Key>

Commands

Usage: ggshield [OPTIONS] COMMAND [ARGS]...

Options:
  -c, --config-path FILE  Set a custom config file. Ignores local and global
                          config files.

  -v, --verbose           Verbose display mode.
  -h, --help              Show this message and exit.

Commands:
  install  Command to install a pre-commit hook (local or global).
  scan     Command to scan various contents.
  ignore   Command to permanently ignore some secrets.

Scan command

ggshield scan is the main command for gg-shield, it has a few config options that can be used to override output behaviour.

Usage: ggshield scan [OPTIONS] COMMAND [ARGS]...

  Command to scan various contents.

Options:
  --show-secrets  Show secrets in plaintext instead of hiding them.
  --exit-zero     Always return a 0 (non-error) status code, even if incidents
                  are found.The env var GITGUARDIAN_EXIT_ZERO can also be used
                  to set this option.

  --json             JSON output results  [default: False]
  --all-policies  Present fails of all policies (Filenames, FileExtensions,
                  Secret Detection). By default, only Secret Detection is
                  shown.

  -v, --verbose   Verbose display mode.
  -o, --output PATH  Route ggshield output to file.
  -h, --help      Show this message and exit.

Commands:
  ci            scan in a CI environment.
  commit-range  scan a defined COMMIT_RANGE in git.
  path          scan files and directories.
  pre-commit    scan as a pre-commit git hook.
  repo          clone and scan a REPOSITORY.

ggshield scan has different subcommands for each type of scan:

• CI: scan each commit since the last build in your CI.

  ggshield scan ci

  No options or arguments

• Commit Range: scan each commit in the given commit range

  Usage: ggshield scan commit-range [OPTIONS] COMMIT_RANGE
  
    scan a defined COMMIT_RANGE in git.
  
    git rev-list COMMIT_RANGE to list several commits to scan. example:
    ggshield scan commit-range HEAD~1...
  

• Path: scan files or directories with the recursive option.

  Usage: ggshield scan path [OPTIONS] PATHS...
  
    scan files and directories.
  
  Options:
    -r, --recursive  Scan directory recursively
    -y, --yes        Confirm recursive scan
    -h, --help       Show this message and exit.
  

• Pre-commit: scan every changes that have been staged in a git repository.

  ggshield scan pre-commit

  No options or arguments

• Repo: scan all commits in a git repository.

  Usage: ggshield scan repo [OPTIONS] REPOSITORY
  
    scan a REPOSITORY at a given URL or path
  
    REPOSITORY is the clone URI or the path of the repository to scan.
    Examples:
  
    ggshield scan repo [email protected]:GitGuardian/gg-shield.git
  
    ggshield scan repo /repositories/gg-shield
  

Install command

The install command allows you to use ggshield as a pre-commit hook on your machine, either locally or globally for all repositories.

You will find further details in the pre-commit part of this documentation.

Usage: ggshield install [OPTIONS]

  Command to install a pre-commit hook (local or global).

Options:
  -m, --mode [local|global]  Hook installation mode  [required]
  -f, --force                Force override
  -h, --help                 Show this message and exit.

Ignore command

The ignore command allows you to ignore some secrets. For the time being, it only handles the --last-found option that ignore all secrets found by the last run scan command. Under the hood, these secrets are added to the matches-ignore section of your local config file (if no local config file is found, a .gitguardian.yaml file is created).

Warning: Using this command will discard any comment present in the config file.

Usage: ggshield ignore

  Command to ignore all secrets found by the previous scan.

Options:
  -h, --help                 Show this message and exit.
  --last-found               Ignore all secrets found by last run scan

Configuration

Configuration in ggshield follows a global>local>CLI configuration scheme.

Meaning options on local overwrite or extend global and options on CLI overwrite or extend local.

ggshield will search for a global config file in the user's home directory (example: ~/.gitguardian.yml on Linux and %USERPROFILE%\.gitguardian on Windows).

ggshield will recognize as well a local config file in the user's working directory (example: ./.gitguardian.yml).

You can also use the option --config-path on the main command to set another config file. In this case, neither local nor global config files will be evaluated (example: ggshield --config-path=~/Desktop/only_config.yaml scan path -r .)

A sample config file can be found at .gitguardian.example

# Exclude files and paths by globbing
paths-ignore:
  - '**/README.md'
  - 'doc/*'
  - 'LICENSE'

# Ignore security incidents with the SHA256 of the occurrence obtained at output or the secret itself
matches-ignore:
  - name:
    match: 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1
  - name: credentials
    match: MY_TEST_CREDENTIAL

show-secrets: false # default: false

# Set to true if the desired exit code for the CLI is always 0,
# otherwise the exit code will be 1 if incidents are found.
# the environment variable GITGUARDIAN_EXIT_ZERO=true can also be used toggle this behaviour.
exit-zero: false # default: false

# By default only secrets are detected. Use all-policies to toggle this behaviour.
all-policies: false # default: false

api-url: https://api.gitguardian.com # GITGUARDIAN_API_URL environment variable will override this setting

verbose: false # default: false

Notes

Old configuration of matches-ignore with list of secrets is deprecated but still supported :

# Ignore security incidents with the SHA256 of the occurrence obtained at output or the secret itself
matches-ignore:
  - 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1
  - MY_TEST_CREDENTIAL

Environment Variables

Some configurations on ggshield can be done through environment variables.

Environment variables will override settings set on your config file but will be overridden by command line options.

At startup, ggshield will attempt to load environment variables from different environment files in the following order:

• path pointed to by the environment variable GITGUARDIAN_DOTENV_PATH
• .env at your current work directory.
• .env at the root of the current git directory

Only one file will be loaded of the three.

Reference of current Environment Variables that affect ggshield:

GITGUARDIAN_API_KEY: [Required] API Key for the GitGuardian API.

GITGUARDIAN_API_URL: Custom URL for the scanning API.

GITGUARDIAN_DONT_LOAD_ENV: If set to any value environment variables won't be loaded from a file.

GITGUARDIAN_DOTENV_PATH: If set to a path, `ggshield` will attempt to load the environment from the specified file.

On-premises configuration

GitGuardian shield can be configured to run on your on-premises dashboard, request an API key from your dashboard administrator.

You can modify your environment variables to include:

GITGUARDIAN_API_KEY=<GitGuardian API Key>
GITGUARDIAN_API_URL=<GitGuardian on-premises API URL>

Alternatively to setting the GITGUARDIAN_API_URL environment variable, set the api-url in your .gitguardian.yaml.

Ignoring a secret

Useful for ignoring a revoked test credential or a false positive, there are three ways to ignore a secret with gg-shield:

In code

⚠ this will also ignore the secret in the GitGuardian dashboard.

Secrets can be ignored in code by suffixing the line with a ggignore comment.

Examples:

def send_to_notifier() -> int:
  return send_slack_message(token="xoxb-23s2js9912ksk120wsjp") # ggignore

func main() {
  high_entropy_test := "[email protected]@K( // ggignore
}

Through configuration

⚠ Your secret will still show up on the GitGuardian dashboard as potential incident.

You can use the ignore command to ignore the last found secrets in your scan or directly add the ignore SHA that accompanies the incident or one of the secret matches to the configuration file

⚠ A secret ignored on the GitGuardian dashboard will still show as a potential incident on ggshield.

Pre-commit

The pre-commit framework

In order to use ggshield with the pre-commit framework, you need to do the following steps.

Make sure you have pre-commit installed:

$ pip install pre-commit

Create a .pre-commit-config.yaml file in your root repository:

repos:
  - repo: https://github.com/gitguardian/gg-shield
    rev: main
    hooks:
      - id: ggshield
        language_version: python3
        stages: [commit]

Then install the hook with the command:

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

Now you're good to go!

If you want to skip the pre-commit check, you can add -n parameter:

$ git commit -m "commit message" -n

Another way is to add SKIP=hook_id before the command:

$ SKIP=ggshield git commit -m "commit message"

The global and local pre-commit hook

To install pre-commit globally (for all current and future repos), you just need to execute the following command:

$ ggshield install --mode global

It will do the following:

• check if a global hook folder is defined in the global git configuration
• create the ~/.git/hooks folder (if needed)
• create a pre-commit file which will be executed before every commit
• give executable access to this file

You can also install the hook locally on desired repositories. You just need to go in the repository and execute:

$ ggshield install --mode local

If a pre-commit executable file already exists, it will not be overridden.

You can force override with the --force option:

$ ggshield install --mode local --force

If you already have a pre-commit executable file and you want to use gg-shield, all you need to do is to add this line in the file:

$ ggshield scan pre-commit

If you want to try pre-commit scanning through the docker image:

$ docker run -e GITGUARDIAN_API_KEY -v $(pwd):/data --rm gitguardian/ggshield ggshield scan pre-commit

Do not forget to add your GitGuardian API Key to the GITGUARDIAN_API_KEY environment variable of your project or development environment.

Pre-receive

A pre-receive hook allows you to reject commits from being pushed to a git repository if they do not validate every check.

You can find gg-shield's pre-receive hook samples in the doc/pre-receive.sample and doc/pre-receive-python.sample.

Python git pre-receive hook

⚠ this pre-receive hook requires the host machine to have python>=3.6 and pip installed

pre-receive-python.sample

• Install ggshield from pip: pip install ggshield
• Move pre-receive-python.sample to .git/hooks/pre-receive
• Do not forget to chmod +x .git/hooks/pre-receive
• either set an environment variable machine wide GITGUARDIAN_API_KEY or set it in the .git/hooks/pre-receive as instructed in the sample file.

How do I add ignored matches and use a custom config in this pre-receive hook?

• Create a gitguardian.yaml somewhere in the system. An example config file is available here
• Replace in the pre-receive hook

  ggshield scan commit-range "${span}" && continue
  

  with:

  ggshield -c <INSERT path to gitguardian.yaml> scan commit-range "${span}" && continue
  

Docker git pre-receive hook

⚠ this pre-receive hook requires the host machine to have docker installed.

pre-receive.sample

• Move pre-receive.sample to .git/hooks/pre-receive
• Do not forget to chmod +x .git/hooks/pre-receive
• either set an environment variable machine wide GITGUARDIAN_API_KEY or set it in the .git/hooks/pre-receive as instructed in the sample file.

How do I add ignored matches and use a custom config in this pre-receive hook?

• Create a gitguardian.yaml somewhere in the system. An example config file is available here
• Replace in the pre-receive hook

  docker run --rm -v $(pwd):/data -e GITGUARDIAN_API_KEY gitguardian/ggshield:latest ggshield scan commit-range "${span}" && continue
  

  with:

  docker run --rm -v $(pwd):/data -v <INSERT path of gitguardian.yaml directory>:/config -e GITGUARDIAN_API_KEY gitguardian/ggshield:latest ggshield -c /config/gitguardian.yaml scan commit-range "${span}" && continue
  

GitLab

You may be interested in using GitGuardian's GitLab integration to ensure full coverage of your GitLab projects as well as full git history scans and reporting.

Configuring GitLab pipelines to use ggshield is as simple as adding a step to your project's pipeline:

stages:
  - scanning

🦉 gitguardian scan:
  image: gitguardian/ggshield:latest
  stage: scanning
  script: ggshield scan ci

Do not forget to add your GitGuardian API Key to the GITGUARDIAN_API_KEY environment variable in your project settings.

GitHub

You may be interested in using GitGuardian's GitHub integration to ensure full coverage of your GitHub projects as well as full git history scans and reporting.

ggshield's support of GitHub comes in the form of GitHub actions.

The action for this repository is hosted at gg-shield-action.

Configuring a GitHub workflow to use ggshield is as simple as adding a step to your project's workflow:

name: GitGuardian scan

on: [push, pull_request]

jobs:
  scanning:
    name: GitGuardian scan
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]
        with:
          fetch-depth: 0 # fetch all history so multiple commits can be scanned
      - name: GitGuardian scan
        uses: GitGuardian/[email protected]
        env:
          GITHUB_PUSH_BEFORE_SHA: ${{ github.event.before }}
          GITHUB_PUSH_BASE_SHA: ${{ github.event.base }}
          GITHUB_PULL_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          GITHUB_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
          GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}

Do not forget to add your GitGuardian API Key to the GITGUARDIAN_API_KEY secret in your project settings.

Bitbucket

⚠ Bitbucket pipelines do not support commit ranges therefore only your latest commit in a pushed group or in a new branch will be scanned.

Configuring a Bitbucket pipeline to use ggshield is as simple as adding a step to your project's workflow:

pipelines:
  default:
    - step:
        image: gitguardian/ggshield:latest
        services:
          - docker
        script:
          - ggshield scan ci

Do not forget to add your GitGuardian API Key to the GITGUARDIAN_API_KEY environment variable in your project settings.

Circle CI

Circle CI is supported in gg-shield through gg-shield-orb.

To add gg-shield to your pipelines configure your .circleci/config.yml to add the gg-shield orb:

orbs:
  gg-shield: gitguardian/ggshield

workflows:
  main:
    jobs:
      - gg-shield/scan:
          name: gg-shield-scan # best practice is to name each orb job
          base_revision: << pipeline.git.base_revision >>
          revision: <<pipeline.git.revision>>

Do not forget to add your GitGuardian API Key to the GITGUARDIAN_API_KEY environment variable in your project settings.

Travis CI

To add gg-shield to your pipelines configure your .travis.yml to add a gg-shield scanning job:

jobs:
  include:
    - name: GitGuardian Scan
      language: python
      python: 3.8
      install:
        - pip install ggshield
      script:
        - ggshield scan ci

Do not forget to add your GitGuardian API Key to the GITGUARDIAN_API_KEY environment variable in your project settings.

• Defining encrypted variables in .travis.yml

Jenkins

To add gg-shield to your pipelines configure your Jenkinsfile to add a gg-shield stage:

pipeline {
    agent none
    stages {
        stage('GitGuardian Scan') {
            agent {
                docker { image 'gitguardian/ggshield:latest' }
            }
            environment {
                GITGUARDIAN_API_KEY = credentials('gitguardian-api-key')
            }
            steps {
                sh 'ggshield scan ci'
            }
        }
    }
}

Do not forget to add your GitGuardian API Key to the gitguardian-api-key credential in your project settings.

Output

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

$ ggshield 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 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_____|

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).

Contributing

If you have questions you would like to ask the developers, or feedback you would like to provide, feel free to create an issue on our issue tracker.

We would love to hear from you. Additionally, if you have a feature you would like to suggest, feel free to create an issue on our issue tracker.

Related open source projects

• truffleHog
• gitleaks
• gitrob
• git-hound
• AWS git-secrets
• detect-secrets

License

GitGuardian shield is MIT licensed.