Remediate incidents
Guidelines (& misconceptions)
It is crucial development teams fully understand the problem of secrets-in-code, beyond the simple act of exposing a secret in plain text and committing it to the shared codebase.
Developers need to acknowledge the threats and consequences of secrets sprawl, and picture how collaborating with security teams can strengthen the overall security posture – without compromising speed and productivity.
Collaborating with developers
Involving developers is crucial for the remediation. Developers also have knowledge about the secret itself, since they are the ones who used it. They also understand the system's architecture and the services that may depend on the secret. They can provide insight into affected services and the best way to mitigate issues. This knowledge is essential in creating an effective and efficient remediation plan.
GitGuardian's goal is to enable easy collaboration with your developers by providing flexible ways to share your incidents.
Share the incident
You can collaborate by sharing the incident in two ways:
- Internally, with users registered on the dashboard, via the "Grant access" action. This option is only available for Business workspaces.
- Externally, with non-registered users, via the "Public sharing" action.
More details are available in our dedicated Collaboration and sharing section.
Collect the feedback
The feedback form enables you to collect standardized feedback about an incident. To fill out the form, registered users require the "Can edit" incident permission. They can also edit or delete their own feedback.
Whenever feedback is submitted for an incident, whether by a registered user or a non-registered user, an email notification is sent:
- to the incident assignee, if applicable.
- to all users with access to the incident, if there is no assignee.
Every action taken by the developer will be logged in the incident details timeline.
The feedback form is not customizable yet.
Remediation workflow
Default remediation workflow
Remediating an incident can be complex. That is why a remediation workflow is displayed by default on an incident's details page.
This workflow is intended to guide anyone involved in the remediation of a hardcoded secret incident. It describes the steps that must be followed to mitigate the risks of exposure.
Custom remediation workflow
GitGuardian provides a remediation workflow by default. As each organization has its own context and remediation policies, you have the ability to customize the remediation workflow.
Managing the remediation workflow
As a workspace Manager, you can manage the remediation workflow in the Secrets detection section of your settings.
From here, you can create, edit or delete a custom remediation workflow. You may also have the ability to switch between the default GitGuardian remediation workflow and your custom remediation workflow.
Alternatively, you can access this section directly by clicking the Edit workflow
button on any remediation workflow in an incident's details page.
Creating a new custom remediation workflow
By default, there is no custom remediation workflow on your workspace.
You can create one by clicking the Create custom workflow
button.
You will be asked to create each step of your remediation workflow:
Remediation workflow steps
Each step is composed of:
- A title (mandatory)
- A description (optional, Markdown syntax is not yet supported)
- A link (optional, this link is a good way to provide direct access to an external resource specific to your company)
Once the fields are filled in, simply click on the Add step
button to validate the creation of your step.
Repeat the process to add any other steps.
Note that you can create a maximum of 20 steps for a custom remediation workflow.
Activating a remediation workflow
Once a custom remediation workflow has been created, you are free to select between the default GitGuardian remediation workflow and your own custom remediation workflow.
Once activated, the selected remediation workflow will be immediately displayed on all your incident's details pages. It will also affect any shared incident pages.
Editing a custom remediation workflow
Once created, a custom remediation workflow can be edited by:
- Adding a new step with the
Next Step
button - Editing a step with the pen button close to it
- Deleting a step with the thrash button close to it
- Reordering steps by dragging & dropping them
Any modification will be taken into account in real-time.
Deleting your custom remediation workflow
You can delete your custom remediation workflow with the red Delete workflow
button.
By doing this, the default GitGuardian remediation workflow will be activated automatically.
This will also allow you to create a new custom remediation workflow.
Custom messages when using GitGuardian CLI (ggshield)
When GitGuardian CLI detects secrets in developers' code, whether in pre-commit or other stages, it is highly beneficial to provide them with clear instructions on using secrets in their code according to company standards (Vaults, Environment variables, ..).
Security teams have the ability to customize these messages, which will be disseminated through the CLI at different stages of the Software Development Life Cycle such as pre-commit, pre-push, and pre-receive.
Leverage Secret Managers integration
GitGuardian integrates with Secret Managers through ggscout, enabling you to synchronize secrets incidents with secrets stored in your Secret Managers.
By leveraging this integration, you can identify secrets that are not yet securely stored in a Secret Manager. Once identified, GitGuardian helps streamline the remediation process by pushing the leaked secret to the appropriate Secret Manager instance. Here’s the standard workflow:
- The security engineer or developer team lead can insert the leaked secret using the push-to-vault feature.
- The developer can update the code to reference the secret from its proper storage location.
- The developer can verify that the code fix works as expected.
- The security engineer or developer team lead can rotate and revoke the secret from both the Secret Manager or the affected service.
Learn more on Secrets Managers integrations
Secret revocation from GitGuardian
GitGuardian's integrated secret revocation feature enables you to revoke valid secrets directly from the platform for supported providers, drastically reducing the time secrets remain exposed and accelerating your incident response workflows.
This feature eliminates the need to switch between multiple tools and platforms during remediation, providing a streamlined path from detection to resolution.
- The secret shall have a Valid status.
- You shall have
Full Access
permissions on the incident. - The secret revocation is supported by the provider.
Supported providers
Secret revocation is currently available for the following providers:
- GitHub personal access tokens and fine-grained tokens.
- GitLab personal access tokens.
- OpenAI API keys.
GitGuardian actively advocates with service providers to adopt programmatic revocation capabilities and implement standardized revocation endpoints, making secret management more secure across the ecosystem.
Additional providers are being added regularly. Check back for updates or contact support to request specific provider support.
Enabling secret revocation
The secret revocation feature can be toggled on or off in your workspace settings:
- Navigate to Settings > Secrets > General.
- Locate the Secret Revocation toggle.
- Toggle the feature on or off as needed.
Workspace Managers and Owners can control this setting. When disabled, the revoke button will not appear on incident details pages.
Filtering for revocable incidents
Focus your team's efforts on these high-impact, actionable incidents that can be immediately revoked:
- Navigate to your incidents list.
- Filter secrets
Valid
secrets usingSecret Validity
. - Filter revocable secrets using
Revocable by GitGuardian
GitGuardian tag.
Revoking a secret
Revoking a secret may have dramatic side effects on your systems, applications, or workflows. Therefore, you should always consider checking what the revocation will impact before proceeding.
GitGuardian provides you with a lot of context and insights to assess the impact of the exposure, but more importantly, measure the impact of the revocation, thanks to the identification of the workloads using these credentials.
To revoke a secret directly from GitGuardian:
- Navigate to the incident: Open the incident details page for the secret you want to revoke.
- Locate the revoke button: Find the Revoke button in the secret details right-panel section.
- Initiate revocation: Click Revoke to open the confirmation dialog.
- Confirm the action: Confirm the revocation by inserting
revoke
in the modal dialog.
- Monitor the timeline: The revocation action will be automatically logged in the incident timeline.
After revocation
Once a secret is revoked, GitGuardian automatically re-runs the validity checker. If successful:
- The secret status changes from
Valid
toInvalid
. - The linked incident status changes to
Closed
assuming Playbook Automatically resolves incidents when valid secrets are revoked is enabled.
All revocation activities are logged in the incident timeline for audit and compliance purposes.
Most revocation APIs do not explicitly confirm successful revocation. GitGuardian relies on subsequent validity checks to determine if the revocation was successful.