ggshield 1.0.0

Detect secrets from all sources using GitGuardian's brains

---

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 or issues in your code.

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
• GitLab
• GitHub Actions
• Bitbucket Pipelines
• Circle CI Orbs
• Travis CI
• Jenkins

Table of Contents

1. Introduction

2. Installation

3. Configuration

4. Commands

   • Scan
   • Install

5. Pre-commit

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

6. GitLab

7. GitHub Actions

8. Circle CI

9. Travis CI

10. Jenkins

11. Output

12. Contributing

13. 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 GitGuardian to use ggshield.

Add the API Key to your environment variables:

GITGUARDIAN_API_KEY=<GitGuardian API Key>

Commands

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

Options:
  -h, --help    Show this message and exit.

Commands:
  install  Command to install a pre-commit hook (local or global).
  scan     Command to scan various content.

Scan command

gg-shield allows you to scan your files in 3 different ways:

• Pre-commit: scan every changes that have been staged in a git repository.
• CI: scan every commit since the last build in your CI.
• Files: scan files or directories with the recursive option.
• Repo: (--repo <URL>) scan all commits in a repository.

Usage: ggshield scan [OPTIONS] [PATHS]...

  Command to scan various content.

Options:
  -m, --mode [pre-commit|ci]  Scan mode (pre-commit or ci)
  -r, --recursive             Scan directory recursively
  -y, --yes                   Confirm recursive scan
  --show-secrets              Show secrets in plaintext instead of hiding them
  -v, --verbose               Display the list of files before recursive scan
  --repo TEXT                 Scan a Git Repository (repo url)
  -h, --help                  Show this message and exit.

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.

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 (./.gitguardian.yml)

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

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

# SHA256 of policy break obtained at output or plaintext matches
matches-ignore:
  - 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1
  - MY_TEST_CREDENTIAL

show-secrets: false # default: false

verbose: false # default: false

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: dev
    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 repo), 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 overriden.

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 --mode pre-commit

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

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 -m 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/checkout@v2
        with:
          fetch-depth: 0 # fetch all history so multiple commits can be scanned
      - name: GitGuardian scan
        uses: GitGuardian/gg-shield-action@master
        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 -m 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 -m 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 -m 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 -m 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 -m 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 | }

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

License

GitGuardian-shield is MIT licensed.