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; usespattern-sources/pattern-sinks/pattern-sanitizers/pattern-propagators. See Taint analysis.analysis— a built-in native analyzer named byanalyzer:, 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:
| Pattern | Matches |
|---|---|
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.
| Form | Meaning |
|---|---|
$X | matches a single expression, name, or value and binds it to X |
$...ARGS | matches a run of arguments or elements and binds the whole run |
$X reused | the 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.
| Operator | Effect |
|---|---|
pattern | code must match this pattern |
patterns | all of the listed clauses must hold (AND) |
pattern-either | at least one of the listed clauses must hold (OR) |
pattern-not | the match must not also match this pattern |
pattern-inside | the match must be nested somewhere inside this pattern |
pattern-not-inside | the match must not be nested inside this pattern |
pattern-regex | code must match this regular expression (text, not structure) |
pattern-not-regex | excludes 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:
| Operator | Effect |
|---|---|
metavariable-pattern | the metavariable's code must itself match a nested pattern (optionally in another language, e.g. SQL inside a string) |
metavariable-regex | the metavariable's text must match a regular expression |
metavariable-comparison | a 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 scanis read-only, so the separatexgrep fixcommand 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:
| Option | Effect |
|---|---|
implicit_ellipsis: false | a record/object pattern must match the literal's fields exactly, instead of allowing extra fields (the default). See matching a record exactly. |
interfile: true | the 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