Skip to Content
Code ScanningRules

Writing Rules

The xgrep rule format and the rule features it supports.

xgrep uses the Semgrep YAML rule format:

rules:
  - id: my-rule
    pattern: eval(...)
    message: Avoid using eval()
    severity: WARNING
    languages: [python]

Let an agent do it. The author-detections skill from the secure-stack marketplace drives xgrep to write a rule from a description, generate test cases, and run xgrep test until it passes — including taint-mode rules and porting a rule to new languages. Install it into your coding agent (see AI agent skills), then describe the pattern you want to catch. The rest of this page is the reference for when you write or review rules by hand.

Supported rule features include:

  • pattern, patterns, pattern-either, pattern-not, pattern-inside, pattern-not-inside
  • pattern-regex, pattern-not-regex
  • Metavariables ($VAR, $...ARGS)
  • metavariable-pattern, metavariable-regex, metavariable-comparison
  • focus-metavariable
  • fix (autofix support)
  • Taint analysis (mode: taint with pattern-sources, pattern-sinks, pattern-sanitizers, pattern-propagators) — see Taint analysis
  • Native analyzers (mode: analysis with analyzer:) for checks too context-dependent for patterns — see Analysis mode
  • Supply chain rules (r2c-internal-project-depends-on)
  • options including interfile: true for cross-file analysis and implicit_ellipsis: false for exact record matching (below)
  • min-version / max-version for engine version constraints

Comments inside a code pattern are ignored, like whitespace, so a pattern can explain itself:

pattern: |
  // the call runs its argument as code
  eval($X); // any argument

The comment syntax is that of the rule's languages (// and /* */ for C-family languages, # for Python, Ruby and shell, -- for Lua). Text inside string literals is never treated as a comment. A pattern that consists only of a comment is kept as written. To match comment text itself, use pattern-regex.

For the precise semantics of each operator and metavariable form, see the Syntax reference. For the upstream specification, see the Semgrep rule syntax documentation.

Matching a record exactly

A pattern that names some of an object literal's properties matches a literal that carries others as well, at every position the literal can be written in:

pattern: http.get($URL, { host: $H })

matches http.get(u, { host: h, port: 1, timeout: 5 }) — the properties the pattern does not name are not a mismatch. This is what makes a pattern usable against a real options object, whose shape the rule author does not control.

When a rule needs the opposite reading — the literal carries the named properties and nothing else — set implicit_ellipsis: false:

rules:
  - id: exact-options
    languages: [javascript]
    severity: MEDIUM
    message: exactly these options
    options:
      implicit_ellipsis: false
    pattern: f({ host: $H })

That rule matches f({ host: h }) and not f({ host: h, port: 1 }).

The option applies to record patterns wherever they appear, including inside pattern-not. Note the direction there: a strict pattern-not matches fewer literals, so it suppresses fewer findings and the rule reports more, not less. It does not affect the other lists a pattern can leave partly unspecified — an implements clause or a set of annotations still match as a subset.

Version-gating a rule on a dependency

r2c-internal-project-depends-on reads the project's manifests (package.json, go.mod, requirements.txt, pom.xml, Cargo.toml, composer.json, *.csproj) and matches when the named package is declared, optionally within a version constraint:

patterns:
  - pattern: yaml.load($X)
  - r2c-internal-project-depends-on:
      namespace: npm
      package: js-yaml
      version: '< 4'

Nesting the same clause under pattern-not inverts it — the rule matches unless the manifest establishes the claim:

patterns:
  - pattern: yaml.load($X)
  - pattern-not:
      r2c-internal-project-depends-on:
        namespace: npm
        package: js-yaml
        version: '>= 4'

The two are not mirror images, and the difference matters when you are gating a security rule. The positive form fires only on proof that the project is affected, so it stays silent when no manifest is in scan scope, when the package is reached transitively, or when the declared version is a tag like latest that names no version. The negated form fires in all of those cases and goes quiet only on proof that the project is safe. For a vulnerability rule, prefer the negated form: absence of evidence should not read as evidence of safety.

A version is compared against the lower bound of the declared range, so ^5.2.0 and ~5.2.0 both compare as 5.2.0. A declaration that names no version at all matches no constraint.

Fixes and findings on the same line

A rule reports a line once: when two of its findings cover the same lines, one is kept (the wider one, if they differ). A fix or fix-regex rewrites the text of the finding that is kept, so if a rule matches a short span (one token) and that token appears twice on a line, one run fixes the first occurrence and the next run fixes the second. To fix every occurrence in one pass, let the match cover the whole statement and write the fix-regex so it rewrites each occurrence inside it (a list of entries, each with a count).

Security metadata

Security rules (metadata.category: security or secrets) carry standardized classification metadata that flows into SARIF and GitLab reports:

metadata:
  category: security
  cwe:
    - 'CWE-918: Server-Side Request Forgery (SSRF)'
  owasp:
    - A10:2021
    - A01:2025
  references:
    - https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html

Conventions:

  • cwe — "CWE-N: Name" using the exact name from the MITRE CWE catalog. Use concrete weakness IDs, never category or view IDs (e.g. CWE-16, CWE-275, CWE-730 are categories, not weaknesses).
  • owasp — OWASP Top 10 categories as a bare code + edition with no descriptive text: A0X:2021 and/or A0X:2025 (the human-readable name is added by the output layer, so storing it would only risk drift). Tag both editions: derive the 2021 category from the CWE via the official Top 10:2021 CWE mapping, then add its 2025 equivalent — note 2025 renumbered the list, folded SSRF into A01:2025, renamed Vulnerable/Outdated Components to Software Supply Chain Failures (A03:2025), and added A10:2025 Mishandling of Exceptional Conditions. If the CWE is unmapped, use its nearest mapped ancestor in the CWE hierarchy. CWEs with no applicable category (denial-of-service, memory-safety, integer overflow, race conditions) omit the key — do not force-fit a category.
  • references — curated reading only, from official sources: owasp.org (including cheat sheets), NIST, IETF/RFC, W3C. No vendor or blog links. Do not add links that are derivable from the tags above — CWE definition and OWASP Top 10 category links are generated from the cwe/owasp entries by the output layer (SARIF, GitLab), never hand-written. Most rules therefore need no references at all.

Once you've written a rule, test it.

Last updated on

On this page