GitGuardian Shield
Detect secret in source code, scan your repo for leaks. Find secrets with GitGuardian and prevent leaked credentials. GitGuardian is an automated secrets detection & remediation service.
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>
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 rangeUsage: 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
-
Docker
: scan a Docker image after exporting its filesystem and manifest with thedocker save
command.Usage: ggshield scan docker [OPTIONS] IMAGE_NAME ggshield will try to pull the image if it's not available locally Options: -h, --help Show this message and exit.
Install command
The install
command allows you to use ggshield as a pre-commit or pre-push hook
on your machine, either locally or globally for all repositories.
You will find further details in the pre-commit/pre-push part of this documentation.
Usage: ggshield install [OPTIONS]
Command to install a pre-commit or pre-push hook (local or global).
Options:
-m, --mode [local|global] Hook installation mode [required]
-t, --hook-type [pre-commit|pre-push]
Type of hook to install
-f, --force Force override
-a, --append Append to existing script
-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 := "A@@E*JN#DK@OE@K(JEN@I@#)" // 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-push
⚠ Pre-push hooks will not scan more than a 100 commits to avoid developer interruption.
In case there are more than a 100 commits in a push the hook will be skipped.
Pre-push hooks are executed just before git push
sends data to the remote host.
It will pickup and scan the range of commits between the local ref and the origin ref.
If incidents are detected in this range the push will be cancelled.
With 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-push
language_version: python3
stages: [push]
Then install the hook with the command:
$ pre-commit install --hook-type pre-push
pre-commit installed at .git/hooks/pre-push
With the install command
To install the pre-push hook globally (for all current and future repos), you just need to execute the following command:
$ ggshield install --mode global -t pre-push
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-push
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 -t "pre-push"
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 -t "pre-push"
Or you can append to the existing pre-push
script with the --append
option:
$ ggshield install --mode local --force -t "pre-push"
Now you're good to go!