Creating and managing rules with Semgrep Playground

Semgrep Playground is a live editor used to create and test rule patterns on sample code. By testing rule patterns on sample code, you are able to quickly assess the purpose, utility, and speed of a rule as well as save it for later refinement, reuse, or sharing.

The Playground is composed of three panes and a top menu.

Library

View and open various rules through the library. You must be signed in to view your saved rules and access the Registry.

Rule editor

Enter your rule's YAML schema in this pane. This pane supports both a simple and advanced view.

Sample code

Enter test code in this pane and click the Run button to verify that the rule performs as intended. A matches panel appears after Semgrep is run to display matches and tests. This pane also contains metadata editing and docs viewing functionalities.

Top menu

Save, share, and add your rule to the Rule Board through this menu.

To resize the panes, position your mouse over the borders and drag to the desired width. You can hide the entire library pane to give more space for the editing panes.

Creating a rule

Use two modes to create a rule:

Simple mode

Simple mode is best for quick and simple pattern-matching use cases, but does not display all Semgrep operators.

Advanced mode

Advanced mode provides the minimum required YAML keys for a Semgrep rule. To complete the rule, advanced mode requires users to fill in additional keys such as pattern operators or metadata.

Learning Semgrep basics through simple mode

Simple mode provides the most common pattern-matching operators in Semgrep.

The following keys are supported in this mode as drop-down boxes:

• language
• pattern
• pattern-either
• pattern-inside
• pattern-not
• pattern-not-inside
• pattern-regex
• autofix

Limitations of simple mode

Simple mode has the following limitations:

• Supports only one language per rule.

• Does not include support for the following operators:

  • pattern-not-regex
  • metavariable-regex
  • metavariable-pattern
  • metavariable-comparison

• Does not support the following modes:

  • Join mode
  • Taint mode

To create a rule in simple mode:

1. Ensure that you are in Simple mode:
2. Click File > New to start from a blank slate.
3. Select a language from the language is drop-down box to specify a language in which the test code is written.
4. After the code is button, enter the rule pattern.
5. Optional: Click on the plus button to add fields for additional operators. Select the pattern operator and enter the pattern.
6. Optional: Click on Rule metadata tab on the Sample code pane to enter additional metadata fields.
7. Click Run or press Ctrl+Enter (⌘+Enter on Mac).

Try Turbo mode (beta)

Semgrep can automatically scan for findings using the Semgrep OSS Engine, on any change in the Rule or Sample Code panes.

Click the Turbo mode toggle to try it out.

In this mode, the Run button is hidden because Semgrep scans upon detecting any change to the text. Turbo mode works in both Simple mode and Advanced mode. Turbo mode cannot be enabled for Semgrep Pro Engine.

Writing complex rules using advanced mode

Advanced mode is a YAML editor for writing a rule using any valid key from the Semgrep schema. Advanced mode provides default values for the required keys for a Semgrep rule definition and expects the user to modify and add keys to finish the rule.

To create a rule in advanced mode:

1. Ensure that you are in the Advanced mode.
2. Enter the keys and values needed to finish your rule.
3. Click Run or press Ctrl+Enter (⌘+Enter on Mac).

Running and testing a rule for precision

Testing a rule ensures that it meets your standards for precision and speed. Aside from running a rule in the Playground, it is possible to test a rule by creating comment annotations for intended and unintended findings (matches). You can achieve this by creating assertions within the test pane.

Refer to Testing rules for the syntax and method to run test files.

Debugging errors when creating a rule

Common errors are syntax or match issues.

The pattern can't be parsed for the language

Check that the Language is value and Test code language match. Use full AST elements for the language. For example:

• In Java, Python's print command is not a valid element.
• 1+ or if $X: are not valid patterns because they are not full AST elements.

The pattern syntax is invalid

Check your metavariable definitions, and use of operators. Metavariables must be uppercase letters preceded by a dollar sign $, such as $PAYMENT_OUTPUT or $X. Refer to Pattern syntax.

