Skip to main content

Quickstart

Learn how to set up Semgrep OSS, scan your codebase for security issues, and view your findings in the CLI.

Prerequisites​

See Prerequisites to ensure that your machine meets Semgrep's requirements.

Set up Semgrep​

Install the Semgrep CLI and confirm the installation:

# macOS users only
brew install semgrep

# macOS, Linux, or Windows Subsystem for Linux (WSL) users
python3 -m pip install semgrep

# confirm
semgrep --version

Scan your codebase​

Navigate to the root of your codebase, and run your first scan. The specific command you use depends on how you want to view the results.

To run a scan using recommended rules for your programming language, and view the results in the CLI:

semgrep scan

To export the results to a plain text file:

semgrep scan --text --text-output=semgrep.txt

To export the results to a SARIF file:

semgrep scan --sarif --sarif-output=semgrep.sarif

To export the results to a JSON file:

semgrep scan --json --json-output=semgrep.json

In addition to the --text, --json, and --sarif flags, which set the primary output formats, and the --output=<value> flag that saves the results to a file or posts to a URL, you can append --<format>-output=<file> to obtain additional output streams:

# prints findings in SARIF format to standard output and writes in JSON format to `findings.json`.
semgrep scan --sarif --json-output=findings.json

# prints findings in text to standard out and writes JSON output to `findings.json`.
semgrep scan --json-output=findings.json

# prints text output to `findings.txt` and writes in SARIF to `findings.sarif`.
semgrep scan --output=findings.txt --sarif-output=findings.sarif

# writes text to `semgrep.txt`, JSON to `semgrep.json`, and SARIF to `semgrep.sarif`.
semgrep scan --text --output=semgrep.txt --json-output=semgrep.json --sarif-output=semgrep.sarif

Accepted values for <format>: text, json, sarif, gitlab-sast, gitlab-secrets, junit-xml, emacs, vim

Scan your codebase with a specific ruleset​

You can scan your codebase using --config auto to run Semgrep with rules that apply to your programming languages and frameworks:

semgrep scan --config auto --pro
info

Semgrep collects pseudonymous metrics when you use rules from the Registry. You can turn this off with --metrics=off.

To scan your codebase with a specific ruleset, either one that you write or one that you obtain from the Semgrep Registry, use the --config flag.

# Scan with the rules defined in rules.yaml
semgrep scan --config rules.yaml

You can include as many configuration flags as necessary.

# Scan with rules defined in two separate config files
semgrep scan --config rules.yaml --config more_rules.yaml

Rules stored under a hidden directory, such as dir/.hidden/myrule.yml, are processed by Semgrep when scanning with the --config flag.

Scan with rules in a directory and all its subdirectories:

semgrep scan --config DIRECTORY_NAME

Scan with all YAML rules detected in the current working directory and all its subdirectories:

semgrep scan --config .