refactor(guardrails): extract the scan engine into scanner.py, scan.py keeps the catalogue

This commit is contained in:
bchanot committed 2026-10-19 00:30:03 +02:00
1 parent ed06e8cc1d
commit 988038cce3
2 files changed
+272 -242

No files matched your search

+23 -242
View File
@@ -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))
+249
View File
@@ -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 <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)