Getting started with Semgrep

Detect security issues, vulnerable dependencies, and more by scanning your code with Semgrep. Semgrep performs both SAST (Static application security testing) and SCA (Software composition analysis) scans.

The following guide walks you through:

• Installing Semgrep in your computer locally.
• Running a single scan for both SAST and SCA.
• Sending results to Semgrep Cloud Platform for triage and analysis.

info

• Code is not uploaded. Only findings are sent to Semgrep Cloud Platform.

Installing and running Semgrep locally

Prerequisite

The Semgrep command-line tool requires Python 3.7 or later.

To install and run Semgrep, use one of the following options:

macOS

1. Install:

   brew install semgrep

   Alternatively:

   python3 -m pip install semgrep

2. Confirm installation:

   semgrep --version

3. Sign up or log in to Semgrep Cloud Platform (SCP):

   semgrep login

   This command automatically opens a new tab or browser window. You can also click the link in the CLI to complete the step.

4. A modal appears after logging in to SCP. Click Create an organization. Note that you can further integrate organizations (orgs) with GitLab accounts and GitHub accounts, including personal and org accounts, after you complete this procedure.

5. After creating an organization in the previous step, return to the CLI and run a scan:

   semgrep ci

Linux

1. Install:

   python3 -m pip install semgrep

2. Confirm installation:

   semgrep --version

3. Sign up or log in to Semgrep Cloud Platform (SCP):

   semgrep login

   This command automatically opens a new tab or browser window. You can also click the link in the CLI to complete the step.

4. A modal appears after logging in to SCP. Click Create an organization. Note that you can further integrate organizations (orgs) with GitLab accounts and GitHub accounts, including personal and org accounts, after you complete this procedure.

5. After creating an organization in the previous step, return to the CLI and run a scan:

   semgrep ci

Windows Subsystem for Linux (WSL)

Prerequisite

You must have Windows Subsystem for Linux installed. To install WSL, refer to Microsoft's documentation on Installing Linux on Windows with WSL.

1. Within your WSL interface, install Semgrep:

   python3 -m pip install semgrep
2. Confirm installation:

   semgrep --version
3. Sign up or log in to Semgrep Cloud Platform (SCP):

   semgrep login
   This command automatically opens a new tab or browser window. You can also click the link in the CLI to complete the step.
4. A modal appears after logging in to SCP. Click Create an organization. Note that you can further integrate organizations (orgs) with GitLab accounts and GitHub accounts, including personal and org accounts, after you complete this procedure.
5. After creating an organization in the previous step, return to the CLI and run a scan:

   semgrep ci

Docker

1. Pull the latest image locally:

   docker pull semgrep/semgrep
2. Confirm version:

   docker run --rm semgrep/semgrep semgrep --version
3. For macOS or Linux Docker users, perform the following steps:
   1. Sign up or log in to Semgrep Cloud Platform (SCP):

      docker run -it semgrep/semgrep semgrep login
      This command automatically opens a new tab or browser window. You can also click the link in the CLI to complete the step.
   2. A modal appears after logging in to SCP. Click Create an organization. Note that you can further integrate organizations (orgs) with GitLab accounts and GitHub accounts, including personal and org accounts, after you complete this procedure.
   3. After creating an org in the previous step, return to the CLI and copy the token displayed in the CLI.
   4. Run the following command to start a scan using recommended Semgrep rules, substituting YOUR_TOKEN with the value you copied in the previous step:

      docker run -e SEMGREP_APP_TOKEN=YOUR_TOKEN --rm -v "${PWD}:/src" semgrep/semgrep semgrep ci
      The provided -v option mounts the current directory into the container to be scanned. Change directories locally or provide a specific local directory in the command to scan a different directory.
4. For Windows Docker users, perform the following steps:
   1. Sign up or log in to Semgrep Cloud Platform (SCP):

      docker run -it semgrep/semgrep semgrep login
   2. A modal appears after logging in to SCP. Click Create an organization. Note that you can further integrate organizations (orgs) with GitLab accounts and GitHub accounts, including personal and org accounts, after you complete this procedure.
   3. After creating an org in the previous step, return to the CLI and copy the token displayed in the CLI.
   4. Run the following command to start a scan using recommended Semgrep rules, substituting YOUR_TOKEN with the value you copied in the previous step:

      docker run -e SEMGREP_APP_TOKEN=YOUR_TOKEN --rm -v "%cd%:/src" semgrep/semgrep semgrep ci
      The provided -v option mounts the current directory into the container to be scanned. Change directories locally or provide a specific local directory in the command to scan a different directory.

You have just finished installing and running a Semgrep scan. Use Semgrep Cloud Platform to triage your findings and view vulnerabilities.

tip

• You can also run semgrep scan --config=auto for offline-only SAST scans. No SCA scan is performed with this command.

note

• By default, when Semgrep Registry is used, Semgrep collects usage metrics.
• If you install Semgrep through Homebrew, ensure that you have added Homebrew to your PATH. See My Mac .apps don’t find Homebrew utilities! in Homebrew documentation.

Next steps

By completing this guide, you are now familiar with a simple use of Semgrep. Here are some additional resources to follow:

• Follow tutorials on Learn Semgrep to learn about Semgrep interactively.
• See Running rules to try out and understand more about Semgrep rules.
• See CLI Reference for command line options and exit codes.
• Explore the Semgrep Rules Registry to add rules to your project or writing a rule.
• Read the Trail of Bits Automated Testing Handbook to learn about configuring and optimizing security tools, including Semgrep.

Testing Semgrep on vulnerable repositories

The following community projects are designed to test code scanners and teach security concepts. Try cloning and scanning them with Semgrep.

Expand for sample projects! 🎉

# juice-shop, a vulnerable Node.js + Express app:
git clone https://github.com/bkimminich/juice-shop
cd juice-shop
semgrep --config=auto

# Or if you don't have Semgrep installed, replace the semgrep command with:
docker run --rm -v "$(pwd)/juice-shop:/src" semgrep/semgrep semgrep --config p/security-audit /src

# Try railsgoat, a vulnerable Ruby on Rails app:
git clone https://github.com/OWASP/railsgoat
cd railsgoat
semgrep --config=auto

# govwa, a vulnerable Go app:
git clone https://github.com/0c34/govwa
cd govwa
semgrep --config=auto 

# Vulnerable-Flask-App, vulnerable Python + Flask:
git clone https://github.com/we45/Vulnerable-Flask-App
cd Vulnerable-Flask-App
semgrep --config=auto 

# WebGoat, a vulnerable Java + Spring app:
git clone https://github.com/WebGoat/WebGoat
cd WebGoat
semgrep --config=auto 

Run Semgrep continuously

Semgrep is at its best when used to continuously scan code. Check out Semgrep in CI to learn how to get results where you already work: GitHub, GitLab, Slack, Jira, and more. To get results even earlier in the development process, such as in a Git pre-commit hook or VS Code, check the available Semgrep extensions.

Check out Semgrep Cloud Platform (SCP) to integrate Semgrep scans into your CI environment with PR or MR comments, monitor progress, host private rules (Team and Enterprise tiers), and much more!

Updating Semgrep

We release new Semgrep versions often! See Updating for more details.

---

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