diff --git a/skills/guardrails/scripts/scan.py b/skills/guardrails/scripts/scan.py index 3c13a65..c5e4935 100644 --- a/skills/guardrails/scripts/scan.py +++ b/skills/guardrails/scripts/scan.py @@ -1,251 +1,32 @@ #!/usr/bin/env python3 -"""Static guardrails scan: API, hosting, a11y, Supabase, messaging, functions. +"""Static guardrails scan: the guardrails catalogue on the shared 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 GUARDRAILS-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 GUARDRAILS-NO-NEW only when no FAIL/WARN hit appeared. +See scanner.py for the modes and exit codes. """ -import argparse -import json import sys -from collections import Counter -from dataclasses import dataclass -from pathlib import Path +import scanner from checks import a11y, apis, functions, hosting, messaging, supabase -from checks.common import Project - -DOMAINS = { - "api": apis, - "hosting": hosting, - "a11y": a11y, - "supabase": supabase, - "messaging": messaging, - "functions": functions, -} -SEVERITY_RANK = {"FAIL": 0, "WARN": 1, "MANUAL": 2} -RULE_DOMAINS = { - "API": "api", "HOST": "hosting", "A11Y": "a11y", "SB": "supabase", - "MSG": "messaging", "FN": "functions", -} -MANUAL_RULES = { - "HOST-WAF-DDOS", "HOST-SPEND-CAP", "SB-RLS-LIVE", "FN-CAP-UNVERIFIED", - "FN-BUDGET-STOP", -} -GATED = ("FAIL", "WARN") - - -@dataclass(frozen=True) -class Result: - findings: list - applicable: list - skipped: list - - -def parse_args(argv): - parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) - parser.add_argument("path", help="project root to scan") - parser.add_argument( - "--domain", default=",".join(DOMAINS), - help="comma list among: " + ", ".join(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, names): - findings, applicable, skipped = [], [], [] - for name in names: - module = 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, result): - lines = [ - f"guardrails 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(rule): - return 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(value): - for rule, path in _pairs(value): - if not path or not _rule_domain(rule): - return f"bad --assert-absent item {rule}:{path}, want RULE:path" - if rule in 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(args): - unknown = [n for n in _split(args.domain) if n not in 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(args.assert_absent) or _baseline_error(args.baseline) - - -def _pair_status(hits, applicable, pair): - rule, path = pair - if _rule_domain(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, result, pairs): - """Positive control first: an empty tree or an unscanned domain fails.""" - rows = [_pair_status(_hits(result.findings), 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) - return ok, lines + ([f"GUARDRAILS-CLEAR {len(pairs)}"] if ok else []) - - -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(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 ["GUARDRAILS-NO-NEW"]) - - -def _check_modes(project, result, args): - checks = [] - if args.assert_absent: - checks.append( - assert_absent(project, result, _pairs(args.assert_absent))) - if args.baseline: - checks.append( - baseline_report(_load_baseline(args.baseline), result)) - return checks - - -def _scan(args): - project = Project(Path(args.path), _split(args.exclude)) - result = run_checks(project, _split(args.domain)) - checks = _check_modes(project, result, args) - if not checks: - render = render_json if args.json else render_text - print(render(project, result)) - 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): - args = parse_args(argv) - error = _usage_error(args) - if error: - print(f"usage error: {error}", file=sys.stderr) - return 2 - return _scan(args) +CATALOGUE = scanner.Catalogue( + name="guardrails", + domains={ + "api": apis, + "hosting": hosting, + "a11y": a11y, + "supabase": supabase, + "messaging": messaging, + "functions": functions, + }, + rule_domains={ + "API": "api", "HOST": "hosting", "A11Y": "a11y", "SB": "supabase", + "MSG": "messaging", "FN": "functions", + }, + manual_rules=frozenset({ + "HOST-WAF-DDOS", "HOST-SPEND-CAP", "SB-RLS-LIVE", + "FN-CAP-UNVERIFIED", "FN-BUDGET-STOP", + }), +) if __name__ == "__main__": - sys.exit(main(sys.argv[1:])) + sys.exit(scanner.main(sys.argv[1:], CATALOGUE)) diff --git a/skills/guardrails/scripts/scanner.py b/skills/guardrails/scripts/scanner.py new file mode 100644 index 0000000..c19a437 --- /dev/null +++ b/skills/guardrails/scripts/scanner.py @@ -0,0 +1,249 @@ +#!/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 -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 -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)