igbuend/sarif-tools

SARIF Tools

Microsoft's sarif-tools — a Python CLI and library for working with SARIF (Static Analysis Results Interchange Format) files.

Installation

# pip
pip install sarif-tools

# pipx (recommended — isolated environment)
pipx install sarif-tools

# Verify
sarif --version

If sarif is not on PATH after install, use python -m sarif instead.

Commands

| Command | Purpose | |---------|---------| | summary | Text summary with issue counts by severity and tool | | csv | Export issues to CSV for spreadsheet analysis | | html | Generate HTML report for browser viewing | | word | Generate MS Word (.docx) summary report | | diff | Compare two sets of SARIF files (new vs old findings) | | copy | Merge/filter SARIF files into a single consolidated file | | blame | Augment SARIF with git blame info (who last modified each line) | | codeclimate | Convert to Code Climate JSON for GitLab Code Quality reports | | info | Print structural information about SARIF files | | ls | List all SARIF files in a directory | | trend | Generate CSV time series from timestamped SARIF files | | emacs | Output in emacs-compatible format |

Usage Examples

Summarize Findings

# Summary of a single file
sarif summary scan-results.sarif

# Summary of all SARIF files in a directory
sarif summary ./sarif-output/

Output shows counts by severity (error, warning, note) grouped by tool and rule.

Consolidate Multiple SARIF Files

# Merge all SARIF files into one
sarif copy -o consolidated.sarif ./sarif-output/

# Merge with timestamp in filename (for trend tracking)
sarif copy -o consolidated.sarif --timestamp ./sarif-output/

Export to CSV

# Basic CSV export
sarif csv -o findings.csv ./sarif-output/

# Strip common path prefix for cleaner output
sarif csv --autotrim -o findings.csv ./sarif-output/

# Strip specific prefix
sarif csv --trim /home/user/project -o findings.csv ./sarif-output/

CSV includes columns: severity, rule ID, message, file, line. If blame info is present, includes author.

Generate HTML Report

sarif html -o report.html ./sarif-output/

Generate Word Report

sarif word -o report.docx ./sarif-output/

Diff Between Builds

# Compare old vs new scan results
sarif diff ./old-sarif/ ./new-sarif/

# Output diff to JSON file
sarif diff -o diff-report.json ./old-sarif/ ./new-sarif/

# Exit with error if new issues at warning level or above
sarif diff --check warning ./old-sarif/ ./new-sarif/

Add Git Blame Information

# Augment SARIF with blame info (run from git repo root)
sarif blame -o ./blamed-sarif/ ./sarif-output/

# Specify git repo path explicitly
sarif blame -o ./blamed-sarif/ -c /path/to/repo ./sarif-output/

Adds author, commit, timestamp to each finding's property bag. Enables author-based filtering and CSV author column.

Code Climate for GitLab

# Generate Code Climate JSON for GitLab merge request UI
sarif codeclimate -o codeclimate.json ./sarif-output/

Publish as a Code Quality artifact in GitLab CI pipeline.

Filtering

After running sarif blame, use filter files to include/exclude findings by author, date, or other blame properties:

# Apply filter to CSV export
sarif csv --filter my-filter.yaml -o filtered.csv ./blamed-sarif/

# Apply filter to copy (consolidated output)
sarif copy --filter my-filter.yaml -o filtered.sarif ./blamed-sarif/

Filter file format (YAML):

# Include only findings from specific authors
include:
  author:
    - "[email protected]"

# Exclude findings from specific authors
exclude:
  author:
    - "[email protected]"

CI/CD Integration

# Exit with error code if any error-level findings exist
sarif --check error summary ./sarif-output/

# Exit with error code if any warning-or-above findings exist
sarif --check warning summary ./sarif-output/

# Check for regressions between builds
sarif diff --check warning ./baseline-sarif/ ./current-sarif/

File Discovery

# List all SARIF files in a directory tree
sarif ls ./project-output/

# Get structural info about SARIF files
sarif info ./sarif-output/

Trend Analysis

# Generate CSV time series from timestamped SARIF files
# Files must have timestamps in filenames: myapp_tool_20260212T120000Z.sarif
sarif trend -o trend.csv ./sarif-history/

SARIF Format Notes

SARIF v2.1.0 is the standard format. Key fields used by sarif-tools:

• Severity levels: error, warning, note, none
• Result fields: ruleId, message, level, locations, codeFlows
• Location: physicalLocation.artifactLocation.uri + region.startLine

Different tools map their severity levels differently. sarif-tools handles common variations, but some tools may need preprocessing for best results.

Glob Patterns

All commands accept glob patterns for input:

# Process all devskim SARIF files recursively
sarif summary "./output/**/devskim*.sarif"

Python Library Usage

from sarif import loader

# Load SARIF files
sarif_files = loader.loader("./sarif-output/")

# Access results programmatically
for run in sarif_files:
    for result in run.get_results():
        print(result.get("ruleId"), result.get("level"))

References

• Repository: https://github.com/microsoft/sarif-tools
• PyPI: https://pypi.org/project/sarif-tools/
• SARIF Standard: https://sarifweb.azurewebsites.net/
• SARIF Spec (OASIS): https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html