Getting started with Semgrep Secrets

Detect and triage leaked secrets and credentials by scanning with Semgrep Secrets.

Save time by prioritizing which secrets to rotate based on whether they are valid (active and in-use) or not.

Figure. Semgrep Secrets page.

This document guides you through the following:

• Enabling Semgrep Secrets
• Receiving findings in GitHub PR comments
• Triaging findings

To learn about how Semgrep Secrets detects secrets, see Conceptual overview of Semgrep Secrets.

Feature maturity

• This feature is in public beta.
• You or your developers may encounter bugs. For issues, reach out to support@semgrep.com.

Sign-up

To gain access to this feature, fill out the Semgrep Secrets Beta form.

Supported developer environments and features

This section lists the source code managers (SCMs) that Semgrep Secrets supports.

Source code manager	Semgrep Secrets	PR or MR comments for valid secrets findings
GitHub	✔️	✔️
GitLab	✔️	❌
BitBucket	✔️	❌

Enabling Semgrep Secrets

Prerequisites

• Semgrep Secrets can only be enabled through Semgrep Cloud Platform (SCP). Create an account to enable Semgrep Secrets.
• You have added or onboarded at least one repository to Semgrep Cloud Platform for scanning. See Starting a SAST and SCA scan on a remote repository.

1. Contact the Semgrep team by filling out the Semgrep Secrets Beta form.
2. When you have received confirmation that Semgrep Secrets has been activated for your account, sign in to Semgrep Cloud Platform.
3. Click Settings.
4. In the Products section, click the Secrets toggle.
5. Optional: After enabling Semgrep Secrets, you can trigger a full scan manually through your CI provider or wait for your scheduled Semgrep full scan, typically daily.

Scanning environments

A scan can be triggered in the following environments:

• You can start a scan manually from your CI provider if your CI provider supports running CI jobs on-demand. Refer to your CI provider's documentation for details.
• You can start a scan from your CLI. It is recommended to run CLI scans on non-mainline branches, such as feature branches.
• When you open a PR or MR, Semgrep automatically scans the branch.

Scanning for secrets through a CI job

After following the steps in Enabling Semgrep Secrets, all Semgrep scans in your CI jobs include secret scanning. There are no additional steps to take.

After each scan, your findings are displayed in Semgrep Cloud Platform > Secrets.

Troubleshooting

If you do not receive any secrets findings in your scans after enabling Semgrep Secrets, check the following:

• Check the job's log in your CI provider.
  • Search for the following line or similar to ensure that a secrets scan was included as part of the scan: Enabled products: Semgrep Code, Semgrep Supply Chain, Semgrep Secrets
  • If the log does not include the line, your CI job may be running an out-of-date Semgrep version or the wrong semgrep command. Ensure that your Docker image or custom runner is up-to-date, and ensure that you are running semgrep ci.
• Feel free to contact support@semgrep.com for additional assistance.
• If a secrets scan ran successfully, it is unlikely but possible that there are no findings.

Scanning for secrets in your local development machine (CLI)

Prerequisites

• An up-to-date installation of the Semgrep CLI tool. Semgrep Secrets does not work on older versions of Semgrep. See Getting started.
• An existing Semgrep Cloud Platform account.
• An existing Semgrep organization.
• Semgrep Secrets must be enabled in Semgrep Cloud Platform.

You can scan for secrets from your local development machine by using the Semgrep CLI tool.

1. Ensure you are logged in to Semgrep:

semgrep login

2. Run a scan:

semgrep ci

3. Once the scan has completed, you can view that repository's findings in Semgrep Cloud Platform by logging in then clicking Projects, then the number of Secrets findings under REPOSITORY_NAME.
   

Findings from local scans are differentiated from their remote counterparts through their slugs. Remote repositories are identified as ACCOUNT_NAME/REPOSITORY_NAME, while local repositories are identified as REPOSITORY_NAME.

Receiving findings in GitHub through PR comments

This section describes how to set up PR or MR comments from Semgrep.

info

After enabling this feature, only valid (active) secrets-related findings leave a PR or MR comment.

Figure. Semgrep Secrets finding in a PR comment.

Findings in GitHub pull requests

Perform the following steps to receive Secrets findings as comments in GitHub PRs:

1. Follow the steps in GitHub PR comments.
2. Inform support@semgrep.com that you want to enable this feature.

Triaging secrets in Semgrep Cloud Platform

Triage secrets-related findings in the Secrets page. By default, all findings are displayed. A common triage workflow includes the following tasks:

1. Filtering for a particular characteristic of a finding, such as its Validation status, its Repository or Branch, or its Type.
2. Analyzing if the findings are true or false positives.
3. Applying a triage state to the filtered findings based on the analysis in step 2.
   1. Setting a finding as Ignored means that no action is undertaken and the finding is closed. Subsequent scans won't include this finding.
   2. Setting or retaining a finding as Open means that the finding is a true positive and needs to be fixed or resolved.
      1. Optional: You can create a ticket for Linear, Jira, or Asana to assign a developer to fix Open findings.
4. When commits are added to the PR or MR, Semgrep re-scans the PR or MR and detects if a finding is fixed. The finding is resolved automatically upon scanning. Users do not need to set a finding as Fixed manually.

Common filtering use cases

Find and perform bulk operations through filtering. Perform all filter operations in the Secrets page.

Task	Steps
Viewing valid findings	Under Validation, click ⚠️Confirmed valid.
View findings in a specific project or branch	1. Under Projects, select a repository from the drop-down menu. 2. Under Branches, select a branch from the drop-down menu.
View findings of a specific type of secret, such as personal token or password.	Under Type, select a type of secret.
View findings of a specific severity	Under Severity, select a value.

Figure. Secrets page and relevant triaging elements: (a) All available filters; (b) Bulk selection toggle; (c) Bulk triage button.

Triage findings in bulk by performing the following steps:

1. Begin by ensuring that you display all Open findings.
2. Apply filters with as much specificity as possible. You may have to perform bulk triage several times. By starting with the most specific cases, and closing the findings from those specific cases, you are able to narrow down findings as you work from specific to broad filter criteria.
3. Click the bulk select check box.
4. Click Triage, then your selected triage state, typically Ignore.
5. Optional: Repeat this procedure to triage all open findings.

Further customization

• Create tickets in Jira, Linear, or Asana for secrets-related findings. See Ticketing.
• See Secrets API documentation.

Appendix: Semgrep Secrets filters

This section describes what filters are available to quickly sort through findings and perform operations on filtered findings.

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.
Fixed	Fixed findings were detected in a previous scan, but are no longer detected in the most recent scan of that same branch.

Severity

Severity is assigned based on how sensitive or crucial the exposed web service is. Possible values include:

• 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.

info

Semgrep supports visibility detection only for GitHub repositories of any plan.

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: Scans from local developer machines. Scans from any non-GitHub source code manager, such as GitLab.

Type

Refers to the type of secret, such as Private key, or web service that makes use of the secret, such as Sendgrid or Stripe.

Project

A repository that's been onboarded to Semgrep for scanning.

Branch

A branch of any Project.

---

Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.