Sarif Parsing

SARIF analysis

Contract

Inputs

• Required: SARIF content: a file path to a local .sarif or .json file, or raw SARIF JSON pasted directly.
• Optional, context-dependent:
  • Target format for conversion (CSV, HTML, or a SARIF variant such as a specific schema version).
  • Filter criteria for inspection (e.g., rule ID pattern, file path glob, severity threshold).
  • Aggregation strategy (count by rule, by file, by severity, by tool).
  • Deduplication scope (exact match, or relaxed by ignoring line numbers or fingerprints).
  • A second SARIF file for diff.
  • A gating threshold or rule list.

Procedure

1. Load and parse the provided SARIF as JSON. If the input is a file path, read it from the local filesystem. If parsing fails, stop with invalid-input. Done when: the SARIF is parsed as JSON, or an invalid-input stop is reported.
2. Validate the top-level structure of the SARIF object (must contain runs as an array). If the structure is invalid, stop with invalid-sarif. Done when: the top-level structure is validated, or an invalid-sarif stop is reported.
3. Resolve inherited severity for every result that omits an explicit level: walk the rules/ruleDescriptors lookup table in the same run object, then fall back to the tool default (warning). Done when: every result has a resolved severity level.
4. Apply the user request:
   • Inspect / Filter: apply the stated filter criteria to runs[].results[], keeping every result that matches.
   • Deduplicate: within each run, group results by the deduplication scope (exact, or relaxed) and retain one representative per group.
   • Aggregate / Summarize: compute the requested aggregation over the full run set and emit the summary table.
   • Diff: align results from two SARIF inputs by normalized file path plus rule ID; report added results (in B not A) and removed results (in A not B). Normalize file URIs to filesystem paths before comparison.
   • Convert: transform the SARIF into the requested format (CSV, HTML summary, or SARIF variant) preserving the results, rules, and tool metadata.
   • Gate: evaluate each result against the stated threshold or rule list; report pass/fail per rule and overall.
   • Any other request: stop with unsupported-request. Done when: the user request is applied and the requested operation is completed, or an unsupported-request stop is reported.
5. If the requested artifact must be written to a local file, write it to the stated path. Roll back by deleting the file if a subsequent step fails. Done when: the artifact is written to the stated path or confirmed not to require a file.
6. Return the produced findings or derived artifact inline or confirm the written path. Done when: the findings or derived artifact are returned inline or the written path is confirmed.

Failure and recovery

• invalid-input: SARIF is not valid JSON or the file does not exist. Do not produce any artifact.
• invalid-sarif: JSON parses but does not conform to the SARIF 2.1.0+ structure. Do not produce any artifact.
• unsupported-request: The request is not inspect, filter, aggregate, deduplicate, diff, convert, or gate. State that the operation is unsupported and stop without writing.
• results-not-produced: A request for a derived artifact cannot be satisfied (e.g., empty result set after filter). Return an empty result set with a note; do not fabricate findings.

Output

One of:

• A filtered or deduplicated SARIF JSON object.
• A diff report listing added and removed results with rule ID and normalized file path.
• A converted artifact in the requested format (CSV, HTML, or SARIF variant).
• An aggregation summary table with row counts grouped by the requested dimension and any aggregation metadata (tool name, run date, total result count).
• A gating report listing each evaluated rule and its pass/fail status.