/sarif-parsing

name: sarif-parsing
description: >-
  Parses and processes SARIF files from static analysis tools like CodeQL, Semgrep, or other
  scanners. Triggers on "parse sarif", "read scan results", "aggregate findings", "deduplicate
  alerts", or "process sarif output". Handles filtering, deduplication, format conversion, and
  CI/CD integration of SARIF data. Does NOT run scans — use the Semgrep or CodeQL skills for that.
allowed-tools: Bash Read Glob Grep

SARIF Parsing Best Practices

You are a SARIF parsing expert. Your role is to help users effectively read, analyze, and process SARIF files from static analysis tools.

When to Use

Use this skill when:

• Reading or interpreting static analysis scan results in SARIF format
• Aggregating findings from multiple security tools
• Deduplicating or filtering security alerts
• Extracting specific vulnerabilities from SARIF files
• Integrating SARIF data into CI/CD pipelines
• Converting SARIF output to other formats

When NOT to Use

Do NOT use this skill for:

• Running static analysis scans (use CodeQL or Semgrep skills instead)
• Writing CodeQL or Semgrep rules (use their respective skills)
• Analyzing source code directly (SARIF is for processing existing scan results)
• Triaging findings without SARIF input (use variant-analysis or audit skills)

SARIF Structure Overview

SARIF 2.1.0 is the current OASIS standard. Every SARIF file has this hierarchical structure:

sarifLog
├── version: "2.1.0"
├── $schema: (optional, enables IDE validation)
└── runs[] (array of analysis runs)
    ├── tool
    │   ├── driver
    │   │   ├── name (required)
    │   │   ├── version
    │   │   └── rules[] (rule definitions)
    │   └── extensions[] (plugins)
    ├── results[] (findings)
    │   ├── ruleId
    │   ├── ruleIndex (index into tool.driver.rules[])
    │   ├── level (OPTIONAL, inherited from the rule when absent)
    │   ├── message.text
    │   ├── locations[]
    │   │   └── physicalLocation
    │   │       ├── artifactLocation.uri
    │   │       └── region (startLine, startColumn, etc.)
    │   ├── fingerprints{}
    │   └── partialFingerprints{}
    └── artifacts[] (scanned files metadata)

Severity Is Not Always on the Result

`result.level` is optional. CodeQL omits it on every result and records severity on the rule as `defaultConfiguration.level`, which the result inherits. Read `result.level` directly and a CodeQL run scores as clean however many errors it found, which is how a severity gate ends up exiting 0 on a failing repo.

Resolve severity in this order (SARIF 2.1.0 section 3.27.10):

1. `kind` other than `"fail"` (a pass/notApplicable record), so `"none"` 2. `result.level`, when present 3. the matched rule's `defaultConfiguration.level`, joining `ruleIndex` into `runs[].tool.driver.rules[]`, or matching `ruleId` against `rules[].id` when the tool omits `ruleIndex` 4. `"warning"`, the SARIF default

Every severity query in this skill starts from that resolution. In jq it is the `LEVEL_FN` definition in [{baseDir}/resources/jq-queries.md]({baseDir}/resources/jq-queries.md); in Python it is `resolve_level(result, run)` in [{baseDir}/resources/sarif_helpers.py]({baseDir}/resources/sarif_helpers.py).

Why Fingerprinting Matters

Without stable fingerprints, you can't track findings across runs:

• **Baseline comparison**: "Is this a new finding or did we see it before?"
• **Regression detection**: "Did this PR introduce new vulnerabilities?"
• **Suppression**: "Ignore this known false positive in future runs"

Tools report different paths (`/path/to/project/` vs `/github/workspace/`), so path-based matching fails. Fingerprints hash the *content* (code snippet, rule ID, relative location) to create stable identifiers regardless of environment.

Tool Selection Guide

| Use Case | Tool | Install / run | |----------|------|--------------| | Quick CLI queries | jq | `brew install jq` / `apt install jq` | | Python scripting (simple) | pysarif | `uv run --with pysarif python script.py` | | Python scripting (advanced) | sarif-tools | `uv run --with sarif-tools python script.py` | | .NET applications | SARIF SDK | NuGet package | | JavaScript/Node.js | sarif-js | npm package | | Go applications | garif | `go get github.com/chavacava/garif` | | Validation | SARIF Validator | sarifweb.azurewebsites.net |

Strategy 1: Quick Analysis with jq

For rapid exploration and one-off queries:

# Pretty print the file
jq '.' results.sarif

# Count total findings
jq '[.runs[].results[]] | length' results.sarif

# List all rule IDs triggered
jq '[.runs[].results[].ruleId] | unique' results.sarif

# Severity resolution, needed by every query below that filters on level.
# See resources/jq-queries.md for the annotated version.
LEVEL_FN='
  def rule($run):
    . as $r
    | ($run.tool.driver.rules // []) as $rules
    | (if ($r.ruleIndex | type) == "number" and $r.ruleIndex >= 0
       then $rules[$r.ruleIndex] else null end)
      // first($rules[] | select(.id == $r.ruleId))
      // null;
  def level($run):
    . as $r
    | if ($r.kind // "fail") != "fail" then "none"
      else ($r.level // rule($run).defaultConfiguration.level // "warning") end;
'

# Extract errors only
jq "$LEVEL_FN"'.runs[] as $run | $run.results[] | select(level($run) == "error")' results.sarif

# Get findings with file locations
jq '.runs[].results[] | {
  rule: .ruleId,
  message: .message.text,
  file: .locations[0].physicalLocation.artifactLocation.uri,
  line: .locations[0].physicalLocation.region.startLine
}' results.sarif

# Filter by severity and get count per rule
jq "$LEVEL_FN"'[.runs[] as $run | $run.results[] | select(level($run) == "error")] | group_by(.ruleId) | map({rule: .[0].ruleId, count: length})' results.sarif

# Extract findings for a specific file
jq --arg file "src/auth.py" '.runs[].results[] | select(.locations[].physicalLocation.artifactLocation.uri | contains($file))' results.sarif

Strategy 2: Python with