Skip to main content
  • Semgrep Code
  • Team & Enterprise Tier
  • Community Tier

Getting started with Semgrep Code

Secure your code quickly and continuously by scanning with Semgrep Code, a fast and lightweight SAST (Static Application Security Testing) engine that leverages Semgrep OSS.

Semgrep uses rules to scan code. Matches found based on those rules are called findings. A Semgrep rule encapsulates pattern-matching logic and data-flow analysis used to find vulnerabilities such as code violations, security issues, or outdated libraries.

Semgrep Code is transparent: you can fully configure what rules are run and inspect the Semgrep syntax to understand how the finding was detected. The content of a rule can be customized to improve the true positive rate of a rule or its message to fellow developers.

This document provides steps to get started with Semgrep Code for all tiers except where indicated.

Semgrep Code with Semgrep Cloud Platform​

Semgrep Code includes Semgrep Cloud Platform (SCP), a web application that helps security teams meet their goals, such as:

  • Sorting, filtering, triaging, and remediating security issues.
  • Enforcing coding standards through the creation of custom rules.
  • Preventing insecure code from reaching production or staging servers by blocking pull or merge requests, based on how you configure your rules.
  • Notifying security teams of findings (results) as well as communicating with other developers by leaving pull or merge request comments in GitHub, GitLab, or BitBucket.
SUGGESTED WORKFLOWS
  • You can use SCP to scan remote repositories (GitHub, GitLab, or BitBucket) and consolidate the findings.
  • You can also use Semgrep Cloud Platform to consolidate findings from a Semgrep CLI scan performed on a local machine.
  • Semgrep Code can be integrated into your custom infrastructure without SCP. See API for details.

Scanning a repository​

Signing in to Semgrep Cloud Platform​

Signing in to Semgrep Cloud Platform requires either a GitHub or GitLab account. Semgrep Cloud Platform 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. You are redirected back to Semgrep Cloud Platform.
  5. Click Accept to accept Semgrep's Terms of Service.
  6. Optional: Fill out the survey and click Complete or click Skip to omit this step.

You are now signed in to Semgrep Cloud Platform with a personal account.

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

tip

To use Semgrep with your team, create an organization account. An organization account enables users to share rules and perform triage or remediation as a team.

Performing a scan​

Scanning is Semgrep's primary operation. When you first sign into Semgrep Cloud Platform, it uses a default SAST ruleset selected to enforce best practices for a repository's framework and programming language. You can customize future scans to address your organization's specific practices.

Semgrep Cloud Platform enables users to choose what findings prevent a pull or merge request (PR or MR) from merging into the repository. Setting these blocking and non-blocking rules is achieved through the Rule Board.

Adding or onboarding a new project (repository)​

A project is a repository from either:

  • Your GitHub, GitLab, or BitBucket account that you add to Semgrep Cloud Platform for scanning.
  • A local Git repository in your machine. Projects from your local machine are integrated through Semgrep CLI.

Semgrep Cloud Platform can run scans on many projects with rules set in the Rule Board. First-time Semgrep Cloud Platform users scan projects with pre-selected rules chosen based on the repository's language and framework. To view these pre-selected rules, see the Registry default ruleset.

Over time, users modify the Rule Board with rules specific to their codebase's security or business goals.

Optional workflows

Option A: Scanning a local repository through Semgrep CLI​

Scanning a project from the CLI is a standalone action. This means that you manually triggered the scan. Scans from CLI are not continuous nor scheduled, unlike scans run in a CI job.

Prerequisites
  • Semgrep CLI must be installed. See Getting started with Semgrep OSS Engine.
  • Ensure that you are running a recent version of Semgrep CLI. Semgrep Cloud Platform supports the 10 most recent minor versions of Semgrep CLI.

To scan a local repository through Semgrep CLI, follow these steps:

  1. Ensure you are signed in to Semgrep Cloud Platform.
  2. Click Projects on the left sidebar.
  3. Click Scan new project > Run a scan locally.
  4. Log in to Semgrep from the CLI:
    semgrep login
  5. Follow the instructions in the CLI.
  6. After logging in, run a scan by entering the following command. This command sends the findings to Semgrep Cloud Platform.
    semgrep ci
  7. View your project's findings.
note

Scans from local repositories do not access their corresponding remote repositories. For this reason, links to specific lines of code in the Findings page are not created. See Linking local scans to their remote repositories for a workaround.

Linking local scans to their remote repositories​

Screenshot of findings page snippet with no hyperlinks Figure 1. Partial screenshot of findings page with no hyperlinks.

