Running rules
Introductionโ
Rules are specific patterns based on which Semgrep reports findings in code. These findings may help you to catch issues of security, performance, correctness, and other bugs. Rules are stored in open-source Semgrep Registry that enables you to scan code without need to write anything custom.
Contribute to the registry by writing your own rules and adding them to the Semgrep rules repository.
You can run existing and custom Semgrep rules locally with the Semrgep command line tool or continuously with Semgrep CI. See Getting started for their respective installation and setup.
Run Registry rulesโ
Explore the Semgrep Registry and run rules and rulesets via:
# Automatically survey languages and frameworks and run recommended Registry rules
semgrep --config=auto path/to/src
# Run a ruleset with rules for many languages using --config
semgrep --config=<ruleset-id> path/to/src
# Run simultaneously with Registry rulesets and local rules
semgrep --config=<ruleset-id> --config=path/to/yml path/to/src
note
--config auto
sends your repository's project URL to Semgrep Registry to find rules configured for your repository and as a key for cached rule recommendations.- When Semgrep Registry is used, usage metrics are collected by default.
Rulesets can be added to Semgrep CI scans using their "Add to Policy" button on Semgrep Community and Semgrep Team.
Run 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.
tip
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
YAML-defined rulesโ
Create a YAML rule file that you can run repeatedly.
- Create a
rule.yaml
file. - Below is a simple example rule for Python which you can paste into your
rule.yaml
file.See Getting started for the full example.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/rule.yaml
Running multiple rules simultaneouslyโ
To run multiple rules simultaneously, use --config
before every YAML URL, or Semgrep registry entry name. See the following code example (substitute the colored values as necessary):
semgrep --config p/python --config myrules/myrule.yaml
Appendixโ
We are working on optimizations to improve Semgrep's performance, which necessitates a change in rules processing. If you are using v0.55.0 or later and encounter an unexpected metavariable binding or missing result, try running with --optimizations none
to use the original code path.
You may find some files that Semgrep previously parsed are now skipped; this happens when Semgrep can confirm the rule does not match the file without parsing it. You can similarly run Semgrep with --optimizations none
to avoid this behavior.
Findingsโ
- See Managing findings for information on Semgrep findings.
- See Ignoring findings for details on suppressing rule output.
Find what you needed in this doc? Join the Slack group to ask the maintainers and the community if you need help.