The YAML syntax is unparsable in the advanced view

Check for spelling and indentation issues. The key names must match Semgrep's schema.

The rule does not behave as expected or does not find the desired match

File a bug or reach out through Semgrep Community Slack.

Exploring rules through Semgrep Registry

Semgrep Registry is an open-source, community-driven repository of rules. These rules can detect OWASP vulnerabilities, best practice violations, and security issues for a wide variety of languages and frameworks. These rules can be used as a starting point for writing your own custom rules by creating a forked rule.

Signing in to Semgrep Cloud Platform enables you to access the Registry directly from the Playground's Library pane.

Jumpstart rule writing using existing rules

Another method of creating rules is by forking or copying from existing rules found in Semgrep Registry. For example, Semgrep’s Java crypto ruleset prohibits the use of weak hashing algorithms SHA-1 and MD5. An organization can further limit the use of other hash functions as part of its standards or security compliance. The next steps illustrate forking through copying an existing use-of-sha1 rule and changing the rule to forbid MD2 hashes.

1. Enter related terms into the search bar to find potential rules. In our example, this is SHA1.
   
2. Registry rules cannot be edited directly. They can be forked by right-clicking on their entry in the Library and selecting Fork rule.
   
3. The rule is copied to your organization’s rules.
4. Enter edits to finalize your rule. In this example, the patterns are changed to find matches for MD2 and the severity is increased from WARNING to ERROR.
5. Enter updates to test cases.
6. Click Run to validate your rule.
7. Click Save to save your rule. The following rule displays the end result.

Setting code standards by adding a rule to the Rule Board

The Rule Board displays rules that Semgrep Cloud Platform uses to scan your project's code. Adding a rule to the Rule Board allows you to quickly set a rule as part of every Semgrep scan. A rule on the Rule Board is represented as a card and can be placed on either the Audit Board or the Block board depending on the importance of the rule. Rules can be dragged from one column to another.

To add a rule to the Rule Board:

1. Ensure that you are signed in.
2. Click Add to Rule Board.
3. Select either the Monitor, Comment, or Block board based on the importance of the rule. Findings for rules on the Block board prevent PR merges within a CI environment. Findings for rules on the Comment board leave comments within the PR or MR.

Embedding a rule in your site

The Embedded Playground is an interactive editor which can be embedded in an external domain or web page such as a blog post. It is a means to display Semgrep's rules in action.

The Embedded Playground has two panes:

Rule Pane

This displays the rule data. The rule must have a reference (either a short identifier or saved name) from Semgrep Playground.

Test Code

This displays the code that the rule will act upon. On the bottom right is the Run button, which will run the rule on the test code.

Both panes are editable, allowing viewers to try the Semgrep rule out for themselves or to change parts of the rule.

Prerequisite

A site or page with sufficient editing permissions for you to embed the rule.

To embed a rule:

1. In the Playground, click Share.

2. Copy the identifier. This comes in two patterns:

   1. For signed-in users: [username]:[rule-name], such as ievans:print-to-logger
   2. For anonymous users: [4-letter permalink], such as dZkP

3. Create the URL reference. Substitute the identifier in this template: https://semgrep.dev/embed/editor?snippet=IDENTIFIER. For example, using the identifier ievans:print-to-logger creates https://semgrep.dev/embed/editor?snippet=ievans:print-to-logger.

4. Optional: To test the URL reference, enter the URL in your browser's address bar.

5. In the following snippet, replace the src="URL_REFERENCE" placeholder value with the previously-created URL reference:

   <iframe title="Semgrep example no prints" src="URL_REFERENCE" width="100%" height="432" frameborder="0"></iframe>

   The rendered iframe example:

   <iframe title="Semgrep example no prints" src="https://semgrep.dev/embed/editor?snippet=ievans:print-to-logger" width="100%" height="432" frameborder="0"></iframe>

---

Find what you needed in this doc? Join the Semgrep Community Slack group to ask the maintainers and the community if you need help.