Running rules
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:
- One-off ephemeral rules passed into the command line.
- YAML-defined 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 test Semgrep Registry rules with the following command:
semgrep --config=auto PATH/TO/SRC
Substitute the optional placeholder PATH/TO/SRC
with the path to your source code.
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 --config="RULESET-ID" PATH/TO/SRC
- Optional: Run registry rules simultaneously with local rules:
semgrep --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
-e
or--pattern
flags 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.
Ephemeral rules
Use the -e
or --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.
Both local rule.yaml
files and ephemeral rules are called local rules.
YAML-defined rules
To create a local YAML file where you define your own rules and run them with Semgrep, follow these steps:
- Create a
rule.yaml
file. - Below is a simple example rule for Python which you can paste into your
rule.yaml
file.rules:
- id: is-comparison
languages:
- python
message: The operator 'is' is for reference equality, not value equality! Use
`==` instead!
pattern: $SOMEVAR is "..."
severity: ERROR - Run the following command to run local YAML rule files:
semgrep --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 --config p/python --config PATH/TO/MYRULE.YAML
Findings
- See Managing findings for information on Semgrep findings.
- See Ignoring findings for details on suppressing rule output.
Next steps
Find out how to contribute to Semgrep Registry by reading Contributing rules guide.
Number of Semgrep Registry rules
Semgrep supports a large number of languages and rules! Their number is continuously expanding.
Find what you needed in this doc? Join the Semgrep Community Slack group to ask the maintainers and the community if you need help.