Investigate incidents

For every incident, GitGuardian will provide you with the following metadata about the secret and its occurrences:

• Type of secret (raised by the detector)
• Date (at which the occurrence of the secret was committed)
• Commit author email (involved developer)
• Repository name
• File name and extension
• Commit SHA-1 hash
• Git history presence (when possible)
• Validity (when possible)
• Additional tags (e.g., Default branch, From historical scan, Publicly exposed, Publicly leaked, Regression, Test file, etc.)

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.

The validity check can return 5 possible values:

• valid: the secret can still be exploited and needs to be revoked and rotated .
• invalid: the secret has been revoked.
• failed to check: GitGuardian was not able determine the validity of the secret. It happens when it is not possible to distinguish the error caused by an invalid secret and an IP allowlist or another mechanism preventing the validity check. It can also mean the service provider is temporarily unavailable.
• cannot check: the service provider or the secret type do not allow for checks by GitGuardian. This status is also displayed when secret validity checks are disabled by a workspace Manager.
• unknown: GitGuardian has recently introduced a validity checker, this secret’s validity has not been verified yet.

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	Monthly
Free	Ignored	Less than a year old	Half-yearly
Business	Ignored	More than a year old	Half-yearly
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 use GitGuardian self-hosted, 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.

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.

caution

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.

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 (eg: Agora API keys).

Customize validity checks

GitGuardian allows customization of validity checks for certain detectors by specifying a custom host.

Consider the GitLab token detector. By default, it checks secrets against gitlab.com (GitLab SaaS). However, if you have a self-hosted GitLab instance, you can provide the URL of your instance. GitGuardian will then verify any detected GitLab token secrets against your self-hosted environment.

A validity checker endpoint includes:

• a host
• a path

You only need to provide the host. GitGuardian uses the same path as the default host for the custom check.

So let's say that the validity checker of the GitLab token is https://gitlab.com/the-route-to-check-the-validity.
You simply need to provide the host (eg: https://my_gitlab.self_hosted_instance.corp) and GitGuardian builds the validity checker https://my_gitlab.self_hosted_instance.corp/the-route-to-check-the-validity.

When you submit a custom host for validity checks, all previously detected secrets for that detector will be re-checked against the new host. This ensures that you have the most accurate validity information.

info

Only detectors that support validity checks and have the attribute On-premise instance exist: True can be customized with a custom host URL for validity checks.

If you are under Business plan, you can see the list on the eligible detectors in the table of detectors.

This feature is only available for workspaces under our Business plan.

Secret presence checks

With the presence check, it is possible to verify the presence (and thus reachability) of every occurrence of the secret in your repositories. For each incident, GitGuardian will display the dates at which each occurrence was first and last seen and if it is still present in the repository.

Once you have fully deleted the repository or rewritten the git history, return to your incident's page to obtain the secret's occurrence proof of deletion (see screenshot below). Once an occurrence is no longer visible in the git history, GitGuardian will stop checking for its presence.

GitGuardian will regularly check for the presence of occurrences, to the best of its ability and considering existing VCS API rate limits, to mirror the state of your git repository. You can also manually run the presence check should you need to force update the status of the occurrences of an incident.

The frequency of these automated 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.

⚠️ Presence checks and orphan commits

When you delete a repository, all its commits are permanently deleted. However, using git push --force to remove a specific commit in a repository does not permanently delete it. It becomes an orphan commit, still existing but no longer referenced by any branch. It's impossible to see orphan commits in a pull request or in an existing branch unless you have access to the unique id (sha) of the commit. GitGuardian considers a secret's occurrence in an orphan commit as present. VCSs provide garbage collection, completely emptying the bin of orphan commits. In the case of:

• GitHub, contacting the support to run the garbage collection is necessary
• GitLab, the frequency of garbage collection is decided by the VCS admin

When you decide to unmonitor a repository, GitGuardian consequently loses access to that repository, which in turn prompts the presence check to lose its ability to update values with regards to its corresponding occurrences. GitGuardian will display an icon to indicate that the repository is no longer monitored.

For incidents containing occurrences related to more than one repository, the presence check will continue to work for the rest of the occurrences linked to the monitored sources until the last monitored source gets removed from the perimeter.

Secret leak checks

With the leak check, it is possible to check whether your secret has been detected on a public place outside your perimeter (GitHub public repositories, issues, and gists your organization does not own). When this occurs, the situation is extremely serious, indicating that your secret is compromised and may be found by anyone on GitHub. Note that for security reasons, GitGuardian only manipulates a hashed version of your secrets.

Such secret incidents are identified with the Publicly leaked tag. You can filter these incidents using this tag in order to better prioritize your incidents.

info

The leak check feature is not supported for multi-match secrets. Secrets detected as publicly leaked in more than 10 places are considered false positives (e.g. standard test credentials) and are not tagged as Publicly leaked.

GitGuardian regularly updates the leak status of your secret incidents and determines the places on public GitHub (repositories, issues and gists) where the secret has been detected. You can also run the leak check manually, should you need to force update the leak status of the secret incident.

The frequency of these automated checks depends on your plan, incident status and secret validity:

Plan	Incident status	Secret validity	Incident age	Frequency
Business	Opened	Not invalid	Less than a year old	Daily
Business	Opened	Not invalid	More than a year old	Weekly
Business	Resolved	Not invalid	Any	Monthly
Business	Ignored	Not invalid	Any	Never
Business	Opened	Invalid	Any	Never
Business	Resolved	Invalid	Any	Never
Business	Ignored	Invalid	Any	Never

From the sidebar, you can consult the list of places (up to 10) where your secret has been publicly leaked.
For each place, we provide:

• the type of place (GitHub repository, issue or gist)
• a link to the original source

This gives you more context to check the leak and better qualify your secret incident.

info

The leak check feature is exclusively available for workspaces under the Business plan, and is not available for GitGuardian self-hosted instances. If you are interested in public monitoring and would like to find out more, you can look at our:

• GitGuardian Public Monitoring product to extend the secret detection to the entire GitHub public space.