Local repository scans require additional configuration to create hyperlinks to their corresponding remote repositories. Set up environment variables within your command line to configure cross-linking between local and remote repositories within Semgrep Cloud Platform.

Screenshot of sample environment variables on a Linux shell Figure 2. Sample environment variables set up on a Linux shell.

To set up environment variables:

  1. Ensure that your current working directory is the root of the repository to create links for.
  2. Set up the SEMGREP_REPO_URL:
    1. Retrieve the URL by navigating to your online repository. Copy the value in the address bar. This is your URL_ADDRESS.
    2. Set the variable by entering the text below, substituting URL_ADDRESS with the value from the previous step.
      export SEMGREP_REPO_URL=URL_ADDRESS
  3. Set up the SEMGREP_BRANCH:
    1. Run the following to retrieve the branch name:
      git rev-parse --abbrev-ref HEAD
    2. Set the variable by entering the text below, substituting BRANCH_NAME with the value from the previous step.
      export SEMGREP_BRANCH=BRANCH_NAME
  4. Set up the SEMGREP_REPO_NAME:
    1. Retrieve the repository name by logging in to your GitHub or GitLab account and copying the repository name from your dashboard.
    2. Set the variable by entering the text below, substituting REPO_NAME with the value from the previous step.
      export SEMGREP_REPO_NAME=REPO_NAME
  5. Set up the SEMGREP_COMMIT:
    1. Run the following to retrieve the commit hash:
      git log -n 1
    2. Set the variable by entering the text below, substituting COMMIT_HASH with the value from the previous step.
      export SEMGREP_COMMIT=COMMIT_HASH

Sample values:

# Set the repository URL
$> export SEMGREP_REPO_URL=https://github.com/corporation/s_juiceshop

# Set the repository name
$> export SEMGREP_REPO_NAME=corporation/s_juiceshop

# Retrieve the branch 
$> git rev-parse --abbrev-ref HEAD
s_update
# Set the branch
$> export SEMGREP_BRANCH=s_update

# Retrieve the commit hash
$> git log -n 1
commit fa4e36b9369e5b039bh2220b5h9R61a38b077f29 (HEAD -> s_juiceshop, origin/master, origin/HEAD, master)
# Set the commit hash
$> export SEMGREP_COMMIT=fa4e36b9369e5b039bh2220b5h9R61a38b077f29

Screenshot of findings page snippet with hyperlinks

Figure 3. Partial screenshot of findings page with hyperlinks.

Option B: Adding a repository from GitHub, GitLab, or BitBucket​

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

Prerequisite
  • For GitHub or GitLab SaaS users: A GitHub or GitLab SaaS repository associated with your account.
  • For BitBucket SaaS users: A BitBucket repository and sufficient permissions to edit a BitBucket Pipeline and add repository variables.

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

  1. Ensure you are signed in to Semgrep Cloud Platform.
  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 Cloud Platform page for your particular CI provider.

You have now added a repository to Semgrep Cloud Platform. A scan begins automatically after adding a new repository.

Detecting GitHub repositories​

To ensure that your GitHub repository is detected by Semgrep Cloud Platform:

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

Running a scan​

By default, Semgrep scans are defined during a project's initial setup in Semgrep Cloud Platform. Semgrep scans are triggered by the following parameters:

  • Daily or weekly schedule.
  • After every PR or MR.
  • Update to the semgrep.yml file (dependent on your CI provider).

To change these scan parameters:

  • Manually edit the semgrep.yml file.
  • Remove the project and redo the steps described in Scanning a new project section.

Set up additional scan parameters in your organization's Settings page.

You can also configure additional configuration options for a specific project. To configure project specific settings, follow these steps:

  1. Click Projects on the left sidebar.
  2. Select the name of the project to modify, and then click the respective gear icon in the Settings column.
  3. Make changes as necessary.
Path ignores
Specify which directories or files you want to exclude from Semgrep scans. See Defining ignored files and folders in Semgrep Cloud Platform for specific details.
Tags
Add or remove tags to specific projects. See Tagging projects for more information.

Adding rules and rulesets to scan with​

Semgrep Cloud Platform's Rule Board displays all rules and rulesets that are used to scan repositories. These rules are scanned based on the repository's programming language and framework as well as additional Semgrep parameters, such as ignored files.

For example, given five repositories each with different programming languages, the Rule Board only scans using rules and rulesets for that repository's language that are in the Rule Board.

Semgrep's speed is not affected by having multiple rules for different languages in the Rule Board.

