igbuend 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:
- "developer@company.com"
# Exclude findings from specific authors
exclude:
author:
- "bot@company.com"
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