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:
- 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 Mac).
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:
- 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 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+
orif $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.
- Enter related terms into the search bar to find potential rules. In our example, this is
SHA1.
- 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
WARNING
toERROR
. - 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 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:
- 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 asievans:print-to-logger
- 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 identifierievans:print-to-logger
createshttps://semgrep.dev/embed/editor?snippet=ievans:print-to-logger
.Optional: To test the URL reference, enter the URL in your browser's address bar.
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.