Scan for secrets
Semgrep Secrets allows you to detect and triage leaked secrets and credentials and save time by prioritizing which secrets to rotate based on whether they're active and in use.
This document guides you through:
- Enabling Semgrep Secrets and scanning your repository
- Configuring your ignore files
- Upgrading your Semgrep Code rules to Semgrep Secrets rules
To access Semgrep Secrets, contact your Semgrep account executive or email the Support team at support@semgrep.com for a trial license.
Language and environment support
Semgrep Secrets can scan repositories using any programming language and supports the posting of PR and MR comments to GitHub, GitLab, and Bitbucket.
Enable Semgrep Secrets
You have completed a Semgrep core deployment.
- Sign in to Semgrep AppSec Platform.
- Click Settings.
- On the Deployment tab, navigate to the Secrets section, and click the Secrets scans toggle to enable.
Once you've enabled Secrets for your organization, all Semgrep scans include secret scanning.
Scan your repository
After you've enabled Semgrep Secrets, you can:
- Manually trigger a full scan of your repository through your CI provider
- Start a scan from the CLI (Semgrep recommends that you run CLI scans only on feature branches, not main branches)
- Wait for your scheduled Semgrep full scan
- Open a pull request or merge request and wait for Semgrep to scan the branch automatically
View your findings
You can use Semgrep AppSec Platform's Secrets page to view the findings generated by Semgrep Secrets after it scans your codebase. To access the Secrets page:
- Sign in to Semgrep AppSec Platform.
- Click Secrets to navigate to your results.
Secrets page structure
The Secrets page consists of:
- The filter panel, which you can use to group and filter for specific findings
- Information about findings identified by Semgrep Secrets. Each finding in the list includes:
- When the finding was created
- The type of secret found and where in the code it is located, including its Project and branch information
- Its severity level
- Whether it has been validated by a Semgrep validator
- Whether it is a historical finding
- For users of the Semgrep Jira integration: whether there is a Jira ticket that accompanies that finding
- A link to the commit where the finding was first identified
- A link to the lines of code where the finding was most recently seen
Group findings
By default, Semgrep groups all of the findings by the rule Semgrep used to match the code. This view is called the Group by rule view.
Semgrep sorts findings by severity. For a given severity, Semgrep further sorts findings as follows:
- Findings generated by custom rules
- Issue count in descending order
- Findings ID in ascending order
To view findings individually, toggle Group by Rule to No grouping using the drop-down menu in the header. Findings are displayed based on the date they were found, with the most recent finding listed at the top.
Filter findings
Use filters to narrow down your results. The following criteria are available for filtering:
| Filter | Description |
|---|---|
| Projects | Filter by repositories connected to Semgrep AppSec Platform. |
| Branches | Filter by findings in different Git branches. |
| Teams | Filter for findings in projects to which the specified teams are associated with. Available only to organizations with Semgrep Teams enabled. |
| Tags | Filter for findings based on the tags associated with the project. |
| Status | Filter the triage state of a finding. Refer to Triage statuses to understand triage states. |
| Severity | Filter by the severity of a finding. Severity is computed based on the values assigned for Likelihood and Impact by the rule's author. Possible values:
|
| Validation state | Filter by whether the secret is actively in use or not. Semgrep Secrets rules include validators, which can check whether the secret is valid for the service with which it is associated. |
| Repository visibility | Filter by whether the repository's visibility status. |
| Secret type | Filter by the type of secret, such as private key, or the web service that makes use of the secret, such as Sendgrid or Stripe. |
| Component | Filter by Semgrep Assistant component tags. Semgrep Assistant uses AI to categorize the file where the finding was identified based on its function, such as payments, user authentication, and infrastructure. |
| Historical findings | Filter for findings that are valid, leaked secrets in previous Git commits. |
Triage status
| Status | Description |
|---|---|
| Open | Findings are open by default. A finding is open if it was present the last time Semgrep scanned the code and it has not been ignored. An open finding represents a match between the code and a rule that is enabled in the repository. Open findings require action, such as rewriting the code to eliminate the detected vulnerability. |
| Ignored | Findings that are ignored are present in the code, but have been labeled as unimportant. Ignore findings that are false positives or deprioritized issues. You can filter findings with a status of Ignored further by reason: False positive, Acceptable risk, No time to fix, or No triage reason. |
| Fixed | Fixed findings were detected in a previous scan, but are no longer detected in the most recent scan of that same branch due to changes in the code. |
Severity
Severity is assigned based on how sensitive or crucial the exposed web service is. Possible values include:
- Critical
- High
- Medium
- Low
Validation
Refers to whether or not a secret is active and can be used to grant resources or authentication, or if a secret is inactive.
| Validation | Description |
|---|---|
| Confirmed valid | Semgrep made an API call using the secret and it returned an HTTP response of 200 or similar and granted authentication. |
| Confirmed invalid | Semgrep made an API call using the secret and it returned an HTTP response of 403 or similar. |
| Validation error | Semgrep made an API call but it returned and HTTP response of 400 or similar; a server error, such as a timeout, occurred. The Semgrep Team recommends manually reviewing the finding. |
| No validator | Semgrep does not perform any validation on this finding. You must manually review the finding. |
Repository visibility
Refers to whether or not the repository is a public repository or private. This is detected through your source code manager.
| Repository visibility | Description |
|---|---|
| Public | Repository access doesn't require authentication; at a minimum, it can be viewed by anyone. |
| Private | Repository access requires authentication. |
| Unknown | Semgrep Secrets is unable to detect your repository visibility. This is typically assigned to:
|
Semgrep supports visibility detection only for GitHub repositories of any plan.
Configure files to ignore
Semgrep Secrets scans all files, even those specified in a local .semgrepignore file, since secrets can often be found in files that aren't relevant for code scanning. To specify files that Semgrep Secrets should ignore:
- Sign in to Semgrep AppSec Platform.
- From the Dashboard Sidebar, select Projects > [Project name].
- Click Secrets to expand and display the Path Ignores box.
- Enter files and folders to ignore in the Path Ignores box.
- Click Save changes.
Upgrade your rules
If you're using Semgrep Code rules to identify leaked credentials, you'll see prompts in Semgrep AppSec Platform indicating that there's an improved version that uses Semgrep Secrets' feature set, primarily its validators, which can validate whether the detected credential is active, and improvements in detecting and hiding false positives.
You can see individual findings for which there is a Semgrep Secrets rule upgrade in Semgrep AppSec Platform's Findings page. The findings are tagged with a label that says Secrets version available! Click to see rule(s).
To see the rules you're using for which there is a Secrets rule upgrade in Semgrep AppSec Platform:
- Sign in to Semgrep AppSec Platform.
- Go to Rules > Policies > Code.
- Under Available rule upgrades, ensure that you've selected Secrets.
Next steps
- Learn how to view and triage secrets in Semgrep AppSec Platform
Additional information
- Learn more about the structure of rules for Semgrep Secrets, as well as how to manage your rules using Semgrep AppSec Platform.
- Learn how to write custom validators for your Semgrep Secrets rules.
Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.