Investigate incidents
#
Incident metadataFor every incident, GitGuardian will provide you with the following metadata:
- 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., Test file, exposed publicly, regression, from historical scan, etc.)
#
OccurrencesThe same secret can be seen multiple times in your VCS. They are referred to as occurrences. GitGuardian automatically groups several occurrences under the same incident in order to facilitate your remediation process.
Thus, an occurrence of a secret incident is uniquely identified by the combination of the following parameters:
- the source (GitHub repository or GitLab project) impacted by the secret occurrence
- the commit in which we detected the secret occurrence
- the commit file containing the secret occurrence
- the line within the commit file where the secret occurred
Alerts are sent only when a new incident is created or reopened because of a regression. A new occurrence attached to an already-existing open secret incident won't raise any alerts.
#
Presence and validity checks#
Secret presence checksWith 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 validity checks#
How it worksTo 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.
#
Enabling and disabling validity checksIt 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 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
.