Skip to main content

Configuration

Dependencies between the dashboard and ggshield#

The following paragraph describes how the GitGuardian REST API and ggshield (CLI) work in relation to the dashboard and how you can customize the dashboard experience to best fit your approach to secrets scanning in developer workflows.

Here is the complete list of settings and interactions between the dashboard and the API or CLI:

  • Ignored secret incidents
    Secrets for which the related incident has been ignored on your GitGuardian dashboard will no longer be raised by ggshield.
  • Resolved secret incidents
    If the Regression setting is OFF, secrets for which the related incident has been resolved on your GitGuardian dashboard will no longer be raised by ggshield. However, if the Regression setting is turned ON, ggshield will raise them.
  • Disabled/enabled detectors
    Secrets associated with detectors you have disabled on your GitGuardian dashboard will not be raised by ggshield.
  • Activated/de-activated validity checks for secret
    ggshield follows the validity check setting of your GitGuardian dashboard. If this setting is turned OFF, ggshield will no longer perform validity checks, and neither will your dashboard.
  • Filepath exclusions
    Secrets found in a filepath excluded on your GitGuardian dashboard will not be raised by ggshield.

For each secret found with ggshield, we indicate whether it is known by your GitGuardian dashboard. If a secret incident already exists on your GitGuardian dashboard, ggshield will also print the URL of the associated secret incident to your console.

caution

To view this information in the ggshield secret scan output, you need to upgrade to version v1.15. The information will be available in the Known by GitGuardian dashboard and Incident URL fields.

For example, this information can be leveraged, by using the --ignore-known-secrets option, which makes ggshield ignore secrets that are already known to your dashboard.

General Configuration#

When it comes to configuration, you can fine-tune ggshield's behavior using three sources of parameters. From higher priority to lower priority:

  • CLI options
  • Environment variables
  • Configuration files This means that CLI options override environment variables, which override settings set in configuration files.

CLI options#

A few configuration parameters are available as CLI options. We recommend using --help with the command you intend to use to get more insights on what behaviors can be configured this way.

Environment Variables#

Some of ggshield's behaviors can be tuned via environment variables. When starting up, ggshield will attempt to load environment variables from different environment files in the following order:

  • the file pointed by the GITGUARDIAN_DOTENV_PATH environment variable.
  • A .env file at the current working directory.
  • A .env file at the root of the current git directory.

Only one of the env files will be loaded out of the three.

List of supported environment variables#

  • GITGUARDIAN_API_KEY: API Key for the GitGuardian API. Use this if you don't want to use the ggshield auth commands.

  • GITGUARDIAN_INSTANCE: Custom URL of the GitGuardian dashboard. The API URL will be inferred from it.

  • GITGUARDIAN_DONT_LOAD_ENV: If set to any value then 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.

  • GITGUARDIAN_TIMEOUT: If set to a float, ggshield secret scan pre-receive will timeout after the specified value. Set to 0 to disable the timeout.

  • GITGUARDIAN_MAX_COMMITS_FOR_HOOK: If set to an int, ggshield secret scan pre-receive and ggshield secret scan pre-push will not scan more than the specified value of commits in a single scan.

  • GITGUARDIAN_CRASH_LOG: If set to True, ggshield will display a full traceback when crashing.

  • GITGUARDIAN_LOG_FILE: If set to a file, ggshield will send log output to it. You can also set it to - to send output to stderr. Equivalent to the --log-file option.

Configuration files#

Configuration files selection in ggshield follows a global to local hierarchy.

ggshield will first search for a global config file in the user's home directory:

  • ~/.gitguardian.yml on Linux or MacOS
  • %USERPROFILE%\.gitguardian.yaml on Windows

ggshield will then recognize a local config file in the current working directory (i.e.: ./.gitguardian.yml).

Alternatively, the --config-path or -c option can be used on the main command to specify a custom config file. In this case, neither local nor global config files will be evaluated (example: ggshield --config-path ~/Desktop/custom_config.yaml secret scan path -r . or ggshield -c ~/Desktop/custom_config.yaml secret scan path -r .)

A sample config file can be found hereunder:

# Required, otherwise ggshield considers the file to use the deprecated v1 formatversion: 2
# 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.exit-zero: false # default: false
verbose: false # default: false
instance: https://dashboard.gitguardian.com # default: https://dashboard.gitguardian.com
# Maximum commits to scan in a hook.max-commits-for-hook: 50 # default: 50
# Accept self-signed certificates for the API.allow-self-signed: false # default: false
secret:  # Exclude files and paths by globbing  ignored-paths:    - '**/README.md'    - 'doc/*'    - 'LICENSE'
  # Ignore security incidents with the SHA256 of the occurrence obtained at output or the secret itself  ignored-matches:    - name:      match: 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1    - name: credentials      match: MY_TEST_CREDENTIAL
  show-secrets: false # default: false
  ignore-known-secrets: false # default: false
  # Detectors to ignore.  ignored-detectors: # default: []    - Generic Password

Size limits and API call volume consideratons#

ggshield relies on the GitGuardian API to perform secret scanning. The maximum size for a document that can be scanned is 1MB. Any files larger than 1MB will be ignored. Using the --verbose option will show information about any files skipped when performing a secret scan.

The GitGuardian API limits batches of files per call to a maximum of 20 documents. If a repository or folder contains more than 20 documents, ggshield will bundle files into groups of 20 or fewer to be scanned per API call. Scanning repositories containing more than 20 documents will result in multiple API calls.

You can explore this topic further in the GitGuardian API reference documentation.

Specificities for on-premise configuration#

ggshield can also be configured to run on your on-premise GitGuardian instance.

First, you need to point ggshield to your instance, by either defining the instance key in your .gitguardian.yaml configuration file or by defining the GITGUARDIAN_INSTANCE environment variable.

Then, you need to authenticate against your instance using the ggshield auth login --instance https://mygitguardianinstance.mycorp.local command using the --instance option, or by obtaining an API key from your dashboard administrator and storing it in the GITGUARDIAN_API_KEY environment variable.