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: [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 listUseful 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 configurationggshield 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
.