forked from bchanot/claude
250 lines
8.3 KiB
Python
250 lines
8.3 KiB
Python
#!/usr/bin/env python3
|
|
"""Static scan engine shared by the guardrails and a11y scanners.
|
|
|
|
A Catalogue names the check modules, the rule prefixes and the MANUAL
|
|
rules; its name gives the report title and the markers the check modes
|
|
print. The engine reads a project tree as data and never executes it.
|
|
Exit codes: 0 no FAIL, 1 at least one FAIL, 2 usage error.
|
|
|
|
Two check modes replace the report and its exit code:
|
|
--assert-absent RULE:path,... exit 0 and print <NAME>-CLEAR only when
|
|
none of these FAIL/WARN pairs remain (a fix contract's oracle);
|
|
--baseline before.json compare with an earlier --json run, exit 0 and
|
|
print <NAME>-NO-NEW only when no FAIL/WARN hit appeared.
|
|
"""
|
|
import argparse
|
|
import json
|
|
import sys
|
|
from collections import Counter
|
|
from dataclasses import dataclass
|
|
from pathlib import Path
|
|
|
|
from checks.common import Project
|
|
|
|
SEVERITY_RANK = {"FAIL": 0, "WARN": 1, "MANUAL": 2}
|
|
GATED = ("FAIL", "WARN")
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Catalogue:
|
|
"""What one scanner CLI exposes."""
|
|
name: str # report title and marker prefix (upper-cased)
|
|
domains: dict # ordered: domain name -> check module
|
|
rule_domains: dict # rule prefix (before the first '-') -> domain
|
|
manual_rules: frozenset = frozenset()
|
|
|
|
@property
|
|
def marker(self):
|
|
return self.name.upper()
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Result:
|
|
findings: list
|
|
applicable: list
|
|
skipped: list
|
|
|
|
|
|
def parse_args(argv, cat):
|
|
parser = argparse.ArgumentParser(
|
|
description=f"{cat.name} static scan: reads the tree, runs nothing")
|
|
parser.add_argument("path", help="project root to scan")
|
|
parser.add_argument(
|
|
"--domain", default=",".join(cat.domains),
|
|
help="comma list among: " + ", ".join(cat.domains))
|
|
parser.add_argument(
|
|
"--exclude", default="",
|
|
help="comma list of relative paths to skip (copies, vendored code)")
|
|
parser.add_argument("--json", action="store_true", help="JSON output")
|
|
parser.add_argument(
|
|
"--assert-absent", default="", metavar="RULE:path,...",
|
|
help="contract oracle: pass only when these pairs are gone")
|
|
parser.add_argument(
|
|
"--baseline", default="", metavar="JSON",
|
|
help="earlier --json run: report fixed, remaining and new hits")
|
|
return parser.parse_args(argv)
|
|
|
|
|
|
def _split(value):
|
|
return [part.strip() for part in value.split(",") if part.strip()]
|
|
|
|
|
|
def run_checks(project, cat, names):
|
|
findings, applicable, skipped = [], [], []
|
|
for name in names:
|
|
module = cat.domains[name]
|
|
if module.applies(project):
|
|
applicable.append(name)
|
|
findings += module.check(project)
|
|
else:
|
|
skipped.append(name)
|
|
findings.sort(key=lambda f: (
|
|
SEVERITY_RANK[f.severity], f.domain, f.path, f.line))
|
|
return Result(findings, applicable, skipped)
|
|
|
|
|
|
def summarize(findings):
|
|
return {sev: sum(f.severity == sev for f in findings)
|
|
for sev in SEVERITY_RANK}
|
|
|
|
|
|
def _domain_lines(domain, findings):
|
|
rows = [f for f in findings if f.domain == domain]
|
|
return [f"\n[{domain}]"] + (
|
|
[f" {f.severity:<6} {f.rule:<24} {f.path}:{f.line} {f.message}"
|
|
for f in rows] or [" no finding"])
|
|
|
|
|
|
def _summary_line(findings):
|
|
totals = summarize(findings)
|
|
return "\nsummary: " + ", ".join(
|
|
f"{n} {sev}" for sev, n in totals.items())
|
|
|
|
|
|
def render_text(project, cat, result):
|
|
lines = [
|
|
f"{cat.name} scan: {project.root} ({len(project.files)} files)",
|
|
"scanned: " + (", ".join(result.applicable) or "none"),
|
|
]
|
|
if result.skipped:
|
|
lines.append("not applicable: " + ", ".join(result.skipped))
|
|
for domain in result.applicable:
|
|
lines += _domain_lines(domain, result.findings)
|
|
return "\n".join(lines + [_summary_line(result.findings)])
|
|
|
|
|
|
def render_json(project, result):
|
|
return json.dumps({
|
|
"root": str(project.root), "files": len(project.files),
|
|
"applicable": result.applicable, "not_applicable": result.skipped,
|
|
"summary": summarize(result.findings),
|
|
"findings": [f.as_dict() for f in result.findings],
|
|
}, indent=2)
|
|
|
|
|
|
def _rule_domain(cat, rule):
|
|
return cat.rule_domains.get(rule.split("-", 1)[0])
|
|
|
|
|
|
def _pairs(value):
|
|
"""'RULE:path,RULE:path' -> [(rule, path)]; a missing path stays ''."""
|
|
return [tuple(p.strip() for p in item.partition(":")[::2])
|
|
for item in _split(value)]
|
|
|
|
|
|
def _assert_error(cat, value):
|
|
for rule, path in _pairs(value):
|
|
if not path or not _rule_domain(cat, rule):
|
|
return f"bad --assert-absent item {rule}:{path}, want RULE:path"
|
|
if rule in cat.manual_rules:
|
|
return f"{rule} is MANUAL: no static scan can prove it fixed"
|
|
return ""
|
|
|
|
|
|
def _hits(findings):
|
|
return Counter((f.rule, f.path) for f in findings if f.severity in GATED)
|
|
|
|
|
|
def _load_baseline(path):
|
|
data = json.loads(Path(path).read_text(encoding="utf-8"))
|
|
return Counter((f["rule"], f["path"]) for f in data["findings"]
|
|
if f["severity"] in GATED)
|
|
|
|
|
|
def _baseline_error(path):
|
|
if not path:
|
|
return ""
|
|
try:
|
|
_load_baseline(path)
|
|
except (OSError, ValueError, KeyError, TypeError) as exc:
|
|
return f"unreadable baseline {path}: {exc}"
|
|
return ""
|
|
|
|
|
|
def _usage_error(cat, args):
|
|
unknown = [n for n in _split(args.domain) if n not in cat.domains]
|
|
if unknown:
|
|
return f"unknown domain {unknown}"
|
|
if not Path(args.path).is_dir():
|
|
return f"not a directory: {args.path}"
|
|
return (_assert_error(cat, args.assert_absent)
|
|
or _baseline_error(args.baseline))
|
|
|
|
|
|
def _pair_status(cat, hits, applicable, pair):
|
|
rule, path = pair
|
|
if _rule_domain(cat, rule) not in applicable:
|
|
return False, f" CONTROL {rule} {path}: domain not scanned, " \
|
|
"absence proves nothing"
|
|
if hits[pair]:
|
|
plural = "s" if hits[pair] > 1 else ""
|
|
return False, f" PRESENT {rule} {path} ({hits[pair]} hit{plural})"
|
|
return True, f" CLEAR {rule} {path}"
|
|
|
|
|
|
def assert_absent(project, cat, result, pairs):
|
|
"""Positive control first: an empty tree or an unscanned domain fails."""
|
|
hits = _hits(result.findings)
|
|
rows = [_pair_status(cat, hits, result.applicable, p) for p in pairs]
|
|
lines = [text for _, text in rows]
|
|
if not project.files:
|
|
lines.insert(0, " CONTROL no file scanned, absence proves nothing")
|
|
ok = bool(project.files) and all(passed for passed, _ in rows)
|
|
marker = [f"{cat.marker}-CLEAR {len(pairs)}"] if ok else []
|
|
return ok, lines + marker
|
|
|
|
|
|
def _moved(more, less):
|
|
"""Pairs where `more` holds extra hits over `less`, with the surplus."""
|
|
return [(key, more[key] - less[key]) for key in sorted(more)
|
|
if more[key] > less[key]]
|
|
|
|
|
|
def _rows(tag, moved, sign):
|
|
return [f" {tag:<5} {rule} {path} ({sign}{n})"
|
|
for (rule, path), n in moved]
|
|
|
|
|
|
def baseline_report(cat, before, result):
|
|
after = _hits(result.findings)
|
|
fixed, new = _moved(before, after), _moved(after, before)
|
|
summary = (f"baseline: {sum(n for _, n in fixed)} fixed, "
|
|
f"{sum((before & after).values())} remaining, "
|
|
f"{sum(n for _, n in new)} new")
|
|
lines = _rows("FIXED", fixed, "-") + _rows("NEW", new, "+") + [summary]
|
|
return not new, lines + ([] if new else [f"{cat.marker}-NO-NEW"])
|
|
|
|
|
|
def _check_modes(project, cat, result, args):
|
|
checks = []
|
|
if args.assert_absent:
|
|
checks.append(
|
|
assert_absent(project, cat, result, _pairs(args.assert_absent)))
|
|
if args.baseline:
|
|
checks.append(
|
|
baseline_report(cat, _load_baseline(args.baseline), result))
|
|
return checks
|
|
|
|
|
|
def _scan(cat, args):
|
|
project = Project(Path(args.path), _split(args.exclude))
|
|
result = run_checks(project, cat, _split(args.domain))
|
|
checks = _check_modes(project, cat, result, args)
|
|
if not checks:
|
|
text = (render_json(project, result) if args.json
|
|
else render_text(project, cat, result))
|
|
print(text)
|
|
return 1 if any(f.severity == "FAIL" for f in result.findings) else 0
|
|
for _, lines in checks:
|
|
print("\n".join(lines))
|
|
return 0 if all(ok for ok, _ in checks) else 1
|
|
|
|
|
|
def main(argv, cat):
|
|
args = parse_args(argv, cat)
|
|
error = _usage_error(cat, args)
|
|
if error:
|
|
print(f"usage error: {error}", file=sys.stderr)
|
|
return 2
|
|
return _scan(cat, args)
|