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.
- Code is not uploaded. Only findings are sent to Semgrep Cloud Platform.
Installing and running Semgrep locally
The Semgrep command-line tool requires Python 3.7 or later.
To install and run Semgrep, use one of the following options:
- macOS
- Linux
- Windows Subsystem for Linux (WSL)
- Docker
Install:
brew install semgrep
Alternatively:
python3 -m pip install semgrep
Confirm installation:
semgrep --version
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.
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.
After creating an organization in the previous step, return to the CLI and run a scan:
semgrep ci
Install:
python3 -m pip install semgrep
Confirm installation:
semgrep --version
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.
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.
After creating an organization in the previous step, return to the CLI and run a scan:
semgrep ci
You must have Windows Subsystem for Linux installed. To install WSL, refer to Microsoft's documentation on Installing Linux on Windows with WSL.
- Within your WSL interface, install Semgrep:
python3 -m pip install semgrep
- Confirm installation:
semgrep --version
- Sign up or log in to Semgrep Cloud Platform (SCP):This command automatically opens a new tab or browser window. You can also click the link in the CLI to complete the step.
semgrep login
- 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.
- After creating an organization in the previous step, return to the CLI and run a scan:
semgrep ci
- Pull the latest image locally:
docker pull returntocorp/semgrep
- Confirm version:
docker run --rm returntocorp/semgrep semgrep --version
- For macOS or Linux Docker users, perform the following steps:
- Sign up or log in to Semgrep Cloud Platform (SCP):This command automatically opens a new tab or browser window. You can also click the link in the CLI to complete the step.
docker run -it returntocorp/semgrep semgrep login
- 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.
- After creating an org in the previous step, return to the CLI and copy the token displayed in the CLI.
- Run the following command to start a scan using recommended Semgrep rules, substituting
YOUR_TOKEN
with the value you copied in the previous step:The provideddocker run -e SEMGREP_APP_TOKEN=YOUR_TOKEN --rm -v "${PWD}:/src" returntocorp/semgrep semgrep ci
-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.
- Sign up or log in to Semgrep Cloud Platform (SCP):
- For Windows Docker users, perform the following steps:
- Sign up or log in to Semgrep Cloud Platform (SCP):
docker run -it returntocorp/semgrep semgrep login
- 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.
- After creating an org in the previous step, return to the CLI and copy the token displayed in the CLI.
- Run the following command to start a scan using recommended Semgrep rules, substituting
YOUR_TOKEN
with the value you copied in the previous step:The provideddocker run -e SEMGREP_APP_TOKEN=YOUR_TOKEN --rm -v "%cd%:/src" returntocorp/semgrep semgrep ci
-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.
- Sign up or log in to Semgrep Cloud Platform (SCP):
You have just finished installing and running a Semgrep scan. Use Semgrep Cloud Platform to triage your findings and view vulnerabilities.
- You can also run
semgrep scan --config=auto
for offline-only SAST scans. No SCA scan is performed with this command.
- 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" returntocorp/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.