Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,321 @@
# 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)_