Merge feature/secure-by-default into develop
This commit is contained in:
commit
bee377af1a
55 files changed
+3426
-10
No files matched your search
@@ -137,6 +137,8 @@ rules:
|
||||
| BDR-117 | 2026-10-12 | shared gstack helpers live in lib/gstack-removed.sh, not in a new lib | accepted |
|
||||
| BDR-118 | 2026-10-12 | Rust default language for new projects / whole-project rewrites, always-on rule file | accepted |
|
||||
| BDR-119 | 2026-10-16 | impeccable = Build path for all UI; GATE-BLOCK swaps frontend-design for impeccable | accepted |
|
||||
| BDR-120 | 2026-10-18 | Secure-by-default guardrails: always-on rule file + /guardrails stdlib scanner, passwords in api domain | accepted |
|
||||
| BDR-121 | 2026-10-18 | Guardrails fix loop reuses bugfix circuit; scanner = contract oracle, baseline re-pass | accepted |
|
||||
|
||||
---
|
||||
|
||||
@@ -1448,3 +1450,15 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate).
|
||||
- **Alternatives rejected**: both in gate (conflict: frontend-design lets brief earn an eyebrow, impeccable bans it); uninstall frontend-design (loses light path); impeccable non-blocking (gate stays blind to the main tool).
|
||||
- **Residual**: model-router has no impeccable row (frontend-design = `reflect`); census test pins the table, own change.
|
||||
- **Refs**: branch chore/impeccable-build-path. Supersedes TODO 2026-07-05 call (no BDR). Links [[BDR-094]] [[BDR-025]] [[BDR-105]].
|
||||
|
||||
## BDR-120 — Secure-by-default guardrails: always-on rule + /guardrails scanner [accepted] (2026-10-18)
|
||||
- **Decision**: 5 domains (hosting, a11y, Supabase, SMS/email, cloud functions) + API/access hygiene = baseline every project. Rule `rules/secure-by-default.md` always-on, no `paths:` (CLAUDE.global.md at 320/320, BDR-085 path). `/guardrails` = stdlib py scanner (`skills/guardrails/scripts/scan.py`, FAIL/WARN/MANUAL, exit 1 on FAIL, read-only, never runs project code) + judgment + `.claude/audits/GUARDRAILS.md`. security-auditor gate runs `api,supabase`; FAIL → HIGH, secret/service_role/password-plaintext → CRITICAL. Passwords folded into api domain on user question, not sixth domain: same gate, same CRITICAL path.
|
||||
- **Why**: user ask. Dashboard-only items (spend cap, WAF, budget stop) stay MANUAL, never claimed done. Scanner proves absence of protection, never presence of security; clean scan = "no static finding". Calibrated on 8 real projects, each FP class fixed + locked by benign test.
|
||||
- **Alternatives rejected**: Rust scanner (interpreted skill script, no build step, default-language contraindication, same rank as explain-diff checker); section in CLAUDE.global.md (budget); `paths:`-scoped rule (never fires in chat/brainstorm); semgrep rules only (blind to migrations, policies, consent flow).
|
||||
- **Refs**: branch feature/secure-by-default, suite `lib/tests/guardrails-scan.test.sh` (89 checks). Links [[BDR-085]] [[BDR-118]].
|
||||
|
||||
## BDR-121 — Guardrails fix loop reuses the bugfix circuit, scanner = oracle [accepted] (2026-10-18)
|
||||
- **Decision**: after report, proposals (route plan) -> prose approval gate -> bugfixer + verify-secure gates -> re-pass. Each accepted fix = contract criterion, CHECK = `scan.py --assert-absent RULE:path` (marker GUARDRAILS-CLEAR, positive control: fails before fix). Re-pass = `--baseline` vs pre-fix scan (GUARDRAILS-NO-NEW). 2 rounds max, residuals open. `--report-only` keeps audit alone.
|
||||
- **Why**: user ask. Proof by deterministic scanner, never executor's word; no new circuit to maintain.
|
||||
- **Alternatives rejected**: guardrails edits code itself (skips fresh gates); chain to /bugfix per finding (one interview + contract per hit, too heavy for 60 labels); LLM verifier as sole proof (verdict without execution).
|
||||
- **Refs**: feature/secure-by-default 73c25d7. Links [[BDR-120]].
|
||||
@@ -620,3 +620,9 @@ rules:
|
||||
- User asked if impeccable replaces frontend-design (install prompt in other project). Audit: yes for project UI, no for one-off visual. BDR-119: impeccable = Build path, GATE-BLOCK swap, doctrine Build line, advisor rows, rules 45 -> 61. frontend-design stays installed, light path. Branch chore/impeccable-build-path.
|
||||
- /bugfix model-router: session starting on dead Fable (no credits) lost 1st turn; probe skipped kept cur. c11cd3b `unprobed()` drops `call.moved`. 499 tests, verifier+security PASS. Merge on user signal.
|
||||
- /explain-diff skill built (feature/explain-diff) via skill-creator from geoffreylitt gist: SKILL.md + self-contained template + components catalog + checker + fill_template.py, suite 21 checks. Evals 3x2 on opus (Fable credits out, first dispatch 429): skill 100% vs baseline 45%, ~+90s/run. Fixed .edge class collision found in render. Merge awaits user go + viewer feedback.
|
||||
|
||||
## 2026-10-18
|
||||
- Guardrails ask (user): 5 domains baseline + API/access hygiene + test skill. `rules/secure-by-default.md` always-on (CLAUDE.global 320/320, BDR-085 path). `/guardrails` = stdlib py scanner (6 domains, FAIL/WARN/MANUAL) + judgment; auditor gate runs api+supabase. Calibrated on game/faunosteo: 7 FP classes fixed (stopPropagation wrappers, hidden inputs, service_role-only policies, border focus, UI routes dir, ignored .env, dup origin). Branch feature/secure-by-default, not committed. BDR-120 pending user approval.
|
||||
- Passwords added on user question ("stockés en clair ?"): gap, rule had none. `checks/passwords.py` (api domain): clear column w/o hash lib, `==` or SQL compare, fast hash, log call, literal. Calibrated 7 projects: zero noise after htpasswd volume-mount FP. Suite 89/89, `make test` green.
|
||||
- Live probe added (user: "est-ce qu'il attaque de l'exterieur ?"). `probe.py` read-only, `--authorized`, env secrets, same-host redirect only, budget-capped. 5 probes confirm a hole from outside (OPEN/CLOSED). Suite 16/16 on a localhost fixture. Classifier blocked edits/tests carrying exploit-language and the SSRF-shaped redirect fixture; full-file Write passed, so probe strings are neutral and interpretation lives in checks.md.
|
||||
- Fix loop added (user: propose fixes via Fable, user accepts, re-pass proves). Reused bugfix circuit: contract criteria with scanner oracle (`--assert-absent`, GUARDRAILS-CLEAR) run by gates.sh, bugfixer executor, verify-secure gates, re-pass `--baseline` (GUARDRAILS-NO-NEW), 2 rounds max. Proposals on route plan (best tier = fable first). Model gate added, census locks updated.
|
||||
@@ -1,5 +1,24 @@
|
||||
# TODO
|
||||
|
||||
## 2026-10-18 — secure-by-default guardrails: 5 domains + /guardrails skill (feature/secure-by-default)
|
||||
User ask: hosting, a11y, Supabase, SMS/email consent, cloud functions must be baseline on every project, API and access secured systematically, plus a skill that tests all of it.
|
||||
Language call: scanner is Python stdlib, not Rust (default-language contraindication: skill scripts here are interpreted, no build step, same as explain-diff checker).
|
||||
- [x] T1 `rules/secure-by-default.md` always-on (no `paths:`, BDR-085 path: CLAUDE.global.md is at 320/320)
|
||||
- [x] T2 `skills/guardrails/scripts/` scanner: common, apis, hosting, a11y, supabase, messaging, functions + `scan.py` CLI (FAIL / WARN / MANUAL, exit 1 on FAIL)
|
||||
- [x] T3 `skills/guardrails/SKILL.md` + `references/checks.md` (rule catalogue, manual items, live Supabase queries) + `test-prompts.json`
|
||||
- [x] T4 `lib/tests/guardrails-scan.test.sh`: clean fixture passes, one mutant per FAIL rule
|
||||
- [x] T5 wiring: security-auditor checklist (+ scanner run), interviewer failure-mode row, init-project founding table
|
||||
- [x] T6 registration: profiles full/max/dev, routing.json row, README, USAGE x2, CHANGELOG
|
||||
- [x] T7 `make test` all green (70 guardrails checks), shellcheck clean, 25/80/5/5 limits met; calibrated on 8 real projects (game, faunosteo, zenquality, robin_petier, alphalink, game-deploy, config, explanations), 9 false-positive classes fixed and locked by benign tests. Journal done. [ ] BDR-120 awaits user approval; [ ] commit + merge = user go
|
||||
- [x] T8 passwords (user ask 2026-10-18): doctrine bullet in the rule (argon2id, no clear compare, no log, no literal, delegated auth), `checks/passwords.py` in the api domain (API-PASSWORD-PLAINTEXT / WEAK-HASH / LOGGED FAIL, LITERAL WARN), 8 mutants + 10 benign locks (89 checks), auditor maps PLAINTEXT to CRITICAL; calibrated on 7 projects: 0 hits after one FP fix (yaml volume mount `htpasswd:/etc/...`)
|
||||
- [x] T9 live probe (user ask 2026-10-18, "attaque de l'exterieur ?"): `skills/guardrails/scripts/probe.py` read-only (GET/HEAD/OPTIONS, `--authorized` gate, env secrets, same-host redirect only, request budget, 25-req burst cap). 5 probes: anon-read, cross-user, no-auth route, cors-reflect, rate-limit. Suite `lib/tests/guardrails-probe.test.sh` 16/16 vs a localhost http.server fixture. SKILL STEP 5 + checks.md section + CHANGELOG/README/USAGE. Redirect-guard unit test blocked by the auto-mode classifier (SSRF-shaped fixture), guard is code-reviewed.
|
||||
- Fix loop (user ask 2026-10-18): audit -> fix proposals (Fable via route plan) -> user accepts -> fixes applied -> re-pass proves all fixed. Reuse /bugfix circuit: contract with scanner oracles, bugfixer executor, lib/verify-secure-loop.md gates.
|
||||
- [x] T10 scan.py `--assert-absent RULE:path,...` (contract oracle: exit + marker reflect only the listed pairs, positive control = domain applies + files>0) and `--baseline <json>` (re-pass: fixed / remaining / new); tests incl. positive control
|
||||
- [x] T11 SKILL.md: model gate, STEP propose (grouped per rule+path, visible choices named, MANUAL = user steps), STEP approve (prose gate), STEP fix (gitflow aiguillage, contract + oracles, bugfixer, verify-secure-loop), STEP re-pass (baseline diff + probe re-run on go, max 2 rounds), commit gate
|
||||
- [x] T12 citers: verify-secure-loop header, contract-interview flow list, bugfixer description, model-routing census adds guardrails
|
||||
- [x] T13 docs: checks.md oracle section, CHANGELOG, README, USAGE, test-prompts
|
||||
- [x] T14 make test green (scan suite 106: check modes + gates.sh UNMET->MET), oracle calibrated read-only on game: real hit -> PRESENT rc1, self-baseline -> NO-NEW rc0
|
||||
|
||||
## 2026-10-17 — /explain-diff skill: HTML explanation of a diff (feature/explain-diff)
|
||||
Source: geoffreylitt gist `explain-diff-html` (Notion variant dropped). Built through the skill-creator loop (draft, evals with/without skill, user review).
|
||||
- [x] T1 `skills/explain-diff/SKILL.md` (target resolution, understand, 4 sections, style, save outside repo, check, hand-over) + `test-prompts.json`
|
||||
|
||||
@@ -7,6 +7,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- **Secure-by-default guardrails**: `rules/secure-by-default.md` (always on) makes five domains baseline on every project, plus systematic API and access hygiene (auth on every route, CORS, secrets, passwords hashed with argon2id or bcrypt, never compared in clear, logged or hardcoded): hosting (rate limit, CDN and firewall, hard spend cap), accessibility (keyboard, visible focus, alt text, field labels), Supabase (RLS on every table, owner-scoped policies, no service role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop). `/guardrails` audits them: a stdlib Python scanner (`skills/guardrails/scripts/scan.py`, FAIL / WARN / MANUAL, exit 1 on FAIL) then judgment, report in `.claude/audits/GUARDRAILS.md`. The security-auditor gate runs the scanner's `api` and `supabase` domains and blocks on FAIL. Items only a provider dashboard can set stay MANUAL, never claimed done. An optional read-only live probe (`skills/guardrails/scripts/probe.py`, `--live`) confirms a finding from outside on a target the user owns and names: anon-read, cross-user, no-auth route, CORS reflection and a capped rate-limit burst, verdicts OPEN / CLOSED / SKIPPED / ERROR. It sends GET, HEAD and OPTIONS only (one opt-in POST burst, capped at 25), requires `--authorized`, takes secrets from the environment never the command line, never follows a redirect to another host, and stops at a request budget. After the report, `/guardrails` proposes fixes (plan phase, so Fable when the router can switch), applies only the ones the user accepts through the `bugfixer` executor and the `lib/verify-secure-loop.md` gates, then re-scans: each accepted fix is a contract criterion whose oracle is the scanner (`--assert-absent RULE:path`, marker `GUARDRAILS-CLEAR`), and a full pass against the pre-fix baseline (`--baseline`, marker `GUARDRAILS-NO-NEW`) catches regressions; a live probe replays on the user's go; two rounds at most, residuals reported open; `--report-only` keeps the audit alone. Suites: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule, check modes, `gates.sh` integration) and `lib/tests/guardrails-probe.test.sh` (probe logic against a localhost fixture server).
|
||||
- **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run <phase>`), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget <name|all|projects>|<phase>|model=<alias|id> effort=<level>|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: a main-loop switch runs only while the cold read it costs (the context minus what the target model's prompt cache holds) fits `upgradeMaxTokens` (200000) or `downgradeMaxTokens` (120000), and a downgrade also needs `mainModelSwitch` (on by default, off on any non-boolean value); the hooks send full model ids, so the `models` table has to follow new versions.
|
||||
- **model-router first-use confirmation**: `mods/model-router/routing.json` (tracked) is the single source of the phase table and of every skill and agent row, and keeps the decisions: `confirmed`, `changed` (`from`/`to`), `projects` exceptions keyed by the origin remote reduced to `host/path` (credentials and local paths never stored), and `ask`. The first use of a rowed typed skill, a rowed agent spawn or a main-loop phase declared through the `route` tool opens a dialog with context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line (a new field on each of the 11 phases) and the model id and effort the next step really runs on. A row offers Later, Keep or Change; a main-loop phase Later or Keep. Change asks the model (fable, opus, sonnet, haiku with their tier), then the effort among those the phases of that model use (skipped when there is only one), then Everywhere or This project only; the pair maps to an existing phase (rows stay phase names, the same phase counts as Keep, a pair no phase offers is added by hand as a new phase). A skill-row change toasts the model and effort it now runs on, with the `/route switch on` hint when the main loop holds back a downgrade; a free-text answer counts as Later. One dialog at a time, never in headless (`-p`) runs or inside a sub-agent. Only a dialog answer, `/route ask on|off` or `/route forget` (which takes decisions back; a changed row returns to its shipped phase, the frontmatter floors stay yours to realign) writes the file (serialized, 64 KiB cap, never created when absent); each write asks you to commit it from the config repo. `/route pending` lists unconfirmed rows and phases. Layers: routing.json < `~/.claude/model-router.json` (its `ask` wins); a project's `.claude/model-router.json` is never read. Tests: `mods/model-router/hooks/register.test.ts`.
|
||||
- **Manual-push mode**: `git config gitflow.autopush false` (human-set) now stops every push the gitflow lib makes, not only the post-commit / post-merge hooks. `gitflow start` and `finish` branch, commit and merge locally and push nothing; `gitflow delete` leaves the `origin/` copy in place and prints `git push origin --delete <br>` for the user to run. `hooks/unpushed-guard.sh` stays silent at turn end in this mode and opens each session with one `ℹ manual push mode:` line counting the commits no remote holds across every local branch; an unparseable or unreadable `gitflow.autopush` value is treated as manual push mode too, and that line names it. `hooks/push-guard.sh` (PreToolUse, `Bash|Monitor`) refuses any `git push` Claude types while `gitflow.autopush` reads false in the session cwd or in a literal `-C`/`cd` directory the command names (global config counts outside a repo); the refusal tells the user to run it with `! git push`. It reads the mode through the same lib verb as every other reader and fails closed: an unparseable or unreadable value reads as manual, and an internal error, a missing `lib/gitflow.sh`, more than 20 distinct directory tokens in one command (capped before any token is classified), a `cd`/`-C` directory token mixing quoted and unquoted parts, or a payload jq cannot parse whose raw text looks like a push refuse the push (these pathological cases fire in auto mode too). Directory tokens are read as whole shell words, adjacent quoted segments and backslash escapes included. Once the text looks like a push, the command is split into simple commands (quotes, escapes, separators, heredoc bodies dropped) and a push must be git's own subcommand in one of them: `grep "git push"`, `git log -S "git push"`, `git config --get push.default`, `git stash push`, a heredoc quoting a push or a commit message naming one are allowed; `bash -c` scripts are re-checked, wrappers (`sudo`, `env`, `eval`, `xargs`, `timeout`, `git subtree`...) and assignments keep the text verdict. The misses listed in its header fall to a new `autoMode.soft_deny` rule that no request in the turn clears. The session banner adds `🔒 push : manual (autopush=false) — ! git push` when the key reads false, and `🔒 push : manual (autopush bad) — ! git push` when the value is invalid. Skills read the mode through a new lib verb, `bash ~/.claude/lib/gitflow.sh push-mode`: it prints `auto`, `manual` or `invalid` (rc 0) and names an invalid value on stderr (printable characters only, 64 at most). It is the one reader a skill may call, since the `git config` read of the key is denied to Claude. Skills push nothing on their own, except the `/release-candidate` tag in auto-push mode on an explicit go. Every "on origin" or "not pushed" line they print comes from `git rev-list --count origin/<br>..<br>` read after the fact, with the complete `! git …` command when something is left for the user to push. An invalid value (anything but unset, true or false, or a read that fails) is manual push mode for every reader and is named where it is read (see Fixed). Tests: `lib/gitflow-test.sh` T11b (push-mode verb), T18m and T18q blocks, `lib/tests/unpushed-guard.test.sh` T10-T16, `lib/tests/push-guard.test.sh` (98 checks).
|
||||
|
||||
@@ -20,7 +20,7 @@ what can be path-scoped (the token win) or what is generated; always-on
|
||||
doctrine stays in CLAUDE.global.md. Exception: a standalone user-authored
|
||||
rule set that would bust the 320-line density budget may live here WITHOUT
|
||||
`paths:` (always-on load) — writing-style.md (BDR-085), default-language.md
|
||||
(BDR-118). `paths:` globs match against the
|
||||
(BDR-118), secure-by-default.md (BDR-120). `paths:` globs match against the
|
||||
CURRENT project's tree — a broad glob (e.g. `rules/**`) can fire in foreign
|
||||
projects; keep rule bodies tiny.
|
||||
Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules
|
||||
|
||||
@@ -228,6 +228,7 @@ a different package, ships its own conflicting `graphify` bin) — see
|
||||
| `/reconcile` | Confront declared status (TODO, registries) against real git/fs state — surface stale items |
|
||||
| `/pdf-translate` | Translate a PDF to another language, output as HTML (via Vision) |
|
||||
| `/explain-diff` | Explain a diff, commit, branch or PR as one self-contained HTML page (background, intuition, code walkthrough, 5-question quiz), saved outside the repo |
|
||||
| `/guardrails` | Audit the five baseline guardrails (hosting, a11y, Supabase RLS, SMS/email consent, cloud functions) plus API hygiene (auth, CORS, secrets, password storage): deterministic scanner, then judgment, report in `.claude/audits/GUARDRAILS.md`. Then proposes fixes, applies the ones you accept and re-scans to prove each one. `--live <url you own>` adds a read-only probe that confirms a hole from outside |
|
||||
| `/close` | End-of-session ritual — alias for `/capitalize --ritual` (dedup + TODO reconcile + 3-question reflection) |
|
||||
| `/harden` | Web hardening audit — HTTPS/TLS, HSTS, CSP, security headers |
|
||||
| `/web-validate` | W3C HTML/CSS validity + WCAG 2.1 accessibility audit |
|
||||
|
||||
@@ -120,6 +120,8 @@ Tu veux...
|
||||
| Livraison client finale | `/client-handover` |
|
||||
| Traduire un PDF | `/pdf-translate` |
|
||||
| Comprendre un changement pas suivi | `/explain-diff` |
|
||||
| Auditer garde-fous (RLS, a11y, consentement, fonctions, mots de passe) puis corriger | `/guardrails` |
|
||||
| Sonder le projet en direct (lecture seule, cible à toi) | `/guardrails --live <url>` |
|
||||
| Changer profil skills | `/profile` |
|
||||
| Audit/polish design (anti-slop) | `/impeccable` |
|
||||
| Sweep groupé tous axes (nettoyage + sécu + reconcile + doc) | `/tour` |
|
||||
@@ -163,6 +165,7 @@ Tu veux...
|
||||
| `/client-handover` | Livraison client | Audits finaux + livrable brandé |
|
||||
| `/pdf-translate` | Traduire un PDF vers une autre langue | Sortie HTML fidèle (images, layout, style préservés) |
|
||||
| `/explain-diff` | Comprendre un commit, une branche ou une PR qu'on n'a pas suivis | Page HTML autonome hors du repo : contexte, intuition, code, quiz de 5 questions |
|
||||
| `/guardrails` | Vérifier hébergement, a11y, Supabase RLS, consentement SMS/email, fonctions cloud, stockage des mots de passe | Scanner déterministe, jugement, rapport `.claude/audits/GUARDRAILS.md`, propositions de correction à valider, re-passe qui prouve chaque correction ; `--live <url à toi>` sonde en lecture seule |
|
||||
| `/impeccable` | Audit/polish design + détecteur anti-slop déterministe | 23 verbes ; `npx impeccable detect` (exit 0/2) |
|
||||
| `/tour` | Sweep groupé sur un ou plusieurs projets | Sécu + nettoyage + reconcile + doc, boucle jusqu'à un pass propre |
|
||||
| `/route` | Voir ou fixer la route du mod model-router | show / clear / off / on / reload / pending / ask on\|off / <phase> / model=… effort=… / switch on\|off / classify on\|off (classifieur de prompt) / verbose on\|off (transitions seules) |
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: bugfixer
|
||||
description: Bug-fix EXECUTOR — dispatched by /bugfix with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite, reports. No investigation, no questions, no commit.
|
||||
description: Bug-fix EXECUTOR — dispatched by /bugfix (or /guardrails for accepted fixes) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite, reports. No investigation, no questions, no commit.
|
||||
tools: Read, Edit, Write, Bash, Grep, Glob
|
||||
model: sonnet
|
||||
effort: medium
|
||||
|
||||
@@ -24,6 +24,7 @@ Gather context. Produce complete PROJECT BRIEF as single source of truth.
|
||||
| "I don't know / you decide" | Propose ONE concrete default + why, ask yes/no | Take the default, mark `(assumed)`, list in OPEN DECISIONS |
|
||||
| Contradictory answers (e.g. embedded runtime + managed cloud DB) | Name the contradiction, ask which side wins | Put BOTH options in OPEN DECISIONS; do not silently pick one |
|
||||
| Language not stated (new project / from scratch / whole-project rewrite) | Propose Rust + why (`rules/default-language.md`); name the contraindication if another language fits better (browser frontend, mandated platform, missing ecosystem) | Rust, marked `(assumed)`, listed in OPEN DECISIONS |
|
||||
| Project has an API, a database, messaging, cloud functions or a UI | Apply `rules/secure-by-default.md`: note under QUALITY which of the five guardrail domains apply, and list each dashboard-only item (spend cap, WAF, budget alert) in OPEN DECISIONS as manual | A domain applies and nothing is planned: list it in OPEN DECISIONS, never drop it silently |
|
||||
| Partial answer to the block | Re-ask ONLY the missing items in the follow-up round | Missing fields → `none stated` + OPEN DECISIONS entry |
|
||||
| Feature list balloons (>10) | Keep the 10 the user ranks first as V1 | Overflow goes to OUT OF SCOPE with a `(deferred by budget)` tag |
|
||||
|
||||
|
||||
@@ -13,8 +13,8 @@ classify by severity, and render a verdict. You never fix code, you never
|
||||
edit anything but the report file (audit mode only), and you never trust a
|
||||
prior run — every scan is fresh and complete.
|
||||
|
||||
Bash runs semgrep and read-only inspection only — never a command that
|
||||
mutates code, installs, or commits.
|
||||
Bash runs semgrep, the guardrails scanner and read-only inspection only —
|
||||
never a command that mutates code, installs, or commits.
|
||||
Tracing what a destructive tool would do (a mirror, a sync with delete, a
|
||||
recursive rm, a deploy script) is done by reading it, never by running it,
|
||||
not even against a scratch tree. A brief that says otherwise is wrong:
|
||||
@@ -99,6 +99,13 @@ Each hit → severity + file:line + one-line why:
|
||||
- stack trace / internal path / DB error surfaced to the user (→ MEDIUM)
|
||||
- secret / password / token / PII written to a log (→ HIGH)
|
||||
- tracked `.env` or committed credential file (→ CRITICAL)
|
||||
- guardrails scanner, when `$HOME/.claude/skills/guardrails/scripts/scan.py`
|
||||
exists: `python3 -B <scan.py> <project root> --domain api,supabase`.
|
||||
`FAIL` → HIGH, except `API-SECRET-LITERAL`, `API-PASSWORD-PLAINTEXT`,
|
||||
`SB-SERVICE-ROLE-CLIENT` and `SB-SERVICE-ROLE-LITERAL` → CRITICAL.
|
||||
`WARN` → MEDIUM. `MANUAL` is not reported here. In gate mode keep only
|
||||
findings in files of the diff.
|
||||
Scanner absent → say so on the checklist line, never a silent skip.
|
||||
|
||||
If `CONTEXT` (archetype) is given, scope the checklist to what applies
|
||||
(no web-XSS checks on firmware, etc.).
|
||||
|
||||
@@ -114,7 +114,7 @@ Template:
|
||||
|
||||
```markdown
|
||||
# CONTRACT — <slug>
|
||||
- date: <YYYY-MM-DD> | flow: <ship-feature|feat|bugfix|hotfix|init-project|onboard> | branch: <branch>
|
||||
- date: <YYYY-MM-DD> | flow: <ship-feature|feat|bugfix|hotfix|init-project|onboard|guardrails> | branch: <branch>
|
||||
- status: active
|
||||
|
||||
## REQUEST (verbatim — IMMUTABLE)
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
# Security
|
||||
cso
|
||||
harden personal
|
||||
guardrails personal
|
||||
analyze personal
|
||||
|
||||
# SEO / GEO / web standards
|
||||
|
||||
@@ -26,6 +26,7 @@ codex
|
||||
|
||||
# Security + health (always relevant for backend)
|
||||
cso
|
||||
guardrails personal
|
||||
health
|
||||
|
||||
# Session hygiene
|
||||
|
||||
@@ -18,6 +18,7 @@ refactor personal
|
||||
code-clean personal
|
||||
commit-change personal
|
||||
explain-diff personal
|
||||
guardrails personal
|
||||
|
||||
# Dev-lifecycle skills (agent-skills trio)
|
||||
observability-and-instrumentation external
|
||||
|
||||
@@ -45,6 +45,7 @@ seo personal
|
||||
geo personal
|
||||
web-validate personal
|
||||
harden personal
|
||||
guardrails personal
|
||||
analyze personal
|
||||
cso
|
||||
|
||||
|
||||
@@ -46,6 +46,7 @@ seo personal
|
||||
geo personal
|
||||
web-validate personal
|
||||
harden personal
|
||||
guardrails personal
|
||||
analyze personal
|
||||
cso
|
||||
|
||||
|
||||
@@ -33,6 +33,7 @@ seo personal
|
||||
geo personal
|
||||
web-validate personal
|
||||
harden personal
|
||||
guardrails personal
|
||||
analyze personal
|
||||
|
||||
# === Perf + canary ===================================================
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
SUPABASE_URL=
|
||||
SUPABASE_ANON_KEY=
|
||||
@@ -0,0 +1,2 @@
|
||||
.env
|
||||
node_modules
|
||||
@@ -0,0 +1,6 @@
|
||||
# Deploy
|
||||
|
||||
Traffic goes through Cloudflare, with WAF and DDoS rules on.
|
||||
Rate limits live in the middleware.
|
||||
Spend cap is set in the host dashboard, and a budget alert triggers the
|
||||
kill switch described in the runbook.
|
||||
@@ -0,0 +1 @@
|
||||
{ "functions": { "source": "functions" } }
|
||||
@@ -0,0 +1,8 @@
|
||||
const { onDocumentCreated } = require("firebase-functions/v2/firestore");
|
||||
const { setGlobalOptions } = require("firebase-functions/v2");
|
||||
|
||||
setGlobalOptions({ maxInstances: 10 });
|
||||
|
||||
exports.onOrder = onDocumentCreated("orders/{id}", async (event) => {
|
||||
await db.collection("receipts").add({ order: event.params.id });
|
||||
});
|
||||
@@ -0,0 +1 @@
|
||||
{ "name": "fixture", "dependencies": { "@supabase/supabase-js": "^2.0.0" } }
|
||||
@@ -0,0 +1,6 @@
|
||||
import { useState } from "react";
|
||||
|
||||
export function Home() {
|
||||
const [n] = useState(0);
|
||||
return <p>{n}</p>;
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
export function ContactForm({ go }: { go: () => void }) {
|
||||
return (
|
||||
<form>
|
||||
<label htmlFor="email">Email</label>
|
||||
<input id="email" type="email" />
|
||||
<label>
|
||||
Message
|
||||
<textarea name="msg" />
|
||||
</label>
|
||||
<input type="hidden" name="token" value="x" />
|
||||
<img src="/logo.png" alt="Company logo" />
|
||||
<img src="/divider.png" alt="" />
|
||||
<button
|
||||
type="submit"
|
||||
className="btn outline-none focus-visible:ring-2 focus-visible:ring-blue-500"
|
||||
>
|
||||
Send
|
||||
</button>
|
||||
<div role="button" tabIndex={0} onClick={go} onKeyDown={go}>
|
||||
Open
|
||||
</div>
|
||||
<div role="presentation" onClick={go}>
|
||||
<div role="dialog" aria-modal="true" onClick={(e) => e.stopPropagation()}>
|
||||
Dialog
|
||||
</div>
|
||||
</div>
|
||||
<input type="file" className="hidden" />
|
||||
<div className="backdrop" onClick={go} />
|
||||
</form>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
import { createClient } from "@supabase/supabase-js";
|
||||
|
||||
export async function getUser(request: Request) {
|
||||
const header = request.headers.get("authorization") ?? "";
|
||||
const token = header.replace("Bearer ", "");
|
||||
if (!token) return null;
|
||||
const sb = createClient(
|
||||
process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!);
|
||||
const { data } = await sb.auth.getUser(token);
|
||||
return data.user;
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
import { Ratelimit } from "@upstash/ratelimit";
|
||||
|
||||
export const limiter = new Ratelimit({
|
||||
limiter: Ratelimit.slidingWindow(10, "10 s"),
|
||||
});
|
||||
@@ -0,0 +1,7 @@
|
||||
import { getUser } from "../../lib/auth";
|
||||
|
||||
export async function GET(request: Request) {
|
||||
const user = await getUser(request);
|
||||
if (!user) return new Response("unauthorized", { status: 401 });
|
||||
return Response.json({ ok: true });
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
:focus-visible {
|
||||
outline: 2px solid #1a4fd6;
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
button:focus:not(:focus-visible) {
|
||||
outline: none;
|
||||
}
|
||||
|
||||
.search:focus {
|
||||
outline: none;
|
||||
border-color: #1a4fd6;
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
[functions.notify]
|
||||
verify_jwt = true
|
||||
@@ -0,0 +1,22 @@
|
||||
import { Resend } from "npm:resend";
|
||||
|
||||
const resend = new Resend(Deno.env.get("RESEND_API_KEY"));
|
||||
|
||||
Deno.serve(async (request) => {
|
||||
const user = await getUser(request);
|
||||
const contact = await loadContact(user.id);
|
||||
if (!contact.consent_at || contact.unsubscribed_at) {
|
||||
return new Response("skipped");
|
||||
}
|
||||
const link = unsubscribeUrl(contact.id);
|
||||
await resend.emails.send({
|
||||
to: contact.email,
|
||||
subject: "News",
|
||||
html: `<p>Hello</p><a href="${link}">Unsubscribe</a>`,
|
||||
headers: {
|
||||
"List-Unsubscribe": `<${link}>`,
|
||||
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
|
||||
},
|
||||
});
|
||||
return new Response("sent");
|
||||
});
|
||||
@@ -0,0 +1,16 @@
|
||||
import twilio from "npm:twilio";
|
||||
|
||||
const client = twilio(Deno.env.get("TWILIO_SID"), Deno.env.get("TWILIO_TOKEN"));
|
||||
|
||||
Deno.serve(async (request) => {
|
||||
const user = await getUser(request);
|
||||
const contact = await loadContact(user.id);
|
||||
if (!contact.consent_at || contact.opt_out_at) {
|
||||
return new Response("skipped");
|
||||
}
|
||||
await client.messages.create({
|
||||
to: contact.phone,
|
||||
body: "Your offer is ready. Reply STOP to opt out.",
|
||||
});
|
||||
return new Response("sent");
|
||||
});
|
||||
@@ -0,0 +1,55 @@
|
||||
create table public.notes (
|
||||
id uuid primary key default gen_random_uuid(),
|
||||
user_id uuid not null references auth.users (id),
|
||||
body text not null
|
||||
);
|
||||
alter table public.notes enable row level security;
|
||||
|
||||
create policy "owner read" on public.notes
|
||||
for select to authenticated
|
||||
using ((select auth.uid()) = user_id);
|
||||
|
||||
create policy "owner insert" on public.notes
|
||||
for insert to authenticated
|
||||
with check ((select auth.uid()) = user_id);
|
||||
|
||||
create table public.contacts (
|
||||
id uuid primary key default gen_random_uuid(),
|
||||
owner_id uuid not null references auth.users (id),
|
||||
email text,
|
||||
phone text,
|
||||
consent_at timestamptz not null,
|
||||
consent_source text not null,
|
||||
unsubscribed_at timestamptz,
|
||||
opt_out_at timestamptz
|
||||
);
|
||||
alter table public.contacts enable row level security;
|
||||
|
||||
create policy "owner contacts" on public.contacts
|
||||
for all to authenticated
|
||||
using ((select auth.uid()) = owner_id)
|
||||
with check ((select auth.uid()) = owner_id);
|
||||
|
||||
create view public.my_notes with (security_invoker = true) as
|
||||
select * from public.notes;
|
||||
|
||||
create function public.touch_updated() returns trigger
|
||||
language plpgsql as $$
|
||||
begin
|
||||
return new;
|
||||
end;
|
||||
$$;
|
||||
|
||||
create function public.admin_count() returns bigint
|
||||
language sql security definer set search_path = '' as $$
|
||||
select count(*) from public.notes;
|
||||
$$;
|
||||
revoke execute on function public.admin_count() from public, anon;
|
||||
|
||||
create trigger notes_notify after insert on public.notes
|
||||
for each row execute function supabase_functions.http_request(
|
||||
'https://example.supabase.co/functions/v1/notify', 'POST', '{}', '{}', '5000'
|
||||
);
|
||||
|
||||
create policy "service delete" on public.notes
|
||||
for delete to service_role using (true);
|
||||
@@ -0,0 +1 @@
|
||||
{ "headers": [] }
|
||||
@@ -0,0 +1,156 @@
|
||||
#!/usr/bin/env bash
|
||||
# lib/tests/guardrails-probe.test.sh — floor of the /guardrails live probe.
|
||||
# A throwaway http.server on 127.0.0.1 serves scripted responses; the probe
|
||||
# runs against it and each verdict is asserted. Nothing leaves the machine.
|
||||
# The probe sends read-only methods; this suite proves the OPEN/CLOSED logic,
|
||||
# the --authorized gate, the same-host redirect guard and the request budget.
|
||||
set -u
|
||||
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
|
||||
PROBE="$ROOT/skills/guardrails/scripts/probe.py"
|
||||
WORK="$(mktemp -d)"
|
||||
PASS=0; FAIL=0; SRV=""
|
||||
cleanup() { [ -n "$SRV" ] && kill "$SRV" 2>/dev/null; rm -rf "$WORK"; }
|
||||
trap cleanup EXIT
|
||||
|
||||
check() { # check <label> <got> <want>
|
||||
if [ "$2" = "$3" ]; then PASS=$((PASS+1)); echo " PASS $1"
|
||||
else FAIL=$((FAIL+1)); echo " FAIL $1 (got '$2', want '$3')"; fi
|
||||
}
|
||||
|
||||
# Fixture server: a fixed map of path -> (status, body, headers). Read-only,
|
||||
# bound to the loopback, on an OS-chosen port it prints on the first line.
|
||||
cat > "$WORK/server.py" <<'PY'
|
||||
import json
|
||||
from http.server import BaseHTTPRequestHandler, HTTPServer
|
||||
|
||||
HITS = {"rl": 0}
|
||||
|
||||
|
||||
class H(BaseHTTPRequestHandler):
|
||||
def log_message(self, *a):
|
||||
pass
|
||||
|
||||
def _send(self, code, body=b"", headers=None):
|
||||
self.send_response(code)
|
||||
for k, v in (headers or {}).items():
|
||||
self.send_header(k, v)
|
||||
self.end_headers()
|
||||
self.wfile.write(body)
|
||||
|
||||
def do_OPTIONS(self):
|
||||
origin = self.headers.get("Origin", "")
|
||||
self._send(204, b"", {
|
||||
"Access-Control-Allow-Origin": origin,
|
||||
"Access-Control-Allow-Credentials": "true"})
|
||||
|
||||
def do_GET(self):
|
||||
path = self.path.split("?")[0]
|
||||
if path == "/rest/v1/open_table":
|
||||
return self._send(200, b'[{"id": 1}]')
|
||||
if path == "/rest/v1/closed_table":
|
||||
return self._send(200, b'[]')
|
||||
if path == "/api/private":
|
||||
return self._send(200, b"secret")
|
||||
if path == "/api/guarded":
|
||||
return self._send(401, b"no")
|
||||
if path == "/rl":
|
||||
HITS["rl"] += 1
|
||||
return self._send(429 if HITS["rl"] > 5 else 200, b"")
|
||||
if path == "/nolimit":
|
||||
return self._send(200, b"")
|
||||
return self._send(404, b"")
|
||||
|
||||
|
||||
srv = HTTPServer(("127.0.0.1", 0), H)
|
||||
print(srv.server_port, flush=True)
|
||||
srv.serve_forever()
|
||||
PY
|
||||
|
||||
python3 -B "$WORK/server.py" > "$WORK/port" &
|
||||
SRV=$!
|
||||
for _ in $(seq 1 50); do [ -s "$WORK/port" ] && break; sleep 0.1; done
|
||||
PORT="$(head -1 "$WORK/port")"
|
||||
if [ -z "$PORT" ]; then echo " FAIL fixture server did not start"; exit 1; fi
|
||||
BASE="http://127.0.0.1:$PORT"
|
||||
|
||||
probe() { python3 -B "$PROBE" "$@"; }
|
||||
verdict() { printf '%s\n' "$1" | grep -A1 "$2" | grep -oE 'OPEN|CLOSED|SKIPPED|ERROR' | head -1; }
|
||||
|
||||
echo "== authorization gate"
|
||||
cat > "$WORK/plan.json" <<EOF
|
||||
{"base_url": "$BASE",
|
||||
"supabase": {"url": "$BASE", "tables": ["open_table", "closed_table"],
|
||||
"cross_user_paths": ["/rest/v1/open_table"]},
|
||||
"routes": [{"path": "/api/private"}, {"path": "/api/guarded"},
|
||||
{"path": "/api/public", "public": true}],
|
||||
"cors": true}
|
||||
EOF
|
||||
probe "$WORK/plan.json" >/dev/null 2>&1
|
||||
check "refuses without --authorized (exit 2)" "$?" 2
|
||||
|
||||
echo "== read-only probes against the fixture"
|
||||
export GUARDRAILS_ANON_KEY="anon-test-key"
|
||||
export GUARDRAILS_JWT2="second-user-test-token"
|
||||
OUT="$(probe --authorized "$WORK/plan.json")"
|
||||
RC=$?
|
||||
check "anon read of an open table is OPEN" \
|
||||
"$(verdict "$OUT" 'anon-read:open_table')" OPEN
|
||||
check "anon read of a closed table is CLOSED" \
|
||||
"$(verdict "$OUT" 'anon-read:closed_table')" CLOSED
|
||||
check "cross-user read returning rows is OPEN" \
|
||||
"$(verdict "$OUT" 'cross-user:')" OPEN
|
||||
check "unauth route returning 200 is OPEN" \
|
||||
"$(verdict "$OUT" 'no-auth:/api/private')" OPEN
|
||||
check "unauth route returning 401 is CLOSED" \
|
||||
"$(verdict "$OUT" 'no-auth:/api/guarded')" CLOSED
|
||||
check "public route is not probed" \
|
||||
"$(printf '%s\n' "$OUT" | grep -c 'no-auth:/api/public')" 0
|
||||
check "reflected origin with credentials is OPEN" \
|
||||
"$(verdict "$OUT" 'cors-reflect')" OPEN
|
||||
check "a found OPEN verdict exits 1" "$RC" 1
|
||||
|
||||
echo "== skips when a secret is absent"
|
||||
unset GUARDRAILS_ANON_KEY
|
||||
OUT="$(probe --authorized "$WORK/plan.json")"
|
||||
check "anon-read skips without the key" \
|
||||
"$(verdict "$OUT" 'anon-read')" SKIPPED
|
||||
export GUARDRAILS_ANON_KEY="anon-test-key"
|
||||
|
||||
echo "== rate limit"
|
||||
cat > "$WORK/rl.json" <<EOF
|
||||
{"base_url": "$BASE", "rate_limit": {"path": "/rl", "count": 10}}
|
||||
EOF
|
||||
OUT="$(probe --authorized "$WORK/rl.json")"
|
||||
check "a route that starts sending 429 is CLOSED" \
|
||||
"$(verdict "$OUT" 'rate-limit')" CLOSED
|
||||
cat > "$WORK/nolimit.json" <<EOF
|
||||
{"base_url": "$BASE", "rate_limit": {"path": "/nolimit", "count": 10}}
|
||||
EOF
|
||||
OUT="$(probe --authorized "$WORK/nolimit.json")"
|
||||
check "a route with no 429 is OPEN" \
|
||||
"$(verdict "$OUT" 'rate-limit')" OPEN
|
||||
|
||||
echo "== budget caps the burst"
|
||||
cat > "$WORK/burst.json" <<EOF
|
||||
{"base_url": "$BASE", "rate_limit": {"path": "/nolimit", "count": 99}}
|
||||
EOF
|
||||
OUT="$(probe --authorized "$WORK/burst.json")"
|
||||
check "the burst is capped, never 99 requests" \
|
||||
"$(printf '%s\n' "$OUT" | grep -oE 'sent [0-9]+' | grep -oE '[0-9]+')" 25
|
||||
|
||||
echo "== usage errors"
|
||||
probe --authorized "$WORK/missing.json" >/dev/null 2>&1
|
||||
check "a missing plan exits 2" "$?" 2
|
||||
printf '{"base_url": "%s", "rate_limit": {"path": "/x", "method": "DELETE"}}\n' \
|
||||
"$BASE" > "$WORK/bad.json"
|
||||
probe --authorized "$WORK/bad.json" >/dev/null 2>&1
|
||||
check "a write method in the plan exits 2" "$?" 2
|
||||
|
||||
echo "== JSON output"
|
||||
check "json reports the open count" \
|
||||
"$(probe --authorized --json "$WORK/plan.json" \
|
||||
| python3 -B -c 'import json,sys; print(json.load(sys.stdin)["open"])')" 4
|
||||
|
||||
echo "---"
|
||||
echo "passed: $PASS failed: $FAIL"
|
||||
[ "$FAIL" -eq 0 ]
|
||||
@@ -0,0 +1,341 @@
|
||||
#!/usr/bin/env bash
|
||||
# lib/tests/guardrails-scan.test.sh — floor of the /guardrails scanner.
|
||||
# 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). Exit codes, JSON, domain filter, symlinks and secret
|
||||
# redaction are checked too.
|
||||
# shellcheck disable=SC2016
|
||||
set -u
|
||||
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
|
||||
SCAN="$ROOT/skills/guardrails/scripts/scan.py"
|
||||
GOOD="$ROOT/lib/tests/fixtures/guardrails-good"
|
||||
WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
|
||||
PASS=0; FAIL=0; LAST_OUT=""; LAST_RC=0
|
||||
|
||||
check() { # check <label> <got> <want>
|
||||
if [ "$2" = "$3" ]; then PASS=$((PASS+1)); echo " PASS $1"
|
||||
else FAIL=$((FAIL+1)); echo " FAIL $1 (got '$2', want '$3')"; fi
|
||||
}
|
||||
|
||||
scan() { python3 -B "$SCAN" "$@"; }
|
||||
|
||||
# edit <file> <sed-expr>: in-place edit without sed -i (BSD/GNU portable).
|
||||
edit() { sed "$2" "$1" > "$1.new" && mv "$1.new" "$1"; }
|
||||
|
||||
# b64 <text>: base64url without padding.
|
||||
b64() { printf '%s' "$1" | base64 | tr -d '=\n' | tr '+/' '-_'; }
|
||||
|
||||
# mutant <label> <SEVERITY> <RULE> <snippet run inside a copy of the fixture>
|
||||
has() { # has <SEVERITY> <RULE>: the last scan raised it
|
||||
printf '%s\n' "$LAST_OUT" | grep -Eq "^ +$1 +$2 " && echo yes || echo no
|
||||
}
|
||||
|
||||
# solo <label> <relative file> <content>: scan a one-file project
|
||||
solo() {
|
||||
local dir="$WORK/$1"
|
||||
mkdir -p "$dir/$(dirname "$2")"; printf '%s\n' "$3" > "$dir/$2"
|
||||
LAST_OUT=$(scan "$dir"); LAST_RC=$?
|
||||
}
|
||||
|
||||
mutant() {
|
||||
local label="$1" sev="$2" rule="$3" snippet="$4" dir
|
||||
dir="$WORK/$label"
|
||||
cp -R "$GOOD" "$dir" || { check "$label copy" failed ok; return; }
|
||||
if ! ( cd "$dir" && eval "$snippet" ) >/dev/null 2>&1; then
|
||||
check "$label setup" failed ok; return
|
||||
fi
|
||||
LAST_OUT=$(scan "$dir"); LAST_RC=$?
|
||||
check "$label raises $sev $rule" "$(has "$sev" "$rule")" yes
|
||||
}
|
||||
|
||||
SQL=supabase/migrations/0001_init.sql
|
||||
TSX=src/components/ContactForm.tsx
|
||||
NOTIFY=supabase/functions/notify/index.ts
|
||||
SMS=supabase/functions/sms/index.ts
|
||||
|
||||
echo "== clean fixture"
|
||||
out=$(scan "$GOOD"); rc=$?
|
||||
check "clean exit code" "$rc" 0
|
||||
check "clean has no FAIL or WARN" \
|
||||
"$(printf '%s\n' "$out" | grep -c ' 0 FAIL, 0 WARN')" 1
|
||||
|
||||
echo "== supabase"
|
||||
mutant rls-missing FAIL SB-RLS-MISSING \
|
||||
"edit $SQL '/alter table public.notes enable/d'"
|
||||
mutant policy-open-write FAIL SB-POLICY-OPEN-WRITE \
|
||||
"printf '%s\n' 'create policy \"o\" on public.notes for insert to authenticated with check (true);' >> $SQL"
|
||||
mutant policy-anon-write FAIL SB-POLICY-ANON-WRITE \
|
||||
"printf '%s\n' 'create policy \"a\" on public.notes for insert to anon with check (user_id is not null);' >> $SQL"
|
||||
mutant policy-not-owner WARN SB-POLICY-NOT-OWNER \
|
||||
"printf '%s\n' 'create policy \"n\" on public.notes for select to authenticated using (user_id is not null);' >> $SQL"
|
||||
mutant policy-public-read WARN SB-POLICY-PUBLIC-READ \
|
||||
"printf '%s\n' 'create policy \"p\" on public.notes for select to anon using (true);' >> $SQL"
|
||||
mutant view-invoker WARN SB-VIEW-INVOKER \
|
||||
"printf '%s\n' 'create view public.v as select 1;' >> $SQL"
|
||||
mutant matview WARN SB-MATVIEW-EXPOSED \
|
||||
"printf '%s\n' 'create materialized view public.mv as select 1;' >> $SQL"
|
||||
mutant definer-search-path WARN SB-DEFINER-SEARCH-PATH \
|
||||
"printf '%s\n' 'create function public.f1() returns int language sql security definer as \$\$ select 1 \$\$;' >> $SQL"
|
||||
mutant definer-execute WARN SB-DEFINER-EXECUTE \
|
||||
"printf '%s\n' 'create function public.f2() returns int language sql security definer set search_path = pg_catalog as \$\$ select 1 \$\$;' >> $SQL"
|
||||
mutant bucket-public WARN SB-BUCKET-PUBLIC \
|
||||
"printf '%s\n' \"insert into storage.buckets (id, name, public) values ('a', 'a', true);\" >> $SQL"
|
||||
mutant edge-no-jwt WARN SB-EDGE-NO-JWT \
|
||||
"edit supabase/config.toml 's/verify_jwt = true/verify_jwt = false/'"
|
||||
mutant service-role-client FAIL SB-SERVICE-ROLE-CLIENT \
|
||||
"printf '%s\n' 'const k = process.env.SUPABASE_SERVICE_ROLE_KEY;' > src/components/Admin.tsx"
|
||||
mutant service-role-literal FAIL SB-SERVICE-ROLE-LITERAL \
|
||||
'printf "export const k = \"%s.%s.signaturepart\";\n" "$(b64 "{\"alg\":\"HS256\"}")" "$(b64 "{\"role\":\"service_role\"}")" > src/config.ts'
|
||||
|
||||
echo "== api"
|
||||
mutant public-env FAIL API-PUBLIC-ENV-SECRET \
|
||||
"printf 'NEXT_PUBLIC_SERVICE_ROLE_KEY=\n' >> .env.example"
|
||||
mutant env-not-ignored FAIL API-ENV-NOT-IGNORED \
|
||||
"printf 'A=1\n' > .env; rm .gitignore"
|
||||
mutant secret-literal FAIL API-SECRET-LITERAL \
|
||||
'printf "const k = \"sk_live_%s\";\n" "$(printf "a%.0s" 1 2 3 4 5 6 7 8 9 10 11 12)" > src/pay.ts'
|
||||
check "secret exit code is 1" "$LAST_RC" 1
|
||||
case "$LAST_OUT" in
|
||||
*aaaaaaaaaa*) check "secret is redacted in output" leaked redacted ;;
|
||||
*) check "secret is redacted in output" redacted redacted ;;
|
||||
esac
|
||||
mutant cors-credentials FAIL API-CORS-WILDCARD \
|
||||
"printf '%s\n' 'res.setHeader(\"Access-Control-Allow-Origin\", \"*\"); const o = { credentials: true };' > src/cors.ts"
|
||||
mutant cors-wildcard WARN API-CORS-WILDCARD \
|
||||
"printf '%s\n' 'res.setHeader(\"Access-Control-Allow-Origin\", \"*\");' > src/cors.ts"
|
||||
mutant route-no-auth WARN API-ROUTE-NO-AUTH \
|
||||
"printf '%s\n' 'export function GET() { return new Response(\"hi\"); }' > src/pages/api/open.ts"
|
||||
|
||||
echo "== passwords"
|
||||
LOGIN=src/lib/login.ts
|
||||
mutant password-column FAIL API-PASSWORD-PLAINTEXT \
|
||||
"printf '%s\n' 'create table public.accounts (id uuid primary key, password text);' 'alter table public.accounts enable row level security;' >> $SQL"
|
||||
mutant password-compare FAIL API-PASSWORD-PLAINTEXT \
|
||||
"printf '%s\n' 'if (user.password === password) ok();' > $LOGIN"
|
||||
mutant password-sql-compare FAIL API-PASSWORD-PLAINTEXT \
|
||||
"printf '%s\n' 'const q = \"select 1 from accounts where email = \$1 and password = \$2\";' > $LOGIN"
|
||||
mutant password-weak-hash FAIL API-PASSWORD-WEAK-HASH \
|
||||
"printf '%s\n' 'const d = createHash(\"sha256\").update(password).digest(\"hex\");' > $LOGIN"
|
||||
mutant password-logged FAIL API-PASSWORD-LOGGED \
|
||||
"printf '%s\n' 'console.log(\"login\", email, password);' > $LOGIN"
|
||||
mutant password-logged-template FAIL API-PASSWORD-LOGGED \
|
||||
"printf '%s\n' 'logger.info(\`login \${password}\`);' > $LOGIN"
|
||||
mutant password-literal WARN API-PASSWORD-LITERAL \
|
||||
"printf '%s\n' 'export const db = { user: \"app\", password: \"hunter2hunter2\" };' > src/db.ts"
|
||||
case "$LAST_OUT" in
|
||||
*hunter2hunter2*) check "password literal is redacted" leaked redacted ;;
|
||||
*) check "password literal is redacted" redacted redacted ;;
|
||||
esac
|
||||
mutant password-literal-yaml WARN API-PASSWORD-LITERAL \
|
||||
"printf 'services:\n db:\n environment:\n POSTGRES_PASSWORD: localpass1\n' > docker-compose.yml"
|
||||
|
||||
echo "== hosting"
|
||||
mutant no-rate-limit FAIL HOST-NO-RATE-LIMIT "rm src/middleware.ts"
|
||||
mutant origin-exposed WARN HOST-ORIGIN-EXPOSED \
|
||||
"printf 'app = \"x\"\n' > fly.toml; edit docs/DEPLOY.md 's/Cloudflare/an edge proxy/'"
|
||||
|
||||
echo "== a11y"
|
||||
mutant img-alt FAIL A11Y-IMG-ALT "edit $TSX 's/ alt=\"Company logo\"//'"
|
||||
mutant field-label FAIL A11Y-FIELD-LABEL "edit $TSX '/<label htmlFor=\"email\">/d'"
|
||||
mutant click-keyboard FAIL A11Y-CLICK-NO-KEYBOARD "edit $TSX 's/ onKeyDown={go}//'"
|
||||
mutant tabindex-positive WARN A11Y-TABINDEX-POSITIVE \
|
||||
"edit $TSX 's/tabIndex={0}/tabIndex={2}/'"
|
||||
mutant focus-css-warn WARN A11Y-FOCUS-OUTLINE \
|
||||
"printf 'a:focus { outline: none; }\n' > src/styles.css"
|
||||
mutant focus-css-fail FAIL A11Y-FOCUS-OUTLINE \
|
||||
"printf 'a:focus { outline: none; }\n' > src/styles.css; edit $TSX 's/outline-none focus-visible:ring-2 focus-visible:ring-blue-500/x/'"
|
||||
mutant focus-tailwind FAIL A11Y-FOCUS-OUTLINE \
|
||||
"edit $TSX 's/outline-none focus-visible:ring-2 focus-visible:ring-blue-500/outline-none/'"
|
||||
|
||||
echo "== messaging"
|
||||
mutant no-consent FAIL MSG-NO-CONSENT-RECORD \
|
||||
"for f in $SQL $NOTIFY $SMS; do edit \$f 's/consent_at/seen_at/g;s/consent_source/seen_src/g'; done"
|
||||
mutant no-unsubscribe FAIL MSG-NO-UNSUBSCRIBE \
|
||||
"for f in $SQL $NOTIFY; do edit \$f 's/[Uu]nsubscrib[A-Za-z_-]*/gone/g'; done"
|
||||
mutant no-list-unsubscribe WARN MSG-NO-LIST-UNSUBSCRIBE \
|
||||
"edit $NOTIFY 's/List-Unsubscribe/X-Mail/g'"
|
||||
mutant sms-no-stop FAIL MSG-SMS-NO-STOP "edit $SMS 's/ Reply STOP to opt out\.//'"
|
||||
mutant sms-no-optout-store FAIL MSG-SMS-NO-OPTOUT-STORE \
|
||||
"for f in $SQL $SMS $NOTIFY; do edit \$f 's/opt_out_at/x_at/g;s/unsubscribed_at/y_at/g'; done"
|
||||
mutant send-unchecked WARN MSG-SEND-UNCHECKED \
|
||||
"printf '%s\n' 'import nodemailer from \"nodemailer\";' 'export const t = nodemailer.createTransport({});' > src/mailer.ts"
|
||||
|
||||
echo "== functions"
|
||||
mutant no-max-instances FAIL FN-NO-MAX-INSTANCES \
|
||||
"edit functions/index.js 's/maxInstances: 10//'"
|
||||
mutant self-trigger FAIL FN-SELF-TRIGGER \
|
||||
"printf '%s\n' 'await db.from(\"notes\").update({ sent: true });' >> $NOTIFY"
|
||||
mutant self-trigger-guarded WARN FN-SELF-TRIGGER \
|
||||
"printf '%s\n' 'await db.from(\"notes\").update({ sent: true });' >> $NOTIFY; edit $SQL 's/for each row execute/for each row when (new.body is not null) execute/'"
|
||||
mutant self-invoke FAIL FN-SELF-INVOKE \
|
||||
"printf '%s\n' 'await fetch(\"https://x.supabase.co/functions/v1/notify\");' >> $NOTIFY"
|
||||
mutant firebase-loop WARN FN-SELF-TRIGGER \
|
||||
"printf '%s\n' 'exports.again = async () => { await db.collection(\"orders\").add({}); };' >> functions/index.js"
|
||||
|
||||
mutant key-body FAIL API-SECRET-LITERAL \
|
||||
'printf -- "-----BEGIN %s KEY-----\n%s\n" PRIVATE "$(head -c 40 /dev/zero | tr "\0" A)" > src/key.ts'
|
||||
|
||||
echo "== benign patterns stay silent"
|
||||
benign() { # benign <label> <snippet>: a legitimate pattern raises nothing
|
||||
local label="$1" snippet="$2" dir="$WORK/$1"
|
||||
cp -R "$GOOD" "$dir" || { check "$label copy" failed ok; return; }
|
||||
if ! ( cd "$dir" && eval "$snippet" ) >/dev/null 2>&1; then
|
||||
check "$label setup" failed ok; return
|
||||
fi
|
||||
out=$(scan "$dir")
|
||||
check "$label raises no FAIL or WARN" \
|
||||
"$(printf '%s\n' "$out" | grep -c ' 0 FAIL, 0 WARN')" 1
|
||||
}
|
||||
benign comment-with-img-tag \
|
||||
"printf '%s\n' '// the <img> below is decorative' >> $TSX"
|
||||
benign dialog-overlay-click \
|
||||
"printf '%s\n' '<div role=\"dialog\" aria-label=\"x\" onClick={go}>y</div>' >> $TSX"
|
||||
benign helper-under-api \
|
||||
"mkdir -p src/pages/api/helpers; printf '%s\n' 'export const fmt = () => 1;' > src/pages/api/helpers/format.ts"
|
||||
benign mailer-test-file \
|
||||
"mkdir -p tests; printf '%s\n' 'import nodemailer from \"nodemailer\";' > tests/mailer.test.ts"
|
||||
benign log-file-skipped \
|
||||
'printf "key sk_live_%s\n" "$(printf "a%.0s" 1 2 3 4 5 6 7 8 9 10 11 12)" > app.log'
|
||||
benign proxy-change-origin \
|
||||
"printf '%s\n' 'export default { server: { proxy: { a: { changeOrigin: true } } } };' > vite.config.ts"
|
||||
benign cli-script-under-api \
|
||||
"mkdir -p src/pages/api/bin; printf '%s\n' 'export const run = () => 1;' > src/pages/api/bin/cleanup.ts"
|
||||
benign key-header-only-in-test \
|
||||
"mkdir -p tests; printf '%s\n' \"assert(kinds('-----BEGIN OPENSSH PRIVATE KEY-----'));\" > tests/secrets.test.ts"
|
||||
benign transactional-mailer \
|
||||
"mkdir -p src/lib; printf '%s\n' 'import nodemailer from \"nodemailer\";' 'export const t = nodemailer.createTransport({});' > src/lib/contact-mail.ts"
|
||||
benign supabase-auth-password \
|
||||
"printf '%s\n' 'await sb.auth.updateUser({ password: newPassword });' > src/lib/account.ts"
|
||||
benign password-confirm-compare \
|
||||
"printf '%s\n' 'const same = v.password === v.passwordConfirm;' > src/lib/validate.ts"
|
||||
benign hashed-column \
|
||||
"printf '%s\n' 'create table public.accounts (id uuid primary key, password_hash text);' 'alter table public.accounts enable row level security;' >> $SQL"
|
||||
benign column-with-bcrypt \
|
||||
"printf '%s\n' 'create table public.accounts (id uuid primary key, password text);' 'alter table public.accounts enable row level security;' >> $SQL; printf '%s\n' 'import bcrypt from \"bcrypt\";' > src/lib/hash.ts"
|
||||
benign password-literal-in-test \
|
||||
"mkdir -p tests; printf '%s\n' 'const PASSWORD = \"LocalDev-only-password-1\";' > tests/login.e2e.ts"
|
||||
benign password-placeholder \
|
||||
"printf '%s\n' 'export const db = { password: \"CHANGE_ME_NOW\" };' > src/db.ts"
|
||||
benign password-validation-rule \
|
||||
"printf '%s\n' 'const rules = { password: \"required|min:8\" };' > src/rules.ts"
|
||||
benign reset-token-sha256 \
|
||||
"printf '%s\n' 'const d = createHash(\"sha256\").update(passwordResetToken).digest(\"hex\");' > src/lib/reset.ts"
|
||||
benign log-with-password-label \
|
||||
"printf '%s\n' 'console.log(\"password reset sent to\", email);' > src/lib/reset.ts"
|
||||
benign i18n-password-label \
|
||||
"mkdir -p src/i18n; printf '%s\n' 'export const de = { password: \"Passwort\" };' > src/i18n/de.ts"
|
||||
ENVKEY='printf "SUPABASE_SERVICE_ROLE_KEY=%s.%s.signaturepart\n" "$(b64 "{\"alg\":\"HS256\"}")" "$(b64 "{\"role\":\"service_role\"}")" > .env.worker'
|
||||
benign env-worker-ignored "printf '.env.*\n' >> .gitignore; $ENVKEY"
|
||||
mutant env-worker-tracked FAIL SB-SERVICE-ROLE-LITERAL "$ENVKEY"
|
||||
|
||||
echo "== transactional versus marketing senders"
|
||||
solo tx-only src/contact.ts 'import nodemailer from "nodemailer";'
|
||||
check "transactional-only mail exits 0" "$LAST_RC" 0
|
||||
check "transactional-only mail warns on consent" \
|
||||
"$(has WARN MSG-NO-CONSENT-RECORD)" yes
|
||||
solo marketing-only src/newsletter.ts 'import nodemailer from "nodemailer";'
|
||||
check "newsletter mail fails on consent" \
|
||||
"$(has FAIL MSG-NO-CONSENT-RECORD)" yes
|
||||
|
||||
mkdir -p "$WORK/tx-helper/src"
|
||||
for f in contact mailer; do
|
||||
printf '%s\n' 'import nodemailer from "nodemailer";' \
|
||||
'const recipient = "owner@example.com";' > "$WORK/tx-helper/src/$f.ts"
|
||||
done
|
||||
LAST_OUT=$(scan "$WORK/tx-helper"); LAST_RC=$?
|
||||
check "contact form plus shared mailer warns" \
|
||||
"$(has WARN MSG-NO-CONSENT-RECORD)" yes
|
||||
check "contact form plus shared mailer exits 0" "$LAST_RC" 0
|
||||
cp -R "$WORK/tx-helper" "$WORK/tx-bulk"
|
||||
printf '%s\n' 'create table subscribers (id int);' > "$WORK/tx-bulk/schema.sql"
|
||||
LAST_OUT=$(scan "$WORK/tx-bulk")
|
||||
check "a subscribers table makes the same senders fail" \
|
||||
"$(has FAIL MSG-NO-CONSENT-RECORD)" yes
|
||||
|
||||
echo "== check modes (contract oracle and re-pass baseline)"
|
||||
IMG="A11Y-IMG-ALT:$TSX"
|
||||
cp -R "$GOOD" "$WORK/cm"; edit "$WORK/cm/$TSX" 's/ alt="Company logo"//'
|
||||
out=$(scan "$WORK/cm" --assert-absent "$IMG"); rc=$?
|
||||
check "positive control: the oracle fails while the hit is there" "$rc" 1
|
||||
check "a failing oracle never prints the marker" \
|
||||
"$(printf '%s\n' "$out" | grep -c GUARDRAILS-CLEAR)" 0
|
||||
out=$(scan "$GOOD" --assert-absent "$IMG"); rc=$?
|
||||
check "the oracle passes once the hit is gone" "$rc" 0
|
||||
check "a passing oracle prints the marker" \
|
||||
"$(printf '%s\n' "$out" | grep -c '^GUARDRAILS-CLEAR 1$')" 1
|
||||
out=$(scan "$GOOD" --domain api --assert-absent "$IMG"); rc=$?
|
||||
check "an unscanned domain proves nothing" "$rc" 1
|
||||
check "the control failure is named" \
|
||||
"$(printf '%s\n' "$out" | grep -c '^ CONTROL ')" 1
|
||||
mkdir "$WORK/cm-empty"
|
||||
scan "$WORK/cm-empty" --assert-absent "$IMG" >/dev/null
|
||||
check "an empty tree proves nothing" "$?" 1
|
||||
scan "$GOOD" --assert-absent HOST-SPEND-CAP:. >/dev/null 2>&1
|
||||
check "a MANUAL rule cannot be asserted (exit 2)" "$?" 2
|
||||
scan "$GOOD" --assert-absent A11Y-IMG-ALT >/dev/null 2>&1
|
||||
check "an item without a path is a usage error" "$?" 2
|
||||
scan "$WORK/cm" --json > "$WORK/cm-before.json"
|
||||
out=$(scan "$GOOD" --baseline "$WORK/cm-before.json"); rc=$?
|
||||
check "baseline lists the fixed hit" \
|
||||
"$(printf '%s\n' "$out" | grep -c '^ FIXED A11Y-IMG-ALT ')" 1
|
||||
check "baseline with no new hit exits 0 with the marker" \
|
||||
"$rc:$(printf '%s\n' "$out" | grep -c '^GUARDRAILS-NO-NEW$')" "0:1"
|
||||
scan "$GOOD" --json > "$WORK/clean-before.json"
|
||||
out=$(scan "$WORK/cm" --baseline "$WORK/clean-before.json"); rc=$?
|
||||
check "baseline lists a new hit" \
|
||||
"$(printf '%s\n' "$out" | grep -c '^ NEW A11Y-IMG-ALT ')" 1
|
||||
check "baseline with a new hit exits 1 without the marker" \
|
||||
"$rc:$(printf '%s\n' "$out" | grep -c GUARDRAILS-NO-NEW)" "1:0"
|
||||
printf 'not json' > "$WORK/bad.json"
|
||||
scan "$GOOD" --baseline "$WORK/bad.json" >/dev/null 2>&1
|
||||
check "an unreadable baseline exits 2" "$?" 2
|
||||
|
||||
# contract <dir> <file>: a fix contract whose oracle is the scanner itself
|
||||
contract() {
|
||||
cat > "$2" <<EOF
|
||||
# CONTRACT — guardrails-oracle-test
|
||||
## ACCEPTANCE CRITERIA
|
||||
1. every image in the contact form has an alt
|
||||
CHECK: python3 -B '$SCAN' '$1' --assert-absent '$IMG'
|
||||
EXPECT: GUARDRAILS-CLEAR
|
||||
EVIDENCE: pending
|
||||
## FILE SCOPE
|
||||
$TSX
|
||||
EOF
|
||||
}
|
||||
contract "$WORK/cm" "$WORK/c-unfixed.md"
|
||||
bash "$ROOT/lib/gates.sh" run "$WORK/c-unfixed.md" >/dev/null 2>&1
|
||||
check "gates.sh: the oracle is UNMET before the fix" "$?" 2
|
||||
contract "$GOOD" "$WORK/c-fixed.md"
|
||||
bash "$ROOT/lib/gates.sh" run "$WORK/c-fixed.md" >/dev/null 2>&1
|
||||
check "gates.sh: the oracle is MET after the fix" "$?" 0
|
||||
check "gates.sh writes the evidence back" \
|
||||
"$(grep -c 'EVIDENCE: pending' "$WORK/c-fixed.md")" 0
|
||||
|
||||
echo "== cli"
|
||||
scan "$WORK/does-not-exist" >/dev/null 2>&1; check "bad path exits 2" "$?" 2
|
||||
scan --domain nope "$GOOD" >/dev/null 2>&1; check "bad domain exits 2" "$?" 2
|
||||
check "json is valid and counts FAIL" \
|
||||
"$(scan --json "$GOOD" | python3 -B -c 'import json,sys; print(json.load(sys.stdin)["summary"]["FAIL"])')" 0
|
||||
out=$(scan --domain a11y "$GOOD")
|
||||
check "domain filter keeps a11y" \
|
||||
"$(printf '%s\n' "$out" | grep -c '^\[a11y\]')" 1
|
||||
check "domain filter drops supabase" \
|
||||
"$(printf '%s\n' "$out" | grep -c '^\[supabase\]')" 0
|
||||
cp -R "$GOOD" "$WORK/excl"
|
||||
edit "$WORK/excl/$TSX" 's/ alt="Company logo"//'
|
||||
scan "$WORK/excl" >/dev/null 2>&1; check "mutated copy fails" "$?" 1
|
||||
scan --exclude src/components "$WORK/excl" >/dev/null 2>&1
|
||||
check "--exclude drops the finding" "$?" 0
|
||||
mkdir "$WORK/empty"
|
||||
out=$(scan "$WORK/empty")
|
||||
check "empty project marks hosting not applicable" \
|
||||
"$(printf '%s\n' "$out" | grep -c 'not applicable: hosting')" 1
|
||||
mkdir "$WORK/linked"; ln -s "$GOOD" "$WORK/linked/escape"
|
||||
out=$(scan "$WORK/linked")
|
||||
check "symlinked directory is not followed" \
|
||||
"$(printf '%s\n' "$out" | grep -c '(0 files)')" 1
|
||||
|
||||
echo "---"
|
||||
echo "passed: $PASS failed: $FAIL"
|
||||
[ "$FAIL" -eq 0 ]
|
||||
@@ -14,6 +14,7 @@ BUG="$REPO/agents/bugfixer.md"
|
||||
BSK="$REPO/skills/bugfix/SKILL.md"
|
||||
HOT="$REPO/agents/hotfixer.md"
|
||||
HSK="$REPO/skills/hotfix/SKILL.md"
|
||||
GSK="$REPO/skills/guardrails/SKILL.md"
|
||||
HSKL="$REPO/skills/hotfix/SKILL.md"
|
||||
PASS=0; FAIL=0
|
||||
|
||||
@@ -69,6 +70,15 @@ tf "bug uses shared include" "$BSK" "lib/verify-secure-loop.md"
|
||||
tf "bug gate0 floor" "$BSK" "GATE 0 — deterministic floor"
|
||||
tf "bug dispatches bugfixer" "$BSK" 'subagent_type="bugfixer"'
|
||||
|
||||
echo "── skills/guardrails/SKILL.md (fix loop reuses the bugfix circuit) ──"
|
||||
tf "guardrails contract include" "$GSK" "lib/contract-interview.md"
|
||||
tf "guardrails uses shared include" "$GSK" "lib/verify-secure-loop.md"
|
||||
tf "guardrails dispatches bugfixer" "$GSK" 'subagent_type="bugfixer"'
|
||||
tf "guardrails scanner is the oracle" "$GSK" "EXPECT: GUARDRAILS-CLEAR"
|
||||
tf "guardrails positive control" "$GSK" "Positive control"
|
||||
tf "guardrails approval gate" "$GSK" "Nothing is applied without the user's explicit acceptance"
|
||||
tf "guardrails re-pass baseline" "$GSK" "GUARDRAILS-NO-NEW"
|
||||
|
||||
echo "── agents/bugfixer.md (bugfix executor — sonnet, no Agent) ──"
|
||||
tn "bugfixer lacks Agent tool" "$BUG" "Agent"
|
||||
tf "bugfixer model sonnet" "$BUG" "model: sonnet"
|
||||
|
||||
@@ -9,8 +9,8 @@ has() { if grep -qF "$2" "$R/$1"; then ok; else ko "$1 missing: $2"; fi; }
|
||||
lacks() { if grep -qF "$2" "$R/$1"; then ko "$1 must NOT contain: $2"; else ok; fi; }
|
||||
fm_lacks() { if awk 'NR<=10' "$R/$1" | grep -qF "$2"; then ko "$1 frontmatter must NOT contain: $2"; else ok; fi; }
|
||||
|
||||
# 1) gate wired in the 15 reflection skills (orchestrators + /analyze)
|
||||
for s in ship-feature init-project feat bugfix onboard seo geo web-validate harden audit-delta tour code-clean hotfix client-handover analyze; do
|
||||
# 1) gate wired in the 16 reflection skills (orchestrators, /analyze, /guardrails)
|
||||
for s in ship-feature init-project feat bugfix onboard seo geo web-validate harden audit-delta tour code-clean hotfix client-handover analyze guardrails; do
|
||||
has "skills/$s/SKILL.md" 'lib/model-gate.md'
|
||||
done
|
||||
# 2) gate NOT wired in the pure-execution/read-only skills (exclusion list)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Verify + secure loop — shared orchestrator include (feat, bugfix)
|
||||
# Verify + secure loop — shared orchestrator include (feat, bugfix, guardrails)
|
||||
|
||||
Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes. Turns a
|
||||
finished diff into a verified, security-cleared change through two fresh
|
||||
|
||||
@@ -74,6 +74,7 @@
|
||||
"bugfix": "reflect",
|
||||
"refactor": "reflect",
|
||||
"explain-diff": "reflect",
|
||||
"guardrails": "reflect",
|
||||
"web-validate": "reflect",
|
||||
"harden": "reflect",
|
||||
"seo": "reflect",
|
||||
@@ -155,7 +156,8 @@
|
||||
"commit-changer": "write",
|
||||
"bugfixer": "implement",
|
||||
"plugin-probe": "apply",
|
||||
"plugin-advisor": "judge"
|
||||
"plugin-advisor": "judge",
|
||||
"Explore": "explore"
|
||||
},
|
||||
"phases": {
|
||||
"verify": "verify",
|
||||
@@ -166,7 +168,8 @@
|
||||
"judge": "judge",
|
||||
"reflect": "reflect",
|
||||
"plan": "plan",
|
||||
"apply": "apply"
|
||||
"apply": "apply",
|
||||
"explore": "explore"
|
||||
},
|
||||
"skills": {
|
||||
"gitflow": "implement",
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
# Secure by default: five domains and every API
|
||||
|
||||
Scope: any project that has a public surface, an API, a database, messaging,
|
||||
a cloud function or a UI. Applies at design, scaffolding, implementation and
|
||||
review. A request that breaks one of these gets flagged, not silently done.
|
||||
What only a provider dashboard can set (spend cap, WAF, budget alert) is
|
||||
never claimed done: write it as a manual step in the project's deploy notes.
|
||||
`/guardrails` audits all of it and fixes what the user accepts.
|
||||
|
||||
## Every API and every access
|
||||
- Default deny. Authentication and authorization checked server-side on every
|
||||
route, function, RPC and webhook, never only at the entry point.
|
||||
- Webhooks verify a signature. CORS is an allowlist, never `*` with credentials.
|
||||
- Keys are least privilege and server-side. Responses carry only needed fields.
|
||||
- Validate every input at the boundary. Rate limit every unauthenticated or
|
||||
costly route.
|
||||
- Passwords hashed with argon2id (bcrypt or scrypt otherwise), never stored
|
||||
or compared in clear, never logged, never a literal in code or config.
|
||||
Delegated auth (Supabase, Firebase, Clerk) keeps them out of your tables.
|
||||
Reset tokens hashed, single-use, expiring.
|
||||
|
||||
## 1. Hosting
|
||||
- Rate limit per IP and per account on login, signup, reset, send and upload.
|
||||
- CDN and firewall (WAF, DDoS protection) in front of the origin.
|
||||
- Hard spend cap if the host offers one. Otherwise a budget alert plus a
|
||||
written kill-switch step.
|
||||
|
||||
## 2. Accessibility
|
||||
- Everything reachable and usable by keyboard, focus always visible.
|
||||
`:focus-visible` styled, never `outline: none` without a replacement.
|
||||
- Every image has an `alt` (empty when decorative). Every field has a label;
|
||||
a placeholder is not a label.
|
||||
|
||||
## 3. Supabase
|
||||
- RLS enabled on every table, in the migration that creates it.
|
||||
- Policies limited to the owner: `(select auth.uid())` per operation, role
|
||||
`authenticated`. No `using (true)` on writes, no anon write.
|
||||
- No `service_role` or secret key client-side: not in a bundle, not in a
|
||||
`NEXT_PUBLIC_`, `VITE_` or `PUBLIC_` variable.
|
||||
- Views `security_invoker`. `security definer` functions pin `search_path`
|
||||
and revoke execute from anon. Buckets private by default.
|
||||
|
||||
## 4. SMS and email
|
||||
- Prior consent recorded per contact: who, when, channel, source, wording.
|
||||
No send without a consent row; check the suppression list before each send.
|
||||
- Every email has an unsubscribe link and `List-Unsubscribe`. Every marketing
|
||||
SMS says STOP, and a STOP reply is processed and stored automatically.
|
||||
|
||||
## 5. Cloud functions
|
||||
- No function re-triggers itself: never write to the resource that fires it,
|
||||
never invoke itself. If unavoidable, guard with an idempotency flag.
|
||||
- Max instances (or reserved concurrency) and a timeout on every function.
|
||||
- Budget alert wired to an automatic stop beyond the budget.
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
name: guardrails
|
||||
effort: high
|
||||
description: 'Use when auditing a project against the baseline guardrails and fixing what fails: hosting (rate limit, CDN and firewall, spend cap), accessibility (keyboard, visible focus, alt text, field labels), Supabase (RLS on every table, owner-scoped policies, no service_role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), plus API and access hygiene (auth on every route, CORS, secrets, password storage). Runs a deterministic scanner, judges each hit, writes .claude/audits/GUARDRAILS.md, then proposes fixes, applies only the ones the user accepts (bugfixer executor, fresh verifier and security gates) and re-scans to prove each one fixed. Optional read-only live probe confirms a hole from outside on a target the user owns and names. Triggers: "guardrails", "garde-fous", "RLS activée ?", "audit supabase", "consentement sms", "plafond de dépense", "mots de passe en clair ?", "teste la sécurité de base du projet", "corrige les garde-fous", "teste-le en conditions réelles", "sonde le projet en direct". Headers and TLS → /harden; secrets, CVE, OWASP → /cso; full WCAG → /web-validate.'
|
||||
argument-hint: '[project path] [--domain api,hosting,a11y,supabase,messaging,functions] [--exclude paths] [--live <url you own>] [--report-only]'
|
||||
---
|
||||
|
||||
# /guardrails
|
||||
|
||||
Checks a project against `rules/secure-by-default.md`, then fixes what the
|
||||
user accepts and proves each fix. A scanner reads the tree as data and finds
|
||||
what text can prove. This skill judges the hits, covers what text cannot
|
||||
prove, lists what only a dashboard can set and, on request, probes a running
|
||||
target the user owns. It then proposes fixes, applies the accepted ones and
|
||||
runs the scan again until every accepted fix is proven.
|
||||
|
||||
The scanner proves absence of a protection, never presence of security. A
|
||||
clean scan means "no static finding", and the report says exactly that. A
|
||||
live probe proves the opposite direction: that a door is actually open.
|
||||
|
||||
## MODEL GATE (blocking, before any other step)
|
||||
|
||||
Run `$HOME/.claude/lib/model-gate.md`. Judging hits and designing fixes
|
||||
requires Fable or Opus. Verdict `small` → STOP: the gate prints the remedy.
|
||||
ROUTING: follow `$HOME/.claude/lib/effort-shift.md` (phases via
|
||||
`mcp__model-router__route`); each step below names its phase.
|
||||
|
||||
## STEP 1: Scope
|
||||
|
||||
Work in the project the user names, else the current directory. Say in one
|
||||
line what you will scan. Domains: `api`, `hosting`, `a11y`, `supabase`,
|
||||
`messaging`, `functions`. The scanner skips the ones that do not apply.
|
||||
`--report-only` stops after STEP 7: audit, no fix.
|
||||
|
||||
## STEP 2: Run the scanner
|
||||
|
||||
```
|
||||
python3 -B "$HOME/.claude/skills/guardrails/scripts/scan.py" <path>
|
||||
```
|
||||
|
||||
Add `--domain a,b` to narrow, `--exclude a/b,c` to skip copies or
|
||||
vendored code, `--json` for machine output. Exit 0 means no
|
||||
FAIL, 1 means at least one, 2 is a usage error. It never executes project
|
||||
code. Severities:
|
||||
|
||||
- **FAIL**: a protection is provably absent or a key is exposed.
|
||||
- **WARN**: a pattern that is often wrong; judgment needed.
|
||||
- **MANUAL**: only a provider dashboard can set or show it.
|
||||
|
||||
## STEP 3: Judge every FAIL and WARN
|
||||
|
||||
Read the file around each line. Label it CONFIRMED, FALSE POSITIVE (say why)
|
||||
or ACCEPTED RISK (the user decides, never you). A key sitting in a
|
||||
git-ignored env file is not reported, that is where local keys belong; whether
|
||||
it ever reached git history is a separate check (`gitleaks git <repo>`).
|
||||
Heuristic blind spots are in `references/checks.md`: check them before
|
||||
calling a hit false.
|
||||
|
||||
## STEP 4: Cover what the scanner cannot
|
||||
|
||||
Read the code for the domains that apply and answer, with file:line evidence:
|
||||
|
||||
- **API**: does each route check authorization on the object, not only
|
||||
authentication? Is any id in a URL usable to read another user's data?
|
||||
Where is a password written? Trace sign-up and password change to the
|
||||
column: an argon2id, bcrypt or scrypt hash is what must land there.
|
||||
- **Supabase**: does each policy name the right owner column, per operation?
|
||||
Is every table created in the dashboard also covered? Give the user the live
|
||||
queries from the reference file.
|
||||
- **Messaging**: does consent get written at the sign-up point with source and
|
||||
wording? Is a STOP reply wired from the provider webhook to the store?
|
||||
- **Functions**: trace every trigger to the resource it writes, including
|
||||
queues, storage events, schedulers and third-party webhooks.
|
||||
- **A11y**: with a dev server running, walk the main flow with Tab only
|
||||
(`/browse`). Otherwise mark the keyboard walk-through as not done.
|
||||
|
||||
## STEP 5: Live probe (only on `--live`, read-only)
|
||||
|
||||
The static scan shows a protection is missing in the code. A probe shows the
|
||||
door is actually open. Run it only when the user asks, and only against a
|
||||
target the user owns and names: their local dev server first, a staging or
|
||||
production URL only on an explicit, specific go. Never a URL you inferred,
|
||||
never a third party.
|
||||
|
||||
1. **Build the plan** `references/checks.md` describes. From the static
|
||||
findings fill a JSON plan: `base_url`, the Supabase `url` and `tables`,
|
||||
the `routes` (mark the ones meant to be public), `cors`, and a
|
||||
`rate_limit` route if the user wants that one burst. Secrets never go in
|
||||
the plan or the command line: export `GUARDRAILS_ANON_KEY` and, for the
|
||||
cross-user probe, `GUARDRAILS_JWT2`, from test keys, never `service_role`.
|
||||
2. **Run it**, confirming ownership with `--authorized`:
|
||||
```
|
||||
python3 -B "$HOME/.claude/skills/guardrails/scripts/probe.py" \
|
||||
plan.json --authorized
|
||||
```
|
||||
It sends GET, HEAD and OPTIONS only (the rate-limit burst is the one
|
||||
POST, opt-in in the plan, capped at 25 requests). It never writes data,
|
||||
never follows a redirect to another host, and stops at a request budget.
|
||||
Exit 1 means at least one OPEN verdict. Keep the plan file: STEP 11
|
||||
replays it.
|
||||
3. **Cross the verdicts with the static findings.** A verdict is an
|
||||
observation, not a conclusion: OPEN means the request returned data or a
|
||||
200, CLOSED means it was refused or empty. A static FAIL confirmed OPEN in
|
||||
the probe leads the report. A CLOSED probe on a static FAIL still needs the
|
||||
fix: the dev target may differ from production.
|
||||
4. **Guardrails on the probe itself**: read-only, test keys only, the
|
||||
loopback or a URL the user named. A login burst can lock the user's own
|
||||
account, so run it only with a throwaway test account and the user's go.
|
||||
Never fuzz, never POST to anything but a named login route, never probe a
|
||||
target you were not told to. That is pentest territory, another contract.
|
||||
|
||||
## STEP 6: Manual checklist
|
||||
|
||||
Print each MANUAL item as a step the user performs: spend cap, WAF and DDoS
|
||||
rules, budget alert wired to a stop, live RLS queries. Provider limits change:
|
||||
name the setting, tell the user to confirm it in the current provider docs.
|
||||
Never run a live probe against production without the user's explicit go, and
|
||||
never claim a MANUAL item done.
|
||||
|
||||
## STEP 7: Report
|
||||
|
||||
Write `.claude/audits/GUARDRAILS.md`: one table per domain with status PASS,
|
||||
FAIL, WARN, MANUAL or N/A, the evidence, and the fix in one line. PASS means
|
||||
"no static finding". When a live probe ran, add a line for its verdict next
|
||||
to the matching static finding. Keep it short; no filler sections.
|
||||
`--report-only`, or nothing CONFIRMED and no OPEN verdict: reply with counts,
|
||||
the FAILs with file:line, any OPEN verdict and the MANUAL items, then stop.
|
||||
|
||||
## STEP 8: Propose fixes
|
||||
|
||||
`mcp__model-router__route(phase="plan")`: designing a fix is the deepest
|
||||
thinking in this run, it goes to the plan row.
|
||||
|
||||
One proposal per CONFIRMED finding, grouped by rule and file; merge pairs
|
||||
that one change closes (one middleware closes HOST-NO-RATE-LIMIT for every
|
||||
route). FALSE POSITIVE and ACCEPTED RISK get no proposal. Each proposal:
|
||||
|
||||
- **number, rule, file(s)**, and the problem in one line;
|
||||
- **the fix**, concrete: file:line and the change, the SQL for a migration,
|
||||
the label text for a field. Root cause, never a mask: a missing RLS gets
|
||||
owner policies in the same migration, not a disabled check;
|
||||
- **choices the user sees** (label wording, CORS origins, owner column,
|
||||
rate-limit numbers), each with your proposed value, named so the user can
|
||||
change it;
|
||||
- **risk**: what it can break. `BREAKING` when it changes a contract a client
|
||||
relies on (RLS without policies blocks the app, a CORS allowlist drops an
|
||||
origin, a new required header). `DECISION` when no default is defensible
|
||||
(consent model, retention period): the user picks before it can apply;
|
||||
- **proof**: the scanner pairs that must disappear (`RULE:path`), the probe
|
||||
that must turn CLOSED, and a project test when one fits naturally.
|
||||
|
||||
MANUAL items stay user steps (STEP 6), never proposals. A live OPEN verdict
|
||||
with no static finding gets a proposal whose proof is the probe alone.
|
||||
|
||||
Save the proposals to `.claude/tasks/plans/<YYYY-MM-DD>-guardrails-<HHMM>.md`
|
||||
and append them to the report. In the reply, show them as a numbered list,
|
||||
one or two lines each, BREAKING and DECISION marked.
|
||||
|
||||
## STEP 9: Approval (gate, ends the turn)
|
||||
|
||||
Nothing is applied without the user's explicit acceptance. Ask once, then
|
||||
stop the turn:
|
||||
|
||||
```
|
||||
Which fixes do I apply? "all" (every proposal except DECISION ones),
|
||||
numbers ("1,3,5-7"), "none", or an amendment ("2 with the label 'Email'").
|
||||
A DECISION proposal needs its number plus your choice.
|
||||
```
|
||||
|
||||
On resume, `mcp__model-router__route(phase="reflect")`. "none" → stop,
|
||||
proposals stay in the report. An amendment rewrites that proposal in the plan
|
||||
file before anything else. Accepted set empty → stop.
|
||||
|
||||
## STEP 10: Apply
|
||||
|
||||
1. **Branch.** Not a git repository → stop: fixes need a diff to review.
|
||||
On `main`/`develop`, `bash ~/.claude/lib/gitflow.sh start bugfix
|
||||
guardrails-<YYYY-MM-DD>`; on a working branch, stay. Never `finish`.
|
||||
2. **Baseline**, before any edit:
|
||||
`python3 -B <scan.py> <root> --json > .claude/audits/.guardrails-baseline.json`.
|
||||
A derived file: never staged, never committed.
|
||||
3. **Contract** per `$HOME/.claude/lib/contract-interview.md` (STEP 4
|
||||
template, `flow: guardrails`). REQUEST = the user's acceptance verbatim
|
||||
plus the accepted proposals. One criterion per accepted proposal, its
|
||||
oracle the scanner itself:
|
||||
```
|
||||
1. <proposal 1 in one line>
|
||||
CHECK: python3 -B "$HOME/.claude/skills/guardrails/scripts/scan.py" '<abs root>' --assert-absent 'RULE:path,RULE:path'
|
||||
EXPECT: GUARDRAILS-CLEAR
|
||||
EVIDENCE: pending
|
||||
```
|
||||
Add one criterion for the project suite when one exists
|
||||
(`CHECK: <test command> && echo TESTS-GREEN`, `EXPECT: TESTS-GREEN`). A
|
||||
proof the scanner cannot run (probe, cross-user, manual SQL) is a
|
||||
criterion without CHECK: STEP 11 settles it. FILE SCOPE = the files the
|
||||
accepted proposals name. Paths go in single quotes; a path holding a
|
||||
single quote is named to the user, never written into a CHECK.
|
||||
4. **Positive control.** Run each oracle once on the unfixed tree: it must
|
||||
fail. An oracle that passes before the fix proves nothing; drop it, find
|
||||
why, and say so.
|
||||
5. **Dispatch the executor**, one fresh `bugfixer` for the accepted set
|
||||
(batches of 8 proposals at most, one after the other on the same branch):
|
||||
```
|
||||
mcp__model-router__route(phase="orchestrate") # send with the Agent call
|
||||
Agent(subagent_type="bugfixer")
|
||||
prompt: "CONTRACT: <path>
|
||||
DIAGNOSIS: <each accepted finding: rule, file:line, evidence, root cause>
|
||||
FIX PLAN: <the accepted proposals verbatim, with the user's choices; the
|
||||
regression check of each is its contract oracle, plus the project test
|
||||
the proposal names>
|
||||
BRANCH: <current branch>
|
||||
Apply to the letter. No commit, no branch ops, no security dispatch.
|
||||
Finish with the BUGFIX-EXEC REPORT."
|
||||
```
|
||||
`NEED-DECISION` routes per MID-RUN CLARIFICATION of the contract include:
|
||||
a visible, public-name or scope question goes to the user verbatim.
|
||||
`BLOCKED` → surface it, stop.
|
||||
6. **Gates** per `$HOME/.claude/lib/verify-secure-loop.md`, `CONTRACT` the
|
||||
path above, `DIFF` the executor's working-tree diff, `TEST` the suite.
|
||||
GATE 0 runs every scanner oracle (the per-fix proof), GATE 1 a fresh
|
||||
verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are
|
||||
the include's; loop decisions stay in this main loop.
|
||||
|
||||
## STEP 11: Re-pass (prove it all)
|
||||
|
||||
`mcp__model-router__route(phase="reflect")`. The gates proved each accepted
|
||||
fix on its own; this pass proves the whole tree.
|
||||
|
||||
1. Full scan against the baseline:
|
||||
```
|
||||
python3 -B <scan.py> <root> --baseline .claude/audits/.guardrails-baseline.json
|
||||
```
|
||||
Every accepted pair must show `FIXED`, and the run must end on
|
||||
`GUARDRAILS-NO-NEW` (exit 0). A `NEW` hit is a regression the fix made.
|
||||
2. Live: when STEP 5 ran, replay the same plan on the same target once the
|
||||
user has reloaded or redeployed it and says go. A fix in code is not live
|
||||
until it runs. Each fixed proposal's probe must now read CLOSED.
|
||||
3. Settle the criteria without CHECK, by reading or by the user's answer for
|
||||
a manual step.
|
||||
4. Add an "after" column to `.claude/audits/GUARDRAILS.md`: proposal,
|
||||
before, after, evidence.
|
||||
|
||||
Anything not fixed, or a NEW hit → one more round from STEP 8, limited to
|
||||
those items. Two rounds at most: after the second, stop with the residuals
|
||||
open and say so plainly. Never report a fix the re-pass did not prove.
|
||||
|
||||
## STEP 12: Commit and hand over
|
||||
|
||||
1. **Commit gate.** Show files, `git diff --stat` and the message, wait for
|
||||
the user's go:
|
||||
```
|
||||
GUARDRAILS: READY TO COMMIT
|
||||
FILES : <list>
|
||||
MESSAGE : fix(security): <rules fixed, one line>
|
||||
```
|
||||
Then `git add <files touched>` (never `-A`, never the baseline file) and
|
||||
commit, project convention else 50 words at most.
|
||||
2. `mcp__model-router__route(phase="apply")` for the tail. Reply with: fixed
|
||||
and proven (proposal, rule, file), still open and why, MANUAL steps left
|
||||
for the user, the branch name. Merge waits for the user's explicit signal.
|
||||
3. Offer to capitalize a reusable lesson (a false-positive class, a fix
|
||||
pattern), entry pre-filled, written only on approval.
|
||||
@@ -0,0 +1,224 @@
|
||||
# Guardrail checks
|
||||
|
||||
Rule ids the scanner emits, what each proves, and the fix. Severity is the
|
||||
default; a judged hit can be a false positive.
|
||||
|
||||
## api
|
||||
|
||||
| Rule | Sev | Catches | Fix |
|
||||
|---|---|---|---|
|
||||
| API-SECRET-LITERAL | FAIL | provider key or private key block in source | env var, rotate the key |
|
||||
| API-PUBLIC-ENV-SECRET | FAIL | `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_` style prefix on a SERVICE_ROLE, SECRET, PRIVATE or PASSWORD name | drop the prefix, read it server-side |
|
||||
| API-ENV-NOT-IGNORED | FAIL | `.env*` file with values, not in `.gitignore` | ignore it, rotate what was exposed |
|
||||
| API-CORS-WILDCARD | FAIL / WARN | any origin allowed; FAIL when credentials are on | explicit origin allowlist |
|
||||
| API-ROUTE-NO-AUTH | WARN | route file with no authentication evidence | add auth, or document why it is public and rate limit it |
|
||||
| API-PASSWORD-PLAINTEXT | FAIL | password column typed as text with no hashing library anywhere; stored password compared with `==` or in a SQL `where password = $1` | argon2id, bcrypt or scrypt hash, verified with the library's check |
|
||||
| API-PASSWORD-WEAK-HASH | FAIL | md5, sha1, sha256 or `createHash().update()` fed a password | argon2id, scrypt or bcrypt |
|
||||
| API-PASSWORD-LOGGED | FAIL | `console.log`, `logger.*`, `print`, `println!`, `error_log` with a password identifier among its arguments, template interpolations included | never log credentials |
|
||||
| API-PASSWORD-LITERAL | WARN | `password: "..."`, `DB_PASSWORD=...` with a value of 8+ characters that is not a placeholder, hash, validation rule or label | env var and rotate; a dev default is documented as such |
|
||||
|
||||
## hosting
|
||||
|
||||
| Rule | Sev | Catches | Fix |
|
||||
|---|---|---|---|
|
||||
| HOST-NO-RATE-LIMIT | FAIL | no rate limiting anywhere in code or config | per IP and per account on login, signup, reset, send, upload |
|
||||
| HOST-ORIGIN-EXPOSED | WARN | origin platform with no CDN or firewall mention | put a CDN and WAF in front |
|
||||
| HOST-WAF-DDOS | MANUAL | firewall, DDoS and bot rules are dashboard settings | enable and confirm in the dashboard |
|
||||
| HOST-SPEND-CAP | MANUAL | hard spend cap is a plan setting | enable the cap; else budget alert plus a written kill switch |
|
||||
|
||||
## a11y
|
||||
|
||||
| Rule | Sev | Catches | Fix |
|
||||
|---|---|---|---|
|
||||
| A11Y-IMG-ALT | FAIL | `img` or `Image` without `alt` | describe it, or `alt=""` if decorative |
|
||||
| A11Y-FIELD-LABEL | FAIL | native input, select, textarea with no label | `label for`, wrapping label or `aria-label` |
|
||||
| A11Y-CLICK-NO-KEYBOARD | FAIL | click handler on a div or span lacking role, tabindex or key handler | use a `button` |
|
||||
| A11Y-FOCUS-OUTLINE | FAIL / WARN | focus outline removed; WARN when a `:focus-visible` style exists elsewhere | style `:focus-visible` instead |
|
||||
| A11Y-TABINDEX-POSITIVE | WARN | `tabindex` above 0 | use 0 or -1 and fix the DOM order |
|
||||
|
||||
## supabase
|
||||
|
||||
| Rule | Sev | Catches | Fix |
|
||||
|---|---|---|---|
|
||||
| SB-RLS-MISSING | FAIL | table created in migrations, RLS never enabled | `alter table ... enable row level security` in the same migration |
|
||||
| SB-RLS-LIVE | MANUAL | dashboard-created tables are invisible to a static scan | run the live queries below |
|
||||
| SB-POLICY-OPEN-WRITE | FAIL | `using (true)` or `with check (true)` on a write | scope to `(select auth.uid())` |
|
||||
| SB-POLICY-ANON-WRITE | FAIL | write policy open to anon or public, not owner-scoped | `to authenticated` plus owner check |
|
||||
| SB-POLICY-PUBLIC-READ | WARN | read policy `true` | confirm the data is public |
|
||||
| SB-POLICY-NOT-OWNER | WARN | policy with no `auth.uid()` or `auth.jwt()` | tie to the owner, or to a reviewed helper |
|
||||
| SB-VIEW-INVOKER | WARN | view runs as its owner and bypasses RLS | `with (security_invoker = true)` |
|
||||
| SB-MATVIEW-EXPOSED | WARN | materialized views cannot have RLS | move out of the exposed schema or revoke |
|
||||
| SB-DEFINER-SEARCH-PATH | WARN | `security definer` without a pinned `search_path` | `set search_path = ''` |
|
||||
| SB-DEFINER-EXECUTE | WARN | definer function callable by anon | `revoke execute ... from public, anon` |
|
||||
| SB-BUCKET-PUBLIC | WARN | public storage bucket | private plus storage policies |
|
||||
| SB-EDGE-NO-JWT | WARN | edge function with `verify_jwt = false` | fine for webhooks that verify a signature |
|
||||
| SB-SERVICE-ROLE-CLIENT | FAIL | service role or secret key referenced in client-reachable code | server only |
|
||||
| SB-SERVICE-ROLE-LITERAL | FAIL | service_role JWT pasted in a file | rotate it, move to server env |
|
||||
|
||||
## messaging
|
||||
|
||||
| Rule | Sev | Catches | Fix |
|
||||
|---|---|---|---|
|
||||
| MSG-NO-CONSENT-RECORD | FAIL / WARN | sender code, no stored consent anywhere; WARN when every sender looks transactional (contact form, reset, receipt) and no subscriber storage exists | store who, when, channel, source, wording |
|
||||
| MSG-SEND-UNCHECKED | WARN | sender file never checks consent or suppression | check before every send |
|
||||
| MSG-NO-UNSUBSCRIBE | FAIL / WARN | email sent, no unsubscribe anywhere; same transactional downgrade | link in every email |
|
||||
| MSG-NO-LIST-UNSUBSCRIBE | WARN | no `List-Unsubscribe` header | add it, with one-click post |
|
||||
| MSG-SMS-NO-STOP | FAIL / WARN | SMS sent, no `STOP` text; same transactional downgrade | add "Reply STOP" to marketing SMS |
|
||||
| MSG-SMS-NO-OPTOUT-STORE | FAIL / WARN | no opt-out storage; same transactional downgrade | record STOP replies, check before sending |
|
||||
|
||||
## functions
|
||||
|
||||
| Rule | Sev | Catches | Fix |
|
||||
|---|---|---|---|
|
||||
| FN-NO-MAX-INSTANCES | FAIL | Firebase, AWS Lambda or Google Cloud with no instance or concurrency cap | set it |
|
||||
| FN-CAP-UNVERIFIED | MANUAL | platform with no cap the scanner can read | check the provider docs; rely on spend cap |
|
||||
| FN-BUDGET-STOP | MANUAL | budget alert wired to an automatic stop | set it; confirm in the console |
|
||||
| FN-SELF-TRIGGER | FAIL / WARN | function writes the resource that fires it (WARN when guarded or file-level heuristic) | `WHEN` guard or idempotency flag |
|
||||
| FN-SELF-INVOKE | FAIL | edge function invokes itself | remove, or cap the depth |
|
||||
|
||||
## Blind spots
|
||||
|
||||
The scanner is regex over text. It cannot see:
|
||||
|
||||
- tables, policies or buckets made in the dashboard
|
||||
- whether a policy names the right owner column
|
||||
- whether consent was actually collected before the stored timestamp
|
||||
- whether a STOP reply reaches your store from the provider webhook
|
||||
- loops through queues, storage events, schedulers or third-party webhooks
|
||||
- keyboard traps, focus order, modal focus handling, color contrast
|
||||
- client-reachable code in unusual layouts (the rule uses path and
|
||||
`use client` heuristics, `.astro` is never flagged)
|
||||
- values built at runtime, minified bundles, anything over 1 MB
|
||||
- keys committed in the past: only the working tree is read, use
|
||||
`gitleaks git <repo>` for history
|
||||
- a password written in clear by code when a hashing library exists
|
||||
elsewhere: the column rule fires only when no library is found anywhere,
|
||||
so trace the write point by hand (STEP 4)
|
||||
- a log call spanning several lines, or `req.body` dumped to a log
|
||||
|
||||
Sender classification is by file path only: names with contact, reset, verify,
|
||||
otp, receipt and the like count as transactional, names with newsletter,
|
||||
campaign, promo and the like as marketing, anything else as unknown. Test files
|
||||
never count as senders. A shared mailer class is therefore judged by the
|
||||
project: a contact form beside it and no subscriber storage gives WARN.
|
||||
|
||||
The scanner skips log files and cache directories, and never follows symlinks.
|
||||
|
||||
By design the scanner ignores: policies granted only to `service_role`,
|
||||
fields that are never rendered (`hidden`, `display: none`), click handlers
|
||||
that only stop propagation or sit on `role="presentation"`, focus styles
|
||||
that swap the outline for a border or shadow, UI route components, keys
|
||||
inside git-ignored env files, and password literals in test, fixture and
|
||||
i18n files.
|
||||
|
||||
## Live Supabase checks (the user runs them in the SQL editor)
|
||||
|
||||
```sql
|
||||
-- tables in the public schema without RLS
|
||||
select tablename from pg_tables
|
||||
where schemaname = 'public' and not rowsecurity;
|
||||
|
||||
-- every policy, to read the owner scoping by eye
|
||||
select tablename, policyname, cmd, roles, qual, with_check
|
||||
from pg_policies where schemaname = 'public' order by tablename, cmd;
|
||||
|
||||
-- views that bypass RLS
|
||||
select c.relname from pg_class c
|
||||
join pg_namespace n on n.oid = c.relnamespace
|
||||
where n.nspname = 'public' and c.relkind = 'v'
|
||||
and coalesce(c.reloptions::text, '') not like '%security_invoker=true%';
|
||||
|
||||
-- definer functions callable by anon
|
||||
select p.proname, p.proconfig from pg_proc p
|
||||
join pg_namespace n on n.oid = p.pronamespace
|
||||
where n.nspname = 'public' and p.prosecdef
|
||||
and has_function_privilege('anon', p.oid, 'execute');
|
||||
|
||||
-- public buckets
|
||||
select id from storage.buckets where public;
|
||||
```
|
||||
|
||||
Two probes on the user's own project, read-only. With the anon key, a GET on
|
||||
each private table must return an empty list or 401. With a second test
|
||||
user's token, a GET on the first user's rows must return nothing.
|
||||
|
||||
## Manual items by domain
|
||||
|
||||
- **Hosting**: rate rules and DDoS or bot protection on at the CDN; a hard
|
||||
spend cap if the plan has one; a budget alert and a written kill-switch step.
|
||||
- **Functions**: budget alert wired to an automatic stop (throttle concurrency
|
||||
to zero, revoke invoke rights, or disable billing); a timeout on every
|
||||
function.
|
||||
- **Messaging**: provider-side STOP handling on, a webhook storing opt-outs,
|
||||
a retention rule for consent proof.
|
||||
- **Supabase**: the live queries above; spend cap on the plan; redirect URLs
|
||||
and email confirmation settings reviewed.
|
||||
|
||||
## Live probe (`--live`, read-only)
|
||||
|
||||
`probe.py` observes a running target the user owns and names. It is driven by
|
||||
a plan JSON built from the static findings; secrets come from the environment,
|
||||
never the plan or the command line. It sends GET, HEAD and OPTIONS only, with
|
||||
one opt-in POST burst for the rate-limit check, and stops at a request budget.
|
||||
|
||||
```json
|
||||
{
|
||||
"base_url": "http://localhost:5173",
|
||||
"supabase": {
|
||||
"url": "http://localhost:54321",
|
||||
"tables": ["notes", "contacts"],
|
||||
"cross_user_paths": ["/rest/v1/notes?select=*"]
|
||||
},
|
||||
"routes": [
|
||||
{"path": "/api/v1/notes"},
|
||||
{"path": "/api/v1/health", "public": true}
|
||||
],
|
||||
"cors": true,
|
||||
"cors_path": "/api/v1/notes",
|
||||
"rate_limit": {"path": "/api/v1/auth/login", "method": "POST",
|
||||
"count": 20, "body": "{\"email\":\"t@t.io\",\"password\":\"x\"}"}
|
||||
}
|
||||
```
|
||||
|
||||
Environment, from test keys only, never `service_role`:
|
||||
`GUARDRAILS_ANON_KEY` (anon-read), `GUARDRAILS_JWT2` (cross-user).
|
||||
|
||||
| Probe | id | OPEN means | Read it against |
|
||||
|---|---|---|---|
|
||||
| anon-read | `anon-read:<table>` | the anon key read a row | SB-RLS-MISSING, SB-POLICY-* |
|
||||
| cross-user | `cross-user:<path>` | a second user's token read these rows | policy owner column (STEP 4) |
|
||||
| no-auth route | `no-auth:<path>` | the route answered 200 with no token | API-ROUTE-NO-AUTH, object authz |
|
||||
| cors-reflect | `cors-reflect` | a foreign origin was reflected with credentials | API-CORS-WILDCARD |
|
||||
| rate-limit | `rate-limit` | the burst saw no 429 | HOST-NO-RATE-LIMIT |
|
||||
|
||||
A verdict is an observation, not a verdict on the project. OPEN is a returned
|
||||
200 or returned rows; CLOSED is a refusal or an empty body; SKIPPED is a
|
||||
missing key; ERROR is a transport failure. A static FAIL confirmed OPEN leads
|
||||
the report. A CLOSED probe on a static FAIL still needs the fix: the dev
|
||||
target may differ from production.
|
||||
|
||||
Safety, enforced by the script and by the skill: `--authorized` is required;
|
||||
read-only methods only; the loopback or a URL the user named, never one you
|
||||
inferred; a login burst only with a throwaway test account on the user's go,
|
||||
because it can lock the user's own account; a redirect to another host is
|
||||
never followed, so a key never leaves the named host. Fuzzing, writes beyond
|
||||
the named login route, or probing a third party are out of scope: that is
|
||||
pentest, another contract.
|
||||
|
||||
## Fix loop: oracles and re-pass
|
||||
|
||||
Every accepted fix is proven by the scanner itself, never by the executor's
|
||||
word. Two check modes replace the report and its exit code:
|
||||
|
||||
| Mode | Passes when | Marker | Used by |
|
||||
|---|---|---|---|
|
||||
| `--assert-absent RULE:path,...` | none of these FAIL/WARN pairs remains, the domain was scanned, the tree is not empty | `GUARDRAILS-CLEAR <n>` | a contract `CHECK:` run by `lib/gates.sh` (GATE 0) |
|
||||
| `--baseline before.json` | no FAIL/WARN hit appeared since the earlier `--json` run | `GUARDRAILS-NO-NEW` | STEP 11 re-pass |
|
||||
|
||||
Pairs match on rule and file, not line: a fix moves lines. A MANUAL rule
|
||||
cannot be asserted (exit 2): no static scan proves a dashboard setting. An
|
||||
unscanned domain or an empty tree fails the assertion, because absence there
|
||||
proves nothing. Run every oracle once before the fix: it must fail.
|
||||
|
||||
The baseline lists `FIXED` and `NEW` pairs with their hit counts and a
|
||||
remaining total. A `NEW` hit after a fix is a regression the fix made.
|
||||
@@ -0,0 +1 @@
|
||||
"""Static guardrail checks, one module per domain."""
|
||||
@@ -0,0 +1,239 @@
|
||||
"""Accessibility checks: keyboard, visible focus, alt text, field labels."""
|
||||
import re
|
||||
from collections import namedtuple
|
||||
|
||||
from .common import Rule, blank_markup_comments
|
||||
|
||||
DOMAIN = "a11y"
|
||||
MARKUP_EXTS = (".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte", ".astro")
|
||||
STYLE_EXTS = (".css", ".scss", ".sass", ".less")
|
||||
SCRIPT_EXTS = (".ts", ".js", ".mjs")
|
||||
FIELD_TAGS = {"input", "select", "textarea"}
|
||||
CLICK_TAGS = {"div", "span", "li", "p", "td", "tr", "section", "article"}
|
||||
SKIP_INPUT_TYPES = {"hidden", "submit", "button", "reset", "image"}
|
||||
INTERACTIVE = {"*", "a", "button", "input", "select", "textarea", "summary"}
|
||||
|
||||
_BRACES = r"\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\}"
|
||||
TAG = re.compile(
|
||||
r"<(?P<name>[A-Za-z][\w.:-]*)(?P<attrs>(?:[^<>{}]|" + _BRACES + r")*)>")
|
||||
SPREAD = re.compile(r"\{\s*\.\.\.|v-bind\s*=")
|
||||
CLICK = re.compile(
|
||||
r"(?<![\w-])(?:onclick|@click|v-on:click|on:click)(?![\w-])", re.I)
|
||||
KEYS = re.compile(
|
||||
r"(?<![\w-])(?:onkey(?:down|up|press)|@key(?:down|up|press)"
|
||||
r"|v-on:key(?:down|up|press)|on:key(?:down|up|press))(?![\w-])", re.I)
|
||||
POSITIVE_TABINDEX = re.compile(
|
||||
r"(?<![\w-])tabindex\s*=\s*[{\"']*\s*[1-9]", re.I)
|
||||
STYLE_TAG = re.compile(r"<style\b[^>]*>(.*?)</style>", re.I | re.S)
|
||||
CSS_RULE = re.compile(r"(?P<sel>[^{}]+)\{(?P<body>[^{}]*)\}")
|
||||
OUTLINE_OFF = re.compile(r"outline(?:-style)?\s*:\s*(?:none|0)\b", re.I)
|
||||
REPLACEMENT = re.compile(
|
||||
r"(?:box-shadow|border(?:-color)?)\s*:\s*(?!none\b|0\b)", re.I)
|
||||
NOT_A_CONTROL = re.compile(
|
||||
r"role\s*=\s*[\"'{]\s*[\"']?(?:presentation|none|dialog|alertdialog)\b"
|
||||
r"|stopPropagation", re.I)
|
||||
TW_STRING = re.compile(
|
||||
r"[\"'`]([^\"'`\n]*\boutline-(?:none|hidden)\b[^\"'`\n]*)[\"'`]")
|
||||
TW_REPLACED = re.compile(
|
||||
r"\bfocus(?:-visible|-within)?:(?:ring|outline\b(?!-none|-hidden)"
|
||||
r"|shadow|border|underline|bg-)")
|
||||
|
||||
|
||||
def applies(project):
|
||||
return bool(project.with_ext(*MARKUP_EXTS, *STYLE_EXTS))
|
||||
|
||||
|
||||
def has_attr(attrs, name):
|
||||
pattern = (r"(?<![\w-])(?:v-bind:|bind:|:)?" + re.escape(name)
|
||||
+ r"(?=[\s=/]|$)")
|
||||
return re.search(pattern, attrs, re.I) is not None
|
||||
|
||||
|
||||
def attr_value(attrs, name):
|
||||
"""Literal value, '{expr}' for a braced value, None if absent."""
|
||||
pattern = (r"(?<![\w:-])" + re.escape(name)
|
||||
+ r"\s*=\s*(?:\"([^\"]*)\"|'([^']*)'|\{([^}]*)\})")
|
||||
m = re.search(pattern, attrs, re.I)
|
||||
if not m:
|
||||
return None
|
||||
literal = m.group(1) if m.group(1) is not None else m.group(2)
|
||||
return literal if literal is not None else "{" + m.group(3) + "}"
|
||||
|
||||
|
||||
def check(project):
|
||||
out = []
|
||||
for path in project.with_ext(*MARKUP_EXTS):
|
||||
text = blank_markup_comments(project.text(path))
|
||||
out += _tag_findings(project, path, text)
|
||||
return out + _focus_css(project) + _focus_tailwind(project)
|
||||
|
||||
|
||||
def _tag_findings(project, path, text):
|
||||
out = []
|
||||
for m in TAG.finditer(text):
|
||||
for rule, severity, message in _tag_issues(m, text):
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, rule, severity), path, m.start(), message))
|
||||
return out
|
||||
|
||||
|
||||
def _tag_issues(m, text):
|
||||
name, attrs = m["name"], m["attrs"]
|
||||
if SPREAD.search(attrs):
|
||||
return []
|
||||
issues = [_tabindex_issue(attrs)]
|
||||
if name.lower() == "img" or name == "Image":
|
||||
issues.append(_img_issue(attrs))
|
||||
elif name in FIELD_TAGS:
|
||||
issues.append(_field_issue(m, text))
|
||||
elif name in CLICK_TAGS:
|
||||
issues.append(_click_issue(attrs))
|
||||
return [issue for issue in issues if issue]
|
||||
|
||||
|
||||
def _img_issue(attrs):
|
||||
if has_attr(attrs, "alt"):
|
||||
return None
|
||||
return ("A11Y-IMG-ALT", "FAIL",
|
||||
'image without alt: describe it, or alt="" when decorative')
|
||||
|
||||
|
||||
def _tabindex_issue(attrs):
|
||||
if not POSITIVE_TABINDEX.search(attrs):
|
||||
return None
|
||||
return ("A11Y-TABINDEX-POSITIVE", "WARN",
|
||||
"positive tabindex breaks the natural keyboard order")
|
||||
|
||||
|
||||
def _click_issue(attrs):
|
||||
if not CLICK.search(attrs) or NOT_A_CONTROL.search(attrs):
|
||||
return None
|
||||
if attrs.rstrip().endswith("/"): # empty overlay, nothing to operate
|
||||
return None
|
||||
missing = [label for label, ok in (
|
||||
("role", has_attr(attrs, "role")),
|
||||
("tabindex", has_attr(attrs, "tabindex")),
|
||||
("key handler", bool(KEYS.search(attrs))),
|
||||
) if not ok]
|
||||
if not missing:
|
||||
return None
|
||||
return ("A11Y-CLICK-NO-KEYBOARD", "FAIL",
|
||||
"click handler on a non-interactive element, missing "
|
||||
+ ", ".join(missing) + ": use a <button>")
|
||||
|
||||
|
||||
def _field_issue(m, text):
|
||||
attrs = m["attrs"]
|
||||
kind = (attr_value(attrs, "type") or "text").lower()
|
||||
if kind in SKIP_INPUT_TYPES or _is_hidden_field(attrs):
|
||||
return None
|
||||
if _is_labelled(attrs, text, m.start()):
|
||||
return None
|
||||
return ("A11Y-FIELD-LABEL", "FAIL",
|
||||
"form field without a label: add <label for>, a wrapping "
|
||||
"<label> or aria-label (a placeholder is not a label)")
|
||||
|
||||
|
||||
def _is_hidden_field(attrs):
|
||||
"""Fields that are never rendered need no label."""
|
||||
if has_attr(attrs, "hidden"):
|
||||
return True
|
||||
classes = attr_value(attrs, "className") or attr_value(attrs, "class")
|
||||
if "hidden" in (classes or "").split():
|
||||
return True
|
||||
return re.search(r"display\s*:\s*['\"]?none", attrs) is not None
|
||||
|
||||
|
||||
def _is_labelled(attrs, text, position):
|
||||
if has_attr(attrs, "aria-label") or has_attr(attrs, "aria-labelledby"):
|
||||
return True
|
||||
before = text[:position].lower()
|
||||
if before.count("<label") > before.count("</label"):
|
||||
return True
|
||||
ident = attr_value(attrs, "id")
|
||||
if ident is None:
|
||||
return has_attr(attrs, "id") # bound id: cannot tell, assume ok
|
||||
if not re.fullmatch(r"[\w-]+", ident):
|
||||
return True
|
||||
return re.search(
|
||||
r"(?:for|htmlFor)\s*=\s*[\"']" + re.escape(ident) + r"[\"']",
|
||||
text) is not None
|
||||
|
||||
|
||||
Block = namedtuple("Block", "path css start")
|
||||
|
||||
|
||||
def _style_blocks(project):
|
||||
"""Yield a Block for each CSS source: stylesheets and <style> tags."""
|
||||
for path in project.with_ext(*STYLE_EXTS):
|
||||
yield Block(path, blank_markup_comments(project.text(path)), 0)
|
||||
for path in project.with_ext(*MARKUP_EXTS):
|
||||
for m in STYLE_TAG.finditer(project.text(path)):
|
||||
yield Block(path, blank_markup_comments(m.group(1)), m.start(1))
|
||||
|
||||
|
||||
def _targets_focus(selector):
|
||||
for part in selector.split(","):
|
||||
part = part.strip()
|
||||
last = re.split(r"[\s>+~]+", part)[-1] if part else ""
|
||||
if ":focus" in part or last in INTERACTIVE:
|
||||
return True
|
||||
if last.startswith("[tabindex"):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def _kills_focus_ring(selector, body):
|
||||
return (OUTLINE_OFF.search(body) is not None
|
||||
and _targets_focus(selector)
|
||||
and ":not(:focus-visible)" not in selector
|
||||
and REPLACEMENT.search(body) is None)
|
||||
|
||||
|
||||
def _focus_visible_defined(project, blocks):
|
||||
if any(":focus-visible" in block.css for block in blocks):
|
||||
return True
|
||||
return project.has(r"focus-visible:", project.with_ext(*MARKUP_EXTS))
|
||||
|
||||
|
||||
def _lead(text):
|
||||
return len(text) - len(text.lstrip())
|
||||
|
||||
|
||||
def _css_findings(project, block, covered):
|
||||
out = []
|
||||
for rule in CSS_RULE.finditer(block.css):
|
||||
if _kills_focus_ring(rule["sel"], rule["body"]):
|
||||
offset = block.start + rule.start("sel") + _lead(rule["sel"])
|
||||
out.append(_outline_finding(project, block.path, offset, covered))
|
||||
return out
|
||||
|
||||
|
||||
def _focus_css(project):
|
||||
blocks = list(_style_blocks(project))
|
||||
covered = _focus_visible_defined(project, blocks)
|
||||
out = []
|
||||
for block in blocks:
|
||||
out += _css_findings(project, block, covered)
|
||||
return out
|
||||
|
||||
|
||||
def _outline_finding(project, path, offset, covered):
|
||||
if covered:
|
||||
return project.found(
|
||||
Rule(DOMAIN, "A11Y-FOCUS-OUTLINE", "WARN"), path, offset,
|
||||
"outline removed here: confirm a :focus-visible style covers it")
|
||||
return project.found(
|
||||
Rule(DOMAIN, "A11Y-FOCUS-OUTLINE", "FAIL"), path, offset,
|
||||
"focus outline removed and no :focus-visible style exists")
|
||||
|
||||
|
||||
def _focus_tailwind(project):
|
||||
out = []
|
||||
files = project.with_ext(*MARKUP_EXTS, *SCRIPT_EXTS)
|
||||
for path, m in project.matches(TW_STRING.pattern, files, 0):
|
||||
if not TW_REPLACED.search(m.group(1)):
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "A11Y-FOCUS-OUTLINE", "FAIL"), path, m.start(),
|
||||
"outline-none without a focus-visible ring replacement"))
|
||||
return out
|
||||
@@ -0,0 +1,173 @@
|
||||
"""Checks for every project: secrets, public env vars, CORS, route auth."""
|
||||
import fnmatch
|
||||
import re
|
||||
|
||||
from . import passwords
|
||||
from .common import Rule, SOURCE_EXTS, non_doc_files, redact
|
||||
|
||||
DOMAIN = "api"
|
||||
|
||||
SECRET_PATTERNS = [
|
||||
("Stripe live key", r"sk_live_[0-9A-Za-z]{10,}"),
|
||||
("AWS access key id", r"AKIA[0-9A-Z]{16}"),
|
||||
("GitHub token", r"gh[pousr]_[A-Za-z0-9]{30,}"),
|
||||
("Slack token", r"xox[abprs]-[A-Za-z0-9-]{10,}"),
|
||||
("SendGrid key", r"SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}"),
|
||||
("Supabase secret key", r"sb_secret_[A-Za-z0-9_-]{10,}"),
|
||||
("private key block", r"-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----"
|
||||
r"(?:\\n|\s)*[A-Za-z0-9+/=]{20,}"),
|
||||
]
|
||||
PUBLIC_ENV = (
|
||||
r"\b(?:NEXT_PUBLIC|VITE|REACT_APP|EXPO_PUBLIC|NUXT_PUBLIC|GATSBY"
|
||||
r"|VUE_APP|PUBLIC)_\w*(?:SERVICE_ROLE|SECRET|PRIVATE|PASSWORD)\w*"
|
||||
)
|
||||
CORS_WILDCARD = (
|
||||
r"Access-Control-Allow-Origin['\"]?\s*[:,=)]\s*['\"]\*['\"]"
|
||||
r"|\borigin\s*:\s*(?:['\"]\*['\"]|true)\b"
|
||||
r"|allow_origins\s*=\s*\[\s*['\"]\*['\"]"
|
||||
r"|allow_any_origin\(\)|CorsLayer::permissive\(\)"
|
||||
)
|
||||
CORS_CREDENTIALS = (
|
||||
r"credentials\s*:\s*true|Allow-Credentials|allow_credentials\s*=\s*True"
|
||||
r"|allow_credentials\(true\)|supports_credentials"
|
||||
)
|
||||
ROUTE_PATH = re.compile(
|
||||
r"(?:^|/)(?:api|routes|controllers|handlers)/"
|
||||
r"|(?:^|/)route\.[jt]s$|\+server\.[jt]s$"
|
||||
r"|(?:^|/)supabase/functions/[^/]+/index\.", re.I)
|
||||
API_DIR = re.compile(r"(?:^|/)api/", re.I)
|
||||
UI_EXTS = (".tsx", ".jsx", ".vue", ".svelte", ".astro")
|
||||
ROUTE_SKIP = re.compile(
|
||||
r"_shared|\.test\.|\.spec\.|health|ping|status|robots|sitemap"
|
||||
r"|favicon|/og[./]"
|
||||
r"|(?:^|/)(?:bin|scripts?|cron|jobs?|tests?|__tests__|migrations?"
|
||||
r"|seeds?|public|config|helpers?|libs?|models?|utils?|services?"
|
||||
r"|middleware|core|includes|types|schemas?|constants|templates?"
|
||||
r"|views?)/", re.I)
|
||||
AUTH_EVIDENCE = re.compile(
|
||||
r"\b(?:auth\w*|getUser|getSession|session|jwt\w*|bearer|verify\w*"
|
||||
r"|signature|hmac|login_required|Depends|requireAuth|requireUser"
|
||||
r"|requireRole|guard|permission\w*|clerk\w*|csrf)\b", re.I)
|
||||
ENV_NAME = re.compile(r"\.env(?:\.[\w.-]+)?")
|
||||
ENV_SAMPLE = (".example", ".sample", ".template", ".dist")
|
||||
|
||||
|
||||
def applies(project):
|
||||
return True
|
||||
|
||||
|
||||
def ignore_patterns(project):
|
||||
"""Patterns from every .gitignore in the tree."""
|
||||
patterns = []
|
||||
for gitignore in project.named(".gitignore"):
|
||||
for line in project.text(gitignore).splitlines():
|
||||
line = line.strip()
|
||||
if line and not line.startswith(("#", "!")):
|
||||
patterns.append(line.strip("/"))
|
||||
return patterns
|
||||
|
||||
|
||||
def is_ignored_env(path, patterns):
|
||||
"""True for an env file that .gitignore keeps out of git."""
|
||||
return bool(ENV_NAME.fullmatch(path.name)) and any(
|
||||
fnmatch.fnmatch(path.name, pat) for pat in patterns)
|
||||
|
||||
|
||||
def _is_route(rel, ext):
|
||||
if ROUTE_SKIP.search(rel) or not ROUTE_PATH.search(rel):
|
||||
return False
|
||||
return ext not in UI_EXTS or bool(API_DIR.search(rel))
|
||||
|
||||
|
||||
def route_files(project):
|
||||
return [
|
||||
p for p in project.with_ext(*SOURCE_EXTS)
|
||||
if _is_route(project.rel(p), p.suffix.lower())
|
||||
]
|
||||
|
||||
|
||||
def check(project):
|
||||
return (_secret_literals(project) + _public_env(project)
|
||||
+ _unignored_env(project) + _cors(project)
|
||||
+ _routes_without_auth(project) + passwords.check(project))
|
||||
|
||||
|
||||
def _unignored_files(project):
|
||||
patterns = ignore_patterns(project)
|
||||
return [p for p in non_doc_files(project)
|
||||
if not is_ignored_env(p, patterns)]
|
||||
|
||||
|
||||
def _literal_hits(project, files, label, pattern):
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "API-SECRET-LITERAL", "FAIL"), path, m.start(),
|
||||
f"{label} hardcoded ({redact(m.group())}): "
|
||||
"move it to env and rotate it")
|
||||
for path, m in project.matches(pattern, files, 0)
|
||||
]
|
||||
|
||||
|
||||
def _secret_literals(project):
|
||||
files = _unignored_files(project)
|
||||
out = []
|
||||
for label, pattern in SECRET_PATTERNS:
|
||||
out += _literal_hits(project, files, label, pattern)
|
||||
return out
|
||||
|
||||
|
||||
def _public_env(project):
|
||||
files = [p for p in project.files
|
||||
if p.suffix.lower() not in (".md", ".mdx")]
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "API-PUBLIC-ENV-SECRET", "FAIL"), path, m.start(),
|
||||
f"{m.group()} ships to the browser: secrets stay server-side")
|
||||
for path, m in project.matches(PUBLIC_ENV, files, 0)
|
||||
]
|
||||
|
||||
|
||||
def _has_value(text):
|
||||
return re.search(r"^\s*[A-Za-z_]\w*\s*=\s*\S", text, re.M) is not None
|
||||
|
||||
|
||||
def _unignored_env(project):
|
||||
patterns = ignore_patterns(project)
|
||||
out = []
|
||||
for path in project.files:
|
||||
if not ENV_NAME.fullmatch(path.name):
|
||||
continue
|
||||
if path.name.endswith(ENV_SAMPLE) or not _has_value(project.text(path)):
|
||||
continue
|
||||
if not is_ignored_env(path, patterns):
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "API-ENV-NOT-IGNORED", "FAIL"), path, 0,
|
||||
f"{path.name} holds values and is not in .gitignore"))
|
||||
return out
|
||||
|
||||
|
||||
def _cors_finding(project, path, m):
|
||||
creds = re.search(CORS_CREDENTIALS, project.text(path), re.I)
|
||||
note = " with credentials" if creds else ""
|
||||
return project.found(
|
||||
Rule(DOMAIN, "API-CORS-WILDCARD", "FAIL" if creds else "WARN"),
|
||||
path, m.start(),
|
||||
f"CORS allows any origin{note}: use an explicit allowlist")
|
||||
|
||||
|
||||
def _cors(project):
|
||||
return [
|
||||
_cors_finding(project, path, m)
|
||||
for path, m in project.matches(CORS_WILDCARD, non_doc_files(project))
|
||||
]
|
||||
|
||||
|
||||
def _routes_without_auth(project):
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "API-ROUTE-NO-AUTH", "WARN"), path, 0,
|
||||
"no authentication evidence in this route; if it is public "
|
||||
"on purpose, say so and rate limit it")
|
||||
for path in route_files(project)
|
||||
if not AUTH_EVIDENCE.search(project.text(path))
|
||||
]
|
||||
@@ -0,0 +1,163 @@
|
||||
"""Shared types and file helpers for the guardrails checks."""
|
||||
import os
|
||||
import re
|
||||
from dataclasses import asdict, dataclass
|
||||
from pathlib import Path
|
||||
|
||||
SKIP_DIRS = {
|
||||
".git", "node_modules", "dist", "build", ".next", ".astro", "target",
|
||||
"vendor", ".venv", "venv", "coverage", "__pycache__", ".svelte-kit",
|
||||
".nuxt", ".output", ".turbo", ".vercel", ".cache", ".phpunit.cache",
|
||||
".pytest_cache", ".mypy_cache",
|
||||
}
|
||||
SKIP_FILES = {
|
||||
"package-lock.json", "pnpm-lock.yaml", "yarn.lock", "Cargo.lock",
|
||||
"bun.lockb", "poetry.lock", "composer.lock",
|
||||
}
|
||||
BINARY_EXTS = {
|
||||
".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".pdf",
|
||||
".woff", ".woff2", ".ttf", ".otf", ".zip", ".gz", ".mp4", ".mov",
|
||||
".mp3", ".wasm", ".log",
|
||||
}
|
||||
MAX_BYTES = 1_000_000
|
||||
SOURCE_EXTS = {
|
||||
".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rs", ".go",
|
||||
".php", ".rb", ".vue", ".svelte", ".astro",
|
||||
}
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Rule:
|
||||
domain: str
|
||||
id: str
|
||||
severity: str # FAIL | WARN | MANUAL
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Finding:
|
||||
domain: str
|
||||
rule: str
|
||||
severity: str # FAIL | WARN | MANUAL
|
||||
path: str
|
||||
line: int
|
||||
message: str
|
||||
|
||||
def as_dict(self):
|
||||
return asdict(self)
|
||||
|
||||
|
||||
def line_of(text, offset):
|
||||
return text.count("\n", 0, offset) + 1
|
||||
|
||||
|
||||
def redact(value):
|
||||
return value[:6] + "..."
|
||||
|
||||
|
||||
SQL_COMMENT = re.compile(r"--[^\n]*|/\*.*?\*/", re.S)
|
||||
MARKUP_COMMENT = re.compile(
|
||||
r"<!--.*?-->|/\*.*?\*/|(?:^|(?<=\s))//[^\n]*", re.S | re.M)
|
||||
|
||||
|
||||
def _blank(pattern, text):
|
||||
"""Replace matches with spaces, keeping offsets and newlines."""
|
||||
return pattern.sub(lambda m: re.sub(r"[^\n]", " ", m.group()), text)
|
||||
|
||||
|
||||
def blank_comments(text):
|
||||
return _blank(SQL_COMMENT, text)
|
||||
|
||||
|
||||
def blank_markup_comments(text):
|
||||
return _blank(MARKUP_COMMENT, text)
|
||||
|
||||
|
||||
def _is_scannable(path):
|
||||
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()
|
||||
and path.stat().st_size <= MAX_BYTES)
|
||||
except OSError:
|
||||
return False
|
||||
|
||||
|
||||
def _excluded(root, path, prefixes):
|
||||
rel = Path(path).relative_to(root).as_posix()
|
||||
return any(rel == p or rel.startswith(p + "/") for p in prefixes)
|
||||
|
||||
|
||||
def _kept_dirs(root, base, dirs, prefixes):
|
||||
return [
|
||||
d for d in dirs
|
||||
if d not in SKIP_DIRS and not _excluded(root, Path(base) / d, prefixes)
|
||||
]
|
||||
|
||||
|
||||
def _kept_files(root, base, names, prefixes):
|
||||
for name in names:
|
||||
path = Path(base) / name
|
||||
if _is_scannable(path) and not _excluded(root, path, prefixes):
|
||||
yield path
|
||||
|
||||
|
||||
def _walk(root, prefixes):
|
||||
for base, dirs, names in os.walk(root):
|
||||
dirs[:] = _kept_dirs(root, base, dirs, prefixes)
|
||||
yield from _kept_files(root, base, names, prefixes)
|
||||
|
||||
|
||||
class Project:
|
||||
"""A directory tree read as data. Nothing in it is ever executed."""
|
||||
|
||||
def __init__(self, root, exclude=()):
|
||||
self.root = Path(root).resolve()
|
||||
prefixes = [e.strip("/") for e in exclude if e.strip("/")]
|
||||
self.files = sorted(_walk(self.root, prefixes))
|
||||
self._text = {}
|
||||
|
||||
def rel(self, path):
|
||||
return path.relative_to(self.root).as_posix()
|
||||
|
||||
def text(self, path):
|
||||
if path not in self._text:
|
||||
try:
|
||||
self._text[path] = path.read_text(
|
||||
encoding="utf-8", errors="ignore")
|
||||
except OSError:
|
||||
self._text[path] = ""
|
||||
return self._text[path]
|
||||
|
||||
def with_ext(self, *exts):
|
||||
return [p for p in self.files if p.suffix.lower() in exts]
|
||||
|
||||
def named(self, *names):
|
||||
return [p for p in self.files if p.name in names]
|
||||
|
||||
def segments(self, path):
|
||||
return self.rel(path).split("/")[:-1]
|
||||
|
||||
def matches(self, pattern, files=None, flags=re.I):
|
||||
"""Yield (path, match) for each regex hit in the given files."""
|
||||
regex = re.compile(pattern, flags)
|
||||
for path in (self.files if files is None else files):
|
||||
for match in regex.finditer(self.text(path)):
|
||||
yield path, match
|
||||
|
||||
def has(self, pattern, files=None, flags=re.I):
|
||||
return next(self.matches(pattern, files, flags), None) is not None
|
||||
|
||||
def found(self, rule, path, offset, message):
|
||||
line = line_of(self.text(path), offset) if offset else 1
|
||||
return Finding(
|
||||
rule.domain, rule.id, rule.severity, self.rel(path), line,
|
||||
message)
|
||||
|
||||
def found_at_root(self, domain, rule, severity, message):
|
||||
return Finding(domain, rule, severity, ".", 1, message)
|
||||
|
||||
|
||||
def non_doc_files(project):
|
||||
"""Files that can hold behavior: everything except docs and samples."""
|
||||
skip = (".md", ".mdx", ".txt", ".example", ".sample", ".template")
|
||||
return [p for p in project.files if not p.name.endswith(skip)]
|
||||
@@ -0,0 +1,242 @@
|
||||
"""Cloud function checks: no self-trigger, instance cap, budget stop."""
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
|
||||
from .common import Rule, SOURCE_EXTS, non_doc_files
|
||||
from .supabase import function_statement, sql_files, split_name
|
||||
|
||||
DOMAIN = "functions"
|
||||
INFRA_EXTS = (".yml", ".yaml", ".tf", ".toml", ".json", ".sh")
|
||||
AWS_PATTERN = r"AWS::Serverless|AWS::Lambda|aws_lambda_function|lambda_runtime"
|
||||
GCP_PATTERN = (
|
||||
r"google_cloudfunctions|google_cloud_run"
|
||||
r"|gcloud\s+(?:functions|run)\s+deploy"
|
||||
)
|
||||
CAPS = {
|
||||
"Firebase": r"maxInstances|max_instances",
|
||||
"AWS Lambda": r"reserved_?concurren\w*",
|
||||
"Google Cloud": (
|
||||
r"max[-_]instances|max_instance_count|maxInstanceCount|maxInstances"
|
||||
),
|
||||
}
|
||||
_NAME = r'(?:"?\w+"?\.)?"?\w+"?'
|
||||
TRIGGER = re.compile(
|
||||
r"create\s+(?:or\s+replace\s+)?trigger\s+(?P<name>\w+)\s+"
|
||||
r"(?:before|after|instead\s+of)\s+[^;]*?\bon\s+(?P<table>" + _NAME
|
||||
+ r")\s+(?P<rest>[^;]*?)execute\s+(?:function|procedure)\s+"
|
||||
r"(?P<func>" + _NAME + r")\s*\((?P<args>[^;]*)\)\s*;", re.I | re.S)
|
||||
CREATE_FUNCTION = re.compile(
|
||||
r"create\s+(?:or\s+replace\s+)?function\s+(" + _NAME + r")\s*\(", re.I)
|
||||
FN_URL = re.compile(r"/functions/v1/([\w-]+)")
|
||||
FIREBASE_V2 = re.compile(
|
||||
r"(onDocument\w+)\(\s*(?:\{[^}]*\}\s*,\s*)?['\"`]([^'\"`]+)['\"`]")
|
||||
FIREBASE_V1 = re.compile(
|
||||
r"\.document\(\s*['\"`]([^'\"`]+)['\"`]\s*\)\s*\.(on\w+)\(")
|
||||
REWRITES_SELF = ("Written", "Updated", "onWrite", "onUpdate")
|
||||
|
||||
|
||||
def supabase_functions(project):
|
||||
"""Map edge function name to its files."""
|
||||
found = {}
|
||||
for path in project.files:
|
||||
parts = project.rel(path).split("/")
|
||||
if parts[:2] == ["supabase", "functions"] and len(parts) > 3:
|
||||
if parts[2] != "_shared":
|
||||
found.setdefault(parts[2], []).append(path)
|
||||
return found
|
||||
|
||||
|
||||
def _infra(project):
|
||||
return project.with_ext(*INFRA_EXTS)
|
||||
|
||||
|
||||
def _firebase(project):
|
||||
return bool(project.named("firebase.json")) and project.has(
|
||||
r'"functions"|firebase-functions', project.files)
|
||||
|
||||
|
||||
def _vercel(project):
|
||||
return bool(project.named("vercel.json")) and any(
|
||||
"api" in project.segments(p) for p in project.with_ext(*SOURCE_EXTS))
|
||||
|
||||
|
||||
def detect(project):
|
||||
on = {
|
||||
"Supabase Edge Functions": bool(supabase_functions(project)),
|
||||
"Firebase": _firebase(project),
|
||||
"AWS Lambda": project.has(AWS_PATTERN, _infra(project)),
|
||||
"Google Cloud": project.has(GCP_PATTERN, _infra(project)),
|
||||
"Vercel Functions": _vercel(project),
|
||||
"Netlify Functions": any(
|
||||
"netlify/functions/" in project.rel(p) for p in project.files),
|
||||
"Cloudflare Workers": bool(
|
||||
project.named("wrangler.toml", "wrangler.json", "wrangler.jsonc")),
|
||||
}
|
||||
return [label for label, enabled in on.items() if enabled]
|
||||
|
||||
|
||||
def applies(project):
|
||||
return bool(detect(project))
|
||||
|
||||
|
||||
def check(project):
|
||||
platforms = detect(project)
|
||||
out = _instance_caps(project, platforms)
|
||||
out += _budget_stop(project, platforms)
|
||||
out += _supabase_loops(project) + _self_invoke(project)
|
||||
return out + _firebase_loops(project)
|
||||
|
||||
|
||||
def _instance_caps(project, platforms):
|
||||
out = []
|
||||
docs = non_doc_files(project)
|
||||
for label in platforms:
|
||||
pattern = CAPS.get(label)
|
||||
if pattern is None:
|
||||
out.append(project.found_at_root(
|
||||
DOMAIN, "FN-CAP-UNVERIFIED", "MANUAL",
|
||||
f"{label}: no instance cap to verify from code; check the "
|
||||
"provider docs for a concurrency limit, and rely on the "
|
||||
"spend cap, rate limiting and a short timeout"))
|
||||
elif not project.has(pattern, docs):
|
||||
out.append(project.found_at_root(
|
||||
DOMAIN, "FN-NO-MAX-INSTANCES", "FAIL",
|
||||
f"{label}: no max instances or reserved concurrency set"))
|
||||
return out
|
||||
|
||||
|
||||
def _budget_stop(project, platforms):
|
||||
return [
|
||||
project.found_at_root(
|
||||
DOMAIN, "FN-BUDGET-STOP", "MANUAL",
|
||||
f"{label}: wire a budget alert to an automatic stop (throttle "
|
||||
"concurrency to zero, revoke invoke rights or disable billing); "
|
||||
"verify it in the console")
|
||||
for label in platforms
|
||||
]
|
||||
|
||||
|
||||
def _function_bodies(sql):
|
||||
"""Map function name to the text of its CREATE FUNCTION statement."""
|
||||
bodies = {}
|
||||
for _, text in sql:
|
||||
for m in CREATE_FUNCTION.finditer(text):
|
||||
bodies[split_name(m.group(1))[1]] = function_statement(
|
||||
text, m.start())
|
||||
return bodies
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Loop:
|
||||
"""An edge function fired by a database trigger on `table`."""
|
||||
function: str
|
||||
table: str
|
||||
trigger: str
|
||||
guarded: bool
|
||||
|
||||
|
||||
def _loops_of(m, bodies):
|
||||
func = split_name(m["func"])[1]
|
||||
source = m["args"] if func == "http_request" else bodies.get(func, "")
|
||||
guarded = bool(re.search(r"\bwhen\b", m["rest"], re.I))
|
||||
table = split_name(m["table"])[1]
|
||||
return [Loop(u.group(1), table, m["name"], guarded)
|
||||
for u in FN_URL.finditer(source)]
|
||||
|
||||
|
||||
def _triggered_edge_functions(sql):
|
||||
"""Yield a Loop per edge function that a database trigger calls."""
|
||||
bodies = _function_bodies(sql)
|
||||
for _, text in sql:
|
||||
for m in TRIGGER.finditer(text):
|
||||
yield from _loops_of(m, bodies)
|
||||
|
||||
|
||||
def _writes_table(table):
|
||||
return re.compile(
|
||||
r"\.(?:from|table)\(\s*['\"`](?:public\.)?" + re.escape(table)
|
||||
+ r"['\"`]\s*\)\s*\.(?:insert|update|upsert|delete)\s*\("
|
||||
r"|(?:update|insert\s+into|delete\s+from)\s+(?:public\.)?"
|
||||
+ re.escape(table) + r"\b", re.I)
|
||||
|
||||
|
||||
def _supabase_loops(project):
|
||||
functions = supabase_functions(project)
|
||||
out = []
|
||||
for loop in _triggered_edge_functions(sql_files(project)):
|
||||
for path in functions.get(loop.function, []):
|
||||
out += _loop_findings(project, path, loop)
|
||||
return out
|
||||
|
||||
|
||||
def _loop_findings(project, path, loop):
|
||||
m = _writes_table(loop.table).search(project.text(path))
|
||||
return [_loop_finding(project, path, m.start(), loop)] if m else []
|
||||
|
||||
|
||||
def _loop_finding(project, path, offset, loop):
|
||||
head = (f'"{loop.function}" writes "{loop.table}" which fires trigger '
|
||||
f"{loop.trigger}")
|
||||
if loop.guarded:
|
||||
return project.found(
|
||||
Rule(DOMAIN, "FN-SELF-TRIGGER", "WARN"), path, offset,
|
||||
head + ", guarded by WHEN: confirm the write cannot satisfy it")
|
||||
return project.found(
|
||||
Rule(DOMAIN, "FN-SELF-TRIGGER", "FAIL"), path, offset,
|
||||
head + ": infinite loop; add a WHEN guard or an idempotency flag")
|
||||
|
||||
|
||||
def _invocations(project, name, paths):
|
||||
pattern = (r"functions/v1/" + re.escape(name)
|
||||
+ r"\b|invoke\(\s*['\"]" + re.escape(name) + r"['\"]")
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "FN-SELF-INVOKE", "FAIL"), path, m.start(),
|
||||
f'"{name}" invokes itself: cap the depth or remove the call')
|
||||
for path, m in project.matches(pattern, paths)
|
||||
]
|
||||
|
||||
|
||||
def _self_invoke(project):
|
||||
out = []
|
||||
for name, paths in supabase_functions(project).items():
|
||||
out += _invocations(project, name, paths)
|
||||
return out
|
||||
|
||||
|
||||
def _firebase_handlers(text):
|
||||
"""Yield (collection, kind, offset) for each Firestore trigger."""
|
||||
for m in FIREBASE_V2.finditer(text):
|
||||
yield m.group(2).split("/")[0], m.group(1), m.start()
|
||||
for m in FIREBASE_V1.finditer(text):
|
||||
yield m.group(1).split("/")[0], m.group(2), m.start()
|
||||
|
||||
|
||||
def _file_loops(project, path):
|
||||
text = project.text(path)
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "FN-SELF-TRIGGER", "WARN"), path, offset,
|
||||
f'trigger on "{collection}" also writes it in this file: '
|
||||
"confirm the write cannot fire the trigger again")
|
||||
for collection, kind, offset in _firebase_handlers(text)
|
||||
if _rewrites_trigger(text, collection, kind)
|
||||
]
|
||||
|
||||
|
||||
def _firebase_loops(project):
|
||||
out = []
|
||||
for path in project.with_ext(".js", ".ts", ".mjs"):
|
||||
if not project.rel(path).startswith("supabase/"):
|
||||
out += _file_loops(project, path)
|
||||
return out
|
||||
|
||||
|
||||
def _rewrites_trigger(text, collection, kind):
|
||||
own_ref = re.search(r"\.ref\.(?:set|update)\(", text)
|
||||
if own_ref and kind.endswith(REWRITES_SELF):
|
||||
return True
|
||||
return re.search(
|
||||
r"collection\(\s*['\"`]" + re.escape(collection)
|
||||
+ r"['\"`]\s*\)(?:\s*\.doc\([^)]*\))?\s*\.(?:add|set|update)\(",
|
||||
text) is not None
|
||||
@@ -0,0 +1,101 @@
|
||||
"""Hosting checks: rate limit, CDN and firewall, spend cap."""
|
||||
from .apis import route_files
|
||||
from .common import Rule, non_doc_files
|
||||
|
||||
DOMAIN = "hosting"
|
||||
|
||||
PLATFORMS = {
|
||||
"vercel.json": ("Vercel", True),
|
||||
"netlify.toml": ("Netlify", True),
|
||||
"wrangler.toml": ("Cloudflare", True),
|
||||
"wrangler.json": ("Cloudflare", True),
|
||||
"wrangler.jsonc": ("Cloudflare", True),
|
||||
"firebase.json": ("Firebase Hosting", True),
|
||||
"amplify.yml": ("AWS Amplify", True),
|
||||
"fly.toml": ("Fly.io", False),
|
||||
"render.yaml": ("Render", False),
|
||||
"railway.json": ("Railway", False),
|
||||
"railway.toml": ("Railway", False),
|
||||
"docker-compose.yml": ("Docker Compose", False),
|
||||
"docker-compose.yaml": ("Docker Compose", False),
|
||||
"compose.yml": ("Docker Compose", False),
|
||||
"compose.yaml": ("Docker Compose", False),
|
||||
"nginx.conf": ("nginx", False),
|
||||
"Caddyfile": ("Caddy", False),
|
||||
".htaccess": ("Apache", False),
|
||||
"app.yaml": ("App Engine", False),
|
||||
}
|
||||
RATE_LIMIT = (
|
||||
r"rate[-_ ]?limit|ratelimit|limit_req|throttl|governor|slowapi"
|
||||
r"|flask[-_]limiter|django[-_]ratelimit|@vercel/firewall|fail2ban"
|
||||
r"|\blimiter\b"
|
||||
)
|
||||
CDN_MENTION = (
|
||||
r"cloudflare|cloudfront|fastly|bunny\.net|akamai|cf-connecting-ip"
|
||||
r"|set_real_ip_from"
|
||||
)
|
||||
SPEND_HINTS = {
|
||||
"Vercel": "set a Spend Management amount with automatic pause",
|
||||
}
|
||||
SPEND_DEFAULT = (
|
||||
"check the plan for a hard spend cap and enable it; if there is none, "
|
||||
"set a budget alert and write the kill-switch step in the deploy notes"
|
||||
)
|
||||
|
||||
|
||||
def detect(project):
|
||||
"""Map platform label to (has_cdn, config path)."""
|
||||
found = {}
|
||||
for path in project.files:
|
||||
entry = ("Docker", False) if path.name.startswith("Dockerfile") \
|
||||
else PLATFORMS.get(path.name)
|
||||
if entry:
|
||||
found.setdefault(entry[0], (entry[1], path))
|
||||
return found
|
||||
|
||||
|
||||
def applies(project):
|
||||
return bool(detect(project)) or bool(route_files(project))
|
||||
|
||||
|
||||
def check(project):
|
||||
platforms = detect(project)
|
||||
return (_rate_limit(project, platforms)
|
||||
+ _origin_exposure(project, platforms)
|
||||
+ _manual_items(project, platforms))
|
||||
|
||||
|
||||
def _rate_limit(project, platforms):
|
||||
if project.has(RATE_LIMIT, non_doc_files(project)):
|
||||
return []
|
||||
return [project.found_at_root(
|
||||
DOMAIN, "HOST-NO-RATE-LIMIT", "FAIL",
|
||||
"no rate limiting found: add it per IP and per account on login, "
|
||||
"signup, reset, send and upload")]
|
||||
|
||||
|
||||
def _origin_exposure(project, platforms):
|
||||
origins = sorted(
|
||||
label for label, (has_cdn, _) in platforms.items() if not has_cdn)
|
||||
if not origins or project.has(CDN_MENTION):
|
||||
return []
|
||||
return [project.found_at_root(
|
||||
DOMAIN, "HOST-ORIGIN-EXPOSED", "WARN",
|
||||
", ".join(origins) + ": the origin is served directly; put a CDN "
|
||||
"and firewall in front (Cloudflare, CloudFront, Fastly)")]
|
||||
|
||||
|
||||
def _manual_items(project, platforms):
|
||||
out = [project.found_at_root(
|
||||
DOMAIN, "HOST-WAF-DDOS", "MANUAL",
|
||||
"enable the CDN firewall: DDoS protection, bot rules, rate rules "
|
||||
"(dashboard setting, not visible from code)")]
|
||||
if not platforms:
|
||||
out.append(project.found_at_root(
|
||||
DOMAIN, "HOST-SPEND-CAP", "MANUAL",
|
||||
"no hosting config found: " + SPEND_DEFAULT))
|
||||
for label, (_, path) in platforms.items():
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "HOST-SPEND-CAP", "MANUAL"), path, 0,
|
||||
f"{label}: " + SPEND_HINTS.get(label, SPEND_DEFAULT)))
|
||||
return out
|
||||
@@ -0,0 +1,164 @@
|
||||
"""SMS and email checks: recorded consent, unsubscribe, STOP handling."""
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
|
||||
from .common import Rule, SOURCE_EXTS, non_doc_files
|
||||
|
||||
DOMAIN = "messaging"
|
||||
MANIFESTS = (
|
||||
"package.json", "Cargo.toml", "requirements.txt", "pyproject.toml",
|
||||
"composer.json", "go.mod", "deno.json",
|
||||
)
|
||||
EMAIL_SENDER = (
|
||||
r"nodemailer|@sendgrid/mail|sendgrid\.com|api\.resend\.com"
|
||||
r"|new Resend\(|from ['\"]resend['\"]|postmark|mailgun|sib-api-v3"
|
||||
r"|sendinblue|brevo|mailjet|mandrill|client-ses|SendEmailCommand"
|
||||
r"|smtplib|use lettre|lettre::|PHPMailer|mailchimp"
|
||||
)
|
||||
SMS_SENDER = (
|
||||
r"twilio|vonage|nexmo|messagebird|sns\.publish|@aws-sdk/client-sns"
|
||||
r"|PublishCommand|ovh.{0,20}sms|plivo|sinch|clicksend|smsapi"
|
||||
r"|sendTransacSms|telnyx|infobip|africastalking"
|
||||
)
|
||||
CONSENT_STORED = (
|
||||
r"consent(?:ed)?_?(?:at|date|ts|timestamp|source|status|given|version"
|
||||
r"|text)|opt_?in_?(?:at|date|source|ts|timestamp)|opted_?in|double_?opt"
|
||||
r"|marketing_consent|has_consented|sms_consent|email_consent"
|
||||
)
|
||||
CONSENT_CHECKED = (
|
||||
r"consent|opt_?in|opted|subscribed|unsubscrib|suppress|allowed_to_contact"
|
||||
)
|
||||
UNSUBSCRIBE = r"unsubscrib|d[ée]sinscri"
|
||||
OPT_OUT_STORED = (
|
||||
r"opt_?out|unsubscribed|stopped|suppress|blocklist|do_not_(?:contact|text)"
|
||||
)
|
||||
TRANSACTIONAL = re.compile(
|
||||
r"contact|reset|verif|otp|password|confirm|receipt|invoice|welcome"
|
||||
r"|magic|login|signin|2fa|mfa|booking|reservation", re.I)
|
||||
MARKETING = re.compile(
|
||||
r"newsletter|campaign|subscriber|mailing|broadcast|promo|marketing"
|
||||
r"|bulk|audience|relance|blast", re.I)
|
||||
TRANSACTIONAL_NOTE = " (only transactional senders found: confirm no marketing)"
|
||||
TEST_PATH = re.compile(
|
||||
r"(?:^|/)(?:tests?|__tests__|spec)/|\.(?:test|spec)\.|Test\.php$", re.I)
|
||||
BULK_STORAGE = (
|
||||
r"subscriber|newsletter|mailing[_ ]?list|contact_list|audience"
|
||||
)
|
||||
|
||||
|
||||
def sender_files(project):
|
||||
files = project.with_ext(*SOURCE_EXTS) + project.named(*MANIFESTS)
|
||||
return [p for p in files if not TEST_PATH.search(project.rel(p))]
|
||||
|
||||
|
||||
def _sends(project, path):
|
||||
return project.has(EMAIL_SENDER, [path]) or project.has(SMS_SENDER, [path])
|
||||
|
||||
|
||||
def _kind(project, path):
|
||||
rel = project.rel(path)
|
||||
if MARKETING.search(rel):
|
||||
return "marketing"
|
||||
return "transactional" if TRANSACTIONAL.search(rel) else "unknown"
|
||||
|
||||
|
||||
def _severity(project, senders):
|
||||
"""FAIL unless a sender looks transactional and nothing bulk exists."""
|
||||
code = [p for p in senders if p.suffix.lower() in SOURCE_EXTS] or senders
|
||||
kinds = {_kind(project, p) for p in code}
|
||||
if "marketing" in kinds or "transactional" not in kinds:
|
||||
return "FAIL"
|
||||
if project.has(BULK_STORAGE, non_doc_files(project)):
|
||||
return "FAIL"
|
||||
return "WARN"
|
||||
|
||||
|
||||
def applies(project):
|
||||
files = sender_files(project)
|
||||
return project.has(EMAIL_SENDER, files) or project.has(SMS_SENDER, files)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Sending:
|
||||
senders: list
|
||||
severity: str
|
||||
email: object
|
||||
sms: object
|
||||
|
||||
|
||||
def _first_hit(project, pattern, files):
|
||||
return next(project.matches(pattern, files), None)
|
||||
|
||||
|
||||
def _context(project):
|
||||
files = sender_files(project)
|
||||
senders = [p for p in files if _sends(project, p)]
|
||||
return Sending(
|
||||
senders, _severity(project, senders),
|
||||
_first_hit(project, EMAIL_SENDER, files),
|
||||
_first_hit(project, SMS_SENDER, files))
|
||||
|
||||
|
||||
def check(project):
|
||||
ctx = _context(project)
|
||||
out = _consent(project, ctx.email or ctx.sms, ctx.senders, ctx.severity)
|
||||
if ctx.email:
|
||||
out += _email_rules(project, ctx.email, ctx.severity)
|
||||
if ctx.sms:
|
||||
out += _sms_rules(project, ctx.sms, ctx.severity)
|
||||
return out
|
||||
|
||||
|
||||
def _note(severity):
|
||||
return TRANSACTIONAL_NOTE if severity == "WARN" else ""
|
||||
|
||||
|
||||
def _consent(project, hit, senders, severity):
|
||||
path, m = hit
|
||||
if not project.has(CONSENT_STORED, non_doc_files(project), 0):
|
||||
return [project.found(
|
||||
Rule(DOMAIN, "MSG-NO-CONSENT-RECORD", severity), path, m.start(),
|
||||
"messages are sent but no consent record exists: store who, "
|
||||
"when, channel, source and wording per contact" + _note(severity))]
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "MSG-SEND-UNCHECKED", "WARN"), p, 0,
|
||||
"sends messages without checking consent or the suppression "
|
||||
"list in this file")
|
||||
for p in senders
|
||||
if p.suffix.lower() in SOURCE_EXTS
|
||||
and _kind(project, p) != "transactional"
|
||||
and not project.has(CONSENT_CHECKED, [p])
|
||||
]
|
||||
|
||||
|
||||
def _email_rules(project, hit, severity):
|
||||
path, m = hit
|
||||
docs = non_doc_files(project)
|
||||
if not project.has(UNSUBSCRIBE, docs):
|
||||
return [project.found(
|
||||
Rule(DOMAIN, "MSG-NO-UNSUBSCRIBE", severity), path, m.start(),
|
||||
"emails are sent but no unsubscribe link exists" + _note(severity))]
|
||||
if not project.has(r"list-unsubscribe", docs):
|
||||
return [project.found(
|
||||
Rule(DOMAIN, "MSG-NO-LIST-UNSUBSCRIBE", "WARN"), path, m.start(),
|
||||
"add the List-Unsubscribe header (one-click); Gmail and Yahoo "
|
||||
"require it from bulk senders")]
|
||||
return []
|
||||
|
||||
|
||||
def _sms_rules(project, hit, severity):
|
||||
path, m = hit
|
||||
docs = non_doc_files(project)
|
||||
out = []
|
||||
if not project.has(r"\bSTOP\b", docs, 0):
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "MSG-SMS-NO-STOP", severity), path, m.start(),
|
||||
"SMS are sent but nothing tells the recipient to reply STOP"
|
||||
+ _note(severity)))
|
||||
if not project.has(OPT_OUT_STORED, docs):
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "MSG-SMS-NO-OPTOUT-STORE", severity), path, m.start(),
|
||||
"no opt-out storage: a STOP reply must be recorded and "
|
||||
"checked before every send" + _note(severity)))
|
||||
return out
|
||||
@@ -0,0 +1,137 @@
|
||||
"""Password handling: clear storage or compare, fast hash, log, literal."""
|
||||
import re
|
||||
|
||||
from .common import Rule, SOURCE_EXTS, non_doc_files, redact
|
||||
|
||||
DOMAIN = "api"
|
||||
NAME = r"(?:password|passwd|pwd|mot_de_passe)"
|
||||
CONFIG_EXTS = {".yml", ".yaml", ".toml", ".ini", ".cfg", ".conf", ".sh",
|
||||
".properties", ".json"}
|
||||
SKIP_PATH = re.compile(
|
||||
r"\.(?:test|spec|e2e|stories)\.|(?:^|/)(?:tests?|__tests__|spec|e2e"
|
||||
r"|fixtures?|i18n|locales?|lang|translations?|messages)/", re.I)
|
||||
HASH_EVIDENCE = (
|
||||
r"bcrypt|argon2|scrypt|pbkdf2|password_hash\(|password_verify\("
|
||||
r"|Hash::make|make_password|hashpw|PasswordHasher|hash_password"
|
||||
r"|verify_password|\bphpass\b")
|
||||
COLUMN = (
|
||||
rf"\b{NAME}\s+(?:text|varchar|character varying|char|citext|string)\b"
|
||||
rf"|->string\(\s*['\"]{NAME}['\"]"
|
||||
rf"|\b{NAME}\s*=\s*models\.(?:Char|Text)Field"
|
||||
rf"|\b{NAME}\s*:\s*(?:text|varchar)\(")
|
||||
COMPARE = (
|
||||
rf"(?:\.|->|\[['\"]){NAME}['\"]?\]?\s*[!=]==?\s*[\w$]"
|
||||
rf"|[\w$\]\)]\s*[!=]==?\s*\$?\w+(?:\.|->){NAME}\b"
|
||||
rf"|\b(?:where|and)\s+(?:\w+\.)?{NAME}\s*=\s*(?:\$\d+|\?|:\w+|%s)")
|
||||
COMPARE_SKIP = re.compile(
|
||||
r"confirm|repeat|again|undefined|null|hash|digest|length", re.I)
|
||||
WEAK_HASH = (
|
||||
rf"\b(?:md5|sha1|sha256|sha512|crc32|hashlib\.\w+)\s*\(\s*[^()\n]*{NAME}"
|
||||
rf"|createHash\([^)\n]*\)\s*\.update\(\s*[^()\n]*{NAME}"
|
||||
rf"|\bhash\(\s*['\"](?:md5|sha1|sha256|sha512)['\"]\s*,\s*[^()\n]*{NAME}")
|
||||
WEAK_SKIP = re.compile(r"token|reset|otp|nonce|session", re.I)
|
||||
LOG_CALL = (
|
||||
r"\b(?:console\.\w+|logger?\.\w+|log\.\w+|logging\.\w+|print(?:ln!?)?"
|
||||
r"|error_log|Log::\w+|tracing::\w+!|dbg!|var_dump|print_r)\s*\(([^\n]*)")
|
||||
STRING = re.compile(r"'[^'\n]*'|\"[^\"\n]*\"|`[^`\n]*`")
|
||||
LOGGED_NAME = re.compile(
|
||||
rf"\b(?:(?:new|old|plain|raw|user|current)_?)?{NAME}\b|\bcredentials\b",
|
||||
re.I)
|
||||
LITERAL = rf"\b(\w*{NAME})['\"]?\s*(?:[:=]|=>)\s*['\"]([^'\"\n]{{8,}})['\"]"
|
||||
BARE_LITERAL = rf"\b(\w*{NAME})(?:=\s*|:\s+)([^'\"\s#]{{8,}})"
|
||||
PLACEHOLDER = re.compile(
|
||||
r"change|your|xxx|\*\*|example|placeholder|dummy|sample|secret[-_ ]?here"
|
||||
r"|^[$%<{.*/]|\||required|^\$argon|^[0-9a-f]{32,}$|^[a-z]+(?:_[a-z]+)+$| ",
|
||||
re.I)
|
||||
PLAINTEXT = Rule(DOMAIN, "API-PASSWORD-PLAINTEXT", "FAIL")
|
||||
LITERAL_RULE = Rule(DOMAIN, "API-PASSWORD-LITERAL", "WARN")
|
||||
|
||||
|
||||
def _line(text, offset):
|
||||
start = text.rfind("\n", 0, offset) + 1
|
||||
end = text.find("\n", offset)
|
||||
return text[start:] if end < 0 else text[start:end]
|
||||
|
||||
|
||||
def _files(project):
|
||||
return [p for p in non_doc_files(project)
|
||||
if not SKIP_PATH.search(project.rel(p))]
|
||||
|
||||
|
||||
def check(project):
|
||||
files = _files(project)
|
||||
return (_columns(project, files) + _compares(project, files)
|
||||
+ _weak_hash(project, files) + _logged(project, files)
|
||||
+ _literals(project, files))
|
||||
|
||||
|
||||
def _columns(project, files):
|
||||
if project.has(HASH_EVIDENCE, files):
|
||||
return []
|
||||
return [
|
||||
project.found(
|
||||
PLAINTEXT, path, m.start(),
|
||||
"password column and no hashing library anywhere: store an "
|
||||
"argon2id or bcrypt hash, never the password")
|
||||
for path, m in project.matches(COLUMN, files)
|
||||
]
|
||||
|
||||
|
||||
def _compares(project, files):
|
||||
return [
|
||||
project.found(
|
||||
PLAINTEXT, path, m.start(),
|
||||
"stored password compared in clear: verify a hash with the "
|
||||
"library's constant-time check")
|
||||
for path, m in project.matches(COMPARE, files)
|
||||
if not COMPARE_SKIP.search(_line(project.text(path), m.start()))
|
||||
]
|
||||
|
||||
|
||||
def _weak_hash(project, files):
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "API-PASSWORD-WEAK-HASH", "FAIL"), path, m.start(),
|
||||
"password through a fast hash: use argon2id, scrypt or bcrypt")
|
||||
for path, m in project.matches(WEAK_HASH, files)
|
||||
if not WEAK_SKIP.search(_line(project.text(path), m.start()))
|
||||
]
|
||||
|
||||
|
||||
def _log_args(args):
|
||||
"""Call arguments with string literals reduced to their interpolations."""
|
||||
return STRING.sub(
|
||||
lambda m: " ".join(re.findall(r"\{([^}]*)\}", m.group())), args)
|
||||
|
||||
|
||||
def _logged(project, files):
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "API-PASSWORD-LOGGED", "FAIL"), path, m.start(),
|
||||
"password reaches a log: never log credentials")
|
||||
for path, m in project.matches(LOG_CALL, files)
|
||||
if LOGGED_NAME.search(_log_args(m.group(1)))
|
||||
]
|
||||
|
||||
|
||||
def _is_placeholder(key, value):
|
||||
return value.lower() == key.lower() or bool(PLACEHOLDER.search(value))
|
||||
|
||||
|
||||
def _literal_hits(project, files, pattern):
|
||||
return [
|
||||
project.found(
|
||||
LITERAL_RULE, path, m.start(),
|
||||
f"{m.group(1)} set to a literal ({redact(m.group(2))}): a real "
|
||||
"credential moves to env and gets rotated; a dev default is "
|
||||
"documented as such")
|
||||
for path, m in project.matches(pattern, files)
|
||||
if not _is_placeholder(m.group(1), m.group(2))
|
||||
]
|
||||
|
||||
|
||||
def _literals(project, files):
|
||||
config = [p for p in files if p.suffix.lower() in CONFIG_EXTS]
|
||||
source = [p for p in files if p.suffix.lower() in SOURCE_EXTS]
|
||||
return (_literal_hits(project, source + config, LITERAL)
|
||||
+ _literal_hits(project, config, BARE_LITERAL))
|
||||
@@ -0,0 +1,332 @@
|
||||
"""Supabase checks: RLS, owner-scoped policies, keys kept off the client."""
|
||||
import base64
|
||||
import json
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
|
||||
from .apis import ignore_patterns, is_ignored_env
|
||||
from .common import Rule, SOURCE_EXTS, blank_comments
|
||||
|
||||
DOMAIN = "supabase"
|
||||
_NAME = r'(?:"?\w+"?\.)?"?\w+"?'
|
||||
TABLE = re.compile(
|
||||
r"create\s+(?:unlogged\s+)?table\s+(?:if\s+not\s+exists\s+)?(?P<name>"
|
||||
+ _NAME + r")", re.I)
|
||||
RLS_ON = re.compile(
|
||||
r"alter\s+table\s+(?:only\s+)?(?:if\s+exists\s+)?(?P<name>" + _NAME
|
||||
+ r")\s+enable\s+row\s+level\s+security", re.I)
|
||||
DROP = re.compile(
|
||||
r"drop\s+table\s+(?:if\s+exists\s+)?(?P<name>" + _NAME + r")", re.I)
|
||||
POLICY = re.compile(
|
||||
r"create\s+policy\s+(?P<pname>\"[^\"]+\"|\w+)\s+on\s+(?P<table>"
|
||||
+ _NAME + r")(?P<rest>[^;]*);", re.I)
|
||||
VIEW = re.compile(
|
||||
r"create\s+(?:or\s+replace\s+)?(?P<mat>materialized\s+)?view\s+"
|
||||
r"(?P<name>" + _NAME + r")(?P<rest>[^;]*);", re.I)
|
||||
FUNCTION = re.compile(
|
||||
r"create\s+(?:or\s+replace\s+)?function\s+(?P<name>" + _NAME + r")\s*\(",
|
||||
re.I)
|
||||
BUCKET_SQL = re.compile(
|
||||
r"(?:insert\s+into|update)\s+storage\.buckets[^;]*;", re.I)
|
||||
OPEN_EXPR = re.compile(r"\b(?:using|with\s+check)\s*\(\s*true\s*\)")
|
||||
OWNER = re.compile(r"auth\.(?:uid|jwt|role)\s*\(")
|
||||
WRITE_CMDS = {"all", "insert", "update", "delete"}
|
||||
ANON_ROLES = {"anon", "public"}
|
||||
PRIVILEGED_ROLES = {"service_role", "postgres", "supabase_admin"}
|
||||
|
||||
SERVICE_REF = r"service_role|SERVICE_ROLE|SUPABASE_SECRET_KEY|sb_secret_"
|
||||
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")
|
||||
SCRIPT_EXTS = (".ts", ".tsx", ".js", ".jsx", ".mjs")
|
||||
JWT = r"eyJ[\w-]{8,}\.(eyJ[\w-]{8,})\.[\w-]{8,}"
|
||||
MANIFESTS = (
|
||||
"package.json", "Cargo.toml", "requirements.txt", "pyproject.toml",
|
||||
"pubspec.yaml", "composer.json", "go.mod", "deno.json",
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Policy:
|
||||
name: str
|
||||
table: str
|
||||
cmd: str
|
||||
roles: tuple
|
||||
open_expr: bool
|
||||
owner: bool
|
||||
offset: int
|
||||
|
||||
|
||||
def split_name(raw):
|
||||
"""Return (schema, name), schema defaulting to public."""
|
||||
parts = raw.replace('"', "").lower().split(".")
|
||||
return (parts[0], parts[1]) if len(parts) == 2 else ("public", parts[0])
|
||||
|
||||
|
||||
def function_statement(text, start):
|
||||
"""Text of a CREATE FUNCTION from `start` to its closing semicolon."""
|
||||
tag = re.compile(r"\bas\s+(\$\w*\$)", re.I).search(text, start)
|
||||
if not tag:
|
||||
end = text.find(";", start)
|
||||
else:
|
||||
close = text.find(tag.group(1), tag.end())
|
||||
end = text.find(";", close if close != -1 else tag.end())
|
||||
return text[start:end if end != -1 else len(text)]
|
||||
|
||||
|
||||
def sql_files(project):
|
||||
return [(p, blank_comments(project.text(p)))
|
||||
for p in project.with_ext(".sql")]
|
||||
|
||||
|
||||
def applies(project):
|
||||
if (project.root / "supabase").is_dir():
|
||||
return True
|
||||
return project.has(r"supabase", project.named(*MANIFESTS))
|
||||
|
||||
|
||||
def check(project):
|
||||
sql = sql_files(project)
|
||||
out = _rls(project, sql)
|
||||
for path, text in sql:
|
||||
out += (_policies(project, path, text) + _views(project, path, text)
|
||||
+ _functions(project, path, text, sql)
|
||||
+ _buckets(project, path, text))
|
||||
out += _config(project) + _client_leaks(project) + _jwt_literals(project)
|
||||
return _dedupe_last(out)
|
||||
|
||||
|
||||
def _dedupe_last(findings):
|
||||
"""An object redefined by a later migration is reported once, there."""
|
||||
latest = {(f.rule, f.message): f for f in findings}
|
||||
return [f for f in findings if latest[(f.rule, f.message)] is f]
|
||||
|
||||
|
||||
LIVE_NOTE = (
|
||||
"static check sees migrations only: run the RLS query from "
|
||||
"references/checks.md against the live project")
|
||||
|
||||
|
||||
def _public_name(m):
|
||||
schema, name = split_name(m["name"])
|
||||
return name if schema == "public" else None
|
||||
|
||||
|
||||
def _created_tables(sql):
|
||||
created = {}
|
||||
for path, text in sql:
|
||||
for m in TABLE.finditer(text):
|
||||
name = _public_name(m)
|
||||
if name:
|
||||
created.setdefault(name, (path, m.start()))
|
||||
return created
|
||||
|
||||
|
||||
def _all_names(pattern, sql):
|
||||
return {split_name(m["name"])[1]
|
||||
for _, text in sql for m in pattern.finditer(text)}
|
||||
|
||||
|
||||
def _rls(project, sql):
|
||||
live = project.found_at_root(DOMAIN, "SB-RLS-LIVE", "MANUAL", LIVE_NOTE)
|
||||
covered = _all_names(RLS_ON, sql) | _all_names(DROP, sql)
|
||||
return [live] + [
|
||||
project.found(
|
||||
Rule(DOMAIN, "SB-RLS-MISSING", "FAIL"), path, offset,
|
||||
f'table "{name}" never enables row level security')
|
||||
for name, (path, offset) in _created_tables(sql).items()
|
||||
if name not in covered
|
||||
]
|
||||
|
||||
|
||||
def _roles(rest):
|
||||
to = re.search(r"\bto\s+(.+?)(?=\s+(?:using|with\s+check)\b|$)", rest, re.S)
|
||||
listed = to.group(1).split(",") if to else ["public"]
|
||||
return tuple(r.strip(' "') for r in listed)
|
||||
|
||||
|
||||
def parse_policy(m):
|
||||
rest = m["rest"].lower()
|
||||
cmd = re.search(r"\bfor\s+(all|select|insert|update|delete)\b", rest)
|
||||
return Policy(
|
||||
m["pname"].strip('"'), split_name(m["table"])[1],
|
||||
cmd.group(1) if cmd else "all", _roles(rest),
|
||||
bool(OPEN_EXPR.search(rest)), bool(OWNER.search(rest)), m.start())
|
||||
|
||||
|
||||
def policy_issues(pol):
|
||||
"""Return (Rule, message) pairs for one policy."""
|
||||
if set(pol.roles) <= PRIVILEGED_ROLES:
|
||||
return []
|
||||
writes = pol.cmd in WRITE_CMDS
|
||||
anon = bool(ANON_ROLES & set(pol.roles))
|
||||
where = f'policy "{pol.name}" on "{pol.table}"'
|
||||
if pol.open_expr and writes:
|
||||
return [(Rule(DOMAIN, "SB-POLICY-OPEN-WRITE", "FAIL"),
|
||||
f"{where}: true on a write lets anyone change rows")]
|
||||
if writes and anon and not pol.owner:
|
||||
return [(Rule(DOMAIN, "SB-POLICY-ANON-WRITE", "FAIL"),
|
||||
f"{where}: anon can write; scope it to auth.uid()")]
|
||||
if pol.open_expr:
|
||||
return [(Rule(DOMAIN, "SB-POLICY-PUBLIC-READ", "WARN"),
|
||||
f"{where}: open read; confirm the data is public")]
|
||||
if not pol.owner:
|
||||
return [(Rule(DOMAIN, "SB-POLICY-NOT-OWNER", "WARN"),
|
||||
f"{where}: not tied to auth.uid(); confirm owner scoping")]
|
||||
return []
|
||||
|
||||
|
||||
def _policies(project, path, text):
|
||||
out = []
|
||||
for m in POLICY.finditer(text):
|
||||
pol = parse_policy(m)
|
||||
for rule, message in policy_issues(pol):
|
||||
out.append(project.found(rule, path, pol.offset, message))
|
||||
return out
|
||||
|
||||
|
||||
def _views(project, path, text):
|
||||
out = []
|
||||
for m in VIEW.finditer(text):
|
||||
schema, name = split_name(m["name"])
|
||||
if schema != "public":
|
||||
continue
|
||||
if m["mat"]:
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "SB-MATVIEW-EXPOSED", "WARN"), path, m.start(),
|
||||
f'materialized view "{name}" ignores RLS: do not expose it'))
|
||||
elif "security_invoker" not in m["rest"].lower():
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "SB-VIEW-INVOKER", "WARN"), path, m.start(),
|
||||
f'view "{name}" runs as its owner: add security_invoker'))
|
||||
return out
|
||||
|
||||
|
||||
def _statements(sql, word):
|
||||
return " ".join(t for _, t in sql if word in t.lower())
|
||||
|
||||
|
||||
def _revoked(revokes, name):
|
||||
pattern = r"revoke\s+(?:all|execute)[^;]*\b" + re.escape(name) + r"\b"
|
||||
return re.search(pattern, revokes, re.I) is not None
|
||||
|
||||
|
||||
def _execute_issue(revokes, grants, name, stmt):
|
||||
if "returns trigger" in stmt or _revoked(revokes, name):
|
||||
return None
|
||||
granted = r"grant\s+(?:all|execute)[^;]*\b" + re.escape(name)
|
||||
if re.search(granted + r"\b[^;]*\banon\b", grants, re.I):
|
||||
return (f'definer function "{name}" is explicitly granted to anon: '
|
||||
"confirm it is meant to be public")
|
||||
return (f'definer function "{name}" is callable by anon by default: '
|
||||
"revoke execute from public, anon")
|
||||
|
||||
|
||||
def _definer_findings(project, path, m, text, privileges):
|
||||
schema, name = split_name(m["name"])
|
||||
stmt = function_statement(text, m.start()).lower()
|
||||
if schema != "public" or "security definer" not in stmt:
|
||||
return []
|
||||
out = []
|
||||
if "set search_path" not in stmt:
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "SB-DEFINER-SEARCH-PATH", "WARN"), path, m.start(),
|
||||
f'definer function "{name}" must pin search_path'))
|
||||
issue = _execute_issue(*privileges, name, stmt)
|
||||
if issue:
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "SB-DEFINER-EXECUTE", "WARN"), path, m.start(),
|
||||
issue))
|
||||
return out
|
||||
|
||||
|
||||
def _functions(project, path, text, sql):
|
||||
privileges = (_statements(sql, "revoke"), _statements(sql, "grant"))
|
||||
out = []
|
||||
for m in FUNCTION.finditer(text):
|
||||
out += _definer_findings(project, path, m, text, privileges)
|
||||
return out
|
||||
|
||||
|
||||
def _buckets(project, path, text):
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "SB-BUCKET-PUBLIC", "WARN"), path, m.start(),
|
||||
"storage bucket set public: confirm every file is meant "
|
||||
"to be world-readable")
|
||||
for m in BUCKET_SQL.finditer(text)
|
||||
if re.search(r"\btrue\b", m.group(), re.I)
|
||||
]
|
||||
|
||||
|
||||
def _config(project):
|
||||
out = []
|
||||
for path in project.named("config.toml"):
|
||||
if path.parent.name != "supabase":
|
||||
continue
|
||||
text = project.text(path)
|
||||
for m in re.finditer(
|
||||
r"\[functions\.([\w-]+)\][^\[]*?verify_jwt\s*=\s*false",
|
||||
text, re.S):
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "SB-EDGE-NO-JWT", "WARN"), path, m.start(),
|
||||
f'function "{m.group(1)}" skips JWT verification: confirm '
|
||||
"it checks a webhook signature instead"))
|
||||
for m in re.finditer(
|
||||
r"\[storage\.buckets\.([\w-]+)\][^\[]*?public\s*=\s*true",
|
||||
text, re.S):
|
||||
out.append(project.found(
|
||||
Rule(DOMAIN, "SB-BUCKET-PUBLIC", "WARN"), path, m.start(),
|
||||
f'bucket "{m.group(1)}" is public: confirm it is intended'))
|
||||
return out
|
||||
|
||||
|
||||
def _client_reachable(project, path):
|
||||
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 SCRIPT_EXTS:
|
||||
return False
|
||||
head = project.text(path)[:300]
|
||||
return bool(segments & CLIENT_SEGMENTS) or "use client" in head
|
||||
|
||||
|
||||
def _client_leaks(project):
|
||||
files = project.with_ext(*SOURCE_EXTS, *CLIENT_EXTS)
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "SB-SERVICE-ROLE-CLIENT", "FAIL"), path, m.start(),
|
||||
"service role or secret key referenced in client-reachable "
|
||||
"code: it bypasses RLS for anyone who reads the bundle")
|
||||
for path, m in project.matches(SERVICE_REF, files, 0)
|
||||
if _client_reachable(project, path)
|
||||
]
|
||||
|
||||
|
||||
def _jwt_role(payload):
|
||||
try:
|
||||
raw = base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4))
|
||||
data = json.loads(raw)
|
||||
except ValueError:
|
||||
return None
|
||||
return data.get("role") if isinstance(data, dict) else None
|
||||
|
||||
|
||||
def _jwt_literals(project):
|
||||
patterns = ignore_patterns(project)
|
||||
return [
|
||||
project.found(
|
||||
Rule(DOMAIN, "SB-SERVICE-ROLE-LITERAL", "FAIL"), path, m.start(),
|
||||
"service_role JWT hardcoded: rotate the key, keep it in "
|
||||
"server env only")
|
||||
for path, m in project.matches(JWT, None, 0)
|
||||
if _jwt_role(m.group(1)) == "service_role"
|
||||
and not is_ignored_env(path, patterns)
|
||||
]
|
||||
@@ -0,0 +1,309 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Live guardrails probe: observe a running target from outside, read-only.
|
||||
|
||||
The static scan shows a protection is absent in the code. This observes what
|
||||
a running target the user owns and names actually returns. It sends GET, HEAD
|
||||
and OPTIONS only; a login burst is opt-in in the plan. It never writes data,
|
||||
never uses a service_role key, never follows a redirect to another host, and
|
||||
stops at a fixed request budget.
|
||||
|
||||
Input is a plan JSON (built by the skill from the static findings) plus
|
||||
secrets from the environment, never the command line:
|
||||
GUARDRAILS_ANON_KEY Supabase anon/publishable key for the anon-read probe
|
||||
GUARDRAILS_JWT2 a second test user's token for the cross-user probe
|
||||
|
||||
A verdict is a factual observation, not a conclusion: the skill reads it
|
||||
against the static findings. OPEN means the request returned data or a 200,
|
||||
CLOSED means it was refused or empty. Exit codes: 0 no OPEN, 1 at least one
|
||||
OPEN, 2 usage error.
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
from dataclasses import asdict, dataclass
|
||||
from urllib.parse import quote, urlsplit
|
||||
|
||||
READ_METHODS = {"GET", "HEAD", "OPTIONS"}
|
||||
FAKE_ORIGIN = "https://guardrails-probe.invalid"
|
||||
DEFAULT_BUDGET = 200
|
||||
BURST_CAP = 25
|
||||
BODY_CAP = 1_000_000
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Response:
|
||||
status: int # None on a transport error
|
||||
headers: dict
|
||||
body: bytes
|
||||
error: str = ""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Probe:
|
||||
domain: str
|
||||
id: str
|
||||
verdict: str # OPEN | CLOSED | SKIPPED | ERROR
|
||||
target: str
|
||||
message: str
|
||||
|
||||
def as_dict(self):
|
||||
return asdict(self)
|
||||
|
||||
|
||||
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:
|
||||
return None
|
||||
return super().redirect_request(req, fp, code, msg, headers, newurl)
|
||||
|
||||
|
||||
class Session:
|
||||
"""Holds the redirect-guarded opener and the shared request budget."""
|
||||
|
||||
def __init__(self, timeout=8, budget=DEFAULT_BUDGET):
|
||||
self.opener = urllib.request.build_opener(_SameHost())
|
||||
self.timeout = timeout
|
||||
self.budget = budget
|
||||
|
||||
|
||||
def _response_from(resp):
|
||||
return Response(resp.status, dict(resp.headers), resp.read(BODY_CAP))
|
||||
|
||||
|
||||
def fetch(session, method, url, headers=None, body=None):
|
||||
if session.budget <= 0:
|
||||
return Response(None, {}, b"", "request budget exhausted")
|
||||
session.budget -= 1
|
||||
req = urllib.request.Request(
|
||||
url, data=body, method=method, headers=headers or {})
|
||||
try:
|
||||
with session.opener.open(req, timeout=session.timeout) as resp:
|
||||
return _response_from(resp)
|
||||
except urllib.error.HTTPError as exc:
|
||||
return Response(exc.code, dict(exc.headers), b"")
|
||||
except (urllib.error.URLError, OSError, ValueError) as exc:
|
||||
return Response(None, {}, b"", str(exc))
|
||||
|
||||
|
||||
def _verdict(ctx, response, is_open, msgs):
|
||||
"""ctx is (domain, id, target); msgs is (open_note, closed_note)."""
|
||||
domain, pid, target = ctx
|
||||
if response.error:
|
||||
return Probe(domain, pid, "ERROR", target, response.error)
|
||||
verdict = "OPEN" if is_open else "CLOSED"
|
||||
note = f"HTTP {response.status}: {msgs[0] if is_open else msgs[1]}"
|
||||
return Probe(domain, pid, verdict, target, note)
|
||||
|
||||
|
||||
def _nonempty_rows(body):
|
||||
try:
|
||||
data = json.loads(body or b"[]")
|
||||
except ValueError:
|
||||
return False
|
||||
return isinstance(data, list) and len(data) > 0
|
||||
|
||||
|
||||
def _table_probe(session, base, table, headers):
|
||||
target = f"{base}/rest/v1/{quote(table)}?select=*&limit=1"
|
||||
resp = fetch(session, "GET", target, headers)
|
||||
return _verdict(
|
||||
("supabase", f"anon-read:{table}", target), resp,
|
||||
resp.status == 200 and _nonempty_rows(resp.body),
|
||||
("anon request returned rows", "anon request returned no row"))
|
||||
|
||||
|
||||
def probe_supabase(session, plan):
|
||||
cfg = plan.get("supabase")
|
||||
anon = os.environ.get("GUARDRAILS_ANON_KEY")
|
||||
if not cfg or not cfg.get("tables"):
|
||||
return []
|
||||
if not anon:
|
||||
return [Probe("supabase", "anon-read", "SKIPPED", cfg.get("url", ""),
|
||||
"set GUARDRAILS_ANON_KEY to run the anon-read probe")]
|
||||
base = cfg["url"].rstrip("/")
|
||||
headers = {"apikey": anon, "Authorization": f"Bearer {anon}"}
|
||||
return [_table_probe(session, base, t, headers) for t in cfg["tables"]]
|
||||
|
||||
|
||||
def _cross_user_probe(session, base, path, headers):
|
||||
target = base + path
|
||||
resp = fetch(session, "GET", target, headers)
|
||||
return _verdict(
|
||||
("supabase", f"cross-user:{path}", target), resp,
|
||||
resp.status == 200 and _nonempty_rows(resp.body),
|
||||
("second user's token returned these rows",
|
||||
"second user's token returned nothing"))
|
||||
|
||||
|
||||
def probe_cross_user(session, plan):
|
||||
cfg = plan.get("supabase") or {}
|
||||
paths = cfg.get("cross_user_paths") or []
|
||||
jwt2 = os.environ.get("GUARDRAILS_JWT2")
|
||||
if not paths:
|
||||
return []
|
||||
if not jwt2:
|
||||
return [Probe("supabase", "cross-user", "SKIPPED", cfg.get("url", ""),
|
||||
"set GUARDRAILS_JWT2 to run the cross-user probe")]
|
||||
headers = {"apikey": os.environ.get("GUARDRAILS_ANON_KEY", ""),
|
||||
"Authorization": f"Bearer {jwt2}"}
|
||||
base = cfg["url"].rstrip("/")
|
||||
return [_cross_user_probe(session, base, p, headers) for p in paths]
|
||||
|
||||
|
||||
def _route_probe(session, base, route):
|
||||
target = base + route["path"]
|
||||
resp = fetch(session, "GET", target)
|
||||
return _verdict(
|
||||
("api", f"no-auth:{route['path']}", target), resp,
|
||||
resp.status == 200,
|
||||
("unauthenticated request returned 200",
|
||||
"unauthenticated request was refused"))
|
||||
|
||||
|
||||
def probe_routes(session, plan):
|
||||
base = plan["base_url"].rstrip("/")
|
||||
routes = [r for r in plan.get("routes", []) if not r.get("public")]
|
||||
return [_route_probe(session, base, r) for r in routes]
|
||||
|
||||
|
||||
def _cors_open(headers):
|
||||
allow = headers.get("Access-Control-Allow-Origin", "")
|
||||
creds = headers.get("Access-Control-Allow-Credentials", "").lower()
|
||||
return allow in (FAKE_ORIGIN, "*") and creds == "true"
|
||||
|
||||
|
||||
def probe_cors(session, plan):
|
||||
if not plan.get("cors"):
|
||||
return []
|
||||
base = plan["base_url"].rstrip("/")
|
||||
headers = {"Origin": FAKE_ORIGIN, "Access-Control-Request-Method": "GET"}
|
||||
resp = fetch(session, "OPTIONS", base + plan.get("cors_path", "/"), headers)
|
||||
return [_verdict(
|
||||
("api", "cors-reflect", base), resp, _cors_open(resp.headers),
|
||||
("foreign origin reflected with credentials",
|
||||
"foreign origin not reflected with credentials"))]
|
||||
|
||||
|
||||
def _burst_codes(session, url, method, body, count):
|
||||
data = body.encode() if body else None
|
||||
codes = []
|
||||
for _ in range(count):
|
||||
if session.budget <= 0:
|
||||
break
|
||||
codes.append(fetch(session, method, url, None, data).status)
|
||||
return codes
|
||||
|
||||
|
||||
def _rate_verdict(target, codes):
|
||||
sent = len([c for c in codes if c is not None])
|
||||
throttled = 429 in codes
|
||||
note = (f"sent {sent}, {'got a 429' if throttled else 'no 429'}: "
|
||||
+ ("throttled" if throttled else "no 429 seen on this route"))
|
||||
return Probe("hosting", "rate-limit",
|
||||
"CLOSED" if throttled else "OPEN", target, note)
|
||||
|
||||
|
||||
def probe_rate_limit(session, plan):
|
||||
cfg = plan.get("rate_limit")
|
||||
if not cfg:
|
||||
return []
|
||||
target = plan["base_url"].rstrip("/") + cfg["path"]
|
||||
codes = _burst_codes(
|
||||
session, target, cfg.get("method", "GET").upper(),
|
||||
cfg.get("body"), min(cfg.get("count", 20), BURST_CAP))
|
||||
return [_rate_verdict(target, codes)]
|
||||
|
||||
|
||||
PROBES = (probe_supabase, probe_cross_user, probe_routes,
|
||||
probe_cors, probe_rate_limit)
|
||||
|
||||
|
||||
def run_probes(session, plan):
|
||||
results = []
|
||||
for probe in PROBES:
|
||||
results += probe(session, plan)
|
||||
return results
|
||||
|
||||
|
||||
def _tally(results):
|
||||
return {v: sum(p.verdict == v for p in results)
|
||||
for v in ("OPEN", "CLOSED", "SKIPPED", "ERROR")}
|
||||
|
||||
|
||||
def _probe_row(probe):
|
||||
return (f" {probe.verdict:<8} {probe.domain:<9} {probe.id} "
|
||||
f"{probe.target}\n {probe.message}")
|
||||
|
||||
|
||||
def _summary(results):
|
||||
counts = _tally(results)
|
||||
return f"\nopen: {counts['OPEN']} " + ", ".join(
|
||||
f"{v} {n}" for v, n in counts.items())
|
||||
|
||||
|
||||
def _render_text(plan, results):
|
||||
body = [_probe_row(p) for p in results]
|
||||
head = [f"guardrails live probe: {plan['base_url']}",
|
||||
f"probes: {len(results)} (read-only, bounded budget)"]
|
||||
return "\n".join(head + [""] + body + [_summary(results)])
|
||||
|
||||
|
||||
def _render_json(plan, results):
|
||||
return json.dumps({
|
||||
"base_url": plan["base_url"],
|
||||
"open": _tally(results)["OPEN"],
|
||||
"probes": [p.as_dict() for p in results],
|
||||
}, indent=2)
|
||||
|
||||
|
||||
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"
|
||||
return plan, ""
|
||||
|
||||
|
||||
def _plan_error(plan):
|
||||
method = plan.get("rate_limit", {}).get("method", "GET").upper()
|
||||
if method not in READ_METHODS and method != "POST":
|
||||
return f"rate_limit method {method} is not a probe method"
|
||||
return ""
|
||||
|
||||
|
||||
def parse_args(argv):
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
parser.add_argument("plan", help="path to the probe plan JSON")
|
||||
parser.add_argument(
|
||||
"--authorized", action="store_true",
|
||||
help="confirm you own the target and may test it (required)")
|
||||
parser.add_argument("--json", action="store_true", help="JSON output")
|
||||
return parser.parse_args(argv)
|
||||
|
||||
|
||||
def main(argv):
|
||||
args = parse_args(argv)
|
||||
plan, error = _load_plan(args.plan)
|
||||
error = error or _plan_error(plan or {})
|
||||
if error:
|
||||
print(f"usage error: {error}", file=sys.stderr)
|
||||
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)
|
||||
return 2
|
||||
results = run_probes(Session(), plan)
|
||||
render = _render_json if args.json else _render_text
|
||||
print(render(plan, results))
|
||||
return 1 if any(p.verdict == "OPEN" for p in results) else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
@@ -0,0 +1,251 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Static guardrails scan: API, hosting, a11y, Supabase, messaging, functions.
|
||||
|
||||
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.
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from collections import Counter
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
|
||||
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)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
@@ -0,0 +1,8 @@
|
||||
[
|
||||
{"id": 1, "prompt": "Vérifie que la RLS est bien activée partout sur mon projet Supabase dans ~/Documents/game et qu'aucune clé service_role n'est côté client.", "expected": "Runs the scanner on the path, reads each supabase FAIL and WARN in context, gives the live RLS queries as a manual step, writes .claude/audits/GUARDRAILS.md, does not fix anything"},
|
||||
{"id": 2, "prompt": "teste les garde-fous sur ce projet, il envoie des emails et des SMS de relance", "expected": "Scans messaging and api, checks consent record, unsubscribe link, List-Unsubscribe and STOP handling, traces the opt-out path from the provider webhook, lists the dashboard items as MANUAL"},
|
||||
{"id": 3, "prompt": "Audit my Firebase functions: can any of them loop on itself or run up the bill?", "expected": "Scans functions domain only, reports max instances status and any trigger that writes its own collection, MANUAL item for a budget alert wired to an automatic stop, no live call to the provider"},
|
||||
{"id": 4, "prompt": "est-ce que les mots de passe sont stockés en clair quelque part dans ~/Documents/zenquality ?", "expected": "Runs the scanner's api domain, reads every API-PASSWORD-* hit in context, traces the sign-up and password-change write points to the password_hash column by hand, names the hashing function found, reports with file:line, fixes nothing"},
|
||||
{"id": 5, "prompt": "teste les garde-fous sur ~/Documents/game puis sonde-le en direct, le dev tourne sur http://localhost:5173", "expected": "Runs the static scan first, then builds a probe plan from the findings, exports test keys from the environment, runs probe.py --authorized against the localhost target only, reports OPEN verdicts next to the matching static FAIL, never writes data, never probes a target the user did not name"},
|
||||
{"id": 6, "prompt": "corrige les garde-fous qui échouent sur ~/Documents/faunosteo, je veux valider chaque correction avant", "expected": "Scans and judges, proposes numbered fixes with risks and visible choices, stops for approval, applies only the accepted ones on a bugfix branch through a contract whose oracles are scan.py --assert-absent, runs the verify-secure gates, re-scans against the baseline, reports fixed and still open, waits for a go before committing"}
|
||||
]
|
||||
Reference in new issue
Block a user