Getting started
ggshield is GitGuardian CLI application (Command Line Interface) to help you detect more than 300 types of secrets, as well as other potential security vulnerabilities or policy breaks.
ggshield is open source on GitHub and accessible here.
ggshield can run:
- in your local environment to scan local files and repositories or as a pre-commit hook.
- in a CI environment,
- in a pre-receive hook, if you have a self-managed VCS instance
#
Step 1: Authenticate using an API keyggshield requires an API key to associate the CLI with your GitGuardian workspace. There are 2 different types of API keys.
- Service Accounts: a special type of token intended to represent a non-human user that needs to authenticate and be authorized for scenarios such as secrets scanning in CI pipelines or batch processing open incidents.
- Personal Access Tokens: a token intended for the use of the GitGuardian API and command-line application ggshield by individual developers on their local workstations (e.g. pre-commit or pre-push git hooks).
#
Create your API keyTo create your API key, please follow the steps described in the authentication paragraph of the API section. Once you have your API key ready, come back to this page.
#
Source your API key in your environment- For ggshield to use your API key it must be present in your environment variables as
GITGUARDIAN_API_KEY
. You can set theGITGUARDIAN_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.
- 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 (eg:https://dashboard.gitguardian.mycorp.local/exposed/
).
#
Step 2: Install ggshieldThe minimum requirements for installing ggshield are:
- python 3.6+
- git
- pip
#
Ubuntu (16.04, 18.04, 20.04)- Install or update pip
$ sudo apt update$ sudo apt install python3-pip
- Install ggshield
$ pip install -U ggshield
#
Fedora- Install or update pip
$ sudo dnf install python3
- Install ggshield
$ pip install -U ggshield
#
Arch Linux- Install or update pip
$ sudo pacman -Syu python-pip
- Install ggshield
$ pip install -U ggshield
#
macOS- Install homebrew
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- Install or update pip
$ brew install python
- Install ggshield
$ pip install -U ggshield
#
Step 3: Scan your first content with ggshield- Go to one of your repository
$ cd my_repo/
- Scan it with ggshield
ggshield scan repo .
- Run
ggshield -h
for help
#
Go further with ggshieldIf 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.