Rules are instructions based on which Semgrep detects patterns in code. When Semgrep reports a code using mentioned rules, the detected code is called a finding. The process of scanning and detecting a piece of code is sometimes called matching, as Semgrep matches the code using rules to report a finding.
Semgrep findings can help you to find issues of security, performance, correctness, and enforce best practices. You can define custom rules through Semgrep's rule syntax or rely on rules created by the community or Semgrep, Inc. Rules are stored in Semgrep Registry which enables you to scan code without the need to write anything custom. Semgrep Registry is stored in an open-source repository.
Rules can be organized in rulesets. Rulesets are rules related through a programming language, OWASP category, or framework. The rulesets are curated by the team at Semgrep and updated as new rules are added to the Semgrep Registry. Therefore, you do not have to check the registry to pull individual rules.
The list below covers different kinds of Semgrep rules:
- Existing Semgrep Registry rules. You can also contribute to the open source Semgrep Registry, see Contributing rules.
- Local rules:
- A combination of local rules and Semgrep Registry rules or a combination of multiple rules in general.
You can run all rules on your code locally or continuously in your Source Code Management (SCM) service (such as GitHub or GitLab) with Semgrep in CI. For more information, see the Semgrep CI overview.
Running Semgrep Registry rules locally
You can scan your git environment with pre-selected Semgrep Registry rules, then send the resulting findings (no code is uploaded) to Semgrep Cloud Platform. This is the recommended method to run Semgrep, as a record of your findings is created and can be tracked and triaged from detection to fixed or ignore states.
- An existing Semgrep Cloud Platform account
- An up-to-date Semgrep CLI installation.
Log in to Semgrep Cloud Platform and run a scan:
semgrep login && semgrep ci
Similarly you can run a SAST scan offline running pre-selected Semgrep Registry rules:
semgrep scan --config=auto
By default, when Semgrep Registry is used, Semgrep collects usage metrics.
Explore the Semgrep Registry by following these steps:
- See the Semgrep Registry, click a ruleset, and then choose a rule.
- On the page of the rule, click Run Locally.
- Copy the code for local install, and then add the path to the source code you want to check in your terminal:
semgrep scan --config="RULESET-ID" PATH/TO/SRC
- Optional: Run registry rules simultaneously with local rules:
semgrep scan --config="RULESET-ID" --config=PATH/TO/MYRULE.YAML PATH/TO/SRC
Running Semgrep Registry continuously
To use Semgrep Registry continuously in your CI/CD pipeline, see the Semgrep in CI documentation.
Creating and using local rules
Local rules can be either:
- Ephemeral rules with the
--patternflags for use in a single command.
- Configured in YAML rule files that conform to the Rule syntax schema.
See Writing rules > Getting started to learn how to write rules.
--pattern flags in your terminal for ephemeral rules that are used once.
For example: Check for Python
== where the left and right sides are the same (often a bug):
semgrep -e '$X == $X' --lang=py PATH/TO/SRC
Substitute the optional placeholder
PATH/TO/SRC with the path to your source code.
rule.yaml files and ephemeral rules are called local rules.
To create a local YAML file where you define your own rules and run them with Semgrep, follow these steps:
- Create a
- Below is a simple example rule for Python which you can paste into your
- id: is-comparison
message: The operator 'is' is for reference equality, not value equality! Use
pattern: $SOMEVAR is "..."
- Run the following command to run local YAML rule files:
semgrep scan --config PATH/TO/MYRULE.YAML
For more information, see Getting started.
Running multiple rules simultaneously
To run multiple rules simultaneously, use
--config before every YAML URL, or Semgrep registry entry name. This option let's you include your local rules as well as Semgrep Registry rules. See the following code example (substitute the colored values as necessary):
semgrep scan --config p/python --config PATH/TO/MYRULE.YAML
- See Managing findings for information on Semgrep findings.
- See Ignoring findings for details on suppressing rule output.
Number of Semgrep Registry rules
Semgrep supports a large number of languages and rules! Their number is continuously expanding.