Rule syntax

A rule file is a YAML document with a top-level rules list. Each item of the list is a rule:

rules:
  - id: find-eval
    pattern: eval(...)
    message: found eval
    languages: [python]
    severity: WARNING

Required keys

Key	Value
`id`	The identifier of the rule.
`languages`	The languages of the files the rule runs on.
`message`	The text reported with each finding.
`severity`	The severity of the findings.
pattern keys	In the default search mode, one of `pattern`, `patterns`, `pattern-either` and `pattern-regex`. In taint mode, `pattern-sources` and `pattern-sinks`.

Patterns are written in the pattern syntax.

Unknown keys

Opengrep ignores an unknown key at the top level of a rule, logs a warning such as Skipping unknown field 'nosuchkey' in rule "find-eval", and runs the rule. An unknown key where the set of keys is fixed, such as under paths or options, makes the rule invalid.

Index

Name	Summary
`by-side-effect`	Whether a taint source, sanitizer or propagator also changes the variable it matches for the code that follows.
`control`	Make a taint source taint the flow of control, so that any sink reached after it is reported.
`exact`	Whether a taint source, sanitizer or sink is only the code it matches or also the code inside it.
`fix`	The code that replaces each match, applied by --autofix.
`fix-regex`	Fix each match by replacing what a regular expression matches inside it.
`focus-metavariable`	Report only the code a metavariable matched, not the whole match.
`id`	The identifier of a rule, reported with each of its findings.
`label`	Distinguish kinds of taint in a taint rule, and require some of them at a sink.
`languages`	The languages of the files a rule runs on, and the language its patterns are written in.
`message`	The text reported with each finding; metavariables in it are replaced by the code they matched.
`metadata`	Data attached to a rule and copied into its findings, such as CWE and OWASP references.
`metavariable-analysis`	Keep the matches where a metavariable passes an analysis: entropy for secrets, redos for regular expressions.
`metavariable-comparison`	Keep the matches where an expression over metavariables is true.
`metavariable-pattern`	Keep the matches where the code a metavariable matched also matches a further pattern.
`metavariable-regex`	Keep the matches where the code bound to a metavariable matches a regular expression.
`metavariable-type`	Keep the matches where the expression of a metavariable has a given type.
`min-version`	Skip a rule written for a newer or an older rule format, by Semgrep version number.
`mode`	The matching mode of a rule: search, the default, or taint.
`mode: taint`	Find data that flows from sources to sinks without passing through a sanitizer.
`options`	Settings that change how a rule matches, for that rule only.
`paths`	Limit a rule to files whose paths match, or do not match, glob patterns.
`pattern`	Match code against a pattern written in the language of the rule.
`pattern-either`	Match code that matches any one of a list of patterns.
`pattern-inside`	Keep only the matches that lie inside code matching this pattern.
`pattern-not`	Drop the matches that also match this pattern.
`pattern-not-inside`	Drop the matches that lie inside code matching this pattern.
`pattern-not-regex`	Drop the matches that contain a match of this regular expression.
`pattern-propagators`	In a taint rule, operations that pass taint from one value to another.
`pattern-regex`	Match the text of the file with a PCRE regular expression.
`pattern-sanitizers`	In a taint rule, the code that makes untrusted data safe.
`pattern-sinks`	In a taint rule, the code that must not receive untrusted data.
`pattern-sources`	In a taint rule, the code that produces untrusted data.
`patterns`	Match code that satisfies every condition of a list.
`rules`	The top-level list of a rule file, one entry per rule.
`severity`	The severity of the findings: ERROR, WARNING or INFO, or CRITICAL, HIGH, MEDIUM or LOW.

Examples

An unknown key produces a warning

rule.yaml

rules:  - id: find-eval    pattern: eval(...)    message: found eval    languages: [python]    severity: WARNING    nosuchkey: whatever

app.py

eval(1)

Command and result

$ opengrep scan --config rule.yaml app.py 2>&1 | grep Skipping
warning  Skipping unknown field 'nosuchkey' in rule "find-eval"
$ opengrep scan --config rule.yaml app.py > /dev/null 2>&1; echo "exit status: $?"
exit status: 0

Rule syntax

## Required keys

## Unknown keys

## Index

## Examples

### An unknown key produces a warning

Required keys

Unknown keys

Index

Examples

An unknown key produces a warning