Files
bchanot 5a98c2c095 fix(guardrails): probe fails closed on budget, redirects and unread bodies; rules lose five false positives and gain seven misses
The probe trusted the plan's Supabase url, followed redirects for free,
crashed on deep JSON and stopped at the first unconfirmed map candidate.
Rules now scope hydrated state to the export chunk, silence dev configs,
UI-suffixed data attributes, GraphQL types and metadata keys, and catch
Go raw strings, triple-quoted f-strings, sql.raw, empty select() and
multi-line hidden inputs; text output is sanitised; per-variant locks.
2026-10-21 00:13:32 +02:00

255 lines
8.5 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, printable
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 _safe_text(text):
"""Control characters from file names and messages never reach the tty."""
return "\n".join(printable(line) for line in text.split("\n"))
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 _safe_text("\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(_safe_text("\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(_safe_text(f"usage error: {error}"), file=sys.stderr)
return 2
return _scan(cat, args)