• Semgrep AppSec Platform
• Team & Enterprise Tier

Write rules using Semgrep Editor

Semgrep Editor allows you to write rules, verify their performance through tests, and add them to your organization’s Policies page to enforce code standards and increase code security.

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

Access Semgrep Editor

1. Sign in to your Semgrep AppSec Platform account.
2. Click Rules > Editor.
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.

View a rule

Semgrep Editor is composed of three panes and a top menu.

Library

View and open rules owned by your organization or available through the Semgrep Registry.

Rule editor

Enter your rule's YAML schema in this pane. This pane supports both structure and advanced modes.

Sample code

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

Top menu

Save, share, and add your rule to one of your policies.

Group rules

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

To group by ruleset, right-click on the empty space on the registry's name entry and select Group by ruleset.

Create a rule

To create a rule, click Create rule on the splash page or the (+) sign next to the Library label.

Semgrep Editor offers two rule-writing modes:

Structure mode (beta)

Structure mode is a hybrid interface that offers guidance for rule writing while supporting additional features the way advanced mode does.

Advanced mode

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

Write a rule using structure mode (beta)

Structure mode is a UI-based ruled writing editor that guides you through the process of writing a rule.

Structure mode features include:

• Match badges: Match badges are visual indicators paired next to pattern operators. The match badge shows the number of matches associated with each pattern operator.
• Automatic indentation: When adding a new pattern to a nested operator such as patterns or pattern-either, the editor automatically indents sub-patterns correctly.
• Differentiation between patterns and pattern constraints: A pattern is one of six different operators that describes zero or more locations in a rule. These include pattern, any, all, inside, regex, and not. You can combine these in prescribed ways, such as any and all, using range union and intersection, but they still define ranges. Pattern constraints describe Boolean constrains that must be met for a match to occur. If the constraint doesn't hold, then the ranges determined by the pattern operators aren't applicable.
• Interoperability with advanced mode: You can write a rule using structure mode and export it in YAML or you can paste in the YAML for a rule and edit it with structure mode.
• Drag and drop" You can move around the elements of a rule using drag and drop.
• Pattern disabling: You can toggle individual patterns on or off for actions like testing.

To write a search rule using structure mode:

1. Ensure that you are in structure mode.
2. Select your first operator. Options include: pattern, any, all, inside, regex.
3. Specify the pattern if applicable. Example: print("...").
4. Optional: specify a constraint by clicking on the filter icon.
   1. Specify whether the constraint is focus, comparison, or metavariable.
   2. Provide the pattern for the code for which the constraint should be applied.
5. Select the child operator and specify its pattern, if applicable. You can add as many child elements as you need. These child elements can also have their own constraints
6. Optional: Expand the Rule info panel, and update the following fields:
   1. Rule ID: the name of the rule
   2. Language: the language of the code for which this rule runs against
   3. Severity: the severity level of the finding if this rule generates a match
   4. Message: the message to print with the finding if this rule generates a match
7. Click Run or press Ctrl+Enter (⌘+Enter on Mac).

To write a taint rule using structure mode:

1. Ensure that you are in structure mode. and that you have selected taint.
2. Define your Sources.
   1. Select your first operator. Options include: pattern, any, all, inside, regex.
   2. Specify the pattern if applicable. Example: print("...").
   3. Optional: specify a constraint by clicking on the filter icon.
      1. Specify whether the constraint is focus, comparison, or metavariable.
      2. Provide the pattern for the code for which the constraint should be applied.
3. Define your Sinks.
   1. Select your first operator. Options include: pattern, any, all, inside, regex.
   2. Specify the pattern if applicable. Example: print("...").
   3. Optional: specify a constraint by clicking on the filter icon.
      1. Specify whether the constraint is focus, comparison, or metavariable.
      2. Provide the pattern for the code for which the constraint should be applied.
4. Add Sanitizers.
   1. Select your first operator. Options include: pattern, any, all, inside, regex.
   2. Specify the pattern if applicable. Example: print("...").
   3. Optional: specify a constraint by clicking on the filter icon.
      1. Specify whether the constraint is focus, comparison, or metavariable.
      2. Provide the pattern for the code for which the constraint should be applied.
5. Optional: Expand the Rule info panel, and update the following fields:
   1. Rule ID: the name of the rule
   2. Language: the language of the code for which this rule runs against
   3. Severity: the severity level of the finding if this rule generates a match
   4. Message: the message to print with the finding if this rule generates a match
6. Click Run or press Ctrl+Enter (⌘+Enter on Mac).

Write a rule using advanced mode

Advanced mode is a YAML editor that allows you to write rules using Semgrep syntax.

Rules syntax

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

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.

To write a rule in advanced mode:

