diff --git a/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md b/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md deleted file mode 100644 index 993cb85..0000000 --- a/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md +++ /dev/null @@ -1,2328 +0,0 @@ -# Guardrails a11y split, injection and exposure domains — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Move accessibility out of `/guardrails` into a standalone `/a11y` skill sharing the scan engine, add the `injection` and `exposure` scanner domains, extend the read-only probe with an `exposure` block, and patch every citer. - -**Architecture:** `scan.py` is split into a parametrized engine (`scanner.py`, a `Catalogue` of domains and prefixes) and two thin catalogue CLIs (guardrails, a11y). Two new check modules follow the `apis.py` pattern (module-level compiled regexes, `applies`, `check`, private `_x(project, files)` lists) on shared helpers added to `checks/common.py` (`code_files`, `hits`, `dedupe_lines`, `client_reachable`). The probe gains one `probe_exposure` entry in `PROBES`, fails closed (ERROR / SKIPPED, never CLOSED on an unobserved target), validates every plan path and keeps 4xx/5xx bodies. Doctrine, routing rows, profiles, locks and docs are patched in the same branch. - -**Tech Stack:** Python 3 stdlib (`python3 -B`), bash test suites run through `make test suite=`, shellcheck, gitflow lib. - -**Spec:** `docs/superpowers/specs/2026-10-18-guardrails-a11y-split-design.md` - -**Contract:** `.claude/tasks/contracts/2026-10-18-guardrails-a11y-split-inj-exp-2210.md` (criteria 4, 5 and 11 amended on 2026-10-19 after the plan challenge, shown at the validation gate: real a11y path, `test -f`, non-zero rule counts) - -**Revision 2 (after the three-lens challenge):** per-language injection patterns (a `$1` placeholder, a typed `sql` tag, Express `raw()` and UI copy stay silent), compiled regexes with bounded gaps and shared helpers, exposure rules scoped to route files, settings modules and non-dev env files, `.map` files over 1 MB listed by the walker, a fail-closed probe with path validation, exposure probed against a production build, the guardrails description under 1024, routing.json staged alone, web-building and seo/harden citers patched. **Revision 3 (confirmation pass):** quote-matched concat patterns with `+` in every language, the dev env lock scoped to the exposure domain, `DEBUG` anchored at column 0, error rules on every server file, hydrated exclusion limited to type-shaped values, Next pages and a root App counted as client code, sourcemap SKIPPED on a non-200 script, a truncated body, an off-host map or an empty list, plan validation that never raises, conditional stash pop, the contract amended on disk. - -## Global Constraints - -- Scanner: read-only, stdlib only, never executes project code, severities FAIL / WARN / MANUAL only, exit 0 / 1 / 2. A clean scan means "no static finding". -- Regexes: module-level `re.compile` with explicit flags, run through `common.hits` (`finditer`), never through `project.matches` with `.pattern` (the module's flags would be lost). Every gap that spans a line is bounded (`{0,200}` / `{0,300}` / `{0,400}`), never `[^\n]*` after a cheap anchor. Minified files, built dirs (`public`, `static`, `www`, `assets`) and test paths are out of `code_files`. -- Probe: GET, HEAD, OPTIONS only plus the existing opt-in POST burst; `--authorized` required; every plan path validated as a string starting with `/`; same-host redirects only; shared budget 200; secrets from env only; never print a response value, only identifier-shaped key names. A target that was not observed is ERROR or SKIPPED, never CLOSED. -- Code style: max 25 logic lines per function, 80 columns, 5 params, 5 locals. One check module per domain exposing `DOMAIN`, `applies(project)`, `check(project)`. -- Tests: every rule has a mutant at its default severity; every false-positive class the challenge found has a `benign` lock; the clean fixtures report ` 0 FAIL, 0 WARN`. Portable shell: no `sed -i`, no `grep -P`, no `stat -c`. -- Git: work on `feature/a11y-split-inj-exp`; commit per task with `git add `; never `git add -A`; never stage `settings.json`; `mods/model-router/routing.json` is committed through the Task 6 stash of that one file; never push by hand (hooks push). -- Safety-classifier fallback (BLK-022 class): if an executor's write of `injection.py` or a mutant block is withheld, the main loop writes that file itself with a single full-file Write against the task's test block as its spec, then re-dispatches the rest of the task. -- Rule, heading and label citers are patched in the same task that changes them (BDR-100). Locked single-line strings in SKILL.md files (loops-light) stay on one line. -- Run `make test suite=` for the suites a task touches; one full `make test` in Task 9. - -## Review Focus - -1. A double-quoted Postgres placeholder (`"… where owner = $1"`) must stay silent: `parameterized-query` lock, Task 2. -2. A typed tagged template (`` sql`select … ${id}` ``) must stay silent: `typed-sql-tag` lock, Task 2. -3. Server-side logging of a stack (`logger.error(…, err.stack)`) must stay silent while `new Response(err.stack)` in a route fails: `logger-stack` lock and `error-stack` mutant, Task 3. -4. An unreachable base page gives a SKIPPED sourcemap row, never CLOSED: `unreachable base page` test, Task 5. -5. A refused or non-JSON route gives a SKIPPED fields row, never CLOSED: `fields on a 401` and `fields on a non-JSON body` tests, Task 5. - ---- - -### Task 1: Extract the scan engine into `scanner.py` - -**Files:** -- Create: `skills/guardrails/scripts/scanner.py` -- Modify: `skills/guardrails/scripts/scan.py` (whole file) -- Test: `lib/tests/guardrails-scan.test.sh` (unchanged, must stay green) - -**Interfaces:** -- Produces: `scanner.Catalogue(name, domains, rule_domains, manual_rules)` and `scanner.main(argv, catalogue) -> int`. The check-mode markers are `-CLEAR ` and `-NO-NEW` with `NAME = catalogue.name.upper()`. - -- [ ] **Step 1: Read the current engine** - -Run: `sed -n 1,251p skills/guardrails/scripts/scan.py`. Every function below is the same logic with the module constants replaced by `cat.`. - -- [ ] **Step 2: Create `skills/guardrails/scripts/scanner.py`** - -```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 -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) -``` - -- [ ] **Step 3: Rewrite `skills/guardrails/scripts/scan.py` as the catalogue** - -Replace the whole file with (a11y stays in the catalogue for now; Task 4 removes it, Tasks 2 and 3 add the new domains): - -```python -#!/usr/bin/env python3 -"""Static guardrails scan: the guardrails catalogue on the shared engine. - -See scanner.py for the modes and exit codes. -""" -import sys - -import scanner -from checks import a11y, apis, functions, hosting, messaging, supabase - -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(scanner.main(sys.argv[1:], CATALOGUE)) -``` - -- [ ] **Step 4: Run the suite, it must be green with the same counts as before** - -Run: `make test suite=lib/tests/guardrails-scan.test.sh` -Expected: `passed: 106 failed: 0` and `all suites green`. Also `python3 -B skills/guardrails/scripts/scan.py lib/tests/fixtures/guardrails-good | head -3` prints `guardrails scan: … (17 files)` then `scanned: api, hosting, a11y, supabase, messaging, functions`. - -- [ ] **Step 5: Commit** - -```bash -git add skills/guardrails/scripts/scanner.py skills/guardrails/scripts/scan.py -git commit -m "refactor(guardrails): extract the scan engine into scanner.py, scan.py keeps the catalogue" -``` - ---- - -### Task 2: Shared helpers in `common.py`, domain `injection`, mutants and benign locks - -**Files:** -- Modify: `skills/guardrails/scripts/checks/common.py` (append `TEST_PATH`, `BUILT_SEGMENTS`, `code_files`, `hits`, `dedupe_lines`) -- Create: `skills/guardrails/scripts/checks/injection.py` -- Modify: `skills/guardrails/scripts/scan.py` (catalogue: add `injection` last, prefix `INJ`) -- Test: `lib/tests/guardrails-scan.test.sh` (new `== injection` block, benign locks) - -**Interfaces:** -- Produces: `common.code_files(project, exts=SOURCE_EXTS) -> [Path]` (hand-written source: no test, fixture or mock path, no built dir, no minified file), `common.hits(project, files, regex, rule, message) -> [Finding]` (compiled regex, `finditer`), `common.dedupe_lines(findings)` (first finding per (path, line) wins), `common.TEST_PATH`. Rules `INJ-SQL-RAW-UNSAFE`, `INJ-SQL-CONCAT`, `INJ-SHELL-DB-TOOL` (FAIL), `INJ-SQL-DYNAMIC-EXEC`, `INJ-POSTGREST-FILTER`, `INJ-NOSQL-OPERATOR` (WARN). Task 4 re-points the check-mode tests to `INJ-SQL-CONCAT:src/pages/api/notes.ts`. - -- [ ] **Step 1: Append the shared helpers to `checks/common.py`** - -```python -TEST_PATH = re.compile( - r"\.(?:test|spec|e2e|stories)\.|(?:^|/)(?:tests?|__tests__|spec|e2e" - r"|fixtures?|mocks?)/", re.I) -BUILT_SEGMENTS = {"public", "static", "www", "assets"} -MINIFIED_NAME = re.compile(r"\.min\.|\.bundle\.", re.I) -LONG_LINE = 5000 - - -def _minified(project, path): - if MINIFIED_NAME.search(path.name): - return True - return any(len(line) > LONG_LINE - for line in project.text(path).splitlines()) - - -def code_files(project, exts=SOURCE_EXTS): - """Hand-written source: no tests, fixtures, built dirs, minified files.""" - return [p for p in non_doc_files(project) - if p.suffix.lower() in exts - and not TEST_PATH.search(project.rel(p)) - and not set(project.segments(p)) & BUILT_SEGMENTS - and not _minified(project, p)] - - -def hits(project, files, regex, rule, message): - """One finding per match of a compiled regex over the given files.""" - return [project.found(rule, path, m.start(), message) - for path in files - for m in regex.finditer(project.text(path))] - - -def dedupe_lines(findings): - """One finding per (path, line): the first emitted wins.""" - seen, out = set(), [] - for finding in findings: - if (finding.path, finding.line) not in seen: - seen.add((finding.path, finding.line)) - out.append(finding) - return out -``` - -- [ ] **Step 2: Write the failing mutants and benign locks** - -In `lib/tests/guardrails-scan.test.sh`, add `API=src/pages/api/notes.ts` next to the other path variables (after `SMS=…`). Right before `echo "== benign patterns stay silent"`, add: - -```bash -echo "== injection" -mutant sql-template FAIL INJ-SQL-CONCAT \ - "printf '%s\n' 'const q = \`select id from notes where owner = \${owner}\`;' >> $API" -mutant sql-concat FAIL INJ-SQL-CONCAT \ - "printf '%s\n' 'const q = \"select id from notes where owner = \" + owner;' >> $API" -mutant sql-fstring FAIL INJ-SQL-CONCAT \ - "printf '%s\n' 'cur.execute(f\"delete from notes where id = {note_id}\")' > src/lib/cleanup.py" -mutant sql-php-interpolation FAIL INJ-SQL-CONCAT \ - "printf '%s\n' 'query(\"select id from notes where owner = \$owner\");' > src/lib/notes.php" -mutant sql-py-concat FAIL INJ-SQL-CONCAT \ - "printf '%s\n' 'cur.execute(\"select id from notes where owner = \" + owner)' > src/lib/cleanup.py" -mutant sql-quoted-value FAIL INJ-SQL-CONCAT \ - "printf '%s\n' \$'const q = \"select id from notes where owner = \\'\" + owner + \"\\'\";' >> $API" -mutant sql-php-dot FAIL INJ-SQL-CONCAT \ - "printf '%s\n' \$'query(\"select id from notes where owner = \\'\" . \$owner . \"\\'\");' > src/lib/notes.php" -mutant sql-raw-unsafe FAIL INJ-SQL-RAW-UNSAFE \ - "printf '%s\n' 'const rows = await prisma.\$queryRawUnsafe(statement);' >> $API" -mutant sql-dynamic-exec WARN INJ-SQL-DYNAMIC-EXEC \ - "printf '%s\n' \"execute 'select count(*) from ' || tbl into n;\" >> $SQL" -mutant postgrest-filter WARN INJ-POSTGREST-FILTER \ - "printf '%s\n' 'const { data } = await supabase.from(\"notes\").select().or(\`owner.eq.\${who}\`);' >> $API" -mutant nosql-operator WARN INJ-NOSQL-OPERATOR \ - "printf '%s\n' 'const doc = await Notes.findOne({ owner: req.body.owner });' >> $API" -mutant shell-db-tool FAIL INJ-SHELL-DB-TOOL \ - "printf '%s\n' 'execSync(\`pg_dump --table=\${table} app > backup.sql\`);' > src/lib/backup.ts" -``` - -And after the existing benign cases, add: - -```bash -benign parameterized-query \ - "printf '%s\n' 'const r = await db.query(\"select id from notes where owner = \$1\", [owner]);' >> $API" -benign tagged-sql-template \ - "printf '%s\n' 'const r = await sql\`select id from notes where owner = \${owner}\`;' >> $API" -benign typed-sql-tag \ - "printf '%s\n' 'const r = await sql\`select id from notes where owner = \${owner}\`;' >> $API" -benign express-raw-webhook \ - "printf '%s\n' 'app.post(\"/hook\", express.raw({ type: \"application/json\" }), onHook);' >> $API" -benign ui-copy-select \ - "printf '%s\n' 'const hint = \`Select a plan from the list, \${name}\`;' >> $TSX" -benign ui-copy-delete \ - "printf '%s\n' 'const label = \"Delete from favorites \" + item.title;' >> $TSX" -benign jquery-not \ - "printf '%s\n' 'const rows = \$(\".row\").not(\".row-\" + id);' >> $TSX" -benign argv-db-tool \ - "printf '%s\n' 'spawnSync(\"pg_dump\", [\"--table\", table, \"app\"]);' > src/lib/backup.ts" -benign format-dynamic-exec \ - "printf '%s\n' \"execute format('select count(*) from %I', tbl) into n;\" >> $SQL" -benign test-path-sql \ - "mkdir -p src/__tests__; printf '%s\n' 'const q = \`select id from notes where owner = \${owner}\`;' > src/__tests__/notes.test.ts" -benign minified-bundle \ - "printf '%s\n' 'const q=\`select id from notes where owner = \${o}\`;' > src/lib/app.min.js" -benign long-line-bundle \ - "head -c 6000 /dev/zero | tr '\\0' x > src/lib/bundle.js; printf '%s\n' ' const q=\`select id from notes where owner = \${o}\`;' >> src/lib/bundle.js" -``` - -- [ ] **Step 3: Run the suite, the twelve mutants must fail** - -Run: `make test suite=lib/tests/guardrails-scan.test.sh 2>&1 | grep -c 'FAIL .* raises'` -Expected: `12` (the rules do not exist yet). The two `$'…'` snippets use ANSI-C quoting so the SQL string can hold a single quote; after the outer double quotes are processed, `eval` sees `$'const q = "… = \'" + owner + "\'";'`. The benign locks already pass, which is the point of writing them first. - -- [ ] **Step 4: Create `skills/guardrails/scripts/checks/injection.py`** - -```python -"""Injection checks: SQL built from input, raw ORM escapes, dynamic SQL, -PostgREST filters, NoSQL operators, a shell into a DB tool.""" -import re - -from .common import Rule, blank_comments, code_files, dedupe_lines, hits - -DOMAIN = "injection" -JS_EXTS = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte", - ".astro") -SQL_EXTS = (".sql", ".pgsql", ".plpgsql") -GAP = r"[^'\"`]{0,200}" -STMT = ( - rf"(?:select\b{GAP}\bfrom\b{GAP}\b(?:where|join|limit|order\s+by" - rf"|group\s+by)\b|select\s+\*\s+from\b" - rf"|insert\s+into\s+[\w.\"]+{GAP}\b(?:values|select)\b" - r"|insert\s+into\s+[\w.\"]+\s*\(|update\s+[\w.\"]+\s+set\b" - r"|delete\s+from\s+[\w.\"]+\s+where\b" - r"|\bwhere\s+[\w.\"]+\s*(?:=|like\b|in\b|<|>)" - r"|create\s+(?:table|index)\s|drop\s+(?:table|index)\s" - r"|alter\s+table\s|truncate\s+table\s)") -DQ = r"[^\"\n]{0,200}" -SQ = r"[^'\n]{0,200}" - - -def _quoted(tail): - """A double- or single-quoted SQL statement string followed by tail.""" - return rf"\"{DQ}?{STMT}{DQ}\"{tail}|'{SQ}?{STMT}{SQ}'{tail}" - - -CONCAT = { - JS_EXTS: re.compile( - rf"(?])`[^`]{{0,400}}?{STMT}[^`]{{0,400}}?\$\{{|" - + _quoted(r"\s*\+\s*[\w$(]"), re.I), - (".py",): re.compile( - rf"\bf['\"][^'\"\n]{{0,200}}?{STMT}|" - + _quoted(r"\s*(?:%\s*[\w(]|\.format\(|\+\s*[\w(])"), re.I), - (".php",): re.compile( - rf"\"{DQ}?{STMT}{DQ}\$[A-Za-z_]\w*|" - + _quoted(r"\s*\.\s*\$[A-Za-z_]"), re.I), - (".rb",): re.compile(rf"\"{DQ}?{STMT}{DQ}#\{{", re.I), - (".rs",): re.compile(rf"format!\(\s*\"{DQ}?{STMT}", re.I), - (".go",): re.compile(rf"fmt\.Sprintf\(\s*\"{DQ}?{STMT}", re.I), -} -RAW = { - JS_EXTS: re.compile( - r"(?:\$queryRawUnsafe|\$executeRawUnsafe|\bknex\.raw" - r"|\bsequelize\.query|\b[Ss]equelize\.literal)\s*\(\s*(?![\s'\"`)])"), - (".py",): re.compile( - r"\.objects\.raw\(\s*(?![\s'\"`)])|\.extra\(\s*(?![\s'\"`)])"), - (".rb",): re.compile(r"\.where\(\s*\"[^\"\n]{0,200}#\{"), -} -SQLA_TEXT = re.compile(r"\btext\s*\(\s*(?![\s'\"`)])") -DYNAMIC_EXEC = re.compile(r"\bexecute\s+(?:'[^']*'|\w+)\s*\|\|", re.I) -POSTGREST = re.compile( - r"\.(?:or|filter|not|match|textSearch)\(\s*(?:`[^`\n]{0,200}\$\{" - r"|['\"][^'\"\n]{0,200}['\"]\s*\+\s*[\w$])") -NOSQL = re.compile( - r"\$where\s*:\s*(?:['\"`]|\w)" - r"|\.(?:find|findOne|findOneAndUpdate|findOneAndDelete|updateOne" - r"|updateMany|deleteOne|deleteMany|countDocuments|replaceOne)\(\s*" - r"(?:req\.(?:body|query|params)\b" - r"|\{\s*\w+\s*:\s*req\.(?:body|query|params)\.\w+\s*[,}])") -SHELL_DB = re.compile( - r"\b(?:exec|execSync|spawn|spawnSync|system|popen|subprocess\.\w+" - r"|os\.system|Command::new|shell_exec|passthru|proc_open)\s*\(" - r"[^\n]{0,300}?\b(?:psql|mysql|mysqldump|pg_dump|pg_restore|mongosh" - r"|mongo|mongodump|redis-cli|sqlite3|clickhouse-client)\b[^\n]{0,300}?" - r"(?:\$\{|\+\s*[\w$]|#\{|\{\w+\}|%s|\$[A-Za-z_])") - - -def applies(project): - return bool(project.with_ext(*JS_EXTS, ".py", ".php", ".rb", ".rs", - ".go", *SQL_EXTS)) - - -def _by_ext(files, exts): - return [p for p in files if p.suffix.lower() in exts] - - -def _per_language(project, files, table, rule, message): - out = [] - for exts, regex in table.items(): - out += hits(project, _by_ext(files, exts), regex, rule, message) - return out - - -def _raw_unsafe(project, files): - rule = Rule(DOMAIN, "INJ-SQL-RAW-UNSAFE", "FAIL") - msg = "raw SQL escape fed a non-literal: bind the values" - sqla = [p for p in _by_ext(files, (".py",)) - if "sqlalchemy" in project.text(p)] - return (_per_language(project, files, RAW, rule, msg) - + hits(project, sqla, SQLA_TEXT, rule, msg)) - - -def _concat(project, files): - return _per_language( - project, files, CONCAT, Rule(DOMAIN, "INJ-SQL-CONCAT", "FAIL"), - "SQL built from an expression: use placeholders") - - -def _dynamic_exec(project): - rule = Rule(DOMAIN, "INJ-SQL-DYNAMIC-EXEC", "WARN") - out = [] - for path in code_files(project, SQL_EXTS): - text = blank_comments(project.text(path)) - for m in DYNAMIC_EXEC.finditer(text): - out.append(project.found( - rule, path, m.start(), - "EXECUTE built with ||: use format() with %I/%L and USING")) - return out - - -def _postgrest(project, files): - client = [p for p in _by_ext(files, JS_EXTS) - if "supabase" in project.text(p)] - return hits(project, client, POSTGREST, - Rule(DOMAIN, "INJ-POSTGREST-FILTER", "WARN"), - "PostgREST filter string built from a value: use .eq()") - - -def _nosql(project, files): - return hits(project, _by_ext(files, JS_EXTS), NOSQL, - Rule(DOMAIN, "INJ-NOSQL-OPERATOR", "WARN"), - "filter taken from the request: allowlist fields, cast") - - -def _shell_db(project, files): - return hits(project, files, SHELL_DB, - Rule(DOMAIN, "INJ-SHELL-DB-TOOL", "FAIL"), - "DB tool run through a shell with input: pass an argv") - - -def check(project): - files = code_files(project) - found = _raw_unsafe(project, files) + _concat(project, files) - found += _dynamic_exec(project) + _postgrest(project, files) - found += _nosql(project, files) + _shell_db(project, files) - return dedupe_lines(found) -``` - -- [ ] **Step 5: Register the domain in `scan.py`** - -In `CATALOGUE`: add `injection` to the `from checks import …` line (alphabetical: `a11y, apis, functions, hosting, injection, messaging, supabase`), add `"injection": injection,` as the LAST entry of `domains`, and `"INJ": "injection",` in `rule_domains`. - -- [ ] **Step 6: Run the suite** - -Run: `make test suite=lib/tests/guardrails-scan.test.sh` -Expected: all PASS, including `clean has no FAIL or WARN` (the fixture's `0001_init.sql` has `execute function …` without `||`) and `empty project marks hosting not applicable` (injection sits after hosting). A mutant or lock that fails is a regex bug: fix the regex against the snippet, never the snippet. - -- [ ] **Step 7: Commit** - -```bash -git add skills/guardrails/scripts/checks/common.py skills/guardrails/scripts/checks/injection.py skills/guardrails/scripts/scan.py lib/tests/guardrails-scan.test.sh -git commit -m "feat(guardrails): injection domain (INJ-*): per-language SQL concat and raw escapes, dynamic EXECUTE, PostgREST, NoSQL, shell into DB tools; shared code_files/hits/dedupe helpers" -``` - ---- - -### Task 3: Domain `exposure`: walker lists large files, `client_reachable` shared, mutants and benign locks - -**Files:** -- Modify: `skills/guardrails/scripts/checks/common.py` (walker returns large files; `client_reachable` and its constants) -- Modify: `skills/guardrails/scripts/checks/supabase.py` (use `common.client_reachable` and `common.CLIENT_EXTS`; delete its own `_client_reachable`, `SERVER_SEGMENTS`, `CLIENT_SEGMENTS`, `CLIENT_EXTS`, `SCRIPT_EXTS`) -- Modify: `skills/guardrails/scripts/checks/passwords.py` (rename `_log_args` to `log_args`, public; update its one caller) -- Create: `skills/guardrails/scripts/checks/exposure.py` -- Modify: `skills/guardrails/scripts/scan.py` (catalogue: `exposure` last, prefix `EXP`) -- Test: `lib/tests/guardrails-scan.test.sh` - -**Interfaces:** -- Consumes: `apis.ENV_NAME`, `ENV_SAMPLE`, `ignore_patterns`, `is_ignored_env`, `route_files`; `passwords.log_args`, `passwords.LOGGED_NAME`; `common.code_files`, `hits`, `dedupe_lines`. -- Produces: `common.client_reachable(project, path) -> bool`, `common.CLIENT_EXTS`, `Project.large` (regular files over `MAX_BYTES`, never read: paths only). Rules `EXP-CONSOLE-DATA`, `EXP-HYDRATED-SENSITIVE`, `EXP-MARKUP-COMMENT`, `EXP-DATA-ATTR-SENSITIVE`, `EXP-ERROR-MESSAGE`, `EXP-RESPONSE-WIDE` (WARN), `EXP-SOURCEMAP-PUBLIC` (FAIL / WARN), `EXP-ERROR-STACK`, `EXP-DEBUG-ON` (FAIL). - -- [ ] **Step 1: Walker: list large files without reading them** - -In `checks/common.py` replace `_is_scannable`, `_kept_files` and the `Project.__init__` body: - -```python -def _candidate(path): - """A regular, non-symlink, non-binary file the walker may list.""" - if path.name in SKIP_FILES or path.suffix.lower() in BINARY_EXTS: - return False - try: - return path.is_file() and not path.is_symlink() - except OSError: - return False - - -def _small(path): - try: - return path.stat().st_size <= MAX_BYTES - except OSError: - return False - - -def _kept_files(root, base, names, prefixes): - for name in names: - path = Path(base) / name - if _candidate(path) and not _excluded(root, path, prefixes): - yield path, _small(path) -``` - -and in `Project.__init__`: - -```python - listed = sorted(_walk(self.root, prefixes)) - self.files = [p for p, small in listed if small] - self.large = [p for p, small in listed if not small] -``` - -`_walk` is unchanged (it yields what `_kept_files` yields). Run `make test suite=lib/tests/guardrails-scan.test.sh`: still green (the symlink and size behaviour of `files` is identical). - -- [ ] **Step 2: Move `client_reachable` into `common.py`** - -Append to `checks/common.py`: - -```python -SERVER_SEGMENTS = { - "functions", "api", "server", "scripts", "tests", "test", "migrations", - "seed", ".github", "supabase", "tools", -} -CLIENT_SEGMENTS = { - "components", "public", "static", "client", "browser", "www", "islands", -} -CLIENT_EXTS = (".vue", ".svelte", ".html", ".htm") -CLIENT_SCRIPT_EXTS = (".ts", ".tsx", ".js", ".jsx", ".mjs") - - -def client_reachable(project, path): - """Heuristic: this file's text ends up in a browser bundle or page.""" - segments = set(project.segments(path)) - if segments & SERVER_SEGMENTS: - return False - if path.suffix.lower() in CLIENT_EXTS: - return True - if path.suffix.lower() not in CLIENT_SCRIPT_EXTS: - return False - head = project.text(path)[:300] - return bool(segments & CLIENT_SEGMENTS) or "use client" in head -``` - -In `supabase.py`: add `CLIENT_EXTS, client_reachable` to the `from .common import …` line; delete the module's `SERVER_SEGMENTS`, `CLIENT_SEGMENTS`, `CLIENT_EXTS`, `SCRIPT_EXTS` constants and its `_client_reachable` function; change the single call site (`if _client_reachable(project, path)`) to `if client_reachable(project, path)`. The `project.with_ext(*SOURCE_EXTS, *CLIENT_EXTS)` line keeps working through the import. In `passwords.py` rename `_log_args` to `log_args` (definition and its one call). Run the suite again: green. - -- [ ] **Step 3: Write the failing mutants and benign locks** - -Add to `lib/tests/guardrails-scan.test.sh` after the `== injection` block: - -```bash -echo "== exposure" -mutant console-data WARN EXP-CONSOLE-DATA \ - "printf '%s\n' 'console.log(\"saved\", session);' >> $TSX" -mutant sourcemap-next FAIL EXP-SOURCEMAP-PUBLIC \ - "printf '%s\n' 'module.exports = { productionBrowserSourceMaps: true };' > next.config.js" -mutant sourcemap-vite-inline FAIL EXP-SOURCEMAP-PUBLIC \ - "printf '%s\n' 'export default { build: { sourcemap: \"inline\" } };' > vite.config.ts" -mutant sourcemap-webpack-warn WARN EXP-SOURCEMAP-PUBLIC \ - "printf '%s\n' 'module.exports = { devtool: \"eval-source-map\" };' > webpack.config.js" -mutant sourcemap-public-dir FAIL EXP-SOURCEMAP-PUBLIC \ - "mkdir -p public/assets; printf '%s\n' '{\"version\":3,\"sources\":[\"src/app.ts\"],\"mappings\":\"AAAA\"}' > public/assets/app.js.map" -mutant sourcemap-large-map FAIL EXP-SOURCEMAP-PUBLIC \ - "mkdir -p public; head -c 1100000 /dev/zero | tr '\\0' a > public/app.js.map" -mutant hydrated-sensitive WARN EXP-HYDRATED-SENSITIVE \ - "printf '%s\n' 'export async function getServerSideProps() { return { props: { accessToken: process.env.CRM_TOKEN } }; }' > src/pages/account.tsx" -mutant markup-comment WARN EXP-MARKUP-COMMENT \ - "printf '%s\n' '' > src/pages/index.html" -mutant data-attr-sensitive WARN EXP-DATA-ATTR-SENSITIVE \ - "printf '%s\n' '
x
' >> $TSX" -mutant error-stack FAIL EXP-ERROR-STACK \ - "printf '%s\n' 'export function onError(err: Error) { return new Response(err.stack, { status: 500 }); }' >> $API" -mutant error-message WARN EXP-ERROR-MESSAGE \ - "printf '%s\n' 'export function onFail(err: Error) { return Response.json({ error: err.message }, { status: 500 }); }' >> $API" -mutant debug-on FAIL EXP-DEBUG-ON \ - "printf '%s\n' 'DEBUG = True' > src/settings.py" -mutant debug-env FAIL EXP-DEBUG-ON \ - "printf '%s\n' 'APP_DEBUG=true' > .env.production" -mutant response-wide WARN EXP-RESPONSE-WIDE \ - "printf '%s\n' 'const { data } = await db.from(\"profiles\").select(\"*\");' >> $API" -mutant error-stack-single-file FAIL EXP-ERROR-STACK \ - "printf '%s\n' 'app.use((err, req, res, next) => res.status(500).send(err.stack));' > server.js" -mutant hydrated-identifier WARN EXP-HYDRATED-SENSITIVE \ - "printf '%s\n' 'export async function getServerSideProps() { const token = await crm(); return { props: { accessToken: token } }; }' > src/pages/account.tsx" -mutant console-next-page WARN EXP-CONSOLE-DATA \ - "printf '%s\n' 'export default function Home({ user }) { console.log(\"render\", user); return null; }' > src/pages/index.tsx" -``` - -And these benign locks next to the Task 2 ones: - -```bash -benign console-plain-string \ - "printf '%s\n' 'console.log(\"ready\");' >> $TSX" -benign console-string-data \ - "printf '%s\n' 'console.log(\"loading data\");' >> $TSX" -benign console-server-file \ - "printf '%s\n' 'console.log(\"saved\", session);' >> $API" -benign logger-stack \ - "printf '%s\n' 'logger.error(\`notes failed \${res.statusCode}\`, err.stack);' >> $API" -benign client-console-stack \ - "printf '%s\n' 'console.warn(\"load failed\", err.stack);' >> $TSX" -benign vite-hidden-sourcemap \ - "printf '%s\n' 'export default { build: { sourcemap: \"hidden\" } };' > vite.config.ts" -benign vendored-map \ - "mkdir -p static/css; printf '%s\n' '{\"version\":3,\"mappings\":\"AAAA\"}' > static/css/bootstrap.min.css.map" -benign level-map \ - "mkdir -p public/levels; printf '%s\n' 'tiles 10x10' > public/levels/1.map" -benign debug-from-env \ - "printf '%s\n' 'DEBUG = os.environ.get(\"DEBUG\") == \"1\"' > src/settings.py" -benign debug-local-settings \ - "printf '%s\n' 'DEBUG = True' > src/settings_local.py" -benign debug-lowercase-elsewhere \ - "printf '%s\n' ' debug = True' > src/lib/tools.py" -benign errorhandler-dev-guard \ - "printf '%s\n' 'if (process.env.NODE_ENV === \"development\") app.use(errorhandler());' >> $API" -benign flask-config-class \ - "printf '%s\n' 'class DevelopmentConfig(Config):' ' DEBUG = True' > src/config.py" -benign error-generic-message \ - "printf '%s\n' 'export function onFail() { return Response.json({ error: \"internal error\" }, { status: 500 }); }' >> $API" -benign ts-type-token \ - "printf '%s\n' 'export async function getServerSideProps() { return { props: {} }; }' 'type Session = { token: string; };' > src/pages/account.tsx" -benign no-semicolon-type \ - "printf '%s\n' 'export async function getServerSideProps() { return { props: {} }; }' 'interface Props {' ' token: string' '}' > src/pages/account.tsx" -benign prisma-multiline-select \ - "printf '%s\n' 'const u = await prisma.user.findUnique({' ' where: { id },' ' select: { id: true },' '});' >> $API" -benign csrf-hidden-input \ - "printf '%s\n' '' >> $TSX" -benign csrf-data-attr \ - "printf '%s\n' '
x
' >> $TSX" -# A committed .env.development trips the api domain's API-ENV-NOT-IGNORED by -# design (the fixture's .gitignore lists .env only), so this lock is scoped -# to the exposure domain: a dev env file must raise no EXP finding. -cp -R "$GOOD" "$WORK/env-dev" -printf '%s\n' 'APP_DEBUG=true' 'GENERATE_SOURCEMAP=true' > "$WORK/env-dev/.env.development" -out=$(scan --domain exposure "$WORK/env-dev") -check "a dev env file raises no exposure finding" \ - "$(printf '%s\n' "$out" | grep -c ' 0 FAIL, 0 WARN')" 1 -``` - -- [ ] **Step 4: Run the suite, the seventeen mutants must fail** - -Run: `make test suite=lib/tests/guardrails-scan.test.sh 2>&1 | grep -c 'FAIL .* raises'` -Expected: `18`: the seventeen mutants plus the exposure-scoped dev-env check, whose `--domain exposure` is a usage error until the domain exists. - -- [ ] **Step 5: Create `skills/guardrails/scripts/checks/exposure.py`** - -```python -"""Exposure checks: what the browser can see that it should not.""" -import re - -from . import passwords -from .apis import ENV_NAME, ENV_SAMPLE, ignore_patterns, is_ignored_env -from .apis import route_files -from .common import Rule, client_reachable, code_files, dedupe_lines, hits - -DOMAIN = "exposure" -MARKUP_EXTS = (".html", ".htm", ".astro", ".php", ".ejs", ".hbs", ".twig", - ".njk", ".liquid") -ATTR_EXTS = MARKUP_EXTS + (".jsx", ".tsx", ".vue", ".svelte") -DEV_TOKEN = re.compile( - r"(?:^|[._-])(?:dev|development|local|test|testing)(?:[._-]|$)", re.I) -CONSOLE = re.compile( - r"\bconsole\.(?:log|info|debug|dir|table)\s*\(([^\n]{0,300})") -DATA_NAMES = re.compile( - r"\b(?:users?|profile|session|token|account|customer|order|payment" - r"|response|res|data|result|rows|body|headers|props|state|error|err" - r"|json|payload|record|items?)\b", re.I) -SENSITIVE = ( - r"(?:token|accessToken|refreshToken|secret|apiKey|api_key|password" - r"|passwordHash|password_hash|serviceRole|service_role|privateKey" - r"|private_key|ssn|iban|stripeSecret|clientSecret)") -LOADER = re.compile( - r"getServerSideProps|getStaticProps" - r"|export\s+(?:async\s+)?function\s+(?:loader|load)\b" - r"|export\s+const\s+(?:loader|load)\b|window\.__\w+__\s*=") -TYPEISH = (r"(?:string|number|boolean|null|undefined|unknown|any|never" - r"|[A-Z][\w<>\[\]|]*)") -HYDRATED = re.compile( - rf"\b{SENSITIVE}\s*:(?!\s*{TYPEISH}\s*(?:[;,}}]|$))", re.M) -COMMENT = re.compile(r"", re.S) -COMMENT_WORDS = re.compile( - r"\b(?:todo|fixme|hack|xxx|debug|password|passwd|secret|token" - r"|api[-_ ]?key|internal|staging|localhost|admin|remove before" - r"|do not commit|don'?t commit|temporary)\b", re.I) -DATA_ATTR = re.compile( - r"\b(data-[\w-]*(?:secret|api-?_?key|password|passwd|jwt|private" - r"|credential|service-?role)[\w-]*)\s*=", re.I) -HIDDEN_INPUT = re.compile(r"\n]{0,300}>", re.I) -SENSITIVE_NAME = re.compile( - r"secret|api[-_]?key|password|passwd|jwt|private|credential", re.I) -SAFE_NAME = re.compile(r"csrf|xsrf|authenticity|nonce", re.I) -SENDING = ( - r"(?:\bres\.(?:status|json|send|end|write)\b" - r"|\breply\.(?:send|code|status)\b|\bctx\.body\b|\bResponse\(" - r"|Response\.json\(|\bjsonify\(|\bJSONResponse\(|\bHTTPException\(" - r"|\bdetail\s*=|\becho\b)") -ERR = r"(?:err|error|e|exc|exception)" -ERROR_STACK = re.compile( - rf"{SENDING}[^\n]{{0,300}}?(?:\b{ERR}\.stack\b|traceback\.format_exc" - rf"|getTraceAsString\(\))" - rf"|\b(?:json|send)\s*\(\s*\{{[^}}\n]{{0,200}}\berror\s*:\s*{ERR}\s*[,}}]") -ERROR_MESSAGE = re.compile( - rf"{SENDING}[^\n]{{0,300}}?(?:\b{ERR}\.message\b|\bstr\({ERR}\)" - rf"|\brepr\({ERR}\)|->getMessage\(\))") -SETTINGS_NAME = re.compile(r"^(?:settings|config)", re.I) -DEBUG_SETTINGS = re.compile(r"^DEBUG\s*=\s*True\b", re.M) -DEBUG_ENV = re.compile( - r"^\s*(?:APP_DEBUG\s*=\s*true|FLASK_DEBUG\s*=\s*1)\b", re.M | re.I) -DEBUG_CODE = re.compile( - r"app\.debug\s*=\s*True|app\.run\([^)\n]{0,200}debug\s*=\s*True") -DEBUG_HANDLER = re.compile( - r"^(?![^\n]*(?:development|NODE_ENV))[^\n]*app\.use\(\s*errorhandler\(\)", - re.M) -DEBUG_RAILS = re.compile(r"consider_all_requests_local\s*=\s*true") -NEXT_MAPS = re.compile(r"productionBrowserSourceMaps\s*:\s*true") -VITE_MAPS = re.compile(r"\bsourcemap\s*:\s*(?:true|['\"]inline['\"])") -WEBPACK_DEVTOOL = re.compile( - r"\bdevtool\s*:\s*['\"](?:source-map|eval[\w-]*|inline[\w-]*" - r"|cheap[\w-]*)['\"]") -ENV_MAPS = re.compile(r"^\s*GENERATE_SOURCEMAP\s*=\s*true\b", re.M | re.I) -ANGULAR_MAPS = re.compile(r"\"sourceMap\"\s*:\s*true") -PUBLIC_DIRS = {"public", "static", "assets", "www"} -VENDORED = re.compile(r"\.min\.|vendor|bootstrap|jquery", re.I) -USERS = (r"(?:users|profiles|accounts|customers|members|employees" - r"|patients|clients)") -WIDE = re.compile( - rf"\.from\(\s*['\"]{USERS}['\"]\s*\)\s*\.select\(\s*['\"]\*['\"]\s*\)" - rf"|select\s+\*\s+from\s+{USERS}\b" - r"|\b(?:user|profile|account|customer|member)\.(?:findUnique|findFirst" - r"|findMany)\(\s*\{(?![^\n]{0,300}\b(?:select|omit)\s*:)[^\n]{0,300}\}" - r"\s*\)", re.I) - - -def applies(project): - return bool(project.with_ext(".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", - ".py", ".php", ".rb", ".vue", ".svelte", - ".astro", *MARKUP_EXTS)) - - -def _named(project, prefix): - return [p for p in project.files if p.name.startswith(prefix)] - - -def _client(project, path): - """client_reachable, plus Next pages and a root App component.""" - if client_reachable(project, path): - return True - segments = project.segments(path) - return (path.suffix.lower() in (".tsx", ".jsx") and "api" not in segments - and ("pages" in segments or path.stem == "App")) - - -def _console_data(project, files): - rule = Rule(DOMAIN, "EXP-CONSOLE-DATA", "WARN") - out = [] - for path in (p for p in files if _client(project, p)): - for m in CONSOLE.finditer(project.text(path)): - if passwords.LOGGED_NAME.search(m.group(1)): - continue - if DATA_NAMES.search(passwords.log_args(m.group(1))): - out.append(project.found( - rule, path, m.start(), - "data logged to the browser console")) - return out - - -def _map_config(project): - fail = Rule(DOMAIN, "EXP-SOURCEMAP-PUBLIC", "FAIL") - warn = Rule(DOMAIN, "EXP-SOURCEMAP-PUBLIC", "WARN") - out = hits(project, _named(project, "next.config"), NEXT_MAPS, fail, - "production source maps enabled") - out += hits(project, _named(project, "vite.config"), VITE_MAPS, fail, - "build source maps enabled: use 'hidden' or false") - prod = _named(project, "webpack.prod") - other = [p for p in _named(project, "webpack") if p not in prod] - out += hits(project, prod, WEBPACK_DEVTOOL, fail, - "devtool emits readable source maps in production") - out += hits(project, other, WEBPACK_DEVTOOL, warn, - "devtool emits readable source maps: confirm not in prod") - return out + hits(project, project.named("angular.json"), ANGULAR_MAPS, - warn, "sourceMap true: confirm not the production build") - - -def _env_files(project): - """Committed env files that are not samples and not dev/local/test.""" - patterns = ignore_patterns(project) - return [p for p in project.files if ENV_NAME.fullmatch(p.name) - and not p.name.endswith(ENV_SAMPLE) - and not DEV_TOKEN.search(p.name[4:] or "x") - and not is_ignored_env(p, patterns)] - - -def _public_map(project, path): - return (set(project.segments(path)) & PUBLIC_DIRS - and not VENDORED.search(project.rel(path))) - - -def _map_files(project): - rule = Rule(DOMAIN, "EXP-SOURCEMAP-PUBLIC", "FAIL") - out = hits(project, _env_files(project), ENV_MAPS, rule, - "GENERATE_SOURCEMAP=true ships source maps") - small = [p for p in project.with_ext(".map") - if _public_map(project, p) and '"mappings"' in project.text(p)] - large = [p for p in project.large - if p.suffix.lower() == ".map" and _public_map(project, p)] - return out + [project.found(rule, p, 0, "source map in a public directory") - for p in small + large] - - -def _hydrated(project, files): - loaders = [p for p in files if LOADER.search(project.text(p))] - return hits(project, loaders, HYDRATED, - Rule(DOMAIN, "EXP-HYDRATED-SENSITIVE", "WARN"), - "sensitive key in server-to-client state") - - -def _markup_comments(project): - rule = Rule(DOMAIN, "EXP-MARKUP-COMMENT", "WARN") - return [project.found(rule, path, m.start(), - "HTML comment shipped to the browser carries " - "internal notes") - for path in project.with_ext(*MARKUP_EXTS) - for m in COMMENT.finditer(project.text(path)) - if COMMENT_WORDS.search(m.group(1))] - - -def _hidden_sensitive(tag): - if not re.search(r"type\s*=\s*[\"']?hidden\b", tag, re.I): - return False - name = re.search(r"name\s*=\s*[\"']([^\"']+)", tag, re.I) - return bool(name and SENSITIVE_NAME.search(name.group(1)) - and not SAFE_NAME.search(name.group(1))) - - -def _data_attrs(project): - rule = Rule(DOMAIN, "EXP-DATA-ATTR-SENSITIVE", "WARN") - out = [] - for path in project.with_ext(*ATTR_EXTS): - text = project.text(path) - out += [project.found(rule, path, m.start(), - "sensitive value in a data-* attribute") - for m in DATA_ATTR.finditer(text) - if not SAFE_NAME.search(m.group(1))] - out += [project.found(rule, path, m.start(), - "sensitive value in a hidden input") - for m in HIDDEN_INPUT.finditer(text) - if _hidden_sensitive(m.group(0))] - return out - - -def _errors(project, files): - server = [p for p in files if not client_reachable(project, p)] - stack = hits(project, server, ERROR_STACK, - Rule(DOMAIN, "EXP-ERROR-STACK", "FAIL"), - "stack trace or error object sent to the client") - message = hits(project, server, ERROR_MESSAGE, - Rule(DOMAIN, "EXP-ERROR-MESSAGE", "WARN"), - "raw exception message sent to the client") - return dedupe_lines(stack + message) - - -def _settings_modules(project, files): - return [p for p in files if p.suffix == ".py" - and (SETTINGS_NAME.match(p.name) - or "settings" in project.segments(p)) - and not DEV_TOKEN.search(p.stem)] - - -def _debug(project, files): - rule = Rule(DOMAIN, "EXP-DEBUG-ON", "FAIL") - out = hits(project, _settings_modules(project, files), DEBUG_SETTINGS, - rule, "DEBUG = True in a settings module") - out += hits(project, _env_files(project), DEBUG_ENV, rule, - "debug mode on in a committed env file") - out += hits(project, files, DEBUG_CODE, rule, - "debug mode enabled in code") - out += hits(project, files, DEBUG_HANDLER, rule, - "dev error handler mounted without an environment guard") - return out + hits(project, project.named("production.rb"), DEBUG_RAILS, - rule, "full error pages enabled in production") - - -def _response_wide(project): - return hits(project, route_files(project), WIDE, - Rule(DOMAIN, "EXP-RESPONSE-WIDE", "WARN"), - "whole rows of a user table returned: select the fields") - - -def check(project): - files = code_files(project) - found = _console_data(project, files) + _map_config(project) - found += _map_files(project) + _hydrated(project, files) - found += _markup_comments(project) + _data_attrs(project) - found += _errors(project, files) + _debug(project, files) - return found + _response_wide(project) -``` - -Notes: `_env_files` strips the leading `.env` before the dev-token test so `.env.development`, `.env.local` and `.env.test` are skipped while `.env.production` and `.env` are kept (the api domain's API-ENV-NOT-IGNORED still judges whether such a file belongs in git). The error rules scan every non-client source file, so a single-file `server.js` or `app.py` counts; `logger-stack` stays silent because the SENDING prefix requires a real sending call (`res.status` does not match `res.statusCode`), and `client-console-stack` because `ContactForm.tsx` is client-reachable. `DEBUG = True` is anchored at column 0: a Flask `class DevelopmentConfig` attribute is indented and stays silent. `route_files` is still imported for `_response_wide`. `ENV_NAME` and `ENV_SAMPLE` exist in `apis.py`. - -- [ ] **Step 6: Register the domain** - -In `scan.py`: import `exposure` (alphabetical: `a11y, apis, exposure, functions, hosting, injection, messaging, supabase`), add `"exposure": exposure,` as the LAST `domains` entry (after `injection`), and `"EXP": "exposure",` in `rule_domains`. - -- [ ] **Step 7: Run the suite** - -Run: `make test suite=lib/tests/guardrails-scan.test.sh` -Expected: every check PASS, `clean has no FAIL or WARN` included (the fixture's hidden `name="token"` carries no sensitive word; `notes.ts` returns `{ ok: true }`). A mutant or lock that fails is a regex bug: fix the regex, never the snippet, unless the snippet contradicts the spec table. - -- [ ] **Step 8: Commit** - -```bash -git add skills/guardrails/scripts/checks/common.py skills/guardrails/scripts/checks/supabase.py skills/guardrails/scripts/checks/passwords.py skills/guardrails/scripts/checks/exposure.py skills/guardrails/scripts/scan.py lib/tests/guardrails-scan.test.sh -git commit -m "feat(guardrails): exposure domain (EXP-*): console data, source maps (config, public dir, large files), hydrated state, shipped comments, data attributes, error bodies in routes, debug mode, wide responses" -``` - ---- - -### Task 4: Split accessibility out: `/a11y` scanner, fixture and suite; guardrails drops the domain - -**Files:** -- Move: `skills/guardrails/scripts/checks/a11y.py` → `skills/a11y/scripts/a11y_checks.py` (`git mv`) -- Create: `skills/a11y/scripts/scan.py` -- Move: `lib/tests/fixtures/guardrails-good/src/styles.css` → `lib/tests/fixtures/a11y-good/src/styles.css` (`git mv`; its only users were the a11y focus mutants) -- Create: `lib/tests/fixtures/a11y-good/src/components/ContactForm.tsx` (copy; the guardrails fixture keeps its own for the EXP tests) -- Create: `lib/tests/a11y-scan.test.sh` -- Modify: `skills/guardrails/scripts/scan.py` (drop `a11y` from the catalogue) -- Modify: `lib/tests/guardrails-scan.test.sh` (drop the a11y blocks, re-point check modes and CLI tests) - -**Interfaces:** -- Consumes: `scanner.Catalogue`, `scanner.main` (Task 1). -- Produces: `python3 -B skills/a11y/scripts/scan.py [--domain a11y] [--exclude] [--json] [--assert-absent A11Y-…:path] [--baseline f.json]`, markers `A11Y-CLEAR ` and `A11Y-NO-NEW`, report header `a11y scan: …`, exit 2 with a named message when the guardrails engine directory is missing. - -- [ ] **Step 1: Move the module and fix its import** - -```bash -mkdir -p skills/a11y/scripts -git mv skills/guardrails/scripts/checks/a11y.py skills/a11y/scripts/a11y_checks.py -``` - -In `skills/a11y/scripts/a11y_checks.py` change `from .common import Rule, blank_markup_comments` to `from checks.common import Rule, blank_markup_comments`. Nothing else changes in the file. - -- [ ] **Step 2: Create `skills/a11y/scripts/scan.py`** - -```python -#!/usr/bin/env python3 -"""Static accessibility scan: keyboard, visible focus, alt text, labels. - -Runs the guardrails scan engine (skills/guardrails/scripts/scanner.py) on -the a11y catalogue. Same options and exit codes; markers A11Y-CLEAR and -A11Y-NO-NEW. -""" -import importlib -import sys -from pathlib import Path - -ENGINE = Path(__file__).resolve().parents[2] / "guardrails" / "scripts" -if not ENGINE.is_dir(): - print(f"usage error: scan engine missing at {ENGINE} " - "(the guardrails skill must be installed)", file=sys.stderr) - sys.exit(2) -sys.path.insert(0, str(ENGINE)) - -scanner = importlib.import_module("scanner") -a11y_checks = importlib.import_module("a11y_checks") - -CATALOGUE = scanner.Catalogue( - name="a11y", - domains={"a11y": a11y_checks}, - rule_domains={"A11Y": "a11y"}, -) - -if __name__ == "__main__": - sys.exit(scanner.main(sys.argv[1:], CATALOGUE)) -``` - -- [ ] **Step 3: Create the a11y fixture** - -```bash -mkdir -p lib/tests/fixtures/a11y-good/src/components -git mv lib/tests/fixtures/guardrails-good/src/styles.css lib/tests/fixtures/a11y-good/src/styles.css -cp lib/tests/fixtures/guardrails-good/src/components/ContactForm.tsx lib/tests/fixtures/a11y-good/src/components/ContactForm.tsx -``` - -- [ ] **Step 4: Create `lib/tests/a11y-scan.test.sh`** (then `chmod +x`) - -The suite proves the a11y catalogue: the clean fixture, one mutant per rule, the two benign locks, the A11Y markers, the gates.sh wiring and the rejection of guardrails rules and domains. Engine behaviour (symlinks, size cap, `--exclude`, JSON shape, empty tree) is proven once in `guardrails-scan.test.sh` on the same code. - -```bash -#!/usr/bin/env bash -# lib/tests/a11y-scan.test.sh — floor of the /a11y scanner catalogue. -# The clean fixture must scan with zero FAIL and zero WARN. Each mutant breaks -# one rule on a copy of it and must raise that rule at the expected severity -# (positive control). The A11Y-CLEAR / A11Y-NO-NEW markers, the gates.sh -# contract wiring and the rejection of guardrails rules are checked too; the -# shared engine itself is proven in guardrails-scan.test.sh. -set -u -ROOT="$(cd "$(dirname "$0")/../.." && pwd)" -SCAN="$ROOT/skills/a11y/scripts/scan.py" -GOOD="$ROOT/lib/tests/fixtures/a11y-good" -WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT -PASS=0; FAIL=0; LAST_OUT="" - -check() { # check