reference Rule syntax

metadata

See also
--inline-metavariables, --sarif, --json, --gitlab-sast

A mapping of arbitrary keys and values attached to the rule. Opengrep does not interpret it when matching. Each finding in the JSON output contains the metadata of its rule unchanged, in extra.metadata.

The SARIF and GitLab SAST outputs read some keys:

KeyValueUse
cwea string or a list of stringsSARIF: each entry becomes a tag of the rule, and the tag security is added.
owaspa string or a list of stringsSARIF: each entry becomes a tag, prefixed with OWASP-.
confidencea string, such as HIGH or LOWSARIF: the tag <value> CONFIDENCE. GitLab SAST: the confidence detail; LOW also flags the finding as a likely false positive.
tagsa list of stringsSARIF: added to the tags of the rule.
referencesa URL or a list of URLsSARIF: listed under References in the help of the rule.
sourcea URLSARIF: the helpUri of the rule, also listed under References. GitLab SAST: the URL of the identifier.
shortDescriptiona stringSARIF: the short description of the rule, Opengrep Finding: <id> by default.
helpa stringSARIF: the help text of the rule, the message by default.
security-severitya numberSARIF: the security-severity property of the rule.
shortlinka URLThe legacy skin of the text output prints it below the message, as Details:.

With --inline-metavariables, metavariables in string values of the metadata are replaced by the code they matched.

Examples

Metadata in the JSON output

rule.yaml
rules:  - id: sql-injection    pattern: cursor.execute("..." % ...)    message: SQL query built with string formatting    languages: [python]    severity: ERROR    metadata:      cwe:        - "CWE-89: Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')"      owasp:        - "A03:2021 - Injection"      confidence: HIGH      references:        - https://owasp.org/Top10/A03_2021-Injection/
app.py
cursor.execute("SELECT * FROM users WHERE name = '%s'" % name)
Command and result
$ opengrep scan --config rule.yaml --json app.py 2>/dev/null | jq .
{
  "version": "X.Y.Z",
  "results": [
    {
      "check_id": "sql-injection",
      "path": "app.py",
      "start": {
        "line": 1,
        "col": 1,
        "offset": 0
      },
      "end": {
        "line": 1,
        "col": 63,
        "offset": 62
      },
      "extra": {
        "metavars": {},
        "message": "SQL query built with string formatting",
        "metadata": {
          "cwe": [
            "CWE-89: Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')"
          ],
          "owasp": [
            "A03:2021 - Injection"
          ],
          "confidence": "HIGH",
          "references": [
            "https://owasp.org/Top10/A03_2021-Injection/"
          ]
        },
        "severity": "ERROR",
        "fingerprint": "ed521f8d06e574b02fa886f268bb26bb1d1c7a0f12f904558b636b32db74a524b2c6f7da84dd8f2d927b16bfedaf455ac40f7e84d43c757fb52581d033540fff_0",
        "lines": "cursor.execute(\"SELECT * FROM users WHERE name = '%s'\" % name)",
        "is_ignored": false,
        "validation_state": "NO_VALIDATOR",
        "engine_kind": "Opengrep"
      }
    }
  ],
  "errors": [],
  "paths": {
    "scanned": [
      "app.py"
    ]
  },
  "interfile_languages_used": [],
  "skipped_rules": []
}

Metadata in the SARIF output

rule.yaml
rules:  - id: sql-injection    pattern: cursor.execute("..." % ...)    message: SQL query built with string formatting    languages: [python]    severity: ERROR    metadata:      cwe:        - "CWE-89: Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')"      owasp:        - "A03:2021 - Injection"      confidence: HIGH      references:        - https://owasp.org/Top10/A03_2021-Injection/
app.py
cursor.execute("SELECT * FROM users WHERE name = '%s'" % name)
Command and result
$ opengrep scan --config rule.yaml --sarif app.py 2>/dev/null | jq .
{
  "version": "2.1.0",
  "runs": [
    {
      "invocations": [
        {
          "executionSuccessful": true,
          "toolExecutionNotifications": []
        }
      ],
      "results": [
        {
          "fingerprints": {
            "matchBasedId/v1": "ed521f8d06e574b02fa886f268bb26bb1d1c7a0f12f904558b636b32db74a524b2c6f7da84dd8f2d927b16bfedaf455ac40f7e84d43c757fb52581d033540fff_0"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "app.py",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "endColumn": 63,
                  "endLine": 1,
                  "snippet": {
                    "text": "cursor.execute(\"SELECT * FROM users WHERE name = '%s'\" % name)"
                  },
                  "startColumn": 1,
                  "startLine": 1
                }
              }
            }
          ],
          "message": {
            "text": "SQL query built with string formatting"
          },
          "properties": {},
          "ruleId": "sql-injection"
        }
      ],
      "tool": {
        "driver": {
          "name": "Opengrep",
          "rules": [
            {
              "defaultConfiguration": {
                "level": "error"
              },
              "fullDescription": {
                "text": "SQL query built with string formatting"
              },
              "help": {
                "markdown": "SQL query built with string formatting\n\n<b>References:</b>\n - [https://owasp.org/Top10/A03_2021-Injection/](https://owasp.org/Top10/A03_2021-Injection/)\n",
                "text": "SQL query built with string formatting"
              },
              "id": "sql-injection",
              "name": "sql-injection",
              "properties": {
                "precision": "very-high",
                "tags": [
                  "CWE-89: Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')",
                  "HIGH CONFIDENCE",
                  "OWASP-A03:2021 - Injection",
                  "security"
                ]
              },
              "shortDescription": {
                "text": "Opengrep Finding: sql-injection"
              }
            }
          ],
          "semanticVersion": "X.Y.Z"
        }
      }
    }
  ],
  "$schema": "https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/schemas/sarif-schema-2.1.0.json"
}