#Interactions with the dashboard
The public API follows the dashboard settings on the following topics:
- Filepath banlist
- Disabled/Enabled detectors
- Ignored incidents
- Activated/de-activated validity checks for secrets
Hence 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. For the same reason if the validity checks
have been disabled in the dashboard this information won't be returned in ggshield's output.
Another way to tie ggshield and the dashboard together is the
--ignore-known-secrets option that will make ggshield
ignore secrets already known in the dashboard.
When it comes to configuration, ggshield's behavior can be fine-tuned 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 in turn override settings set in configuration files.
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.
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
.envfile at the current working directory.
.envfile 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
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-receivewill 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-receiveand
ggshield secret scan pre-pushwill 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.
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.ymlon Linux or MacOS
ggshield will then recognize a
local config file in the current working directory (i.e.:
-c option can be used on the main command to specify a custom config file.
In this case, neither
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 # 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. This means that 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, 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.