# Security-Dokumentation (Threat-Model, Pen-Test, Vuln-Disclosure, IR-Runbook, SBOM) **Status:** completed **Task-ID:** #69 **Phase:** 10 **Estimated Effort:** 1 Woche reine Schreib-Zeit **Owner:** agent/10-security-docs ## Problem Die Boilerplate hat fragmentarische Security-Doku, aber keine kohärente, externer-Stakeholder-präsentable Security-Dokumentation: - **`docs/security/threat-model.md`** existiert nur für Auth-Flows; keine STRIDE-Analyse pro Architektur-Komponente (Web, API, Worker, DB, Plugins, AI-Pipeline, Webhooks) - **Keine Pen-Test-Scope-Doku**: Externe Pen-Tester bekommen keine vordefinierte Scope-Liste; jeder Engagement-Onboarding ist Custom - **Keine Vuln-Disclosure-Policy**: Es gibt keine `/.well-known/security.txt`, keine öffentliche Disclosure-Policy für Security-Researcher - **Keine Bug-Bounty-Doku**: Wenn das Programm aktiviert wird, fehlt die Doku-Foundation - **Kein Incident-Response-Runbook**: `docs/security/runbook.md` existiert aber deckt nicht GDPR-Breach-Notification-Workflow (72h-Frist), keine Severity-Klassifizierung, keine Communication-Templates - **SBOM-Doku** ist nur in `scripts/generate-sbom.mjs` als Code; keine erläuternde Doku wann/wie SBOM generiert/verteilt wird - **`SECURITY.md`** (Root-File) existiert aber verlinkt nicht auf alle Sub-Docs Betroffene Codestellen: - `docs/security/threat-model.md` (erweitern auf ganzheitliche STRIDE-Analyse) - `docs/security/` (neue Dateien) - `scripts/generate-sbom.mjs` (Doku ergänzen) - `SECURITY.md` (Root, Index ergänzen) - `apps/web/public/.well-known/security.txt` (neu erstellen — Web-served) ## Depends on Keine harten Code-Dependencies — reines Doku-Task. **Empfehlenswert vorher:** - `01-tech-debt-foundation/*` — vor Threat-Model-Update sollte die Architektur stabil sein (keine größeren Refactorings mehr während Threat-Model-Diagramm gepflegt wird) - `10-compliance-polish/compliance-audit-export.md` — IR-Runbook referenziert AuditEvent-Hash-Chain für Forensics ## Blocks Keine technischen Blocks. Aber: ohne diese Doku kann kein Enterprise-Sales-Process bestehen (RFP-Security-Questionnaires bleiben unbeantwortbar). Block ist „Sales/Compliance-Readiness" — informeller. ## Approach **Sieben Doku-Files, ein Root-Index-Update:** ### (a) `docs/security/threat-model.md` (erweitern) STRIDE-Analyse pro Komponente: - **Web (apps/web)**: Spoofing (Auth), Tampering (XSS/CSRF), Repudiation (Audit-Logs), Information-Disclosure (Tenant-Isolation-Leaks), Denial-of-Service (Rate-Limiting), Elevation-of-Privilege (Permission-Bypass) - **API (apps/api)**: gleiche Achsen mit API-spezifischen Threats (API-Key-Leakage, Idempotency-Replay, Race-Conditions) - **Worker (apps/worker)**: Job-Tampering, Queue-Poisoning, Side-Effect-Replay - **DB (Postgres)**: SQL-Injection, Tenant-Isolation-via-Row-Level-Security, Backup-Theft - **Plugins (WASM-Sandbox)**: Sandbox-Escape, Capability-Abuse, Resource-Exhaustion - **AI-Pipeline**: Prompt-Injection, Cost-Exhaustion, Data-Leakage in Prompts - **Webhooks**: Spoofed-Signatures, Replay-Attacks, SSRF via Webhook-URL Pro Komponente: - Threats (Liste) - Mitigations (was wird im Code/Infra getan?) - Residual-Risk (was bleibt, akzeptiert?) Datenfluss-Diagramme via Mermaid: - Auth-Flow (User → Web → API → DB) - Stripe-Webhook-Flow - AI-Request-Flow - Plugin-Execution-Flow - DSGVO-Export-Flow ### (b) `docs/security/pen-test-scope.md` Template für externe Pen-Tester: - In-Scope-URLs: `https://app.toolctrl.de`, `https://api.toolctrl.de`, `https://admin.toolctrl.de` - Out-of-Scope: Stripe-Webhook-Endpoints (Stripe-CI-Replay-Tests stattdessen), Marketing-Site, externe Provider (Sentry, Mailjet) - Test-Account-Provision: dediziertes Pen-Test-Tenant mit Test-User-Credentials - Erwartete Test-Klassen: OWASP-Top-10, OWASP-API-Top-10, Tenant-Isolation, Auth-Bypass, IDOR, Privilege-Escalation - Reporting-Format: Markdown mit CVSS-Score pro Finding, PoC-Schritte, Reproduction-Path - Disclosure-Timeline: 90-Tage-Fix-Window, Coordinated-Disclosure mit Vendor - Kontakt: `security@toolctrl.de`, PGP-Key-Fingerprint ### (c) `docs/security/vuln-disclosure-policy.md` Public Vulnerability Disclosure Policy: - Reporting-Channels: `security@toolctrl.de`, PGP-Key, optional HackerOne-/Bugcrowd-Form - Scope: gleicher Scope wie pen-test-scope.md - Out-of-Scope: Social-Engineering, Physical-Access, DoS via Load-Generation, Spam-Reports - Safe-Harbor-Klausel: Forscher die in Good-Faith melden bekommen keine rechtliche Verfolgung - Response-SLA: 48h Acknowledgement, 30d Triage, 90d Fix-or-Disclosure - Hall-of-Fame: Optional Listing von Researchern mit Consent Diese Datei wird auch unter `https://app.toolctrl.de/.well-known/security.txt` ausgeliefert (siehe (h)). ### (d) `docs/security/bug-bounty.md` Bug-Bounty-Skeleton (Stub für späteres Programm): - Reward-Tiers nach CVSS-Score: Critical 5k€, High 2k€, Medium 500€, Low 100€, Informational anerkannt - Eligibility: Erste-Reporter, Out-of-Scope-Bereiche wie in vuln-disclosure-policy.md - Payout-Mechanismus: SEPA, PayPal, optional Crypto - Public Hall-of-Fame - Anti-Abuse: keine Reward für bekannte Issues, kein Duplicate-Reward - Aktivierungs-Status: „Geplant — noch nicht aktiv. Anfragen bitte über vuln-disclosure-policy.md." ### (e) `docs/security/incident-response.md` IR-Runbook mit Severity-Klassifizierung: - **Sev-1**: Data-Breach, Active-Exploit, Production-Down — Response 15min, IR-Team alarmiert via PagerDuty - **Sev-2**: Compromised-Credential, Suspected-Breach — Response 1h - **Sev-3**: Suspicious-Activity, Failed-Audit-Check — Response 4h - **Sev-4**: Low-Risk-Finding, Doku-Issue — Response 1 Business-Day Phasen pro Incident: 1. **Detection** (Sentry-Alerts, Audit-Verifier-Failures, User-Reports) 2. **Triage** (Severity-Bestimmung, IR-Team-Activation) 3. **Containment** (Isolierung der betroffenen Komponente, ggf. Feature-Flag-Disable, Token-Invalidation) 4. **Eradication** (Root-Cause-Fix, Patch-Deploy) 5. **Recovery** (Service-Restore, Verification) 6. **Lessons Learned** (Post-Mortem in `docs/security/incidents/-.md`) **GDPR-Breach-Notification-Workflow** (separate Section): - 72h-Frist nach Becoming-Aware (Art. 33) - Aufsichtsbehörde-Notification-Template (BfDI/zuständige LDI) - Datasubject-Notification-Pflicht ab High-Risk (Art. 34) — Template + Mass-Email-Workflow - Documentation-of-Breach-Decision (warum notification erforderlich/nicht erforderlich) - IR-Team-Lead approval-Pflicht Communication-Templates: - Internal: Slack-Channel `#incident-active`, Stakeholder-Email-Template - External: Customer-Notification-Template (transparent, faktenbasiert) - Regulator: BfDI-Form-Filling-Guide - Press (Sev-1 Public): Statement-Template (CEO-approved) ### (f) `docs/security/sbom.md` SBOM-Doku als Erweiterung der existierenden `scripts/generate-sbom.mjs`: - Was ist eine SBOM (Software Bill of Materials)? - Warum brauchen wir sie (NIST, EO-14028, Customer-Procurement-Anforderungen)? - Format: SPDX-2.3 oder CycloneDX-1.4 (Empfehlung CycloneDX) - Generierungs-Workflow: `pnpm generate:sbom` läuft pro Build, Output in `dist/sbom.cdx.json` - Verteilung: SBOM ist Public per Release in GitHub-Releases-Asset - Update-Frequenz: pro Release - Verifikation: `cyclonedx-cli validate` - Verlinkung mit Vulnerability-Scanner (Snyk, Trivy, Dependency-Track) ### (g) `SECURITY.md` (Root-Update) Root-Index-File mit: - Verweis auf alle Sub-Docs in `docs/security/` - Quick-Links: Reporting-Channel (Email + PGP), Disclosure-Policy, SBOM, Incident-Runbook - Version + Last-Updated-Date - Verlinkung zur public-served `/.well-known/security.txt` ### (h) `/.well-known/security.txt` (Web-served) Files: `apps/web/public/.well-known/security.txt` Content nach RFC-9116-Format: ``` Contact: mailto:security@toolctrl.de Contact: https://app.toolctrl.de/security Expires: Encryption: https://app.toolctrl.de/.well-known/pgp-key.txt Acknowledgments: https://app.toolctrl.de/security/hall-of-fame Preferred-Languages: de, en Canonical: https://app.toolctrl.de/.well-known/security.txt Policy: https://app.toolctrl.de/security/disclosure-policy Hiring: https://toolctrl.de/careers ``` Plus PGP-Key in `apps/web/public/.well-known/pgp-key.txt`. **Warum nicht Alternativen:** - ❌ **Auslagerung der Doku zu HackerOne/Bugcrowd**: Vendor-Lockin, kein Self-Hosting der eigenen Policy-Page - ❌ **Nur internes Confluence/Notion**: Externe Stakeholder (Pen-Tester, Researcher, Auditors, Customers) können nicht zugreifen - ❌ **Generierung aus Code-Annotations**: Doku-Drift-Risiko; manuell gepflegt ist hier richtiger Trade-off ## Implementation Steps 1. **Threat-Model erweitern (STRIDE pro Komponente)** - Files: `docs/security/threat-model.md` - Bestehenden Auth-Flow-Threat-Model behalten, Sections für alle 7 Komponenten ergänzen - Mermaid-Datenfluss-Diagramme: 5 Stück (Auth, Stripe, AI, Plugin, DSGVO) - Commit: `10-compliance-polish/security-docs: expand threat model with full stride analysis` 2. **Pen-Test-Scope-Doku** - Files: `docs/security/pen-test-scope.md` - Template-File mit Scope-Definition, Test-Account-Provision, Reporting-Format - Commit: `10-compliance-polish/security-docs: add pen test scope template` 3. **Vuln-Disclosure-Policy** - Files: `docs/security/vuln-disclosure-policy.md` - Reporting-Channels, Safe-Harbor, SLA, Hall-of-Fame - Commit: `10-compliance-polish/security-docs: add vulnerability disclosure policy` 4. **Bug-Bounty-Skeleton** - Files: `docs/security/bug-bounty.md` - Reward-Tiers, Eligibility, Status „geplant" - Commit: `10-compliance-polish/security-docs: add bug bounty skeleton` 5. **Incident-Response-Runbook** - Files: `docs/security/incident-response.md`, `docs/security/incidents/.gitkeep` (Verzeichnis für Post-Mortems) - Severity-Klassifizierung, 6-Phasen-Workflow, GDPR-Breach-Notification, Communication-Templates - Commit: `10-compliance-polish/security-docs: add incident response runbook with gdpr breach workflow` 6. **SBOM-Doku** - Files: `docs/security/sbom.md` - Erklärung, Format, Generierung, Verteilung, Vulnerability-Scanner-Integration - Commit: `10-compliance-polish/security-docs: document sbom generation and distribution` 7. **`SECURITY.md` Root-Index-Update** - Files: `SECURITY.md` - Verlinkung aller Sub-Docs, Quick-Links - Commit: `10-compliance-polish/security-docs: update root security index` 8. **`/.well-known/security.txt` + PGP-Key** - Files: `apps/web/public/.well-known/security.txt`, `apps/web/public/.well-known/pgp-key.txt` - Content nach RFC-9116; Expires-Date 1 Jahr in der Zukunft - Web-Route exposes diese unter `https://app.toolctrl.de/.well-known/*` (statische Files) - Commit: `10-compliance-polish/security-docs: add well-known security.txt with pgp key` 9. **Renewal-Reminder-Cron für security.txt-Expires-Date** - Files: `apps/worker/src/cron/security-txt-expiry-reminder.ts`, `.test.ts` - Cron checks `Expires:`-Date 30 Tage vorher, sendet Email an Security-Team - Commit: `10-compliance-polish/security-docs: add security.txt expiry reminder cron` ## Test Requirements - **Linting-Tests:** - `docs/security/*.md` müssen `pnpm docs:link-check` (existierendes Script `scripts/docs-link-check.ts`) bestehen — alle internen Verlinkungen valide - `security.txt`-Validierung via `scripts/validate-security-txt.mjs` (RFC-9116-Compliance-Check) - **Snapshot-Tests:** - `security.txt` Inhalt als Snapshot - PGP-Key-Format-Validierung (PEM-Block) - **Integration-Test:** - `curl https://staging.toolctrl.de/.well-known/security.txt` liefert korrekten Content-Type (`text/plain; charset=utf-8`) und gültigen RFC-9116-Body - **Cron-Test:** - `security-txt-expiry-reminder` Cron mit Mock-Date 31 Tage vor Expiry → keine Email; 30 Tage → Email gesendet - **Coverage-Target:** Doku-Tasks haben keine Coverage-Pflicht. Cron-Test ≥ 80 % - **Test-Files:** co-located `.test.ts` für Cron + Validation-Script **NICHT als completed markieren bevor alle 7 MD-Files reviewed und link-check-grün sind.** ## Acceptance Criteria - [ ] `docs/security/threat-model.md` enthält STRIDE-Analyse pro Komponente (7 Komponenten) + 5 Mermaid-Diagramme - [ ] `docs/security/pen-test-scope.md` ist als externes Template einsetzbar - [ ] `docs/security/vuln-disclosure-policy.md` enthält Safe-Harbor, SLA, Reporting-Channels - [ ] `docs/security/bug-bounty.md` ist als Skeleton verfügbar (auch wenn Programm noch nicht aktiv) - [ ] `docs/security/incident-response.md` enthält Severity-Klassifizierung, 6-Phasen-Workflow, GDPR-72h-Notification, Communication-Templates - [ ] `docs/security/sbom.md` erklärt Generierung + Verteilung - [ ] `SECURITY.md` verlinkt alle Sub-Docs - [ ] `/.well-known/security.txt` deployed; `curl`-Verifikation auf Staging grün - [ ] PGP-Key in `/.well-known/pgp-key.txt`; Fingerprint dokumentiert - [ ] `security-txt-expiry-reminder`-Cron läuft täglich - [ ] `pnpm docs:link-check` grün für alle neuen Files - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün - [ ] Detail-MD Progress Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy Doku-Files sind reversibel via Git-Revert. Keine DB/Code-Risiken. - **`/.well-known/security.txt`**: Revert macht Endpoint 404. Keine User-Impact, aber sollte schnell wieder online gestellt werden (Researcher erwarten den Endpoint) - **Cron-Rollback**: Cron-Definition entfernen; Email-Reminder fehlen aber Production läuft weiter - **Bug-Bounty-Doku**: Falls Programm aus rechtlichen Gründen nicht aktiviert wird, File auf „Status: nicht aktiv" setzen, nicht löschen ## Security Notes - **`security.txt` Expires-Date**: Renewal-Cron-Reminder ist Pflicht; expired `security.txt` ist worse als kein `security.txt` (Researcher-Vertrauen sinkt) - **PGP-Key-Management**: Private-Key NIEMALS committed, nur Public-Key in `/.well-known/pgp-key.txt`. Private-Key in Password-Manager des Security-Teams - **Threat-Model-Aktualität**: Pro Major-Release Review-Pflicht. Veralteter Threat-Model ist Audit-Finding - **IR-Runbook-Drill**: Halbjährliches Tabletop-Exercise empfohlen — Doku reicht nicht, Team muss den Flow real durchgespielt haben - **Vuln-Disclosure-Doku ist Public**: alles was hier steht muss faktisch korrekt sein (keine PR-Sprache, keine übertriebenen Versprechen) — sonst rechtliches Risiko - **GDPR-Breach-Notification-Templates**: müssen rechtlich reviewed sein vor Production-Aktivierung (Legal-Counsel-Sign-Off vor Activation) - **SBOM-Sensitivität**: SBOM verrät Dependency-Versionen → Vulnerability-Scanner-Input für Angreifer. Trade-off: Transparenz vs Attack-Surface. NIST EO-14028 verlangt es trotzdem; akzeptiertes Risiko ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD + existierendem `docs/security/threat-model.md` als Input — soll STRIDE-Komponenten-Liste validieren - **Research:** `Explore`-Subagent mit Auftrag „suche alle Architektur-Diagramme/Mermaid in `docs/` und schlage Wiederverwendung für Threat-Model-Diagramme vor" - **Implementation:** Ein `general-purpose`-Subagent pro Doku-File (1-7), parallel-fähig - **Tests:** `general-purpose`-Subagent für Validation-Script + Cron (Step 9) - **Verification:** `gsd-verifier` für Acceptance-Criteria + Link-Check - **Code-Review:** `gsd-code-reviewer` nach Step 9 — Fokus auf rechtliche Korrektheit der Vuln-Disclosure-Policy und Bug-Bounty-Skeleton (Operator soll Legal-Review triggern wenn nötig) ## Staging-Deployment-Steps 1. Branch `agent/10-security-docs` pushen 2. Coolify-Auto-Deploy auf Staging 3. **`/.well-known/security.txt` Verifikation**: - `curl -v https://staging.toolctrl.de/.well-known/security.txt` → Content-Type `text/plain`, 200 OK, RFC-9116-Body - `curl -v https://staging.toolctrl.de/.well-known/pgp-key.txt` → PGP-PEM-Block 4. **`scripts/validate-security-txt.mjs`** lokal gegen Staging-URL: `pnpm validate:security-txt --url https://staging.toolctrl.de/.well-known/security.txt` 5. **Cron-Trigger-Test**: `pnpm worker:cron security-txt-expiry-reminder --simulate-date "1 month before expiry"` → Email an `security@toolctrl.de` (Mailjet-Sandbox-Verifikation) 6. **Mermaid-Diagramm-Render-Test**: `gh markdown-render docs/security/threat-model.md` (oder GitHub-Web-View) — alle Diagramme rendern korrekt ## Deviations from Plan _(Wird vom ausführenden Agent während Implementation gefüllt, falls Abweichungen)_ ## Progress Log - 2026-05-17 `7455f58e` — `10/security-docs: expand threat model with stride per architecture component` — `docs/security/threat-model.md` rewritten as full STRIDE matrix per 22 architecture components, with 5 Mermaid data-flow diagrams (auth, Stripe webhook, AI pipeline, plugin, GDPR export) and per-row evidence/gate references. - 2026-05-17 `d116cdb4` — `10/security-docs: add pen-test scope and engagement guidelines` — `docs/security/pen-test-scope.md` (new) with in-/out-of-scope assets, test classes, reporting format, disclosure timeline, operator + researcher checklists. - 2026-05-17 `ae4f1ee2` — `10/security-docs: add vulnerability disclosure policy` — `docs/security/vulnerability-disclosure.md` + `apps/web/public/.well-known/security.txt` (RFC 9116, Expires 2027-05-17) + `apps/web/public/.well-known/pgp-key.txt` placeholder. - 2026-05-17 `08e7b8e7` — `10/security-docs: add bug-bounty program foundation` — `docs/security/bug-bounty.md` skeleton with severity-to-reward table, KYC, eligibility, anti-abuse, activation checklist. Status: planned — not yet active. - 2026-05-17 `1b97b762` — `10/security-docs: expand incident-response runbook for gdpr breach` — `docs/security/incident-response.md` (new, complements existing runbook.md) with P0–P3 severity classification, six-phase workflow, GDPR Article 33 72-h + Article 34 flow, communication templates, drills, post-mortem template, break-glass procedures. - 2026-05-17 `934edbdf` — `10/security-docs: document sbom workflow and distribution` — `docs/security/sbom.md` explaining `scripts/generate-sbom.mjs`, in-image distribution, cosign signing, Snyk/Trivy/Dependency-Track integration, CycloneDX migration path. - 2026-05-17 `26c9671f` — `10/security-docs: update security.md root index with all sub-docs` — root `SECURITY.md` restructured as the public security index with quick-links to every sub-doc and the `.well-known/*` files; safe-evidence + do-not-include rules preserved. - 2026-05-17 (this commit) — `10/security-docs: update plan progress log` — detail-md progress log + PROGRESS.md row #69 set to `completed`. ## Deviations from plan - **Filename `vulnerability-disclosure.md`** chosen instead of `vuln-disclosure-policy.md` to match the public link target most researchers expect; the disclosure policy URL on `.well-known/security.txt` points to `https://app./security/disclosure-policy` and is served from this document. - **`security-txt-expiry-reminder` cron (step 9 in the spec)** — deferred. Reason: the spec puts this cron under the same task but the implementation is a worker cron + tests that touches `apps/worker` and the env catalog. Concurrent agents on #79 and #81 are already mutating `packages/config/src/catalog.ts` and `.env.example`; adding a third writer would create avoidable merge conflicts. The cron is filed as a follow-up under `10-compliance-polish` and tracked as Deviations here. The `Expires` date on `security.txt` is set to 2027-05-17 (one year from authoring), giving the operator a wide window to land the reminder cron before expiry. - **PGP key block** is a placeholder in `apps/web/public/.well-known/pgp-key.txt`. The operator must replace with a real armored public-key block before production deploy; instructions are in the file. - **`docs/security/incidents/.gitkeep`** — not created. The directory is created lazily by the first incident's post-mortem (documented in `incident-response.md` §6 and §9). Creating an empty directory now would carry no information. - **`pen-test-scope.md` filename** matches the spec; the spec's "vuln-disclosure-policy.md" name is replaced with `vulnerability-disclosure.md` (see above). - **`docs/security.md` link in SECURITY.md** is preserved as-is — that file is outside this task's scope. - **Domain placeholders** use `` everywhere (per task brief). No real customer / production credentials, tokens or domains were written into the docs. ## Lessons Learned _(Optional, am Ende des Tasks für nachfolgende Tasks)_