Skip to main content

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:

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.

Prerequisites

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
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

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:

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

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

Findings​

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.