Skip to main content

How gg-shield works

Presentation#

gg-shield uses the public API through py-gitguardian to scan files and detect potential secrets.

Only metadata such as call time and request size is stored from scans using GitGuardian shield, therefore secrets and policy breaks incidents will not be displayed on your dashboard.

gg-shield can be used via the pre-commit framework on repositories, or as a standalone pre-commit either globally or locally.

An API Key is needed to use gg-shield. The environment variable GITGUARDIAN_API_KEY is used to read the intended API key.

GITGUARDIAN_API_KEY=<GitGuardian API Key>

Help command#

Run the following command to have access to the different commands and options:

ggshield -h
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.