You may select rules and rulesets from your own rules, your organization's rules, or rules from the Registry.

Screenshot of Rule board

The Rule Board is composed of three columns:

Monitor
Rules here show findings only on Semgrep Cloud Platform.
Comment
Rules here show findings to developers through PRs or MRs.
Block
Rules here show block merges and commits, in addition to showing findings in Semgrep Cloud Platform and PRs or MRs.

To add rules and rulesets to your Rule Board:

  1. Click Rule Board on the left sidebar.
  2. Click Add Rules. A right-side drawer appears.
  3. Type in a search term relevant to your codebase's framework or programming language.
  4. Drag a card from the search results to the appropriate column.
  5. Select Save changes.

For more information on operations such as filtering and deleting as well as Rule board management, see Rule board.

Viewing and managing findings​

Viewing findings of a scan​

Screenshot of Dashboard

Both the Dashboard and the Findings page display the results of a scan. These pages are accessible from the left sidebar in Semgrep Cloud Platform. The Dashboard is a report view to assist in evaluating security posture across repositories. It organizes findings into OWASP categories, enabling users to assess habits and trends within their team or organization.

The Findings page enables you to triage findings. Triaging refers to prioritizing a finding based on criteria set by your team or organization. While severity is a factor in triage, your organization may define additional criteria based on coding standards, business, or product goals.

To see the rule specifics that triggered the finding, click on the rule entry.

Automatically resolving findings​

Screenshot of autofix in GitHub

Include code suggestions that resolve findings in both GitHub and GitLab through Semgrep Cloud Platform's autofix feature. This improves the fix rate of findings by reducing the steps needed to resolve a finding. See the section above on Running a scan to enable autofix.

To enable autofix for all projects in your Semgrep Cloud Platform organization, follow these steps:

  1. In Semgrep Cloud Platform, click Settings on the left sidebar.
  2. Click Autofix toggle.

Semgrep Code and Semgrep OSS Engine​

The following table shows differences between Semgrep Code and Semgrep OSS Engine:

FeatureDescriptionSemgrep OSS EngineSemgrep Code
Semgrep CLIRun local scans.✔️✔️
Semgrep CIRun scans on remote repositories.✔️✔️
Custom rulesWrite your own rules tailored to your organization's needs.✔️✔️
Community rulesMake use of community-contributed rules.✔️✔️
Semgrep Cloud PlatformManage findings, rules, and alerts in a centralized location.❌✔️
Semgrep Pro EngineRun Semgrep with interprocedural and interfile analysis.❌✔️ *
Semgrep Pro rulesRules leveraging Semgrep Pro Engine to detect hardcoded secrets, XXE injections, deserialization issues, and more.❌✔️ *
Findings retentionKeep track of when a finding is created and resolved.❌✔️
Alerts & notificationsReceive alerts to catch issues before they reach live servers.❌✔️
Findings managementFilter and sort findings in bulk.❌✔️
API and webhooksQuery and receive scan data for your custom infrastructure.❌✔️

These features require a Team-tier license or above.

Going further with Semgrep Cloud Platform​

Semgrep Cloud Platform supports various phases of the development cycle through the following features:

  • Alerts and notifications keep teams informed without having to leave their working environments, such as Slack or email.
  • Forking Registry rules to easily write custom rules, enabling teams to enforce their own standards.
  • User management and collaboration features for security teams to work as a team in for rule-writing, triage, and remediation.

Tracking findings and receiving notifications​

Receive notifications of new findings through email and Slack after every scan. Additionally, Enterprise or Team tier users are able to set up notifications through webhooks. See Alerts and notifications documentation for more information.

Writing your own rules​

Semgrep's pattern-matching behavior resembles a linter, but its data flow engine extends Semgrep's capabilities as a static application security testing (SAST) tool.

Semgrep provides the following environments to learn, experiment, and write Semgrep rules:

Tutorial
Learn Semgrep's pattern matching syntax, rule composition, and advanced features.
Playground
Learn the nuances of Semgrep operators by creating your own rules and run Semgrep on your own test cases.
Editor
Fork existing security rules to customize them for your own organization or team's use in this advanced editor. Refer to Writing rules using Semgrep Editor.

User management​

You can onboard (add) your entire organization's users and repositories by creating an organization account. Additionally, Semgrep Cloud Platform provides role-based access control (RBAC) for Team or Enterprise tiers. See User management, accounts, and roles to learn more.

Getting support​

Refer to Troubleshooting Semgrep Cloud Platform for common installation issues. Help is also available for all users through the Semgrep Community Slack.

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