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

20 KiB
Raw Blame History

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)