Skip to main content

Run rules

Semgrep OSS performs static application security testing (SAST) scans through the use of rules. Rules are instructions based on which Semgrep detects patterns in code.

When Semgrep reports code using specified rules, the detected code is called a finding. The process of scanning and detecting a piece of code is also called matching, as Semgrep matches the code using rules to report a finding.

Semgrep findings can help you find security, performance, or correctness issues, 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.

Public rules are stored in the 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.

The list below covers different kinds of Semgrep rules:

Running Semgrep Registry rules locally​

You can run a SAST scan in your git environment with pre-selected Semgrep Registry rules:

semgrep scan --config=auto
info

By default, when Semgrep Registry is used, Semgrep collects usage metrics.

Explore the Semgrep Registry by following these steps:

  1. See the Semgrep Registry, click a ruleset, and then choose a rule.
  2. On the page of the rule, click Run Locally.
  3. 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
  4. Optional: Run registry rules simultaneously with local rules:
    semgrep scan --config="RULESET-ID" --config=PATH/TO/MYRULE.YAML PATH/TO/SRC

Creating and using local rules​

Local rules can be either:

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

Substitute the optional placeholder PATH/TO/SRC with the path to your source code.

info

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:

  1. Create a rule.yaml file.
  2. 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
  3. Run the following command to run local YAML rule files:
    semgrep scan --config PATH/TO/MYRULE.YAML

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

For more information on defining custom rules, see Writing rules.

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

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.

Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.