@aegis-scan/skills 0.1.1 → 0.2.1

package/skills/compliance/aegis-native/brutaler-anwalt/references/vertragsrecht.md

@@ -0,0 +1,243 @@
+# Vertragsrecht & AGB — Referenz (Deutschland)
+
+> Lade diese Datei bei: AGB-Prüfung, Softwareverträgen, SaaS-Verträgen, Kündigung, Gewährleistung, Haftungsbegrenzung, Verbraucherrecht, B2B-Verträgen, Mängeln, Schadensersatz.
+
+---
+
+## Primäre Rechtsquellen
+
+| Gesetz | Volltext | Relevanz |
+|--------|---------|---------|
+| **BGB** (Bürgerliches Gesetzbuch) | https://www.gesetze-im-internet.de/bgb/ | Grundlage aller Schuldverhältnisse |
+| **HGB** (Handelsgesetzbuch) | https://www.gesetze-im-internet.de/hgb/ | Kaufmännischer Geschäftsverkehr |
+| **AGBG** (in BGB integriert) | BGB §§ 305-310 | AGB-Recht |
+| **VerbrRRL** Umsetzung | BGB §§ 312 ff. | Verbrauchervertragsrecht, Widerrufsrecht |
+| **Digitale-Inhalte-Richtlinie** | BGB §§ 327 ff. | Software, Apps, digitale Inhalte (seit 2022) |
+| **PRIS** / Preisangabenverordnung | https://www.gesetze-im-internet.de/pangv/ | Preisangaben gegenüber Verbrauchern |
+| **ProdHaftG** | https://www.gesetze-im-internet.de/prodhaftg/ | Produkthaftung (inkl. Software seit 2024) |
+
+---
+
+## AGB-Recht (BGB §§ 305-310)
+
+### Was sind AGB?
+Vorformulierte Vertragsbedingungen, die für eine Vielzahl von Verträgen gestellt werden (§ 305 Abs. 1 BGB).
+- Auch "Nutzungsbedingungen", "Terms of Service", "Allgemeine Geschäftsbedingungen", "Lizenzbedingungen" sind AGB
+- Gilt auch für einmalig verwendete Klauseln, wenn erkennbar vorformuliert (bei B2C)
+
+### Einbeziehungsvoraussetzungen (§ 305 Abs. 2 BGB)
+- Ausdrücklicher **Hinweis** auf AGB bei Vertragsschluss
+- **Möglichkeit der Kenntnisnahme** (Link/Anhang reicht; physische Übergabe nicht zwingend)
+- **Einverständnis** des Vertragspartners (aktives Anklicken empfohlen)
+
+### Wichtige Verbote
+
+#### Klauselverbote ohne Wertungsmöglichkeit (§ 309 BGB) — immer unwirksam bei B2C
+- Kurzfristige Preiserhöhungen (§ 309 Nr. 1)
+- Rücktrittsvorbehalte ohne Grund (§ 309 Nr. 3)
+- Abtretungsverbote (§ 309 Nr. 13)
+- Haftungsausschluss für Körperschäden (§ 309 Nr. 7a)
+- Haftungsausschluss für grobe Fahrlässigkeit (§ 309 Nr. 7b)
+
+#### Klauselverbote mit Wertungsmöglichkeit (§ 308 BGB)
+- Unangemessen lange Lieferfristen (§ 308 Nr. 1)
+- Unzumutbar lange Annahmeverweigerungsfristen (§ 308 Nr. 2)
+- Automatische Vertragsverlängerung > 1 Jahr (§ 308 Nr. 3) — **bei B2C!**
+- Vorbehalt wesentlicher Leistungsänderungen (§ 308 Nr. 4)
+
+#### Generalklausel (§ 307 BGB) — gilt auch B2B
+- Klauseln, die **unangemessen benachteiligen**
+- Verstoß gegen wesentliche Grundgedanken der gesetzlichen Regelung
+- Einschränkung wesentlicher Rechte/Pflichten, die Vertragszweck gefährdet
+
+### B2B vs. B2C — Wichtige Unterschiede
+| Aspekt | B2C (§§ 307-309 BGB) | B2B (§ 307 BGB) |
+|--------|---------------------|----------------|
+| Prüfungsmaßstab | Streng | Milder |
+| § 308, 309 Verbote | Direkt anwendbar | Nur Indizwirkung |
+| Haftungsausschluss grobe Fahrlässigkeit | Unwirksam | Eingeschränkt möglich |
+| Gewährleistungsausschluss | Sehr begrenzt | Weitgehend möglich |
+| Verkürzung Verjährung | Max. 1 Jahr | Auf 1 Jahr möglich |
+
+---
+
+## Vertragstypen im IT-Bereich
+
+### Softwarekauf — Kaufrecht (BGB §§ 433 ff.)
+**Wann:** Dauerhafte Überlassung von Standardsoftware (Download, physisch)
+
+**Mängelrechte (§ 437 BGB):**
+1. Nacherfüllung (Reparatur oder Ersatz) — Vorrang
+2. Rücktritt oder Minderung (nach gescheiterter Nacherfüllung)
+3. Schadensersatz oder Aufwendungsersatz
+
+**Verjährung:** 2 Jahre ab Lieferung (§ 438 BGB); bei arglistigem Verschweigen: 3 Jahre
+
+**Digitale Inhalte (seit 2022, §§ 327 ff. BGB):**
+- Gilt für Software, Apps, eBooks, Streaming
+- Aktualisierungspflicht: Anbieter muss Updates bereitstellen, die für Vertragsgemäßheit nötig sind
+- Gilt auch für "kostenlose" Dienste, bei denen Daten die Gegenleistung sind
+
+### SaaS / Cloud — Mietrecht (BGB §§ 535 ff.)
+**Wann:** Zeitlich begrenzte Nutzung (Abo-Modell, Pay-per-Use)
+
+**Pflichten des Anbieters:**
+- Taugliche Überlassung über gesamte Mietzeit (§ 535 Abs. 1 BGB)
+- Mängelbeseitigung ohne Ankündigungsfrist bei erheblichem Mangel
+
+**Mängelrechte des Nutzers:**
+- Mietminderung (§ 536 BGB) — automatisch, keine Anzeige nötig
+- Kündigung bei erheblichem Mangel (§ 543 BGB)
+- Schadensersatz (§ 536a BGB) — bei anfänglichem Mangel ohne Verschulden!
+
+**Kündigung:**
+- Ordentlich: Vertragliche Regelungen; subsidiär §§ 580a, 565 BGB
+- Außerordentlich: § 543 BGB (wichtiger Grund)
+
+**SLA-Klauseln:** Downtime-Regelungen, Wartungsfenster, Response Times — AGB-rechtlich prüfen!
+
+### Individualentwicklung — Werkvertragsrecht (BGB §§ 631 ff.)
+**Wann:** Erstellung maßgeschneiderter Software
+
+**Abnahme (§ 640 BGB):**
+- Pflicht zur Abnahme bei mangelfreier Leistung
+- Keine Abnahme bei wesentlichen Mängeln
+- Fiktive Abnahme nach Fristablauf möglich (§ 640 Abs. 2 BGB)
+- **Tipp:** Abnahmeprotokoll schriftlich festhalten
+
+**Nach Abnahme:**
+- Gefahr geht auf Besteller über
+- Verjährung beginnt zu laufen
+
+**Mängelrechte nach Abnahme (§ 634 BGB):**
+1. Nacherfüllung (§ 635) — Vorrang, 2 Versuche angemessen
+2. Selbstvornahme + Kostenersatz (§ 637) — nach gescheiterter Nacherfüllung
+3. Rücktritt oder Minderung (§§ 636, 638) — nach gescheiterter Nacherfüllung
+4. Schadensersatz (§ 636 i.V.m. §§ 280 ff.)
+
+**Verjährung:** 2 Jahre ab Abnahme (§ 634a Abs. 1 Nr. 1 BGB)
+
+### Pflege- und Wartungsvertrag
+- Meist Dienstvertrag (kein Erfolg geschuldet) oder Werkvertrag (konkrete Updates)
+- **Klarheit schaffen:** Was genau ist Pflegeinhalt? Reaktionszeiten? SLAs?
+- Kündigung: Dienstvertrag § 621 BGB (fristgerecht); Werkvertrag § 649 BGB (jederzeit, aber Vergütung fällig)
+
+---
+
+## Haftungsbegrenzungen — Was ist möglich?
+
+### Gesetzliche Grenzen (unveränderlich)
+- **Kein Ausschluss** bei Vorsatz (§ 276 Abs. 3 BGB)
+- **Kein Ausschluss** bei grober Fahrlässigkeit und Körper-/Gesundheitsschäden (§ 309 Nr. 7 BGB bei B2C)
+- **Produkthaftung** (ProdHaftG) ist zwingend — kein Ausschluss möglich
+- **DSGVO-Haftung** (Art. 82) kann nicht durch AGB ausgeschlossen werden
+
+### Was geht (B2B)?
+- Haftungsausschluss für einfache Fahrlässigkeit (außer Kardinalpflichten)
+- Haftungshöchstbeträge (z.B. auf Vertragswert begrenzt)
+- Ausschluss mittelbarer Schäden / entgangener Gewinn (mit Einschränkungen)
+- Verkürzung Verjährung auf 1 Jahr (nicht bei Arglist)
+
+### Was geht (B2C)?
+- Sehr begrenzt: Ausschluss nur bei leichter Fahrlässigkeit + Nicht-Kardinalpflicht + kein Körperschaden
+- Haftungshöchstbeträge: Nur wenn angemessen
+- Praktisch: Fast keine sinnvolle Haftungsbegrenzung gegenüber Verbrauchern möglich
+
+---
+
+## Gewährleistung vs. Garantie
+
+| Begriff | Basis | Inhalt |
+|---------|-------|--------|
+| **Gewährleistung** | Gesetzlich (BGB) | Pflicht, Mängel zu beseitigen — unverzichtbar bei B2C |
+| **Garantie** | Freiwillig (vertraglich) | Zusätzliche Versprechen (24-Monate-Garantie etc.) |
+
+**Verjährungsfristen Gewährleistung:**
+- B2C Kauf: 2 Jahre (§ 438 Abs. 1 Nr. 3 BGB) — nicht verkürzbar
+- B2B Kauf: 2 Jahre — auf 1 Jahr verkürzbar per AGB
+- Werk: 2 Jahre ab Abnahme — auf 1 Jahr verkürzbar per AGB (B2B)
+- Arglist: 3 Jahre (kenntnisabhängig, § 199 BGB)
+
+---
+
+## Widerrufsrecht (B2C, §§ 312 ff. BGB)
+
+### Wann gilt es?
+- Fernabsatzverträge (Online, Telefon) mit Verbrauchern
+- **14 Tage** ab Vertragsschluss oder Erhalt der Ware
+
+### Ausnahmen (§ 312g Abs. 2 BGB)
+- Digitale Inhalte (Software, Downloads): Kein Widerruf, wenn Ausführung mit Zustimmung begonnen
+- Maßgeschneiderte Waren/Leistungen
+- Versiegelte Waren nach Öffnung
+
+### Widerrufsbelehrung
+- Muss klar und deutlich vor Vertragsschluss bereitgestellt werden
+- Fehler → Widerrufsfrist verlängert sich auf 12 Monate + 14 Tage (§ 356 Abs. 3 BGB)
+- Muster: Anlage 1 zu Art. 246a § 1 Abs. 2 S. 2 EGBGB
+
+---
+
+## Preisangaben (PAngV / § 5a UWG)
+
+### Pflichten gegenüber Verbrauchern
+- **Endpreis** inkl. MwSt. und sonstiger Preisbestandteile
+- **Grundpreis** bei Waren nach Gewicht/Volumen/Länge/Fläche
+- Preisangabe vor Vertragsschluss, nicht erst im Checkout
+- Fake-Rabatte verboten: Rabatt nur auf tatsächlichen Vorpreis
+
+### Besonderheiten SaaS / Abonnements
+- Gesamtkosten der Mindestlaufzeit angeben
+- Automatische Verlängerung transparent machen
+- Preiserhöhungen: Rechtzeitige Information + Kündigungsrecht
+
+---
+
+## Vertragliche Besonderheiten bei Fremdentwicklern / Freelancern
+
+### Scheinselbstständigkeit (§ 7 SGB IV)
+- Auftraggeber trägt Risiko bei Scheinselbstständigkeit (Nachzahlung Sozialversicherung!)
+- Prüfkriterien: Weisungsgebundenheit, Integration in Organisation, eigenes Unternehmerrisiko
+- **Statusfeststellungsverfahren** beim Rentenversicherungsträger möglich
+
+### IP-Übertragung / Nutzungsrechte
+- Ohne Regelung: Entwickler behält alle Rechte!
+- Im Vertrag klarstellen: Umfang der Nutzungsrechte, exklusiv vs. nicht-exklusiv
+- Quellcode-Übergabe explizit vereinbaren
+- Nutzungsrechte für Dritte (z.B. Kunden des Auftraggebers) separat einräumen lassen
+
+### Vertraulichkeit / NDA
+- Gegenseitiges NDA vor Projektbeginn empfehlenswert
+- Vertragsstrafe für Verstöße vereinbaren
+- Ausnahmen: öffentlich bekannte Informationen, gesetzliche Offenlegungspflichten
+
+---
+
+## Checkliste: Wichtige Klauseln im IT-Vertrag
+
+### Essentialia (Pflichtinhalt)
+- [ ] Leistungsgegenstand präzise beschrieben (Lastenheft / Pflichtenheft)
+- [ ] Vergütung und Zahlungsbedingungen
+- [ ] Laufzeit und Kündigung
+- [ ] Abnahme- und Lieferkonditionen
+
+### Empfohlene Klauseln
+- [ ] Gewährleistung und Haftung (unter Beachtung AGB-Recht)
+- [ ] Datenschutz und AVV-Verweis
+- [ ] Vertraulichkeit / NDA
+- [ ] Nutzungsrechte / IP-Übertragung
+- [ ] Eskalations- und Änderungsmanagement (Change Request Prozess)
+- [ ] SLA / Verfügbarkeitsgarantien
+- [ ] Subunternehmer-Regelung
+- [ ] Audit- und Kontrollrechte
+- [ ] Exportkontrolle (bei internationalen Projekten)
+- [ ] Gerichtsstand und anwendbares Recht (bei internationalen Verträgen)
+- [ ] Schriftformklausel / Textformklausel
+
+### Häufige Fallen
+- ❌ Zu weite Haftungsfreizeichnungen (unwirksam nach AGB-Recht)
+- ❌ Unklare Abnahmeregelungen (Abnahme wird nie formal erklärt)
+- ❌ Fehlende IP-Klausel (Entwickler behält Rechte)
+- ❌ Automatische Verlängerung mit sehr langer Kündigungsfrist (§ 308 Nr. 3 BGB bei B2C)
+- ❌ Preiserhöhungsklausel ohne Kündigungsrecht (unwirksam bei B2C)
+- ❌ Kein Change-Request-Verfahren (führt zu Streit über Mehraufwand)

