Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/10-compliance-polish/security-docs.md
T

322 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<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: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: <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
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 `<source>.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.<your-domain>/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 `<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)_