From c0fdbec3c18b0cc692e2d7d4199aa3f1af23402b Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 19 Oct 2026 11:56:25 +0200 Subject: [PATCH] fix(guardrails): probe map and fields verdicts fail closed, console rule sees public/, raw escape WARN, argv silent, plan validation --- ...2026-10-18-guardrails-a11y-split-design.md | 2 +- lib/tests/guardrails-probe.test.sh | 107 ++++++++++++++++++ lib/tests/guardrails-scan.test.sh | 24 +++- skills/guardrails/references/checks.md | 8 +- skills/guardrails/scripts/checks/common.py | 10 +- skills/guardrails/scripts/checks/exposure.py | 3 +- skills/guardrails/scripts/checks/injection.py | 11 +- skills/guardrails/scripts/probe.py | 85 +++++++++----- 8 files changed, 206 insertions(+), 44 deletions(-) diff --git a/docs/superpowers/specs/2026-10-18-guardrails-a11y-split-design.md b/docs/superpowers/specs/2026-10-18-guardrails-a11y-split-design.md index 44fa4a3..2a7d8ba 100644 --- a/docs/superpowers/specs/2026-10-18-guardrails-a11y-split-design.md +++ b/docs/superpowers/specs/2026-10-18-guardrails-a11y-split-design.md @@ -72,7 +72,7 @@ when two rules match the same line the first in this order wins. | Rule | Sev | Catches | |---|---|---| -| INJ-SQL-RAW-UNSAFE | FAIL | a raw escape fed a non-literal first argument: `$queryRawUnsafe(`, `$executeRawUnsafe(`, `knex.raw(`, `.raw(`, `.extra(`, `sequelize.query(`, `Sequelize.literal(`, `text(` when `sqlalchemy` is imported; ActiveRecord `.where("… #{` | +| INJ-SQL-RAW-UNSAFE | WARN | a raw escape fed a non-literal first argument: `$queryRawUnsafe(`, `$executeRawUnsafe(`, `knex.raw(`, `.raw(`, `.extra(`, `sequelize.query(`, `Sequelize.literal(`, `text(` when `sqlalchemy` is imported; ActiveRecord `.where("… #{`; WARN: a variable may hold a constant | | INJ-SQL-CONCAT | FAIL | a SQL statement string built from an expression: untagged template literal with `${`, quoted SQL followed by `+ identifier`, Python f-string, `%` operator or `.format(`, PHP `"… $var"` or `. $var`, Ruby `#{}`, Rust `format!(`, Go `fmt.Sprintf(` | | INJ-SQL-DYNAMIC-EXEC | WARN | plpgsql `EXECUTE` whose statement uses `\|\|` and is not `format(…)` (SQL files, comments blanked) | | INJ-POSTGREST-FILTER | WARN | supabase-js `.or(`, `.filter(`, `.not(`, `.match(`, `.textSearch(` with a template `${` or a `+` concatenation | diff --git a/lib/tests/guardrails-probe.test.sh b/lib/tests/guardrails-probe.test.sh index 8449bcc..9f52acb 100644 --- a/lib/tests/guardrails-probe.test.sh +++ b/lib/tests/guardrails-probe.test.sh @@ -88,6 +88,40 @@ class H(BaseHTTPRequestHandler): if path == "/api/clean": return self._send(200, b'{"id": 7, "name": "Ada", "role": "member"}', {"Content-Type": "application/json"}) + if path == "/embed.js": + return self._send(200, b'var s="//# sourceMappingURL=data:' + b'application/json;base64,"+btoa(m);\n') + if path == "/redir.js": + return self._send(200, b"console.log(6);\n") + if path == "/redir.js.map": + return self._send(302, b"", {"Location": "http://other.invalid/m"}) + if path == "/hdr.js": + return self._send(200, b"console.log(7);\n", + {"SourceMap": "/hdr.real.map"}) + if path == "/hdr.real.map": + return self._send(200, b'{"version":3,"sources":["a.ts"]}') + if path == "/cmt.js": + return self._send(200, b"console.log(8);\n//# sourceMappingURL=" + b"cmt.real.map\n") + if path == "/cmt.real.map": + return self._send(200, b'{"version":3,"sources":["b.ts"]}') + if path == "/offhost.js": + return self._send(200, b"x();\n//# sourceMappingURL=" + b"http://other.invalid/o.map\n") + if path == "/trunc.js": + return self._send(200, b"a" * 1_000_001) + if path == "/bigmap.js": + return self._send(200, b"y();\n") + if path == "/bigmap.js.map": + return self._send(200, b'{"sources":["c.ts"],"x":"' + b"A" * 1_000_001) + if path == "/api/echo": + bearer = self.headers.get("Authorization", "") + body = b'{"id": 1, "password_hash": "x"}' if bearer else b'{"id": 1}' + return self._send(200, body, {"Content-Type": "application/json"}) + if path == "/api/graphql": + return self._send(200, b'{"data": {"users": {"edges": [{"node": ' + b'{"passwordHash": "x"}}]}}}', + {"Content-Type": "application/json"}) if path == "/boom": return self._send(500, b"Traceback (most recent call last):\n" b' File "app.py", line 12, in handler\n') @@ -274,6 +308,79 @@ OUT="$(probe --authorized "$WORK/lower.json")" check "lowercase CORS header names are still read" \ "$(verdict "$OUT" 'cors-reflect')" OPEN +echo "== exposure probes: map channels and fail-closed paths" +cat > "$WORK/maps.json" < "$WORK/fields.json" < "$WORK/file.json" +probe --authorized "$WORK/file.json" >/dev/null 2>&1 +check "a file:// base_url exits 2" "$?" 2 +printf '{"base_url": 5}\n' > "$WORK/num.json" +ERR="$(probe --authorized "$WORK/num.json" 2>&1 >/dev/null)" +check "a non-string base_url exits 2 without a traceback" \ + "$(printf '%s\n' "$ERR" | grep -c 'Traceback')" 0 +probe --authorized "$WORK/num.json" >/dev/null 2>&1 +check "a non-string base_url exits 2" "$?" 2 +printf '{"base_url": "%s", "rate_limit": {"count": 5}}\n' "$BASE" > "$WORK/nopath.json" +ERR="$(probe --authorized "$WORK/nopath.json" 2>&1 >/dev/null)" +check "a rate_limit with no path gives a usage message, no traceback" \ + "$(printf '%s\n' "$ERR" | grep -c 'rate_limit.path must be a string')" 1 +probe --authorized "$WORK/nopath.json" >/dev/null 2>&1 +check "a rate_limit with no path exits 2" "$?" 2 +printf '{"base_url": "%s", "routes": [{"path": "/a\\u001b[31mb"}]}\n' "$BASE" > "$WORK/ctl.json" +check "a control character in a path is an ERROR row, no traceback" \ + "$(probe --authorized "$WORK/ctl.json" 2>&1 | grep -c 'Traceback')" 0 +check "control characters of a target never reach the output" \ + "$(probe --authorized "$WORK/ctl.json" | LC_ALL=C grep -c "$(printf '\033')")" 0 +same_host() { python3 -B -c ' +import sys +sys.path.insert(0, sys.argv[1]) +import probe +print(bool(probe._same_host(sys.argv[2], sys.argv[3])))' \ + "$ROOT/skills/guardrails/scripts" "$1" "$2"; } +check "an https to http move is not the same host" \ + "$(same_host https://a.test/x http://a.test/y)" False +check "a different port is not the same host" \ + "$(same_host http://a.test/x http://a.test:81/y)" False +check "a same-scheme same-host url is kept" \ + "$(same_host http://a.test/x /y)" True +check "an http to https upgrade on the host is kept" \ + "$(same_host http://a.test/x https://a.test/y)" True + echo "== JSON output" check "json reports the open count" \ "$(probe --authorized --json "$WORK/plan.json" \ diff --git a/lib/tests/guardrails-scan.test.sh b/lib/tests/guardrails-scan.test.sh index 8893b7f..c0ba2bb 100644 --- a/lib/tests/guardrails-scan.test.sh +++ b/lib/tests/guardrails-scan.test.sh @@ -179,8 +179,14 @@ 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 \ +mutant sql-raw-unsafe WARN INJ-SQL-RAW-UNSAFE \ "printf '%s\n' 'const rows = await prisma.\$queryRawUnsafe(statement);' >> $API" +mutant sql-sqla-text-var WARN INJ-SQL-RAW-UNSAFE \ + "printf '%s\n' 'import sqlalchemy' 'conn.execute(text(query))' > src/lib/db.py" +mutant shell-db-os-system FAIL INJ-SHELL-DB-TOOL \ + "printf '%s\n' 'os.system(\"psql \" + url)' > src/lib/backup.py" +mutant shell-db-template FAIL INJ-SHELL-DB-TOOL \ + "printf '%s\n' 'exec(\`psql \${db}\`);' > src/lib/backup.ts" 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 \ @@ -191,6 +197,12 @@ mutant shell-db-tool FAIL INJ-SHELL-DB-TOOL \ "printf '%s\n' 'execSync(\`pg_dump --table=\${table} app > backup.sql\`);' > src/lib/backup.ts" echo "== exposure" +mutant console-data-public-dir WARN EXP-CONSOLE-DATA \ + "mkdir -p public/js; printf '%s\n' 'console.log(user);' > public/js/app.js" +mutant data-attr-hidden-input WARN EXP-DATA-ATTR-SENSITIVE \ + "printf '%s\n' '' >> $TSX" +mutant debug-errorhandler FAIL EXP-DEBUG-ON \ + "printf '%s\n' 'app.use(errorhandler());' >> $API" mutant console-data WARN EXP-CONSOLE-DATA \ "printf '%s\n' 'console.log(\"saved\", session);' >> $TSX" mutant sourcemap-next FAIL EXP-SOURCEMAP-PUBLIC \ @@ -306,6 +318,16 @@ benign minified-bundle \ 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" +benign sqla-text-method \ + "printf '%s\n' 'import sqlalchemy' 'label = project.text(path)' > src/lib/db.py" +benign shell-db-argv-spawn \ + "printf '%s\n' 'spawn(\"psql\", [\"-f\", file], {env});' > src/lib/backup.ts" +benign shell-db-argv-python \ + "printf '%s\n' 'subprocess.run([\"psql\", f\"--dbname={url}\"])' > src/lib/backup.py" +benign shell-db-env-ref \ + "printf '%s\n' 'execSync(\"psql \$DATABASE_URL -f schema.sql\");' > src/lib/backup.ts" +benign console-public-minified \ + "mkdir -p public/js; printf '%s\n' 'console.log(user);' > public/js/app.min.js" benign console-plain-string \ "printf '%s\n' 'console.log(\"ready\");' >> $TSX" benign console-string-data \ diff --git a/skills/guardrails/references/checks.md b/skills/guardrails/references/checks.md index 08313df..b4cb4f7 100644 --- a/skills/guardrails/references/checks.md +++ b/skills/guardrails/references/checks.md @@ -34,12 +34,12 @@ silent by design. | Rule | Sev | Catches | Fix | |---|---|---|---| -| INJ-SQL-RAW-UNSAFE | FAIL | `$queryRawUnsafe`, `$executeRawUnsafe`, `knex.raw`, `sequelize.query`, `Sequelize.literal`, Django `.objects.raw()` / `.extra()`, SQLAlchemy `text()` fed a variable; ActiveRecord `where("… #{}")` | bind the values, or the tagged `$queryRaw` | +| INJ-SQL-RAW-UNSAFE | WARN | `$queryRawUnsafe`, `$executeRawUnsafe`, `knex.raw`, `sequelize.query`, `Sequelize.literal`, Django `.objects.raw()` / `.extra()`, SQLAlchemy `text()` fed a variable (a variable may hold a constant); ActiveRecord `where("… #{}")` | show it is a constant with bound values, else bind them; or the tagged `$queryRaw` | | INJ-SQL-CONCAT | FAIL | a SQL statement (select … from … where, insert into, update … set, delete … where, create/drop/alter) built with `${}`, `+`, an f-string, `%`, `.format`, PHP `$var`, Ruby `#{}`, `format!`, `Sprintf` | placeholders and a parameter list | | INJ-SQL-DYNAMIC-EXEC | WARN | plpgsql `EXECUTE '…' \|\| x` | `format('… %I %L', …)` and `USING` | | INJ-POSTGREST-FILTER | WARN | supabase-js `.or()`, `.filter()`, `.not()`, `.match()`, `.textSearch()` with an interpolated string, in a file that uses supabase | `.eq()` and friends, validated values | | INJ-NOSQL-OPERATOR | WARN | Mongo `$where` with a string; a filter taken from `req.body`, `req.query` or `req.params` | allowlist the fields, cast to string, `sanitizeFilter` | -| INJ-SHELL-DB-TOOL | FAIL | a shell call naming psql, mysql, mysqldump, pg_dump, mongosh, redis-cli, sqlite3… with an interpolated argument | an argv array, no shell, validated input | +| INJ-SHELL-DB-TOOL | FAIL | a shell call naming psql, mysql, mysqldump, pg_dump, mongosh, redis-cli, sqlite3… with an interpolated argument (an argv array and a bare `$ENV_VAR` stay silent) | an argv array, no shell, validated input | ## exposure @@ -50,8 +50,8 @@ silent by design. | EXP-HYDRATED-SENSITIVE | WARN | a token, secret, key, password or ssn-like key returned by `getServerSideProps`, `getStaticProps`, a Remix `loader`, a SvelteKit `load` or set on `window.__STATE__`; a TS type member is skipped | return only the fields the page renders | | EXP-MARKUP-COMMENT | WARN | `` shipped to the browser (html, astro, php, ejs, hbs, twig, njk, liquid) with todo, fixme, debug, password, token, internal, staging, admin… | delete it, or move it to a code comment the build strips | | EXP-DATA-ATTR-SENSITIVE | WARN | `data-*` attribute or hidden input named secret, api-key, password, jwt, private, credential (csrf, xsrf, authenticity, nonce excluded) | keep it server-side, send an opaque id | -| EXP-ERROR-STACK | FAIL | in a route file: `err.stack`, the error object, `traceback.format_exc()` or `getTraceAsString()` in a response | generic message out, full error in the server log | -| EXP-ERROR-MESSAGE | WARN | in a route file: `err.message`, `str(e)`, `$e->getMessage()` sent as is | map to a safe message; validation errors are fine, DB errors are not | +| EXP-ERROR-STACK | FAIL | in any server file: `err.stack`, the error object, `traceback.format_exc()` or `getTraceAsString()` in a response | generic message out, full error in the server log | +| EXP-ERROR-MESSAGE | WARN | in any server file: `err.message`, `str(e)`, `$e->getMessage()` sent as is | map to a safe message; validation errors are fine, DB errors are not | | EXP-DEBUG-ON | FAIL | `DEBUG = True` in a settings module (not dev/local/test), `APP_DEBUG=true` / `FLASK_DEBUG=1` in a committed non-dev env file, `app.debug = True`, `consider_all_requests_local = true`, `errorhandler()` mounted without an environment guard | env-driven, false in production | | EXP-RESPONSE-WIDE | WARN | a route returning `select *` / `select('*')` on a users-like table, or a single-line Prisma `findUnique/findFirst/findMany` without `select` or `omit` | an explicit field list | diff --git a/skills/guardrails/scripts/checks/common.py b/skills/guardrails/scripts/checks/common.py index e03a741..fc4c6ba 100644 --- a/skills/guardrails/scripts/checks/common.py +++ b/skills/guardrails/scripts/checks/common.py @@ -188,12 +188,16 @@ def _minified(project, path): for line in project.text(path).splitlines()) -def code_files(project, exts=SOURCE_EXTS): - """Hand-written source: no tests, fixtures, built dirs, minified files.""" +def code_files(project, exts=SOURCE_EXTS, keep_built=False): + """Hand-written source: no tests, fixtures, built dirs, minified files. + + keep_built keeps public/, static/, www/ and assets/: they also hold the + hand-written browser scripts of server-rendered stacks.""" + skipped = set() if keep_built else BUILT_SEGMENTS 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 set(project.segments(p)) & skipped and not _minified(project, p)] diff --git a/skills/guardrails/scripts/checks/exposure.py b/skills/guardrails/scripts/checks/exposure.py index 30ca03e..c08155a 100644 --- a/skills/guardrails/scripts/checks/exposure.py +++ b/skills/guardrails/scripts/checks/exposure.py @@ -261,7 +261,8 @@ def _response_wide(project): def check(project): files = code_files(project) - found = _console_data(project, files) + _map_config(project) + console = code_files(project, keep_built=True) + found = _console_data(project, console) + _map_config(project) found += _map_files(project) + _hydrated(project, files) found += _markup_comments(project) + _data_attrs(project) found += _errors(project, files) + _debug(project, files) diff --git a/skills/guardrails/scripts/checks/injection.py b/skills/guardrails/scripts/checks/injection.py index 0501f42..2458a6f 100644 --- a/skills/guardrails/scripts/checks/injection.py +++ b/skills/guardrails/scripts/checks/injection.py @@ -49,7 +49,7 @@ RAW = { 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'\"`)])") +SQLA_TEXT = re.compile(r"(?]{1,300}src=[\"']?([^\"'\s>]+)", re.I) -MAP_COMMENT = re.compile(r"//[#@]\s*sourceMappingURL=(\S+)") +MAP_COMMENT = re.compile( + r"^[ \t]*//[#@][ \t]*sourceMappingURL=(\S+)", re.M) TRACE_MARKERS = re.compile( rb"Traceback \(most recent call last\)" rb"|\bat [\w.$<> ]{1,80} \([^)\n]{0,200}:\d+:\d+\)" @@ -71,11 +73,19 @@ class Probe: return asdict(self) +def _stays_on_host(old_url, new_url): + """Same host and port; the scheme may stay or upgrade, never downgrade.""" + old, new = urlsplit(old_url), urlsplit(new_url) + return old.netloc == new.netloc and ( + old.scheme == new.scheme or (old.scheme, new.scheme) + == ("http", "https")) + + class _SameHost(urllib.request.HTTPRedirectHandler): """Follow a same-host redirect, drop one that leaves the host.""" def redirect_request(self, req, fp, code, msg, headers, newurl): - if urlsplit(newurl).netloc != urlsplit(req.full_url).netloc: + if not _stays_on_host(req.full_url, newurl): return None return super().redirect_request(req, fp, code, msg, headers, newurl) @@ -111,8 +121,10 @@ def fetch(session, method, url, headers=None, body=None): return _response_from(resp) except urllib.error.HTTPError as exc: return Response(exc.code, exc.headers, _error_body(exc)) - except (urllib.error.URLError, OSError, ValueError) as exc: - return Response(None, {}, b"", str(exc)) + except (urllib.error.URLError, OSError, ValueError, + http.client.HTTPException) as exc: + reason = str(exc) + return Response(None, {}, b"", reason) def _verdict(ctx, response, is_open, msgs): @@ -247,7 +259,7 @@ def probe_rate_limit(session, plan): def _same_host(context, url): """Absolute url when it stays on context's host, else None.""" full = urljoin(context, url) - return full if urlsplit(full).netloc == urlsplit(context).netloc else None + return full if _stays_on_host(context, full) else None def _page_scripts(session, base): @@ -268,9 +280,9 @@ def _map_candidates(script_url, resp): header = resp.headers.get("sourcemap") or resp.headers.get("x-sourcemap") if header: urls.append(header) - comment = MAP_COMMENT.search(resp.body.decode("utf-8", "ignore")) - if comment: - urls.append(comment.group(1)) + comments = MAP_COMMENT.findall(resp.body.decode("utf-8", "ignore")) + if comments: + urls.append(comments[-1]) return list(dict.fromkeys(urls)) @@ -287,6 +299,9 @@ def _map_verdict(session, script_url, candidates): resp = fetch(session, "GET", target) if resp.error or resp.status is None: return "ERROR", target, resp.error or "no response" + if 300 <= resp.status < 400: + return ("SKIPPED", target, f"HTTP {resp.status}: map redirect " + "dropped (off host or downgraded), not followed") if resp.status == 403 or (resp.status or 0) >= 500: return ("SKIPPED", target, f"HTTP {resp.status}: map not readable, not confirmed") @@ -341,20 +356,17 @@ def _error_paths(cfg): return [random_path] + list(cfg.get("error_routes") or []) -def _keys(data, depth=0): - if depth > 4: - return [] - if isinstance(data, dict): - found = [k for k in data if isinstance(k, str)] - for value in data.values(): - found += _keys(value, depth + 1) - return found - if isinstance(data, list): - found = [] - for value in data[:5]: - found += _keys(value, depth + 1) - return found - return [] +def _keys(data): + """Every string key of the whole body, walked without recursion.""" + found, stack = [], [data] + while stack: + node = stack.pop() + if isinstance(node, dict): + found += [k for k in node if isinstance(k, str)] + stack += node.values() + elif isinstance(node, list): + stack += node + return found def _snake(key): @@ -429,9 +441,15 @@ def _tally(results): for v in ("OPEN", "CLOSED", "SKIPPED", "ERROR")} +def _printable(text): + """Control characters of a remote or plan string never reach the tty.""" + return re.sub(r"[\x00-\x1f\x7f-\x9f]", "?", str(text)) + + def _probe_row(probe): - return (f" {probe.verdict:<8} {probe.domain:<9} {probe.id} " - f"{probe.target}\n {probe.message}") + return _printable( + f" {probe.verdict:<8} {probe.domain:<9} {probe.id} " + f"{probe.target}\n {probe.message}") def _summary(results): @@ -442,7 +460,7 @@ def _summary(results): def _render_text(plan, results): body = [_probe_row(p) for p in results] - head = [f"guardrails live probe: {plan['base_url']}", + head = [_printable(f"guardrails live probe: {plan['base_url']}"), f"probes: {len(results)} (read-only, bounded budget)"] return "\n".join(head + [""] + body + [_summary(results)]) @@ -455,13 +473,18 @@ def _render_json(plan, results): }, indent=2) +def _http_url(value): + return isinstance(value, str) and urlsplit(value).scheme in ( + "http", "https") and bool(urlsplit(value).netloc) + + def _load_plan(path): try: plan = json.loads(open(path, encoding="utf-8").read()) except (OSError, ValueError) as exc: return None, f"cannot read plan: {exc}" - if not isinstance(plan, dict) or not plan.get("base_url"): - return None, "plan needs an object with a base_url" + if not isinstance(plan, dict) or not _http_url(plan.get("base_url")): + return None, "plan needs an object with an http(s) base_url" return plan, "" @@ -494,8 +517,11 @@ def _exposure_error(cfg): def _shape_error(plan): - if "rate_limit" in plan and not isinstance(plan["rate_limit"], dict): + rate = plan.get("rate_limit", {}) + if not isinstance(rate, dict): return "rate_limit must be an object" + if rate and not isinstance(rate.get("path"), str): + return "rate_limit.path must be a string" if plan.get("routes") is not None and \ not isinstance(plan["routes"], list): return "routes must be a list" @@ -539,7 +565,8 @@ def main(argv): return 2 if not args.authorized: print("refused: pass --authorized to confirm you own " - f"{plan['base_url']} and may probe it", file=sys.stderr) + f"{_printable(plan['base_url'])} and may probe it", + file=sys.stderr) return 2 results = run_probes(Session(), plan) render = _render_json if args.json else _render_text