Skip to main content

ggshield secret scan docker


Scan a Docker image after exporting its filesystem and manifest with the docker save command.

ggshield secret scan docker [OPTIONS] NAME

ggshield tries to pull the image if it's not available locally.


  • --docker-timeout SECONDS: Timeout for Docker commands.

    Default: 360.

  • -b, --banlist-detector DETECTOR: Exclude results from a detector.

  • --ignore-known-secrets: Ignore secrets already known by GitGuardian dashboard.

  • --exclude PATTERNS: Do not scan paths that match the specified glob-like patterns.

  • --exit-zero: Always return a 0 (non-error) status code, even if incidents are found. This option can also be set with the GITGUARDIAN_EXIT_ZERO environment variable.

  • --show-secrets: Show secrets in plaintext instead of hiding them.

  • -o, --output PATH: Redirect ggshield output to PATH.

  • --json: Use JSON output.

This command supports all ggshield global options.


$ ggshield secret scan docker gitguardian/ggshield

About caching

When scanning a Docker image for the first time, ggshield stores the DiffID of the layers which have been found to be clean in a disk cache. If the same image is scanned a second time, ggshield skips scanning known clean layers. This can greatly speed-up scanning of large Docker images, since only modified layers are rescanned.

This cache depends on the version of GitGuardian secrets engine. When a new version of the secrets engine is deployed, all layers are rescanned.

When using ggshield secret scan docker in a CI, it is important to retain the cache directory between CI runs, otherwise the cache is never reused. ggshield default cache location depends on the operating system:

  • Linux: $XDG_CACHE_HOME/ggshield, or ~/.cache/ggshield if $XDG_CACHE_HOME is not defined
  • macOS: ~/Library/Caches/ggshield
  • Windows: %LOCALAPPDATA%\GitGuardian\ggshield\Cache

Alternatively, you can define the cache directory using the $GG_CACHE_DIR environment variable.

Note that the Docker cache is in a docker subdirectory of the cache directory.

How can I help you ?