Skip to main content

Secrets detection

Secrets detection is at core of GitGuardian for Internal Repositories Monitoring.

What is a secret?#

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.

How does GitGuardian detect secrets?#

If you want to understand how GitGuardian has implemented its secrets detection engine, please read our documentation dedicated to this subject.

Customizing secrets detection#

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).

  1. Navigate to Settings > Secrets Detection
  2. In the navigation bar, click Table of Detectors (or scroll down until you get there)
  3. Click Add a custom detector, a modal will open

Add a custom detector

  1. 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.

Add a custom detector - form

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 acknowledged or under implementation state however cannot be deleted.

Add a custom detector - ticket

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 submitted requests.

Secret validity checks#

How it works#

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.

Secret validity preview and filter

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:

PlanIncident statusIncident ageFrequency
BusinessOpenLess than a year oldDaily
FreeOpenLess than a year oldWeekly
BusinessOpenMore than a year oldWeekly
FreeOpenMore than a year oldMonthly
BusinessIgnoredLess than a year oldHalf-yearly
FreeIgnoredLess than a year oldNever
BusinessIgnoredMore than a year oldNever
FreeIgnoredMore than a year oldNever
BusinessResolvedLess than a year oldMonthly
FreeResolvedLess than a year oldHalf-yearly
BusinessResolvedMore than a year oldHalf-yearly
FreeResolvedMore than a year oldNever

If you host GitGuardian on-premise, you can change these frequencies in your admin area.

Enabling and disabling validity checks#

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.

Secrets detection settings

In addition, please note that when disabling secret validity checks, new secrets that could be marked as valid or 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.

Table of secrets detectors#

You can find the exhaustive list of GitGuardian secrets detectors in the settings of your workspace.

Table of secrets detectors

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.