• Semgrep Cloud Platform
• Community Tier
• Team & Enterprise Tier

Writing rules using Semgrep Editor

Semgrep Editor is an advanced tool for rule writing. Write rules on a YAML editor, verify their performance through tests, and add them to your organization’s Rule Board to enforce code standards and increase code security.

To quickly learn Semgrep patterns and syntax, explore the Editor’s library of rules from the public Rule Registry. Rules from the Registry can detect OWASP vulnerabilities, best practice violations, and security issues for a wide variety of languages and frameworks. Semgrep Editor enables you to adapt these rules for your own organization’s use by forking them.

The Editor is free to use on all tiers, but saving a rule for private use is a Team/Enterprise tier feature.

Accessing Semgrep Editor

1. Sign in to your Semgrep Cloud Platform account.
2. Click Editor from the App sidebar. The splash page and library pane appear.
3. Do any of the following steps:
   1. To create a new rule, click on the (+) plus sign or Create new rule button.
   2. To open any rule you’ve recently edited, select it from the Recent list.
   3. To view a sample rule, select it from the Examples list. The rule renders within the Editor.
   4. To start a tutorial or read the docs, select it from the Learn list. This navigates you away from the Editor.

Viewing rules

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

Library

View and open various rules through the library. It contains two top-level folders:

• Your organization’s rules
• Publicly-available Semgrep Registry rules from the semgrep-rules repository

Private rules are denoted by a lock icon overlaid over the file icon.

Rule editor

Enter your rule’s YAML schema in this pane.

Sample code window

Enter your rule’s test code in this pane and click the Run button to verify that the rule runs as intended. A matches panel appears after Semgrep is run to display matches and tests.

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 click-drag to the desired width. The library pane can be completely hidden to give more space for the editing panes.

Semgrep Registry rules are initially grouped by directory. Most of these directories correspond to languages. The Library can also be grouped by rulesets, which are rules arranged by category, such as security, best practices, and frameworks.

To group by ruleset, right click on the empty space on the official registry entry and select Group by ruleset.

Creating a rule

To create a rule, click Create rule on the splash page or the (+) sign next to the Library label. The Editor provides the minimum fields to create a rule:

• rules
• id
• pattern
• message
• languages
• severity

Refer to Rule syntax for all possible fields and values to create a rule.

Jumpstart rule writing using existing rules

Another method of creating rules is by forking/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 may want to further limit the use of other hash functions as part of their 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 use-of-sha.
   
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.

Debugging syntax issues

The editor will not save, share, or run if the YAML syntax is unparseable. The editor supports error handling, for the following cases:

• Missing rules key at start
• Invalid language keys
• Incorrect severity fields
• Missing id key
• Missing required schema fields

If no schema or spelling errors are detected, check for indentation or newline issues. You can also get rule-writing help through the Semgrep Community Slack.

Evaluating a rule’s performance

Evaluating a rule through testing ensures that it meets your standards for precision and speed, thus reducing false positives. Semgrep uses certain annotations in comments to enable users to test which blocks of code are intended to match with a rule, and which blocks of code should not match.

In the following example, run the rule and click on the three-dot menu to view the result of the tests.

To test a rule:

1. Create at least one true positive: a code sample intended to match the rule.
2. Above this potential match, create a comment, followed by a space ( ), followed by ruleid:RULE_ID which specifies the rule that should match. In the preceding example, this is // ruleid:hardcoded-conditional.
3. Create at least one true negative: a code sample intended not to match the rule.
4. Above this non-match, create a comment followed by a space ( ), followed by ok:RULE_ID. For example, // ok:hardcoded-conditional.
5. Optional: add more code samples with their corresponding annotations.
6. Click Run. Semgrep will detect the annotations and validate the rule based on your tests.

For additional annotations designed to test false positives and false negatives, refer to Testing rules.

Renaming and saving a rule

• To rename a rule, enter the new name in the YAML editor’s id field.
• To save a rule, enter Ctrl+S or click the Save button.

Sharing a rule and setting a rule’s visibility

Upon saving, a rule’s visibility is unlisted by default. This rule can be shared with anyone through an identifier, even to non-Semgrep Cloud Platform users.

A rule can be saved as a private rule, which is visible only to members within an organization. You can still share a private rule, but only members of the organization can see it. Private rules are a Team/Enterprise tier feature.

• To set a rule’s visibility to private, click Share > Private > Save change.
• To share a private or unlisted rule, click Share and copy the URL link.

Deleting a rule

To delete a rule, right click on its entry in the Library pane and select Delete rule. Deleting a rule is permanent. If the rule was previously added to the Rule Board, it is removed upon deletion.

Setting code standards with the Rule Board

Adding a rule to the Rule Board applies the rule across all projects scanned by Semgrep Cloud Platform. The rule can be added to either the Audit or Blocker columns. Rules in the Blocker column will prevent PRs from being merged until the finding is resolved.

To add a rule to the Rule Board:

1. Click Add to Rule Board.
2. Select which column (Audit or Blocker) to add the rule to, depending on the rule’s relevance.
3. The rule appears on your Rule Board, under the corresponding column.

Contributing to the open-source Semgrep Registry

To have your rule accepted faster, include the following:

• Include test cases for both a true positive and a true negative. See Tests for more details.
• Include a descriptive rule message. See Rule messages for more information.
• Include metadata fields. See Semgrep registry rule requirements for more information.

To create a PR from the Semgrep Editor:

1. Click Share.
2. (Optional) Click Publish to Registry.
3. Fill in the required and optional fields.
4. Click Continue, and then click Create PR.

info

For general contributing guidelines, see Contributing rules.

---

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