SARIF Tools

When working with SarifFileSet, SarifFile, or SarifRun, data is presented at three levels of aggregation:

1. Results: Raw dicts deserialized directly from the SARIF JSON Result objects (per SARIF standard section 3.27).
2. Records: Flat dicts containing sarif_file.BASIC_RECORD_ATTRIBUTES. This is ideal for machine-readable formats like CSV. Attributes include:
   • Tool: Tool name.
   • Severity: error, warning (default), note, or none.
   • Code: Issue code.
   • Description: Issue name.
   • Location: File location.
   • Line: Line number (string, defaults to "1").
3. Reports: IssuesReport objects. These group and sort records to provide structured, human-readable data (e.g., for Word or HTML).

SARIF Tools processes SARIF files by looking at specific key components. While the tool applies some 'fudging' to handle mildly divergent implementations, it expects the following standard elements:

• Severity: Should be one of error, warning, note, or none.
• Code and Message: Issue types should have a short code and a short name (referred to as message in the SARIF standard, but often called description within SARIF Tools).
• Location: A specific location for the issue, typically a file path and line number.

If the tool produces incorrect results for a specific static analysis tool, it may be due to non-standard representations (e.g., putting real severity in custom properties or embedding location info inside the message). In such cases, you may need to pre-process the SARIF output before passing it to SARIF Tools.

SARIF Tools can be installed using pip. Ensure you have Python 3.8 or later installed. The installation creates a sarif (or sarif.exe on Windows) executable in your Python Scripts directory.

Windows Installation

Open a user command prompt and run:

pip install sarif-tools

If you see a warning that the script is not on PATH, add the Python Scripts directory to your environment variables via Windows Settings.

Linux or Mac Installation

Run:

pip install sarif-tools

If you see a warning that the script is not on PATH, add the installation directory (e.g., ~/.local/bin) to your PATH by editing ~/.profile and running source ~/.profile.

Note: Installing system-wide using sudo pip install (Linux) or an Administrator command prompt (Windows) is possible but discouraged for security reasons.

You can use sarif-tools within Python scripts to load and analyze SARIF data. Use sarif.loader to load files into SarifFile or SarifFileSet objects, which provide methods to explore results, records, and reports.

Common workflow:

1. Load data using loader.load_sarif_file(path).
2. Access raw results via .get_results().
3. Access flattened records (useful for CSV) via .get_records().
4. Access structured reports via .get_report().

from sarif import loader

# Load a SARIF file
sarif_data = loader.load_sarif_file('path_to_sarif_file')

# Get a report object for human-readable analysis
report = sarif_data.get_report()

# Get a histogram of issue types for a specific severity
error_histogram = report.get_issue_type_histogram_for_severity("error")

To use sarif-tools in a Continuous Integration (CI) pipeline to enforce quality gates, use the --check flag with the summary or diff commands. This causes the tool to exit with a non-zero exit code if issues are found at or above the specified level.

Valid severity levels for --check: error, warning, note.

Examples:

• Fail if there are any errors or warnings: sarif --check warning summary c:\temp\sarif_files
• Fail if there are any new issues at the error level compared to a baseline: sarif --check error diff c:\temp\old_sarif_files c:\temp\sarif_files

The sarif tool supports multiple output formats for human-readable or machine-readable reports:

# Generate an HTML report
sarif html input.sarif -o report.html

# Generate a CSV report with path trimming
sarif csv input.sarif -o report.csv --trim /home/user/project

After installation, verify that the tool is accessible in your terminal by checking its version:

sarif --version

If the sarif command is not recognized after installation, it is likely because the Python Scripts directory is not in your PATH environment variable.

Solutions:

1. Add to PATH: Locate the Scripts directory (where sarif or sarif.exe was installed) and add it to your system's PATH variable.
2. Use Python module syntax: If you cannot modify your PATH, you can run the tool directly using Python:

   python -m sarif

Debugging Path Conflicts:

• Windows: Use where python and where pip in both normal and Administrator command prompts to verify which installations are being used.
• Linux: Use which python and which pip (with and without sudo) to check for installation mismatches.

You can use the CLI to enrich SARIF data with blame information and combine multiple tool outputs into a single consolidated file.

Workflow Example:

1. Blame: Augment a SARIF file with blame information: sarif blame -o <output_file>.sarif <input_file>.sarif
2. Copy/Consolidate: Combine multiple files into one, adding a timestamp to the output filename: sarif copy --timestamp -o artifacts/combined.sarif

# Augment with blame
sarif blame -o with_blame/myapp_mytool_with_blame.sarif myapp_mytool.sarif

# Combine all tools into one file with a timestamp
sarif copy --timestamp -o artifacts/myapp_alltools_with_blame.sarif

You can manipulate how file paths are represented in your SARIF objects using the following APIs:

Path Shortening Use init_path_prefix_stripping(autotrim, path_prefixes) on a SarifFileSet, SarifFile, or SarifRun to:

• Set autotrim=True to automatically remove the longest common prefix.
• Set autotrim=False and provide a list of path_prefixes to remove specific strings.

General Filtering Use init_general_filter(filter_description, include_filters, exclude_filters) to apply inclusion/exclusion rules.

• After processing, call get_filter_stats() to get a FilterStats object containing filtered_in_result_count and filtered_out_result_count.