Skip to main content

Getting started

gg-shield is GitGuardian CLI application (Command Line Interface) to help you detect more than 200 types of secrets, as well as other potential security vulnerabilities or policy breaks.

gg-shield is open source on GitHub and accessible here.

gg-shield can run:

  • in your local environment to scan local files and repositories or as a pre-commit hook.
  • in a CI environment.

Step 1: Authenticate using an API key#

gg-shield requires an API key to associate the CLI with your GitGuardian workspace.

Create your API key#

  1. If you have not already done so, create your GitGuardian workspace.

  2. Go to the API section of your workspace and click on Create API key.

  3. Name your key according to its use-case (for example <Service Name>-<Environment>).

  4. Make sure to select the scan scope for your API key.

  5. Click on Create new API key.

API Table

Your API key must be kept private and should neither be embedded directly in the code nor versioned in Git. Your API key can be created and revoked from the API section of your dashboard.

Source your API key in your environment#

  1. For gg-shield to use your API key it must be present in your environment variables as GITGUARDIAN_API_KEY. You can set the GITGUARDIAN_API_KEY variable in your /etc/environment or your ${HOME}/.bash_profile
#~/.bash_profileexport GITGUARDIAN_API_KEY='7Adcede2ebE7Ee1A0Ed425FEbaBcd2a4a4bEdBFddCa062c2F6DF8E1aD5d7BCeA'
#/etc/environmentGITGUARDIAN_API_KEY=7Adcede2ebE7Ee1A0Ed425FEbaBcd2a4a4bEdBFddCa062c2F6DF8E1aD5d7BCeA

If you don't want your GITGUARDIAN_API_KEY to be available across your development platform you can add it to the .env file in your current working directory.

  1. If you're using an on-premise version of GitGuardian, you also need to set GITGUARDIAN_API_URL environment variable with your on-premise API URL.

Step 2: Install gg-shield (GitGuardian CLI)#

The minimum requirements for installing gg-shield are:

  • python 3.6+
  • git
  • pip

Ubuntu (16.04, 18.04, 20.04)#

  1. Install or update pip
$ sudo apt update$ sudo apt install python3-pip
  1. Install gg-shield
$ pip install -U ggshield

Fedora#

  1. Install or update pip
$ sudo dnf install python3
  1. Install gg-shield
$ pip install -U ggshield

Arch Linux#

  1. Install or update pip
$ sudo pacman -Syu python-pip
  1. Install gg-shield
$ pip install -U ggshield

macOS#

  1. Install homebrew
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  1. Install or update pip
$ brew install python
  1. Install gg-shield
$ pip install -U ggshield

Step 3: Scan your first content with gg-shield#

  1. Go to one of your repository
$ cd my_repo/
  1. Scan it with gg-shield
ggshield scan repo .
  1. Run ggshield -h for help

Go further with gg-shield#

If you are looking to configure a CI/CD integration, take a look at our CI/CD Integrations page.

If you are looking to use GitGuardian at the git hooks level (pre-commit, pre-receive), take a look at our Git hooks documentation page.