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.
- 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:
Limitations of simple mode
Simple mode has the following limitations:
Supports only one language per rule.
Does not include support for the following operators:
Does not support the following modes:
- Join mode
- Taint mode
To create a rule in simple mode:
- Ensure that you are in Simple mode:
- Click File > New to start from a blank slate.
- Select a language from the language is drop-down box to specify a language in which the test code is written.
- After the code is button, enter the rule pattern.
- Optional: Click on the plus button to add fields for additional operators. Select the pattern operator and enter the pattern.
- Optional: Click on Rule metadata tab on the Sample code pane to enter additional metadata fields.
- Click Run or press Ctrl+Enter (⌘++Enter on Macs).
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:
- Ensure that you are in the Advanced mode.
- Enter the keys and values needed to finish your rule.
- Click Run or press Ctrl+Enter (⌘++Enter on Macs).
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
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
$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
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 App 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
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.
- Enter related terms into the search bar to find potential rules. In our example, this is
- Registry rules cannot be edited directly. They can be forked by right-clicking on their entry in the Library and selecting Fork rule.
- The rule is copied to your organization’s rules.
- Enter edits to finalize your rule. In this example, the patterns are changed to find matches for MD2 and the severity is increased from
- Enter updates to test cases.
- Click Run to validate your rule.
- 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 App 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:
- Ensure that you are signed in.
- Click Add to Rule Board.
- 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.
- A site or page with sufficient editing permissions for you to embed the rule.
To embed a rule:
- In the Playground, click Share.
- Copy the identifier. This comes in two patterns:
- For signed-in users:
[username]:[rule-name], such as
- For anonymous users:
[4-letter permalink], such as dZkP
- For signed-in users:
- Create the URL reference. Substitute the identifier in this template:
https://semgrep.dev/embed/editor?snippet=IDENTIFIER. For example, using the identifier
- Optional: To test the URL reference, enter the URL in your browser's address bar.
- In the following snippet, replace the
srcplaceholder value with the previously-created URL reference:
<iframe title="Semgrep example no prints" src="URL_REFERENCE" width="100%" height="432" frameborder="0"></iframe>
Our example's finished result is:
<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 Slack group to ask the maintainers and the community if you need help.