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

Getting started with Semgrep App

Semgrep App supports code scanning from:

  • local command-line interfaces (CLI)
  • source code management (SCM) systems, such as GitHub and GitLab, through continuous integration (CI)

This guide walks you through scanning code in both types of environments.

Semgrep App enables you to run scans on multiple repositories by integrating with your GitHub or GitLab SaaS account. 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 code violations, security issues, outdated libraries, and other issues.

Diagram of Semgrep App flow

Many rules are available from Semgrep Registry, an open-source, community-driven repository of rules. You can also write your own rules to customize Semgrep for your team's specific practices, or publish rules for the community.

With Semgrep App's Rule Board you can determine which rules Semgrep uses and what action Semgrep undertakes when it generates a finding. The Rule Board can block pull requests (PRs) or merge requests (MRs) from merging until findings are resolved. This behavior helps to prevent vulnerable code from shipping to widely-accessible environments, such as production or staging servers.

Semgrep App enables you to deploy, configure, and manage Semgrep in your continuous integration (CI) environment. Semgrep App supports the upload of findings from CLI scans as well. For more information, see Getting started with Semgrep CLI.

Signing in to 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.

Signing in with GitHubโ€‹

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.

Permissions for GitHubโ€‹

This section explains why Semgrep App requires specific permissions. Semgrep App requires the following permissions in order to log in through GitHub:

Verify your GitHub identity
Enables Semgrep App to read your GitHub profile data, such as your username.
Know which resources you can access
Enables Semgrep App to access and display private repositories you can scan.
Act on your behalf
Enables Semgrep App to start or stop scans on the repository and commit files for continuous integration.

The GitHub integration app is called semgrep-app. This app is used to integrate Semgrep into GitHub repositories. It requires the following permissions:

Read and write permissions to GitHub Actions
Allows Semgrep App to cancel stuck jobs, rerun jobs, pull logs from jobs, and perform on-demand scanning.
Read permissions to GitHub Checks
Facilitates debugging of Semgrep App when configured out of GitHub Actions.
Read and write to GitHub Security Events
Enables integration with the GitHub Advanced Security to show Semgrep results.
.semgrepignore single-file access
Allows debugging of requests and automatic syncing of .semgrepignore between the Semgrep App UI and what is checked into the repository.
Read/write GitHub secrets
Enables automatically adding of the Semgrep App Token to your repository secrets when onboarding projects. This simplifies bulk onboarding of repositories. Semgrep App cannot read the values of your existing or future secrets due to the security design of GitHub Secrets. This permission only permits Semgrep App to know the secret name and programmatically adds the Semgrep token to your repository secrets.

Signing in with GitLabโ€‹

  1. Click the following link: Sign into Semgrep.
  2. Select Sign in with GitLab. You are redirected to the GitLab sign in page if you are not currently signed in.
  3. Sign in with your credentials.
  4. Click Authorize. See the GitLab documentation about Authorized applications 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.

Permissions for GitLabโ€‹

Semgrep requires the following permissions (scopes) to enable the authentication of a session:

  • openid
  • email
  • profile

Performing a scanโ€‹

Scanning is Semgrep's primary operation. When you first sign into Semgrep App, it uses a default ruleset selected to enforce best practices for a repository's framework and programming language. Future scans may be further tuned to an organization's specific practices.

Semgrep App 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.

Scanning a new projectโ€‹

A project is a repository from either:

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

Semgrep App can run scans on many projects with rules set in the Rule Board. First-time Semgrep App 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.

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.

Prequisite: Semgrep CLI must be installed. See Getting started with Semgrep CLI.

  1. Ensure you are signed in to Semgrep App.
  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 on the CLI.
  6. After logging in, run a scan by entering the following command. This command sends the findings to Semgrep App.
    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 App.

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: Scanning a repository from GitHub or GitLabโ€‹

Scanning a repository from SCM providers such as GitHub or GitLab ensures that Semgrep scans your codebase every time a PR or MR is created. To add a repository:

Prerequisite: A GitHub or GitLab SaaS repository associated with your account.

  1. Ensure you are signed in to Semgrep App.
  2. Click Projects on the left sidebar.
  3. Optional: If you do not see the repository you want to add in the Projects page of Semgrep app, follow the steps in the succeeding sections to ensure that Semgrep App can detect the repository.
  4. Click Scan new project, and then click Run scan in CI.
  5. Select which repository provider for Semgrep to integrate with.
  6. Follow instructions displayed on Semgrep App page for particular repository provider.
  7. 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.
  8. If successful, Semgrep App scans the repository for the first time using default, pre-selected rules.
Detecting GitHub repositoriesโ€‹

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

  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, scans are triggered through the following parameters, which are defined during a project's initial setup in Semgrep App:

  • Either a daily or weekly schedule.
  • Upon every PR or MR.
  • Upon every update to the semgrep.yml file.

To change these scan parameters, either:

  • Edit the semgrep.yml file manually.

  • Remove the project and redo the steps described in Adding a project section.

Additional scan parameters include:

Rule recommendation
Select this toggle to receive rule recommendations in the Rule Board based on the framework and language of the repository. Rule recommendations are only suggestions and will not be included in a scan unless you add the recommendations into a rule board.
Autofix
Select this toggle to enable autofix, which creates suggestions in addition to PR or MR comments. For example, a rule may suggest using a function such as logging.debug() instead of print().
Path ignores
Paths and files specified here are not scanned by Semgrep App.

To see additional scan parameters:

  1. Click Projects on the left sidebar.
  2. Select the name of the project to modify.
  3. Make edits as necessary.

Adding rules and rulesets to scan withโ€‹

Semgrep App'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 App.
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 App 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 App. 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 is used 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 App'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.

Going further with Semgrep Appโ€‹

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

  • Integrations 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.
  • Developer feedback enables teams to collaborate and improve on scan quality.

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 and can track findings on Jira. See Integrations 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.

Receiving feedback about a ruleโ€‹

Developer feedback is a Team/Enterprise tier feature in which developers can submit feedback about a rule or finding. This is used to evaluate a rule's performance:

  • Is the rule's message clear?
  • Does the rule have too many false positives?
  • Should the rule be ignored for a certain file or block of code?
  • Are there additional improvements to the rule, such as possible autofix values?

Getting supportโ€‹

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

Additional resourcesโ€‹

Semgrep App session detailsโ€‹

  • The time before you need to reauthenticate to Semgrep App is 7 days.
  • Semgrep App session token is valid for 7 days.
  • This session timeout is not configurable.
  • Semgrep App is not using cookies but localStorage to store access tokens. The data in localStorage expire every 7 days.

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