Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|
Expand Down
1 change: 0 additions & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
## Next
- Environment variable prefixes in `explain`
- `Read` and `Edit` rule explanations
- SARIF output for `lint`

## Later
- `PowerShell(...)` rules
Expand Down
64 changes: 63 additions & 1 deletion plugin/scripts/permwhy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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", "!", "{"}
Expand Down Expand Up @@ -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 = [], []
Expand Down Expand Up @@ -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)
Expand All @@ -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:
Expand Down
44 changes: 44 additions & 0 deletions tests/test_permwhy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down