Skip to main content
  • Semgrep Supply Chain
  • Team & Enterprise Tier

Getting started with Semgrep Supply Chain

Semgrep Supply Chain detects recently discovered security vulnerabilities in your codebase's open source dependencies, prioritizing findings through reachability analysis.

This document walks you through the process of setting up open source dependency scanning with Semgrep Supply Chain.

To learn more about how Semgrep Supply Chain performs reachability analysis, see Overview of Semgrep Supply Chain.

note

Semgrep Supply Chain supports monorepositories (monorepos) by treating each subdirectory as its own repository. Findings are grouped under these repositories based on the lockfile or manifest file present in the subdirectory.

Scanning with Semgrep Supply Chain through Semgrep App​

tip

This is the preferred method to enable and run Semgrep Supply Chain.

Semgrep Supply Chain scans can be set up from the Semgrep App interface.

Perform the following steps to create an account in Semgrep App and add (onboard) a repository for scanning. By adding a repository to Semgrep App, you are able to set up Semgrep Supply Chain scans and receive findings for vulnerabilities which you can triage and remediate.

Read Step 3 if you have already created an account in Semgrep App and added a repository.

Step 1: Creating an account in Semgrep App​

Signing in to Semgrep App requires either a GitHub or GitLab account. Semgrep App supports Single Sign-On (SSO) on Team or Enterprise tiers. This guide focuses on GitHub and GitLab sign-ins. See SSO Configuration for information on single sign-on.

Prerequisite

A GitHub or GitLab SaaS account. The account is used to confirm your identity.

To sign in to Semgrep with a GitHub account:

  1. Click the following link: Sign into Semgrep.
  2. Select Sign in with GitHub. You are redirected to the GitHub sign in page if you are not currently signed in.
  3. Sign in with your credentials.
  4. Click Authorize semgrep-app. See the GitHub documentation about Authorizing GitHub Apps to understand the scope of permissions requested by Semgrep.
  5. You are redirected back to Semgrep App.
  6. Click Accept to accept Semgrep's Terms of Service.
  7. Optional: Fill out the survey and click Complete or click Skip to omit this step.

You are now signed in to Semgrep App.

See Permissions in GitHub to learn more about how Semgrep features use requested permissions in GitHub.

Step 2: Adding or onboarding a new repository​

Adding a repository from GitHub or GitLab enables Semgrep App to perform many of its core features, such as the ability to record, triage, and manage findings.

Prerequisite

A GitHub or GitLab SaaS repository associated with your account.

To add a repository from GitHub or GitLab, follow these steps:

  1. Ensure you are signed in to Semgrep App.
  2. Click Projects on the left sidebar.
  3. Optional: For GitHub Actions. If you do not see the repository you want to add, adjust GitHub Application's Repository Access configuration. See Detecting GitHub repositories for more information.
  4. Click Scan new project, and then click Run scan in CI.
  5. Select which CI provider for Semgrep to integrate with.
  6. Follow the instructions displayed on Semgrep App page for your particular CI provider.

You have now added a repository to Semgrep App.

Detecting GitHub repositories​

To ensure that your GitHub repository is detected by Semgrep App:

  1. Log into GitHub.
  2. Click your profile photo > Settings.
  3. Under Integrations, click Applications.
  4. On the semgrep-app entry, click Configure.
  5. Under Repository access select an option to provide access:
    1. All repositories enables Semgrep App to detect all current and future public and private repositories.
    2. Only select repositories will display explicitly selected repositories.

Step 3: Enabling Semgrep Supply Chain scans from Semgrep App​

To enable and run a Supply Chain (open source dependency) scan in Semgrep App:

  1. Sign in to your Semgrep App account, and then go to Projects page.
  2. Click Projects, and then click gear icon of the repository on which to run Supply Chain rules.
  3. Click Supply Chain. Semgrep Supply Chain rules are included in your next scan, that occurs based on your CI set up, such as schedules and events configuration (push, pull, and merge requests).
  4. Optional: Some CI providers enable you to start workflows manually. To start a dependency scan immediately, go to your CI provider's interface and manually begin the Semgrep workflow or job.

When the scan finishes, Semgrep App displays an overview of findings in the Supply Chain page for further triage and remediation. See Triaging and remediating dependency findings.

Events that trigger a Supply Chain dependency scan​

Dependency scans can be triggered by the following, depending on your CI set up:

EventScope of scanDependency rule set
Pull or merge requestdiff-aware scanAll dependency rules
Push or scheduled event, such as a cron jobfull scanAll dependency rules

For more information on diff-aware and full scans, see Diff-aware scanning.

Blocking a PR or MR​

Both reachable and unreachable findings of Semgrep Supply Chain do not block a pull request or merge request.

info

Semgrep versions v0.122.0 and below previously blocked reachable findings.

Step 4: Set a daily scan schedule​

Semgrep Supply Chain frequently releases new rules. To ensure that your repository is scanned with the latest Semgrep Supply Chain rules, configure Semgrep Supply Chain to scan your codebase every day.

The following table is a summary of methods and resources to set up schedules for different CI providers.

CI providerWhere to set scheduleResource
GitHub ActionsWithin semgrep.yml fileSample code snippet
GitLab CI/CDWithin GitLab CI/CD interfaceOfficial documentation
JenkinsWithin Jenkins interfaceOfficial documentation
BitBucket PipelinesWithin BitBucket Pipelines interfaceOfficial documentation
CircleCIWithin CircleCI interfaceOfficial documentation
BuildkiteWithin Buildkite interfaceOfficial documentation
Azure PipelinesWithin Pipelines interface (recommended)Official documentation

Your Semgrep Supply Chain scan setup is now complete.

Ignoring dependency findings through semgrepignore​

See Ignoring dependency findings.

Triaging and remediating dependency findings​

Semgrep Supply Chain enables developers to perform triage and remediation through the Vulnerabilities page. On this page you can perform the following actions:

  • View specific reachable vulnerable lines of code in your codebase. This helps to evaluate the threat.
  • View specific lines of code where your dependency is being declared.
  • Triage a dependency finding.
  • Attach a PR or MR, or Jira ticket to the finding.
  • Upgrade the dependency that generated the finding to a safe version. A safe version is any newer version of the dependency that does not contain the vulnerability. This resolves the finding.

For more information, see Triaging and remediating findings.

Appendix: Setting up SSC scans for specific project management tools​

Apache Maven (Java)​

Semgrep Supply Chain does not read pom.xml files to parse Maven projects. Instead it parses a dependency tree generated by Maven (mvn). Perform the following steps to enable Semgrep Supply Chain to correctly parse Maven projects:

  1. Generate a file outlining the project's dependency tree by adding the following command to your build pipeline:
    mvn dependency:tree -DoutputFile=maven_dep_tree.txt
    For specific steps to add the command into your build pipeline, refer to your CI provider's documentation.
  2. For each pom.xml file with dependencies you want to scan, create additional dependency trees in their respective directories. Semgrep Supply Chain can detect and parse them all.
  3. Run the Semgrep workflow, action, or step after the dependency tree or trees have been generated.
caution
  • Ensure that Maven is installed in the build environment that is used to generate the dependency trees.
  • Ensure that you generate dependency trees before running Semgrep.

You can run the above commands in a local environment to test its behavior. The following screenshot displays the commands running in a local environment:

Screenshot of Maven dependency tree generated in a local environment


Find what you needed in this doc? Join the Semgrep Community Slack group to ask the maintainers and the community if you need help.