Skip to Content
Code ScanningRules

Syntax Reference

Reference for xgrep pattern operators and metavariables.

xgrep implements the Semgrep rule syntax: a rule matches code by shape, not by text, so it ignores formatting, comments and variable names and sees the parsed structure instead. This page is the quick reference for the operators and metavariable forms. For how to assemble them into a working rule, see Writing rules; for where xgrep's behavior differs from Semgrep's, see Semgrep compatibility.

Rule modes

A rule runs in one mode, selected by the top-level mode: field (default search). A non-search mode forbids the plain pattern clause and unlocks its own keys:

  • search (default) — pattern matching with the operators below.
  • taint — source-to-sink dataflow; uses pattern-sources / pattern-sinks / pattern-sanitizers / pattern-propagators. See Taint analysis.
  • analysis — a built-in native analyzer named by analyzer:, for checks too context-dependent for patterns. Carries no pattern clause. See Analysis mode. (xgrep extension — not portable to Semgrep.)

The ellipsis

... stands for a run of zero or more items, so a pattern names only the parts that matter and the ellipsis absorbs the rest:

PatternMatches
eval(...)eval() with any arguments
foo(1, ..., 5)a call to foo whose first argument is 1 and last is 5
function $F(...) { ... }any function, whatever its parameters and body
$OBJ. ... .$M()a method call reached through any chain of members

An ellipsis inside a statement block ({ ... }) spans statements; inside a call or a sequence it spans arguments or elements.

Metavariables

A metavariable captures a piece of the match so a rule can refer to it, constrain it, or rewrite it.

FormMeaning
$Xmatches a single expression, name, or value and binds it to X
$...ARGSmatches a run of arguments or elements and binds the whole run
$X reusedthe same metavariable twice in one pattern requires the two positions to be identical: $X == $X matches a == a, not a == b
$_matches without binding, when a slot must be filled but its value is not needed

Metavariable names are uppercase by convention. A metavariable matches the parsed node, so $X in $X.foo() binds the whole receiver expression, not just a token.

Pattern operators

The fields a search-mode rule combines. patterns (logical AND) and pattern-either (logical OR) nest to build up a condition.

OperatorEffect
patterncode must match this pattern
patternsall of the listed clauses must hold (AND)
pattern-eitherat least one of the listed clauses must hold (OR)
pattern-notthe match must not also match this pattern
pattern-insidethe match must be nested somewhere inside this pattern
pattern-not-insidethe match must not be nested inside this pattern
pattern-regexcode must match this regular expression (text, not structure)
pattern-not-regexexcludes matches whose text matches this regular expression

pattern-regex escapes the structural engine, so reach for it only when a pattern cannot express the shape (matching inside comments or strings, for example); a structural pattern is more precise everywhere else.

Constraining a metavariable

Inside a patterns block, these narrow what a captured metavariable is allowed to be:

OperatorEffect
metavariable-patternthe metavariable's code must itself match a nested pattern (optionally in another language, e.g. SQL inside a string)
metavariable-regexthe metavariable's text must match a regular expression
metavariable-comparisona numeric or boolean comparison over metavariables, e.g. comparison: $N < 0

Choosing what is reported

  • focus-metavariable — report and highlight the span bound to the named metavariable instead of the whole match. Useful when the surrounding pattern is only there to locate the interesting sub-expression.

Rewriting a match

  • fix — a replacement template; metavariables in it are substituted from the match. xgrep scan is read-only, so the separate xgrep fix command applies fixes through the verification harness (xgrep scan --json | xgrep fix apply).
  • fix-regex — a regex-based rewrite of the matched text, for fixes a template cannot express. See fixes on the same line.

Supply chain

  • r2c-internal-project-depends-on — matches when the project's manifests declare a named package, optionally within a version range. Used on its own or as a clause alongside a code pattern to gate a rule on a vulnerable dependency. See version-gating a rule on a dependency.

Rule options

Set under a rule's options: key:

OptionEffect
implicit_ellipsis: falsea record/object pattern must match the literal's fields exactly, instead of allowing extra fields (the default). See matching a record exactly.
interfile: truethe rule participates in cross-file analysis (taint flows and matches that span files). See taint analysis.

Version gating the engine

  • min-version / max-version — constrain the xgrep/Semgrep engine versions a rule runs under, so a rule that relies on a newer feature is skipped rather than erroring on an older engine.

Metadata

Severity (severity), target languages (languages), the finding message, and classification metadata (metadata.category, cwe, owasp) are documented with their conventions in Writing rules.

Last updated on

On this page