package/skills/defensive/README.md

@@ -1,8 +1,37 @@
-# Defensive Skills
+# Defensive Skills — `defensive/`
 
-Reserved for AEGIS-native defensive skill modules in `skills-v0.2+`.
-Mirrors wizard-cli security patterns into SKILL.md format for agent
-consumption. Content lands in a future release.
+Defensive-security methodology skills for AI coding agents (Claude Code,
+Cursor, etc.). Each skill is a self-contained `SKILL.md` with YAML
+frontmatter that the agent auto-loads when its trigger-keywords match a
+user prompt.
+
+## Sources
+
+| Source dir | License | Skills |
+|---|---|---|
+| `aegis-native/` | MIT (AEGIS-original) | 3 |
+
+## AEGIS-native skills
+
+These skills are AEGIS-original content, mirroring patterns from
+`@aegis-wizard/cli`'s pattern library and remediation guidance for
+`@aegis-scan/cli` scanner findings.
+
+| Skill | Addresses scanner findings |
+|---|---|
+| `rls-defense` | `rls-bypass-checker` (CWE-863), `template-sql-checker` (CWE-89) |
+| `tenant-isolation-defense` | `tenant-isolation-checker` (CWE-639), `mass-assignment-checker` (CWE-915) |
+| `ssrf-defense` | `ssrf-checker` (CWE-918), `taint-analyzer` (CWE-918) |
+
+License: MIT. See top-level [`ATTRIBUTION.md`](../../ATTRIBUTION.md) for
+attribution chain.
+
+## Roadmap
+
+Future expansions in this category may include:
+
+- Cherry-picks from external CC BY-SA / Apache-2.0 / MIT defensive-skill libraries (per the maintainer's source-evaluation cycle).
+- Additional AEGIS-native skills covering the remaining defensive scanner family (csrf-defense, header-defense, prompt-injection-defense, secret-management-defense, supply-chain-defense, etc.).
 
 The broader skill-ecosystem roadmap is maintained in the repository's
 internal planning tree; ask the maintainer for access if you are

package/skills/defensive/aegis-native/rls-defense/SKILL.md

@@ -0,0 +1,174 @@
+<!-- aegis-local: AEGIS-native skill, MIT-licensed; mirrors @aegis-wizard/cli RLS-defense pattern + addresses AEGIS scanner findings: rls-bypass-checker (CWE-863), tenant-isolation-checker (CWE-639). -->
+
+---
+name: defensive-rls-defense
+description: "Supabase Row-Level Security (RLS) hardening methodology. Covers RLS policy design, auth.uid() vs auth.jwt(), service-role-key safety, .rpc() function security, AEGIS rls-bypass-checker remediation, multi-tenant isolation patterns, defensive defaults, regression test patterns, and incident-response when RLS is bypassed. Use when designing or auditing Supabase schemas, fixing rls-bypass-checker findings, hardening multi-tenant SaaS applications, or responding to suspected cross-tenant data leakage."
+---
+
+# RLS Defense — Supabase Row-Level Security Methodology
+
+## When to use this skill
+
+- Designing a new Supabase project — set up RLS correctly from commit 0.
+- Reviewing an existing schema — verify RLS policies actually enforce isolation.
+- Fixing AEGIS `rls-bypass-checker` (CWE-863) or `tenant-isolation-checker` (CWE-639) findings.
+- Responding to suspected cross-tenant data leakage incidents.
+- Hardening before a security audit (SOC 2 / ISO 27001 / PCI-DSS).
+
+## The core invariant
+
+**Every table that holds user-scoped or tenant-scoped data MUST have RLS enabled AND at least one policy that bounds visibility to the requesting user/tenant.** Tables without RLS are a critical exposure; tables with RLS but no policies are equally critical (RLS-enabled-without-policy denies everything but is easy to reverse with a wildcard policy that opens the door).
+
+## Defensive design checklist
+
+### 1. RLS-enabled-by-default discipline
+
+```sql
+-- Enable RLS on every table that holds user/tenant data
+ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.tenants ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;
+
+-- Verify after every migration
+SELECT tablename, rowsecurity FROM pg_tables WHERE schemaname = 'public';
+-- Every row should show rowsecurity = true (except for purely-public reference tables)
+```
+
+### 2. Policy patterns that actually isolate
+
+**Owner-scoped (user owns rows):**
+
+```sql
+CREATE POLICY "Users see only their own rows"
+ON public.documents FOR SELECT
+USING (auth.uid() = user_id);
+
+CREATE POLICY "Users insert only with their own user_id"
+ON public.documents FOR INSERT
+WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Users update only their own rows"
+ON public.documents FOR UPDATE
+USING (auth.uid() = user_id)
+WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Users delete only their own rows"
+ON public.documents FOR DELETE
+USING (auth.uid() = user_id);
+```
+
+**Tenant-scoped (multi-tenant isolation):**
+
+```sql
+-- Pattern: tenant_id flows through profiles → all tables
+CREATE POLICY "Tenant-scoped read"
+ON public.invoices FOR SELECT
+USING (
+  tenant_id IN (
+    SELECT tenant_id FROM public.profiles
+    WHERE profiles.id = auth.uid()
+  )
+);
+
+-- Same shape for INSERT/UPDATE/DELETE with WITH CHECK on tenant_id.
+```
+
+### 3. Anti-patterns that break isolation
+
+**Avoid `auth.jwt() ->> 'role'` for authorization decisions** — JWTs are operator-controllable and the token's claim can be spoofed if your `service_role` ever reaches client-side code.
+
+**Avoid `service_role` keys in API routes that handle user input** — `service_role` bypasses RLS entirely. Every API route that uses `service_role` needs hand-rolled authorization to replace what RLS would have enforced.
+
+**Avoid `.rpc()` with template-literal function names**:
+
+```typescript
+// BAD: function name is interpolated, attacker can rename target function
+await supabase.rpc(`get_${userInput}`, params)
+
+// GOOD: function name is a literal
+await supabase.rpc('get_user_documents', { user_id: validatedId })
+```
+
+The `template-sql-checker` and `rls-bypass-checker` flag both shapes; this skill is the remediation methodology.
+
+### 4. RPC function security
+
+PostgreSQL functions can run with `SECURITY DEFINER` (run as definer's role, often superuser) or `SECURITY INVOKER` (run as caller's role, default).
+
+```sql
+-- DEFAULT — function runs as caller, RLS applies
+CREATE FUNCTION public.get_user_docs()
+RETURNS SETOF documents
+LANGUAGE sql
+SECURITY INVOKER  -- explicit, even if default
+AS $$
+  SELECT * FROM documents WHERE user_id = auth.uid();
+$$;
+
+-- SECURITY DEFINER ONLY when you need to break RLS for a specific elevated operation
+-- AND every parameter is pre-validated
+CREATE FUNCTION public.admin_audit_logs(target_user uuid)
+RETURNS SETOF audit_log
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public  -- prevent search-path-poisoning
+AS $$
+BEGIN
+  -- Hand-rolled authorization check because RLS is bypassed
+  IF NOT EXISTS (
+    SELECT 1 FROM profiles
+    WHERE id = auth.uid() AND role = 'admin'
+  ) THEN
+    RAISE EXCEPTION 'unauthorized';
+  END IF;
+
+  RETURN QUERY SELECT * FROM audit_log WHERE user_id = target_user;
+END;
+$$;
+```
+
+**SECURITY DEFINER without `SET search_path` is a search-path-poisoning vulnerability** — the function inherits the caller's search_path and an attacker who can prepend their own schema can hijack the function.
+
+### 5. Defensive testing — every policy needs a regression test
+
+```sql
+-- Test as user A
+SET LOCAL ROLE authenticated;
+SET LOCAL request.jwt.claim.sub = 'user-a-uuid';
+
+SELECT count(*) FROM documents;  -- should equal A's row count, not all rows
+
+SET LOCAL request.jwt.claim.sub = 'user-b-uuid';
+SELECT count(*) FROM documents;  -- should equal B's row count, NOT A's
+```
+
+Wire this into your test suite. AEGIS doesn't run live SQL tests, but `tenant-isolation-checker` and `rls-bypass-checker` flag the patterns at code-review time.
+
+## Incident response — RLS bypassed
+
+Order of operations:
+
+1. **Disclose internally** — RLS bypass = potential data breach; engage legal + DPO immediately.
+2. **Stop the bleeding** — disable the affected route or endpoint at the gateway level (Vercel / Cloudflare / load balancer) BEFORE patching code.
+3. **Audit log forensics** — Supabase logs every RLS-context query; pull the affected window's logs to bound the exposure.
+4. **Determine reach** — for each suspect query, identify the rows visible to each user-context vs the rows the user should have seen.
+5. **Patch and re-deploy** — fix the policy, re-deploy, verify with regression tests.
+6. **Notify affected users** — per GDPR Art. 33 within 72 hours of becoming aware.
+
+## How AEGIS scanners help
+
+| Scanner | What it catches |
+|---|---|
+| `rls-bypass-checker` (CWE-863) | `service_role` usage in API routes, `.rpc()` template-injection patterns |
+| `tenant-isolation-checker` (CWE-639) | Supabase queries missing `tenant_id` filter |
+| `template-sql-checker` (CWE-89) | Template-literal SQL injection in `.rpc()` / `.execute()` / `.query()` / `.$queryRawUnsafe()` |
+| `mass-assignment-checker` (CWE-915) | Unvalidated `request.json()` flowing into `.insert()` |
+| `auth-enforcer` (CWE-285, 306) | API routes without auth guards |
+
+Run `aegis scan .` on your repo; fix everything `rls-bypass-checker` and `tenant-isolation-checker` flag before going to production.
+
+## See also
+
+- AEGIS scaffold's RLS bootstrap migration — `aegis new <project>` ships a `tenants` + `profiles` table + auto-profile-on-signup trigger pre-wired.
+- AEGIS patterns library — `docs/patterns/index.md` documents the multi-tenant Supabase pattern catalog.
+- Upstream Supabase docs — https://supabase.com/docs/guides/auth/row-level-security

package/skills/defensive/aegis-native/ssrf-defense/SKILL.md

@@ -0,0 +1,179 @@
+<!-- aegis-local: AEGIS-native skill, MIT-licensed; mirrors @aegis-wizard/cli ssrf-defense pattern + addresses AEGIS scanner finding: ssrf-checker (CWE-918). -->
+
+---
+name: defensive-ssrf
+description: "Server-Side Request Forgery (SSRF) defense methodology. Covers RFC 1918 / link-local block-rules, allowlist-vs-denylist trade-offs, DNS rebinding defense, IPv6 considerations, cloud metadata-endpoint protection (AWS / GCP / Azure), proxy/redirect handling, AEGIS ssrf-checker remediation, and the SSRF-safe-fetch primitive. Use when designing fetch-from-user-input flows, fixing AEGIS ssrf-checker findings, or hardening SSRF-prone endpoints (image proxies, webhook receivers, OAuth callbacks)."
+---
+
+# SSRF Defense — Server-Side Request Forgery Methodology
+
+## When to use this skill
+
+- Building any feature where the server fetches a URL based on user input (image proxy, link preview, webhook delivery, OAuth callback, profile-picture import, document-rendering service).
+- Fixing AEGIS `ssrf-checker` (CWE-918) findings.
+- Hardening before a security audit, especially in cloud-deployed apps where metadata endpoints (`169.254.169.254`) are reachable.
+
+## The core invariant
+
+**Server-initiated HTTP requests where the URL is user-controlled MUST validate that the resolved IP is in an allowed set BEFORE issuing the request, AND the validation must survive DNS rebinding.**
+
+The "MUST survive DNS rebinding" is what kills naive defenses. An attacker controls a DNS server that returns a public IP on first lookup and a private IP on second lookup; if your code resolves the URL once for validation and again for the fetch, you lose.
+
+## The secure primitive
+
+```typescript
+// lib/security/safeFetch.ts (AEGIS scaffold ships this)
+
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+
+/**
+ * SSRF-safe fetch — validates the resolved IP before issuing the request,
+ * and pins the resolution to defeat DNS rebinding.
+ */
+export async function safeFetch(url: string, init?: RequestInit): Promise<Response> {
+  const parsed = new URL(url);
+
+  // Reject non-HTTP(S) schemes — file://, gopher://, dict://, etc.
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`SSRF: protocol ${parsed.protocol} not allowed`);
+  }
+
+  // Reject if hostname is already an IP literal in a forbidden range
+  if (isIP(parsed.hostname)) {
+    if (isForbiddenIP(parsed.hostname)) {
+      throw new Error(`SSRF: IP ${parsed.hostname} not allowed`);
+    }
+  } else {
+    // Resolve to an IP and verify
+    const { address } = await lookup(parsed.hostname);
+    if (isForbiddenIP(address)) {
+      throw new Error(`SSRF: ${parsed.hostname} → ${address} not allowed`);
+    }
+    // Defeat DNS rebinding — pin the resolved IP and use it for the fetch
+    const pinnedURL = parsed.protocol + '//' + address + parsed.pathname + parsed.search;
+    return fetch(pinnedURL, {
+      ...init,
+      headers: {
+        ...init?.headers,
+        Host: parsed.hostname,  // preserve original hostname for SNI / Host-header routing
+      },
+    });
+  }
+
+  return fetch(url, init);
+}
+
+function isForbiddenIP(ip: string): boolean {
+  // Loopback
+  if (ip.startsWith('127.') || ip === '::1') return true;
+  // Private RFC 1918
+  if (ip.startsWith('10.')) return true;
+  if (/^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(ip)) return true;
+  if (ip.startsWith('192.168.')) return true;
+  // Link-local
+  if (ip.startsWith('169.254.')) return true;
+  if (ip.toLowerCase().startsWith('fe80:')) return true;
+  // Unique local IPv6 (fc00::/7)
+  if (/^f[cd]/i.test(ip)) return true;
+  // Cloud metadata
+  if (ip === '169.254.169.254') return true;  // AWS / GCP / Azure / DO
+  if (ip === '169.254.170.2') return true;  // ECS task metadata
+  // Carrier-grade NAT (RFC 6598)
+  if (/^100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\./.test(ip)) return true;
+  return false;
+}
+```
+
+## Why "just block 169.254.0.0/16" is not enough
+
+Old advice: block 127.0.0.0/8 and 169.254.0.0/16. Modern requirement: also block:
+
+- All RFC 1918 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) — internal services.
+- IPv6 loopback (`::1`) and link-local (`fe80::/10`) and unique-local (`fc00::/7`).
+- Carrier-grade NAT (100.64.0.0/10, RFC 6598) — your cloud may NAT here.
+- The cloud-specific metadata IPs your provider exposes.
+- Any "alias to localhost" hostnames your provider provides (e.g., `localhost`, `0.0.0.0`).
+
+AEGIS's `ssrf-checker` and the scaffold's `safeFetch` cover all of these.
+
+## Anti-patterns
+
+### Anti-pattern 1 — naive allowlist on hostname before resolution
+
+```typescript
+// BROKEN — bypassed by attacker-controlled DNS
+const ALLOWED = ['api.partner.com'];
+if (!ALLOWED.some(h => url.includes(h))) throw new Error('not allowed');
+await fetch(url);  // attacker registers `api.partner.com.attacker.com` — passes the .includes() check
+```
+
+### Anti-pattern 2 — validate-then-fetch (TOCTOU)
+
+```typescript
+// BROKEN — DNS rebinding gap between validate and fetch
+const { address } = await lookup(new URL(url).hostname);
+if (isForbiddenIP(address)) throw new Error('blocked');
+await fetch(url);  // second resolution may now return a private IP
+```
+
+Always **pin the resolved IP** for the actual fetch (see `safeFetch` above).
+
+### Anti-pattern 3 — trusting `fetch` to follow redirects safely
+
+`fetch` follows up to 20 redirects by default. An attacker-controlled allowed URL can redirect to a private IP. Mitigate:
+
+```typescript
+await safeFetch(url, { redirect: 'manual' });
+```
+
+Then if the response is 3xx, re-validate the `Location` header through `safeFetch` before following.
+
+### Anti-pattern 4 — `encodeURIComponent` as SSRF defense
+
+`encodeURIComponent` blocks XSS and SSRF-via-path-traversal (`../`), but it does NOT block SSRF-via-host. A URL like `http://169.254.169.254/latest/meta-data/` survives `encodeURIComponent` of the path component because the host part isn't encoded. The `ssrf-checker` per-CWE sanitizer-awareness logic catches this — `encodeURIComponent` is recognized as an XSS sanitizer but NOT as an SSRF sanitizer.
+
+## Cloud-metadata-endpoint protection
+
+AWS, GCP, Azure, and DigitalOcean all expose internal metadata at `http://169.254.169.254/`. SSRF-to-metadata is the most common cloud breach pattern of the last decade.
+
+AWS specifically provides IMDSv2 which adds a token-handshake — enable IMDSv2 on every instance:
+
+```bash
+# AWS — enforce IMDSv2 (token-required) at instance level
+aws ec2 modify-instance-metadata-options \
+  --instance-id <id> \
+  --http-tokens required \
+  --http-put-response-hop-limit 1
+```
+
+But IMDSv2 is defense-in-depth; the primary defense is still application-level SSRF protection.
+
+## Webhook receivers — special case
+
+Webhooks are RECEIVED rather than initiated, so SSRF doesn't directly apply. But the pattern of "process this URL someone gave us" often does — for example, a webhook may include a callback URL that your server then fetches. Apply the same `safeFetch` discipline.
+
+For OAuth callbacks: the callback URL is operator-configured, not request-controlled, so SSRF doesn't apply. But verify the redirect_uri matches the registered URL exactly (not `startsWith`-style).
+
+## How AEGIS scanners help
+
+| Scanner | What it catches |
+|---|---|
+| `ssrf-checker` (CWE-918) | `fetch(userInput)` patterns; recognizes `safeFetch`, `parseInt`, RFC 1918 / link-local literals, regex-guarded URL filters as sanitizers per per-CWE awareness rules |
+| `taint-analyzer` (CWE-918) | Cross-file taint from request input → `fetch` sink |
+| `open-redirect-checker` (CWE-601) | Sibling pattern — `redirect(userInput)` |
+| `header-checker` (CWE-693) | CSP includes `connect-src` allowlist that limits client-side fetch destinations |
+
+## Incident response — SSRF exploited
+
+1. **Disclose internally** — immediately if the attacker reached the cloud metadata endpoint (potential credential theft).
+2. **Rotate cloud credentials** — assume any IAM credentials reachable via metadata are compromised.
+3. **Audit logs** — pull all outbound fetches from the affected service in the relevant window.
+4. **Patch and re-deploy** — replace the unsafe `fetch` with `safeFetch`.
+5. **Audit similar code paths** — SSRF tends to come in clusters; one finding usually has siblings.
+
+## See also
+
+- AEGIS patterns library — `docs/patterns/index.md` § "Hardened middleware".
+- `aegis-wizard/cli` scaffold — ships `safeFetch` as one of the 11 clean-room security primitives.
+- OWASP SSRF prevention cheat sheet — https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html