{"id":5468,"library":"sarif-tools","title":"SARIF Tools","description":"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.","status":"active","version":"3.0.5","language":"en","source_language":"en","source_url":"https://github.com/microsoft/sarif-tools","tags":["SARIF","security","static analysis","reporting","CLI"],"install":[{"cmd":"pip install sarif-tools","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"SarifFileSet is located within the sarif_file_set submodule, not directly under sarif_tools.","wrong":"from sarif_tools import SarifFileSet","symbol":"SarifFileSet","correct":"from sarif_tools.sarif_file_set import SarifFileSet"},{"note":"IssueReport is located within the issue_report submodule, not directly under sarif_tools.","wrong":"from sarif_tools import IssueReport","symbol":"IssueReport","correct":"from sarif_tools.issue_report import IssueReport"}],"quickstart":{"code":"import os\nimport json\nfrom sarif_tools.sarif_file_set import SarifFileSet\n\n# Create a dummy SARIF file for demonstration\ndummy_sarif_content = {\n    \"$schema\": \"https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json\",\n    \"version\": \"2.1.0\",\n    \"runs\": [\n        {\n            \"tool\": {\n                \"driver\": {\n                    \"name\": \"Dummy Tool\"\n                }\n            },\n            \"results\": [\n                {\n                    \"message\": {\"text\": \"A dummy error was found.\"},\n                    \"locations\": [\n                        {\n                            \"physicalLocation\": {\n                                \"artifactLocation\": {\"uri\": \"dummy_code.py\"},\n                                \"region\": {\"startLine\": 1, \"startColumn\": 1}\n                            }\n                        }\n                    ],\n                    \"level\": \"error\",\n                    \"ruleId\": \"DUMMY001\"\n                },\n                {\n                    \"message\": {\"text\": \"A dummy warning was found.\"},\n                    \"locations\": [\n                        {\n                            \"physicalLocation\": {\n                                \"artifactLocation\": {\"uri\": \"dummy_code.py\"},\n                                \"region\": {\"startLine\": 5, \"startColumn\": 10}\n                            }\n                        }\n                    ],\n                    \"level\": \"warning\",\n                    \"ruleId\": \"DUMMY002\"\n                }\n            ]\n        }\n    ]\n}\n\ndummy_sarif_path = \"dummy_report.sarif\"\nwith open(dummy_sarif_path, \"w\", encoding=\"utf-8\") as f:\n    json.dump(dummy_sarif_content, f, indent=2)\n\ntry:\n    # Load a SARIF file set\n    sarif_set = SarifFileSet(dummy_sarif_path)\n\n    # Get the issue report (introduced in v3.0.0)\n    report = sarif_set.get_report()\n\n    # Get issues for a specific severity\n    error_issues = report.get_issues_for_severity('error')\n    print(f\"Found {len(error_issues)} error(s):\")\n    for issue in error_issues:\n        print(f\"  - {issue.message} at {issue.location_string}\")\n\n    warning_issues = report.get_issues_for_severity('warning')\n    print(f\"\\nFound {len(warning_issues)} warning(s):\")\n    for issue in warning_issues:\n        print(f\"  - {issue.message} at {issue.location_string}\")\n\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(dummy_sarif_path):\n        os.remove(dummy_sarif_path)\n","lang":"python","description":"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."},"warnings":[{"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)`).","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"~3.0.0"},{"fix":"Upgrade to `sarif-tools` v3.0.5 or newer to benefit from fixes handling invalid UTF-8.","message":"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`.","severity":"gotcha","affected_versions":"<3.0.5"},{"fix":"Upgrade to `sarif-tools` v3.0.4 or newer to resolve crashes with the `--check` command.","message":"The `--check` command previously had a crash issue in certain scenarios.","severity":"gotcha","affected_versions":"<3.0.4"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}