diff --git a/CHANGELOG.md b/CHANGELOG.md index 4bfc599..862eee2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ All notable changes are documented here, in [Keep a Changelog](https://keepachan - README covers common questions ### Added +- `lint` can emit SARIF 2.1.0 reports with stable descriptors for all finding codes. - `explain` shows the permission decision for each subcommand. - `lint` reports nine kinds of ineffective or risky rule. - `explaining-permissions` skill and plugin manifest. diff --git a/README.md b/README.md index d64649e..84683d5 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,9 @@ Try both commands on the rules in `examples/settings.json`. PW007 Bash(aws s3 ls) (examples/settings.json) Shadowed by deny rule Bash(aws *). An allow rule can't carve an exception out of a deny rule. -`lint` exits 1 when it has findings, so it can run in CI. Add `--json` before the subcommand for machine-readable output. Without `--settings`, it reads `~/.claude/settings.json`, `.claude/settings.json` and `.claude/settings.local.json`. +`lint` exits 1 when it has findings, so it can run in CI. Add `--json` before the subcommand for JSON output, or `--sarif` before `lint` for a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html) report suitable for code-scanning consumers. The SARIF report includes descriptors for all nine `PWnnn` rules and points each result to its settings file. Without `--settings`, it reads `~/.claude/settings.json`, `.claude/settings.json` and `.claude/settings.local.json`. + + $ python3 plugin/scripts/permwhy.py --settings examples/settings.json --sarif lint > permwhy.sarif | Code | Finding | |---|---| diff --git a/ROADMAP.md b/ROADMAP.md index 291aaf4..c55dbda 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -3,7 +3,6 @@ ## Next - Environment variable prefixes in `explain` - `Read` and `Edit` rule explanations -- SARIF output for `lint` ## Later - `PowerShell(...)` rules diff --git a/plugin/scripts/permwhy.py b/plugin/scripts/permwhy.py index 31167e6..e940665 100644 --- a/plugin/scripts/permwhy.py +++ b/plugin/scripts/permwhy.py @@ -13,6 +13,7 @@ import sys from dataclasses import asdict, dataclass, field from pathlib import Path +from urllib.parse import quote SEPARATORS = ("&&", "||", "|&", ";", "|", "&", "\n") LEADING_KEYWORDS = {"if", "then", "else", "elif", "while", "until", "do", "!", "{"} @@ -58,6 +59,19 @@ class Finding: message: str +SARIF_RULES = { + "PW001": "Invalid permission rule", + "PW002": "Duplicate permission rule", + "PW003": "Blanket Bash allow", + "PW004": "Wildcarded interpreter allow", + "PW005": "Wildcarded package-manager run allow", + "PW006": "Wildcarded command runner allow", + "PW007": "Allow rule shadowed by a deny rule", + "PW008": "Deny or ask rule matches command text only", + "PW009": "Fragile URL permission pattern", +} + + def split_command(command): """Return ([top-level subcommands], [nested subcommands], parseable).""" top, nested = [], [] @@ -353,16 +367,61 @@ def _print_explanation(result): print(f" {item.decision:8} {item.command}{where}{suffix}") +def _sarif_report(findings): + """Return lint findings as a SARIF 2.1.0 log.""" + rules = [ + {"id": code, "shortDescription": {"text": description}} + for code, description in SARIF_RULES.items() + ] + results = [] + for finding in findings: + source_path = Path(finding.source) + if source_path.is_absolute(): + artifact_location = {"uri": source_path.as_uri()} + else: + artifact_location = { + "uri": quote(source_path.as_posix(), safe="/:@-._~"), + "uriBaseId": "%SRCROOT%", + } + result = { + "ruleId": finding.code, + "level": "warning", + "message": {"text": finding.message}, + "locations": [{ + "physicalLocation": { + "artifactLocation": artifact_location + } + }], + } + results.append(result) + return { + "$schema": "https://json.schemastore.org/sarif-2.1.0.json", + "version": "2.1.0", + "runs": [{ + "tool": {"driver": {"name": "permwhy", "rules": rules}}, + "originalUriBaseIds": { + "%SRCROOT%": {"uri": Path.cwd().as_uri() + "/"} + }, + "results": results, + }], + } + + def main(argv=None): parser = argparse.ArgumentParser(prog="permwhy", description="Explain and lint Claude Code Bash permission rules.") parser.add_argument("--settings", action="append", help="settings file to read (repeatable); defaults to the user and project files") - parser.add_argument("--json", action="store_true", help="print JSON") + output = parser.add_mutually_exclusive_group() + output.add_argument("--json", action="store_true", help="print JSON") + output.add_argument("--sarif", action="store_true", help="print SARIF 2.1.0 (lint only)") commands = parser.add_subparsers(dest="action", required=True) explain_parser = commands.add_parser("explain", help="explain the decision for a command") explain_parser.add_argument("shell_command") commands.add_parser("lint", help="find ineffective or risky rules") args = parser.parse_args(argv) + if args.sarif and args.action != "lint": + parser.error("--sarif is only available with lint") + rules, errors = load_rules(args.settings or default_settings_paths()) for error in errors: print(f"permwhy: {error}", file=sys.stderr) @@ -378,6 +437,9 @@ def main(argv=None): return 0 findings = lint(rules) + if args.sarif: + print(json.dumps(_sarif_report(findings), indent=2)) + return 1 if findings else 0 if args.json: print(json.dumps([asdict(f) for f in findings], indent=2)) else: diff --git a/tests/test_permwhy.py b/tests/test_permwhy.py index 0eec9aa..3334c1d 100644 --- a/tests/test_permwhy.py +++ b/tests/test_permwhy.py @@ -167,6 +167,50 @@ def test_lint_exit_codes(self): self.assertEqual(self.run_cli('{"permissions":{"allow":["Bash(*)"]}}', "lint")[0], 1) self.assertEqual(self.run_cli('{"permissions":{"allow":["Bash(ls)"]}}', "lint")[0], 0) + def test_lint_sarif_maps_findings_to_rules_and_source_locations(self): + code, output = self.run_cli('{"permissions":{"allow":["Bash(*)"]}}', "--sarif", "lint") + report = json.loads(output) + + self.assertEqual(code, 1) + self.assertEqual(report["version"], "2.1.0") + self.assertEqual(report["$schema"], "https://json.schemastore.org/sarif-2.1.0.json") + run = report["runs"][0] + self.assertEqual(run["tool"]["driver"]["name"], "permwhy") + rules_by_id = {rule["id"]: rule for rule in run["tool"]["driver"]["rules"]} + self.assertEqual(set(rules_by_id), set(permwhy.SARIF_RULES)) + finding = run["results"][0] + self.assertEqual(finding["ruleId"], "PW003") + self.assertEqual(finding["level"], "warning") + self.assertIn("Blanket Bash allow", finding["message"]["text"]) + self.assertTrue( + finding["locations"][0]["physicalLocation"]["artifactLocation"]["uri"].startswith( + "file:///" + ) + ) + + def test_sarif_resolves_relative_paths_from_source_root(self): + finding = permwhy.Finding("PW003", "Bash(*)", "examples/settings.json", "unsafe allow") + report = permwhy._sarif_report([finding]) + run = report["runs"][0] + location = run["results"][0]["locations"][0]["physicalLocation"]["artifactLocation"] + + self.assertEqual(location["uri"], "examples/settings.json") + self.assertEqual(location["uriBaseId"], "%SRCROOT%") + self.assertTrue(run["originalUriBaseIds"]["%SRCROOT%"]["uri"].startswith("file:///")) + + def test_lint_sarif_is_valid_with_no_findings(self): + code, output = self.run_cli('{"permissions":{"allow":["Bash(ls)"]}}', "--sarif", "lint") + report = json.loads(output) + + self.assertEqual(code, 0) + self.assertEqual(report["runs"][0]["results"], []) + self.assertEqual(len(report["runs"][0]["tool"]["driver"]["rules"]), 9) + + def test_sarif_is_lint_only(self): + with self.assertRaises(SystemExit) as error: + self.run_cli('{"permissions":{}}', "--sarif", "explain", "ls") + self.assertEqual(error.exception.code, 2) + def test_broken_settings_file(self): self.assertEqual(self.run_cli("{oops", "lint")[0], 2)