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: [Required] API Key for the GitGuardian API.
GITGUARDIAN_API_URL: Custom URL for the scanning API.Default:  "https://api.gitguardian.com/".Set "https://dashboard.gitguardian.mycorp.local/exposed/" if you are using a self-hosted GitGuardian instance.
GITGUARDIAN_DONT_LOAD_ENV: If set to any value 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 scan pre-receive` will timeoutafter the specified value. Set to 0 to disable the timeout
GITGUARDIAN_MAX_COMMITS_FOR_HOOK: if set to an int, `ggshield scan pre-receive` and `ggshield 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 tracebackwhen 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 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.

You can modify your environment variables to include:

GITGUARDIAN_API_KEY=<GitGuardian API Key>GITGUARDIAN_API_URL=<GitGuardian on-premises API URL>

Your GITGUARDIAN_API_URL will usually be https://${your_hostname}/exposed/.

Alternatively to setting the GITGUARDIAN_API_URL environment variable, set the api-url in your .gitguardian.yaml.