Skip to main content

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.

Interaction with the dashboard#

The public API follows the dashboard settings on the following topics:

  • Filepath banlist
  • Disabled/Enabled detectors
  • Ignored incidents

So when using ggshield you won't get warnings about incidents you've already ignored on the dashboard, incidents of detectors you have disabled and incidents present in files that match ignore patterns on the dashboard.

Configuration file#

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 a local config file in the user's working directory as well (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 globbingpaths-ignore:  - '**/README.md'  - 'doc/*'  - 'LICENSE'
# Ignore security incidents with the SHA256 of the occurrence obtained at output or the secret itselfmatches-ignore:  - name:    match: 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1  - name: credentials    match: MY_TEST_CREDENTIAL
show-secrets: false # default: false
# By default only secrets are detected. Use all-policies to toggle this behaviour.all-policies: 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
verbose: false # default: false
api-url: https://api.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
# Detectors to ignore.banlisted-detectors: # default: []  - Generic Password
# Use default excluded vendors foldersignore-default-excludes: false # default: false

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.

  • 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_API_URL: Custom URL for the scanning API. Deprecated, use GITGUARDIAN_INSTANCE instead.

  • 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.

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 out of the three.

Ignore list#

Useful for ignoring a revoked test credential or a false positive, there are different ways to ignore a secret with ggshield.

  • using the secret ignore command to ignore the latest secrets found in your scan.
  • adding the ignore SHA that accompanies the incident or one of the secret matches to the configuration file
  • directly 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}

Note that this ggignore comment will also ignore the secret in your GitGuardian dashboard.

On-premise configuration#

ggshield can 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, by either 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.