feat(guardrails): secure-by-default rule and /guardrails scanner

Always-on rules/secure-by-default.md: hosting, a11y, Supabase RLS,
SMS/email consent, cloud functions, API hygiene incl. password storage.
Stdlib scanner (FAIL/WARN/MANUAL) + skill, 89-check suite, auditor
gate wiring, profiles, routing row (plus Explore rows confirmed
through the router dialog).
This commit is contained in:
bchanot committed 2026-10-18 18:10:20 +02:00
1 parent c5fad5ee8f
commit 558c49e1a1
45 files changed
+2473 -5

No files matched your search

+1
View File
@@ -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. Suite: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule).
- **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).
+1 -1
View File
@@ -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
+1
View File
@@ -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` |
| `/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 |
+2
View File
@@ -120,6 +120,7 @@ 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) | `/guardrails` |
| Changer profil skills | `/profile` |
| Audit/polish design (anti-slop) | `/impeccable` |
| Sweep groupé tous axes (nettoyage + sécu + reconcile + doc) | `/tour` |
@@ -163,6 +164,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 puis jugement ; rapport `.claude/audits/GUARDRAILS.md` |
| `/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
View File
@@ -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 |
+9 -2
View File
@@ -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.).
+1
View File
@@ -5,6 +5,7 @@
# Security
cso
harden personal
guardrails personal
analyze personal
# SEO / GEO / web standards
+1
View File
@@ -26,6 +26,7 @@ codex
# Security + health (always relevant for backend)
cso
guardrails personal
health
# Session hygiene
+1
View File
@@ -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
+1
View File
@@ -45,6 +45,7 @@ seo personal
geo personal
web-validate personal
harden personal
guardrails personal
analyze personal
cso
+1
View File
@@ -46,6 +46,7 @@ seo personal
geo personal
web-validate personal
harden personal
guardrails personal
analyze personal
cso
+1
View File
@@ -33,6 +33,7 @@ seo personal
geo personal
web-validate personal
harden personal
guardrails personal
analyze personal
# === Perf + canary ===================================================
+2
View File
@@ -0,0 +1,2 @@
SUPABASE_URL=
SUPABASE_ANON_KEY=
@@ -0,0 +1,2 @@
.env
node_modules
+6
View File
@@ -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.
+1
View File
@@ -0,0 +1 @@
{ "functions": { "source": "functions" } }
+8
View File
@@ -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 });
});
+1
View File
@@ -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>
);
}
+11
View File
@@ -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;
}
+5
View File
@@ -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 });
}
+13
View File
@@ -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);
+1
View File
@@ -0,0 +1 @@
{ "headers": [] }
+281
View File
@@ -0,0 +1,281 @@
#!/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 "== 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 ]
+5 -2
View File
@@ -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",
+53
View File
@@ -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.
## 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.
+82
View File
@@ -0,0 +1,82 @@
---
name: guardrails
effort: high
description: 'Use when auditing a project against the baseline guardrails: 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. 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". 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]'
---
# /guardrails
Checks a project against `rules/secure-by-default.md`. A scanner reads the
tree as data and finds what text can prove. This skill then judges the hits,
covers what text cannot prove, and lists what only a dashboard can set.
The scanner proves absence of a protection, never presence of security. A
clean scan means "no static finding", and the report says exactly that.
## 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.
## 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: 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, and never claim a MANUAL item done.
## STEP 6: 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". Keep it short; no filler sections.
## STEP 7: Hand over
Reply with counts, the FAILs with file:line and a one-line fix each, and the
MANUAL items. This skill audits; it does not fix. A fix goes through
`/bugfix`, `/feat` or `/hotfix`.
+155
View File
@@ -0,0 +1,155 @@
# 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.
@@ -0,0 +1 @@
"""Static guardrail checks, one module per domain."""
+239
View File
@@ -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
+173
View File
@@ -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))
]
+163
View File
@@ -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
+101
View File
@@ -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)
]
+129
View File
@@ -0,0 +1,129 @@
#!/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.
"""
import argparse
import json
import sys
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}
@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")
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 _usage_error(path, names):
unknown = [n for n in names if n not in DOMAINS]
if unknown:
return f"unknown domain {unknown}"
return "" if Path(path).is_dir() else f"not a directory: {path}"
def _scan(args):
project = Project(Path(args.path), _split(args.exclude))
result = run_checks(project, _split(args.domain))
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
def main(argv):
args = parse_args(argv)
error = _usage_error(args.path, _split(args.domain))
if error:
print(f"usage error: {error}", file=sys.stderr)
return 2
return _scan(args)
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
+6
View File
@@ -0,0 +1,6 @@
[
{"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"}
]