SARIF Tools

3.0.5 · active · verified Mon Apr 13

sarif-tools is a Python library and command-line interface for working with Static Analysis Results Interchange Format (SARIF) files. It provides utilities for summarizing, comparing, transforming, and extracting information from SARIF reports. The current version is 3.0.5, with an active development cadence focusing on bug fixes and occasional breaking changes in major versions.

Warnings

breaking The Python API for `SarifFileSet` changed significantly in v3.0.0. Direct methods like `get_result_count_by_severity()` and `get_records_grouped_by_severity()` were removed. You must now call `sarif_set.get_report()` to get an `IssueReport` object, which exposes the new methods for issue grouping and sorting.
Fix: Update your code to call `sarif_set.get_report()` and then use methods on the returned `IssueReport` object (e.g., `report.get_issue_count_for_severity(severity)` or `report.get_issues_for_severity(severity)`).
breaking In v2.0.0, the CSV output format for the CLI (`sarif csv`) changed: 'Code' and 'Description' are now separate columns, previously combined. Also, the `--blame-filter` argument was replaced by a more general `--filter` which uses a new YAML-based format.
Fix: If parsing CSV output, update your parsing logic for the new column structure. For filtering, replace `--blame-filter` with `--filter` and adapt your filter definitions to the new YAML format. Use the `upgrade-filter` command to assist with conversion.
gotcha Immediate minor releases after a major version (e.g., v3.0.1 after v3.0.0) have historically contained critical bug fixes for commands like `sarif diff`.
Fix: Always use the latest patch release of a major version. For example, if upgrading to v3, use v3.0.5 or later, not v3.0.0.
gotcha When processing SARIF files that may contain non-UTF-8 encoded strings, older versions of `sarif-tools` could crash with `UnicodeDecodeError` when using commands like `sarif blame`.
Fix: Upgrade to `sarif-tools` v3.0.5 or newer to benefit from fixes handling invalid UTF-8.
gotcha The `--check` command previously had a crash issue in certain scenarios.
Fix: Upgrade to `sarif-tools` v3.0.4 or newer to resolve crashes with the `--check` command.

Install

pip install sarif-tools Install stable version

Imports

SarifFileSet
```
from sarif_tools.sarif_file_set import SarifFileSet
```
SarifFileSet is located within the sarif_file_set submodule, not directly under sarif_tools.
IssueReport
```
from sarif_tools.issue_report import IssueReport
```
IssueReport is located within the issue_report submodule, not directly under sarif_tools.

Quickstart

This quickstart demonstrates how to load a SARIF file using `SarifFileSet`, access its issue report via `get_report()`, and then retrieve issues filtered by severity using the v3.0.0+ API. It creates a temporary dummy SARIF file for the example.

import os
import json
from sarif_tools.sarif_file_set import SarifFileSet

# Create a dummy SARIF file for demonstration
dummy_sarif_content = {
    "$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json",
    "version": "2.1.0",
    "runs": [
        {
            "tool": {
                "driver": {
                    "name": "Dummy Tool"
                }
            },
            "results": [
                {
                    "message": {"text": "A dummy error was found."},
                    "locations": [
                        {
                            "physicalLocation": {
                                "artifactLocation": {"uri": "dummy_code.py"},
                                "region": {"startLine": 1, "startColumn": 1}
                            }
                        }
                    ],
                    "level": "error",
                    "ruleId": "DUMMY001"
                },
                {
                    "message": {"text": "A dummy warning was found."},
                    "locations": [
                        {
                            "physicalLocation": {
                                "artifactLocation": {"uri": "dummy_code.py"},
                                "region": {"startLine": 5, "startColumn": 10}
                            }
                        }
                    ],
                    "level": "warning",
                    "ruleId": "DUMMY002"
                }
            ]
        }
    ]
}

dummy_sarif_path = "dummy_report.sarif"
with open(dummy_sarif_path, "w", encoding="utf-8") as f:
    json.dump(dummy_sarif_content, f, indent=2)

try:
    # Load a SARIF file set
    sarif_set = SarifFileSet(dummy_sarif_path)

    # Get the issue report (introduced in v3.0.0)
    report = sarif_set.get_report()

    # Get issues for a specific severity
    error_issues = report.get_issues_for_severity('error')
    print(f"Found {len(error_issues)} error(s):")
    for issue in error_issues:
        print(f"  - {issue.message} at {issue.location_string}")

    warning_issues = report.get_issues_for_severity('warning')
    print(f"\nFound {len(warning_issues)} warning(s):")
    for issue in warning_issues:
        print(f"  - {issue.message} at {issue.location_string}")

finally:
    # Clean up the dummy file
    if os.path.exists(dummy_sarif_path):
        os.remove(dummy_sarif_path)

view raw JSON →