One of the key challenges of a secrets detection and remediation program is prioritizing incidents and identifying where you should focus remediation efforts.
GitGuardian focuses on the precision of its secrets detection engine (to raise the highest percentage of true positives). You can refer to our dedicated documentation for the GitGuardian secrets detection engine for further information. That being said, the severity of a secret incident is still a notion that is hard to grasp from an external standpoint. That is why GitGuardian tries to give as much factual information as possible in order to help you categorize the severity of the secret incident.
#1. Prioritize with the incidents table
You can find a table of all your incidents in the Incident section. Our aim is to help you navigate this table in the most efficient way possible.
#Open incidents by default
The table is filtered by default by open incidents (triggered and assigned incidents). You can still have access to incidents that have been resolved or ignored thanks to the Status filter.
#Most recent incidents
By default, the table of incidents is sorted by "most recent" incidents. As a matter of fact, secrets that were detected most recently have the highest probability of being valid and thus harmful. The date of an incident is the date of its first occurrence.
It is especially important to note here that GitGuardian creates secrets incidents during historical scans. The date of those incidents is the date of the commit where the secret exposure happened, not the date of the historical scan. Such incidents will be marked with the "From historical scan" tag.
Therefore, you can end up with very old incidents as you run GitGuardian on your git history. That is why, we allow you to modify the time frame of the listed incidents and set it to All time. By default, this time frame is set to Last Month.
You can quickly preview the actual secret from the incidents table with a simple hover. If you would like to further investigate, you can click on the secret incident and visit its dedicated page.
Be cautious: sometimes the broader context of a secret can be much more harmful than the secret itself. We always recommend going beyond the secret preview and conducting an in-depth investigation before making a decision on a particular incident.
The table of incidents indicates for each incident if the compromised secret is still valid or not. You can also filter your incidents to view valid secrets only. This can help you set your priorities straight in terms of remediation. We recommend you take care of exposed and valid credentials as soon as possible, since they still represent unmitigated threats.
For more details on this feature, please refer to the dedicated section on validity checkers.
#Occurrences count and presence in git history
The table of incidents also indicates the number of occurrences for each incident. The severity of an incident should not be determined simply by its number of occurrences. This informs you about the potential sprawl of the secret but keep in mind that a secret that is present in more than one place is often not an harmful secret.
The total count is split between the occurrences of the incident present in your git repository and the ones that have been rendered non-existent (following the deletion of a repository or rewriting of the git history).
Removing any trace of the secret in your git repositories may be one of your requirements for full incident remediation. If that is the case, it is possible to filter your incidents to only view the ones for which at least one occurrence is still present or in other words, the ones for which remediation is incomplete.
For each incident, we try to give you as much contextual information as possible. Tags are meant to help you quickly evaluate each incident. In the incidents table, you will see all the tags associated with occurrences of an incident. The different tags are:
Regression: the incident was once resolved but GitGuardian detected a new occurrence.
Test file: one of the occurrences of the incident happened on a potential test file.
Sensitive file: one of the occurrences of the incident happened on a potential sensitive file.
Exposed publicly: one of the occurrences of the incident was detected on a public repository of GitHub.com.
From historical scan: one of the occurrences of the incident was detected thanks to a historical scan, as opposed to being detected in real-time.
#Manual severity assignment
To help you prioritize incidents during triage, you can set a severity for each incident. You can define the severity of an incident either in its dedicated remediation page, or directly from the table of incidents.
The different severity levels are:
- Critical: concerns a critical service. Must be tackled as quickly as possible.
- High: concerns an important service with a potentially broad impact.
- Medium: concerns an important service with a potentially limited impact.
- Low: concerns a minor service with a potentially broad impact.
- Info: concerns a minor service with a potentially limited impact.
- Unknown: default level applied by GitGuardian to new incidents.
#Automated severity scoring
Only Managers and Owner can activate this feature.
Manual severity assignment requires a case-by-case examination of your open incidents and can be time-consuming for your teams. GitGuardian's severity scoring feature automates this approach, where and when applicable, to the incidents in your workspace so that you can save time on their triaging and prioritization.
Automated severity scoring comes in handy after running a historical scan on your perimeter that surfaces hundreds or thousands of incidents. It can help you focus your remediation efforts on the most critical incidents first!
To activate the automated severity scoring feature, go to the secrets detection section of your GitGuardian workspace settings.
You can see the coverage of the automated severity scoring engine. GitGuardian computes this by dividing the total number of incidents for which it has automatically assigned a severity by the total number of open incidents in your workspace.
GitGuardian determines the severity of each incident by following a predefined ruleset that can be customized. The rules are evaluated sequentially for each incident from the first to the last. The severity assigned will be that of the first rule whose conditions are met. In case of multiple occurrences for an incident, the rules engine will evaluate all of them and assign the highest severity among them. You can inspect this ruleset in the Secrets detection section of your settings.
Each rule of the ruleset is composed of the following:
- A name identifying the rule
- A description of the rule
- A severity to be assigned automatically in case of a match
- A set of conditions defining the rule
- The total number of incidents for which the rule has set the severity
As a Manager or Owner or the workspace, you can customize this ruleset by clicking on the Edit ruleset button. This allows you to maximize the coverage of automatically scored incidents by defining a ruleset related to your own context.
The default ruleset designed by GitGuardian can benefit from regular updates. Once customized, the ruleset will not benefit from these updates as you become the manager of these rules.
Once entered the edit mode of the ruleset, you can:
- Add a new rule by clicking on the
New rulebutton (up to 20 rules)
- Edit a rule by clicking on the pen icon of the rule
- Delete a rule by clicking on the bin icon of the rule (You can't empty your entire ruleset)
- Reorder rules by dragging them in relation to each other
Creating or editing a rule allows you to define the:
- Name identifying the rule
- Description of the rule (optional)
- Set of conditions defining the rule (up to 20 conditions)
- Severity to be assigned automatically in case of a match
Once you have customized your ruleset, don't forget to save it by clicking on the
Save changes button. This will result in a new scoring of your open incidents based on your fresh new ruleset. The scoring time depends on the number of your secret incidents and occurrences.
If you wish, you can always reset to the default ruleset defined by GitGuardian by selecting the
Reset to default option in the
... menu. This will allow you to benefit from GitGuardian's ruleset updates again.
You can also manually recompute your severity scoring by selecting the
Recompute severity scoring option.
In the incidents table view, hovering over the severity badge of an incident will display a tooltip indicating whether it was set manually or automatically. In the latter case, the rule that matched will also be indicated. You can always override the automated severity set by GitGuardian by selecting a severity of your choice.
On the details page of a critical or high incident, you will find a banner indicating the automated severity score and its corresponding rule.
In case GitGuardian cannot determine the severity of the incident, it will also inform you in the same banner, and you can assign one directly from there – using the dropdown menu.
#2. Explore with the incident page
Each incident has a dedicated page in which you can find additional information to help you investigate.
#Table of occurrences
The table of occurrences provides you with the following detailed information:
- when the occurrence happened
- who is the developer responsible for the leak (git name, git email)
- where the occurrence took place (repository, commit, file)
- when the occurrence was last seen by GitGuardian and if it still visible in your git history
- the tags associated with the occurrence
For the needs of conducting further investigation, each occurrence has its own menu, with a link to the actual location of the secret occurrence on the VCS, if still present.
For each occurrence of a given secret incident, you have access to the patch of the commit where the secret has been detected. The patch is composed of:
- the lines of code added by the commit
- the lines of code deleted by the commit
- the contextual lines surrounding the added or deleted lines. These lines are also monitored by GitGuardian since they are part of the commit.
A secret can consist of several components. For example, an AWS secret is the combination of
client_secret. You can easily navigate and understand these multiple secret components with the patch in your GitGuardian workspace.
From our experience, lots of valuable information can be found around the patch of a secret (other secrets, sensitive data, ...).