Skip to main content

Scan

The scan command is the main command for ggshield, 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.  --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.  -b, --banlist-detector TEXT  Exclude results from a detector.  --exclude PATH               Do not scan the specified path.  --ignore-default-excludes    Ignore excluded patterns by default. [default:                               False]  --json                       JSON output results  [default: False]  -h, --help                   Show this message and exit.
Commands:  ci            scan in a CI environment.  commit-range  scan a defined COMMIT_RANGE in git.  docker        scan a docker image <NAME>.  path          scan files and directories.  pre-commit    scan as a pre-commit git hook.  pre-push      scan as a pre-push git hook.  pre-receive   scan as a pre-receive git hook.  repo          scan a REPOSITORY's commits at a given URL or path.

ggshield scan has different subcommands for each type of scan.

CI#

CI: scan each commit since the last build in your CI.

ggshield scan ci

No options or arguments

Go to our dedicated documentation for more details about CI/CD integrations with ggshield.

Commit range#

Commit Range: scan each commit in the given commit range.

Usage: 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#

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.

Repository#

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 git@github.com:GitGuardian/ggshield.git
  ggshield scan repo /repositories/ggshield

It is best to use a native VCS integration and view the results of a scan within the dashboard.

Docker#

  • Docker: scan a Docker image after exporting its filesystem and manifest with the docker save command.

    Usage: ggshield scan docker [OPTIONS] IMAGE_NAME
      ggshield will try to pull the image if it's not available locallyOptions:  -h, --help  Show this message and exit.

Example: ggshield scan docker gitguardian/ggshield