Customize detection

Secrets detectors

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

The frequency of a secrets detector is the number of matched secrets per million of commits.

Activate or deactivate detectors

In your workspace settings, on the detectors page, you can activate or deactivate secrets detectors on an individual basis to refine your focus on incidents.

When you deactivate a detector:

• you will not receive a notification for incidents that this detector raises,
• incidents for deactivated detectors will not be displayed in your dashboard. However, the detector will still detect and store such incidents shall you reactivate the detector later.

Custom detectors

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

info

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.

Submit your custom detector request

1. Navigate to Settings > Secrets > Detectors
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
   
   
4. 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.
     
     

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.

Leverage your custom detector

After submitting your request, our engineering team will promptly acknowledge it and reach out to you for validation of the regular expression. Given the complexity of regular expressions and the potential for high-volume alerts, it is crucial that we thoroughly review the results produced by your custom pattern. This ensures the delivery of precise and highly accurate alerts before deploying it to your workspace.

Requests in the submitted state can be modified or deleted. However, requests in the acknowledged or under implementation state cannot be deleted.

Once the implementation of your custom detector is complete, the GitGuardian team will notify you, and your new detector will be ready for detection.

If you are using a GitGuardian self-hosted instance

caution

Custom detectors are available for self-hosted instances starting version 2023.9.0.

If you are using a GitGuardian self-hosted instance, the procedure mentioned above undergoes slight modifications due to the inherent constraints of self-hosting:

1. the request will not be automatically sent to GitGuardian. Instead, you are required to send it to custom.detectors@gitguardian.com.
   
2. upon finalization of your custom detector implementation by our R&D team, you will receive a YAML file that needs to be uploaded to complete the creation of your custom detector.
   

If you delete the request before the upload of the YAML file, a brand new request must be submitted.

Ensure that you first import the YAML file to your staging instance for validation. Once satisfied, import it to your production environment.

Filepath exclusions

By scanning your entire git history, or simply due to your software development activity, you could have many incidents on your GitGuardian dashboard. Decreasing the number of incidents and focusing only on those that matter most is therefore key. This feature only applies to secrets incidents.

Description

In your workspace settings, under the Secrets detection section, you can configure the filepaths you want to exclude from secrets detection. You can link specific repositories to these excluded filepaths, ensuring that the exclusion only applies to those repositories.

When a secret is leaked on an excluded filepath:

• you will not receive any notification,
• no incident will be created in your dashboard.

Note that newly created filepath exclusions will also apply to existing secret incidents and these would therefore be removed from your secret incidents table.

You have the ability to test a filepath against your exclusion list to verify your configuration.

Filepath format

The filepath format is a subset of the glob-style pattern. It uses the “/” character to separate each element of the path (POSIX norm), and allows the special “*” character as a wildcard. Additionally, the “**” sequence can be used to recursively match any number of directories.

PATTERN	CORRESPONDING REGEX	MATCHES	NON-MATCHES
test.py	test\.py$	src/tests/test.py	src/test/file.py src/test.py/README
tests/*.py	tests/([^/]+)\.py$	src/tests/test.py src/tests/file.py	src/test.py src/test.txt
/tests/*.py	^tests/([^/]+)\.py$	tests/test.py	src/tests/test.py
/*/test.py	^([^/]+)/test\.py$	src/test.py	test.py src/tests/test.py
src/**/test.py	src/([^/]+/)*test\.py$	src/test.py src/dir1/dir2/dir3/test.py dir1/src/test.py	dir1/dir2/dir3/test.py
/src/**/test.py	^src/([^/]+/)*test\.py$	src/test.py src/dir1/dir2/dir3/test.py	dir1/src/test.py
**/templates/	templates/	templates/file.html src/templates/file.html	src/file.html

If you misuse the glob-style pattern, GitGuardian will automatically correct your input. For instance:

• src/**/**/**/tests/ will be corrected to src/**/test
• **/src/** will be corrected to src/

Secret pattern exclusion

Description

In your workspace settings, under the Secrets detection section, you can configure the secret pattern you want to exclude from secrets detection. You can link specific repositories to these excluded secret pattern, ensuring that the exclusion only applies to those repositories. The secret pattern you define must use the regular expression pattern.

When a secret pattern is triggered:

• you will not receive any notification,
• no incident will be created in your dashboard.

Note that newly created secret pattern exclusions will also apply to existing secret incidents and these would therefore be removed from your incidents table.

You have the ability to test a secret pattern coverage.