Secrets detection is at core of GitGuardian for Internal Repositories Monitoring.
A secret can be described as any key that provides access to sensitive information, services or assets. Generally these are API keys, encryption keys, Oauth tokens, certificates, PEM files, passwords, and passphrases.
We all know that Version Control Systems are not appropriate places to store secrets. Nonetheless, they are often found hardcoded into source code, within application logs and configuration files.
Guardian ensures that your secrets are not committed or hidden in your git history.
If you want to understand how GitGuardian has implemented its secrets detection engine, please read our documentation dedicated to this subject.
It is not possible to customize the detectors provided with the GitGuardian library. However, you can create your own custom detectors using regular expressions. Please note that this feature is currently in beta and is only available for workspaces under our Business plan (or in Business trial).
- Navigate to Settings > Secrets Detection
- In the navigation bar, click
Table of Detectors(or scroll down until you get there)
Add a custom detector, a modal will open
- Enter the details for your new custom detector:
- You must at least provide the name for your detector, and a set of examples for the format of your internal secret pattern.
- If you have the regular expression for the desired pattern, please provide it.
- You can provide additional information on the pattern, surrounding content or additional match requirements for the secret format you're after.
Once submitted, you will be able to track your custom secret detector request. Our engineering team will acknowledge the request and get in touch with you to validate the regular expression. Due to the nature of regular expressions and the potential for high volumes of alerts, it is important we review the results returned by your custom pattern to ensure precise and high fidelity alerts before deploying it to your workspace.
This feature is designed to help you detect secrets specific to your organization (e.g internal API tokens), all requests for detecting patterns like Personal Identifiable Information (PII) or Protected Health Information (PHI) will be rejected.
Requests in the
submitted state can be edited or deleted. Requests in
under implementation state however cannot be deleted.
Only Managers can create custom detector requests.
Please note that every workspace is only allowed to have 5 custom detector requests at a time. To place a new request, you will have to wait until one of your requests is accepted or rejected, or you can simply delete one of your
To provide you with high-precision alerts, GitGuardian tries to verify the validity of secrets through non-intrusive API calls made to the host, if and when possible.
GitGuardian automatically runs the secret validity checks in the background. The frequency of these checks depends on your plan and the status and age of secret incidents:
|Plan||Incident status||Incident age||Frequency|
|Business||Open||Less than a year old||Daily|
|Free||Open||Less than a year old||Weekly|
|Business||Open||More than a year old||Weekly|
|Free||Open||More than a year old||Monthly|
|Business||Ignored||Less than a year old||Half-yearly|
|Free||Ignored||Less than a year old||Never|
|Business||Ignored||More than a year old||Never|
|Free||Ignored||More than a year old||Never|
|Business||Resolved||Less than a year old||Monthly|
|Free||Resolved||Less than a year old||Half-yearly|
|Business||Resolved||More than a year old||Half-yearly|
|Free||Resolved||More than a year old||Never|
If you host GitGuardian on-premise, you can change these frequencies in your admin area.
It is possible to disable the validity checks for the entire GitGuardian workspace. However, please be advised that some detectors require validity checks to be enabled to be active. If you choose to keep validity checks globally disabled, these detectors will be deactivated and will no longer raise any incidents.
In addition, please note that when disabling secret validity checks, new secrets that could be marked as
invalid will have their validity set to
unknown since their associated validity checker is toggled off. Re-enabling the validity checker will trigger the verification process on all existing incidents, if and when possible.
Please note that these settings also apply to the API and ggshield. Detectors requiring validity checks to be enabled to be active will be deactivated and the rest of the detectors will return the value
unknown for secrets validity checks.
To verify if a detector requires validity checks to be enabled to raise incidents, go to the detector's dedicated page in the Secrets Detection documentation and look for the flag
Only valid secrets raise an alert: True.
You can find the exhaustive list of GitGuardian secrets detectors in the settings of your workspace.
You can activate or deactivate secrets detectors on an individual basis to refine your focus on incidents.
The frequency of a secrets detector is the number of matched secrets per million of commits.