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 dashboardThe 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 fileggshield 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 VariablesSome 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 theggshield 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, useGITGUARDIAN_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
andggshield 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 listUseful 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 configurationggshield 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.