1. Ensure that you are in advanced mode.
2. Click the plus sign and select a template. The New rule template includes the minimum keys required for a Semgrep rule, but there are additional templates that can help you write more complex rules:
   • Semgrep Assistant: use Semgrep Assistant to generate custom rules
   • Metavariable-comparison: demonstrates how to use the metavariable-comparison key
   • Metavariable-pattern: demonstrates how to use the metavariable-pattern key
   • Dataflow analysis: demonstrates how to leverage dataflow analysis through pattern-sources, pattern-sinks, and pattern-sanitizers.
   • Dataflow analysis with taint labels: demonstrates how to define the sources you want to track and how data must flow
   • HTTP validators: Demonstrates how to Semgrep Secrets rules that include validators
3. Modify the template, adding and changing the keys and values needed to finish your rule.
4. Optional: Click Metadata to update and enter additional metadata fields. Metadata view
5. Click Run or press Ctrl+Enter (⌘+Enter on Mac).

Syntax issues

Semgrep Editor won't save or run your rule if it can't parse the YAML syntax of your rule. Fix any issues indicated by the red annotations before proceeding.

Run and test a rule

After you write a rule, testing it ensures it performs as expected. 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 detects the annotations and validate the rule based on your tests

In addition to testing for matches, you can test that it doesn't match what it shouldn't, preventing false positives. To do so, you can create comment annotations for intended and unintended findings in test code.

Once you've written a rule and created comment annotations, you can run your rule against your comment annotations by clicking Run. You can also press Ctrl+Enter (⌘+Enter on Mac).

Turbo mode (beta)

The Turbo option runs your rule automatically against the Semgrep OSS Engine after every keystroke or change to the rule.

Click the Turbo mode toggle to enable.

The Run button is hidden in Turbo mode because Semgrep scans after any changes to the rule. Turbo mode works with the editor in either structure or advanced mode.

Turbo mode is unavailable with Semgrep Pro Engine.

Set a rule’s visibility and share a rule

Upon saving, a rule’s visibility is unlisted by default. This rule can be shared with anyone through an identifier, even to non-Semgrep AppSec 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 > Confirm.
• To share a private or unlisted rule, click Share and copy the URL link.

Rename a rule

To rename a rule, enter the new name in the YAML editor’s id field. The, save the rule by entering Ctrl+S (⌘+S on Mac) or clicking the Save button.

Delete a rule

To remove a private rule, follow these steps:

1. In the Semgrep Editor, find a private rule to delete under the Library tab. Private rules are usually stored in the folder with the same name as your Semgrep AppSec Platform organization.
2. Click the rule you want to delete, and then click the three vertical dots.
3. Click Delete.

Deleting a rule is permanent. If the rule was previously added to the Policies page, it is removed upon deletion.

Add a rule to the Policies page

The Policies page displays rules that Semgrep Cloud Platform uses to scan your project's code. Rules added to the Policies page become part of every Semgrep scan you run.

When adding a rule to your Policies page, you must also set the rule mode that determines what actions Semgrep performs when that rule generates a finding. See Policies for more information on each rule mode.

To add a rule to the Policies page:

1. Ensure you're signed in to Semgrep.
2. Click Add to Policy.
3. Select one of the following rule mode options based on the relevance of the rule: Monitor mode, Comment mode, or Block mode.

If successful, you'll see a pop-up window indicating that your rule has been added.

Semgrep Registry rules

Semgrep Registry is an open-source, community-driven repository of rules. These rules can detect OWASP vulnerabilities, best practice violations, and security issues for various languages and frameworks. You can fork an existing rule to use as a starting point for writing your own.

Write a new rule based on an existing rule

One way to create new rules is to fork an existing rule in Semgrep Registry and modify it to meet your software and business requirements.

For example, Semgrep’s Java crypto ruleset prohibits the use of weak hashing algorithms SHA-1 and MD5. However, your organization also prohibits the use of other hash functions as part of its standards or security compliance. The following steps illustrate the process of forking an existing use-of-sha1 rule and changing it to forbid MD2 hashes.

1. Use the search bar to find relevant rules. For this example, you can search for rules using SHA1.
2. Under java > lang > security > audit > crypto, click use-of-sha1 to load the rule. You cannot directly edit the rules in Semgrep Registry, so click Fork to make a copy. Alternatively, you can right-click the rule's name and select Fork rule.
3. Semgrep copies the rule to your organization's set of rules.
4. Edit the rule.
5. Update your test cases.
6. Click Run to test and validate your rule.
7. When you finish your changes, click Save.

The following example shows how the original rule, identifying uses of SHA-1 and MD5, has been modified to find uses of MD2 and the severity of such findings is increased from WARNING to ERROR.

Contribute to the open-source Semgrep Registry

info

For general contributing guidelines, see Contributing rules.

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.

---

Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.