20 KiB
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.mdexistiert 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.mdexistiert aber deckt nicht GDPR-Breach-Notification-Workflow (72h-Frist), keine Severity-Klassifizierung, keine Communication-Templates - SBOM-Doku ist nur in
scripts/generate-sbom.mjsals 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:
- Detection (Sentry-Alerts, Audit-Verifier-Failures, User-Reports)
- Triage (Severity-Bestimmung, IR-Team-Activation)
- Containment (Isolierung der betroffenen Komponente, ggf. Feature-Flag-Disable, Token-Invalidation)
- Eradication (Root-Cause-Fix, Patch-Deploy)
- Recovery (Service-Restore, Verification)
- Lessons Learned (Post-Mortem in
docs/security/incidents/<date>-<short-id>.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:sbomläuft pro Build, Output indist/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: <ISO-Date 1 Jahr in der Zukunft>
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
-
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
- Files:
-
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
- Files:
-
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
- Files:
-
Bug-Bounty-Skeleton
- Files:
docs/security/bug-bounty.md - Reward-Tiers, Eligibility, Status „geplant"
- Commit:
10-compliance-polish/security-docs: add bug bounty skeleton
- Files:
-
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
- Files:
-
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
- Files:
-
SECURITY.mdRoot-Index-Update- Files:
SECURITY.md - Verlinkung aller Sub-Docs, Quick-Links
- Commit:
10-compliance-polish/security-docs: update root security index
- Files:
-
/.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
- Files:
-
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
- Files:
Test Requirements
- Linting-Tests:
docs/security/*.mdmüssenpnpm docs:link-check(existierendes Scriptscripts/docs-link-check.ts) bestehen — alle internen Verlinkungen validesecurity.txt-Validierung viascripts/validate-security-txt.mjs(RFC-9116-Compliance-Check)
- Snapshot-Tests:
security.txtInhalt als Snapshot- PGP-Key-Format-Validierung (PEM-Block)
- Integration-Test:
curl https://staging.toolctrl.de/.well-known/security.txtliefert korrekten Content-Type (text/plain; charset=utf-8) und gültigen RFC-9116-Body
- Cron-Test:
security-txt-expiry-reminderCron 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
<source>.test.tsfü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.mdenthält STRIDE-Analyse pro Komponente (7 Komponenten) + 5 Mermaid-Diagrammedocs/security/pen-test-scope.mdist als externes Template einsetzbardocs/security/vuln-disclosure-policy.mdenthält Safe-Harbor, SLA, Reporting-Channelsdocs/security/bug-bounty.mdist als Skeleton verfügbar (auch wenn Programm noch nicht aktiv)docs/security/incident-response.mdenthält Severity-Klassifizierung, 6-Phasen-Workflow, GDPR-72h-Notification, Communication-Templatesdocs/security/sbom.mderklärt Generierung + VerteilungSECURITY.mdverlinkt alle Sub-Docs/.well-known/security.txtdeployed;curl-Verifikation auf Staging grün- PGP-Key in
/.well-known/pgp-key.txt; Fingerprint dokumentiert security-txt-expiry-reminder-Cron läuft täglichpnpm docs:link-checkgrün für alle neuen Filespnpm lint,pnpm typecheck,pnpm testgrü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.txtExpires-Date: Renewal-Cron-Reminder ist Pflicht; expiredsecurity.txtist worse als keinsecurity.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 + existierendemdocs/security/threat-model.mdals Input — soll STRIDE-Komponenten-Liste validieren - Research:
Explore-Subagent mit Auftrag „suche alle Architektur-Diagramme/Mermaid indocs/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-verifierfür Acceptance-Criteria + Link-Check - Code-Review:
gsd-code-reviewernach 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
- Branch
agent/10-security-docspushen - Coolify-Auto-Deploy auf Staging
/.well-known/security.txtVerifikation:curl -v https://staging.toolctrl.de/.well-known/security.txt→ Content-Typetext/plain, 200 OK, RFC-9116-Bodycurl -v https://staging.toolctrl.de/.well-known/pgp-key.txt→ PGP-PEM-Block
scripts/validate-security-txt.mjslokal gegen Staging-URL:pnpm validate:security-txt --url https://staging.toolctrl.de/.well-known/security.txt- Cron-Trigger-Test:
pnpm worker:cron security-txt-expiry-reminder --simulate-date "1 month before expiry"→ Email ansecurity@toolctrl.de(Mailjet-Sandbox-Verifikation) - 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.mdrewritten 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.txtplaceholder. - 2026-05-17
08e7b8e7—10/security-docs: add bug-bounty program foundation—docs/security/bug-bounty.mdskeleton 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.mdexplainingscripts/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— rootSECURITY.mdrestructured 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 tocompleted.
Deviations from plan
- Filename
vulnerability-disclosure.mdchosen instead ofvuln-disclosure-policy.mdto match the public link target most researchers expect; the disclosure policy URL on.well-known/security.txtpoints tohttps://app.<your-domain>/security/disclosure-policyand is served from this document. security-txt-expiry-remindercron (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 touchesapps/workerand the env catalog. Concurrent agents on #79 and #81 are already mutatingpackages/config/src/catalog.tsand.env.example; adding a third writer would create avoidable merge conflicts. The cron is filed as a follow-up under10-compliance-polishand tracked as Deviations here. TheExpiresdate onsecurity.txtis 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 inincident-response.md§6 and §9). Creating an empty directory now would carry no information.pen-test-scope.mdfilename matches the spec; the spec's "vuln-disclosure-policy.md" name is replaced withvulnerability-disclosure.md(see above).docs/security.mdlink in SECURITY.md is preserved as-is — that file is outside this task's scope.- Domain placeholders use
<your-domain>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)