feat(playbook): Implementation Playbooks — the Berater renderer ("wie komme ich dort hin?")
Roadmap item 4. After WHAT applies / WHAT is missing / WHICH first, the GF asks HOW. The Implementation Playbook renders, for one capability, the full journey — why / which regulations it closes / tools / process / evidence / controls — and chains the Optimization Roadmap into per-measure playbooks. Another renderer over the same Capability spine (ADR-003/004), not a new engine: ~95% of the data already exists, it just needs a different rendering. - compliance/playbook/: build_playbook() + playbooks_for_plan() (chains optimization -> playbook, acyclic; reuses leverage for "closes which regulations"). Capabilities without curated content render as honest status:missing stubs — the content-owed signal. - knowledge/implementation_playbooks/: curated knowledge layer (Reasoning Knowledge Acquisition), two deep expert drafts (SBOM, CVD/PSIRT, status draft, expert-draft-not-normative) + README. The bottleneck is now CONTENT, not software; Playbook (own knowledge) != regulatory domain. - ADR-004: Implementation Playbooks = renderer + knowledge layer; content is the bottleneck. - reference suite: "Implementation Playbook" section renders the SBOM journey + Roadmap->Playbook table (high-leverage caps flagged "fehlt (Inhalt)" — content backlog, highest leverage first). - refactor: extracted markdown helpers to reference_scenarios/_helpers.py to keep generate.py under the 500-LOC budget. 9 playbook tests (40 with optimization+transition+company), mypy --strict clean, check-loc 0. Product code with no app caller + knowledge/ADR/reference = non-runtime -> no deploy (ADR-001). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
@@ -0,0 +1,51 @@
|
||||
# Implementation Playbooks — curated knowledge ("wie komme ich dort hin?")
|
||||
|
||||
**Curated implementation KNOWLEDGE in machine-readable form — not an algorithm, not runtime code.**
|
||||
After the Capability Delta Engine says WHAT is missing and the Optimization renderer says WHICH
|
||||
measure first, a Playbook says HOW to implement one capability: why it is required, which tools and
|
||||
process steps stand it up, which evidence proves it, which controls it maps to, and which regulatory
|
||||
gaps it closes. The renderer is `compliance/playbook/`; this directory holds the content it renders.
|
||||
|
||||
Nothing imports these at runtime — `compliance/playbook` reads them and assembles a `Playbook`
|
||||
view. Adding or curating a playbook is therefore **non-runtime → no deploy** (ADR-001).
|
||||
|
||||
## Playbook vs. regulatory domain (a deliberate distinction)
|
||||
|
||||
- A **Playbook** is BreakPilot's OWN knowledge layer: `Capability → recommended approach → tools →
|
||||
process → typical evidence → controls`. It does not introduce a new regulation.
|
||||
- A **regulatory domain** (e.g. ISO 14001 → environmental law) is a new *regulatory* knowledge
|
||||
domain (obligations, applicability), owned with Legal Knowledge / Execution.
|
||||
|
||||
These scale independently. Once a domain lands, every new capability it needs can immediately be
|
||||
embedded into the SAME playbook mechanism — which is why playbooks come first.
|
||||
|
||||
## The bottleneck is CONTENT, not software
|
||||
|
||||
The renderer is small and done. The value now grows with the **number and depth of playbooks**.
|
||||
A capability with no playbook renders as a `status: missing` stub (the honest "content owed" signal).
|
||||
This is Reasoning's Knowledge Acquisition responsibility (same as `../transition_patterns/`):
|
||||
AI produces the first draft offline; BreakPilot reviews, versions and OWNS the library.
|
||||
|
||||
## Maturity lifecycle
|
||||
|
||||
`draft (L1) → reviewed (L2, internal) → validated (L3, domain expert) → proven (L4, field)`.
|
||||
Curated content is an **EXPERT DRAFT, never a normative requirement**; tools/steps are recommended
|
||||
practice, not a mandatory catalogue. Controls are **injected from the Execution layer** (may be
|
||||
empty until linked) — no Execution data lives in the playbook content or in Reasoning product code.
|
||||
|
||||
## Schema (per file)
|
||||
|
||||
`id` · `capability_id` · `status` · `title` · `why` · `tools[]` · `process_steps[{title, detail}]`
|
||||
· `expected_evidence[]` · `typical_controls[]` (indicative) · `how_others_do_it` · `disclaimer`.
|
||||
`closes_regulations` / `leverage` are NOT stored here — the renderer supplies them from the
|
||||
Optimization leverage (`covers_targets`), so one playbook serves every regulation it closes.
|
||||
|
||||
## Catalogue
|
||||
|
||||
| Playbook | Capability | status |
|
||||
|---|---|---|
|
||||
| `playbook_sbom_creation_v1.yaml` | sbom_creation | `draft` (L1) |
|
||||
| `playbook_coordinated_vulnerability_disclosure_v1.yaml` | coordinated_vulnerability_disclosure (PSIRT) | `draft` (L1) |
|
||||
|
||||
Next candidates (high-leverage CRA/MaschinenVO delta): `security_update_support_period` ·
|
||||
`secure_signed_update_distribution` · `product_cyber_risk_assessment`.
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
# Implementation Playbook — curated KNOWLEDGE (the "wie komme ich dort hin?" layer), not runtime code.
|
||||
# Capability: coordinated_vulnerability_disclosure (PSIRT). Expert FIRST DRAFT — a product-security
|
||||
# practitioner would validate this; NOT a normative requirement.
|
||||
|
||||
id: PB-coordinated_vulnerability_disclosure-v1
|
||||
capability_id: coordinated_vulnerability_disclosure
|
||||
status: draft # draft -> reviewed -> validated -> proven
|
||||
version: 1
|
||||
|
||||
title: "Coordinated Vulnerability Disclosure (CVD) / PSIRT aufbauen"
|
||||
|
||||
why: >
|
||||
Der CRA verlangt eine Richtlinie zur koordinierten Offenlegung von Schwachstellen und einen
|
||||
Meldekanal (Annex I Teil II) sowie deren Bearbeitung. Forscher und Nutzer brauchen einen Weg,
|
||||
Schwachstellen verantwortungsvoll zu melden; der Hersteller braucht einen Prozess, um zu
|
||||
triagieren, zu beheben und abgestimmt zu veröffentlichen. Diese Funktion heißt PSIRT (Product
|
||||
Security Incident Response Team).
|
||||
|
||||
tools:
|
||||
- "security.txt (RFC 9116) — maschinenlesbarer Sicherheitskontakt"
|
||||
- "Veröffentlichte CVD-Policy (Webseite)"
|
||||
- "Dediziertes PSIRT-Postfach + PGP-Schlüssel"
|
||||
- "Triage-/Ticketsystem mit CVSS-Bewertung"
|
||||
- "CSAF (Common Security Advisory Framework) für maschinenlesbare Advisories"
|
||||
- "CVE Numbering Authority (CNA) — optional, für eigene CVE-Vergabe"
|
||||
|
||||
process_steps:
|
||||
- title: "CVD-Policy + Kontakt veröffentlichen"
|
||||
detail: "Öffentliche Richtlinie (Scope, Safe-Harbor, Fristen) + security.txt mit Kontakt/PGP."
|
||||
- title: "Meldekanal betreiben"
|
||||
detail: "PSIRT-Postfach/Portal, verschlüsselte Übermittlung, Eingangsbestätigung mit SLA."
|
||||
- title: "Triage + Schweregrad"
|
||||
detail: "Eingang reproduzieren, CVSS bewerten, Betroffenheit über die SBOM bestimmen."
|
||||
- title: "Behebung koordinieren"
|
||||
detail: "Fix + Offenlegungsfrist mit dem Melder abstimmen (Coordinated Disclosure)."
|
||||
- title: "CVE zuweisen"
|
||||
detail: "Über die eigene oder eine partnernde CNA eine CVE-ID vergeben."
|
||||
- title: "Advisory veröffentlichen + Nutzer benachrichtigen"
|
||||
detail: "Maschinenlesbares CSAF-Advisory; betroffene Nutzer/Behörden informieren (verbindet mit Meldepflicht)."
|
||||
|
||||
expected_evidence:
|
||||
- "Veröffentlichte CVD-Policy + security.txt mit Kontakt"
|
||||
- "PSIRT-Triage-Runbook (Rollen, Fristen, CVSS)"
|
||||
- "Beispiel-Advisory (CSAF oder gleichwertig)"
|
||||
|
||||
typical_controls: # INDIKATIV — echte Control-Zuordnung kommt aus der Execution-Schicht
|
||||
- "vulnerability_disclosure"
|
||||
- "incident_response"
|
||||
|
||||
how_others_do_it: >
|
||||
Verbreitete Praxis: security.txt + öffentliche CVD-Policy, ein PSIRT-Postfach mit PGP, Triage per
|
||||
CVSS und Betroffenheitsanalyse über die SBOM, abgestimmte Veröffentlichung als CSAF-Advisory.
|
||||
Viele Hersteller werden selbst CNA, um CVEs zeitnah vergeben zu können.
|
||||
|
||||
disclaimer: >
|
||||
Kuratiertes Experten-Wissen (Erstentwurf), KEINE normative Anforderung. Werkzeug- und
|
||||
Schrittempfehlungen sind bewährte Praxis, kein Pflichtkatalog. Review durch eine:n PSIRT-/
|
||||
Product-Security-Expert:in ausstehend (status: draft).
|
||||
@@ -0,0 +1,58 @@
|
||||
# Implementation Playbook — curated KNOWLEDGE (the "wie komme ich dort hin?" layer), not runtime code.
|
||||
# Capability: sbom_creation. Expert FIRST DRAFT — an SBOM practitioner would validate this; it is
|
||||
# NOT a normative requirement. The renderer (compliance/playbook) assembles it into the journey.
|
||||
|
||||
id: PB-sbom_creation-v1
|
||||
capability_id: sbom_creation
|
||||
status: draft # draft -> reviewed -> validated -> proven
|
||||
version: 1
|
||||
|
||||
title: "Software Bill of Materials (SBOM) aufbauen und betreiben"
|
||||
|
||||
why: >
|
||||
Der CRA verlangt von Herstellern, die Komponenten ihres Produkts zu identifizieren und zu
|
||||
dokumentieren (Schwachstellenbehandlung, Annex I Teil II). Eine SBOM ist das maschinenlesbare
|
||||
Inventar aller (auch transitiven) Software-Bestandteile mit Version und Lizenz. Ohne SBOM kann
|
||||
niemand verlässlich sagen, welche Produkte von einer neuen Schwachstelle (CVE) betroffen sind —
|
||||
SBOM ist damit die Voraussetzung für Schwachstellenüberwachung, Security-Updates und Meldepflichten.
|
||||
|
||||
tools:
|
||||
- "CycloneDX (Format, OWASP)"
|
||||
- "SPDX (Format, Linux Foundation)"
|
||||
- "Syft (Generator, Container/Filesystem)"
|
||||
- "cdxgen (Generator, Multi-Ökosystem)"
|
||||
- "Trivy (Generator + Scan)"
|
||||
- "OWASP Dependency-Track (Verwaltung + kontinuierliche Überwachung)"
|
||||
|
||||
process_steps:
|
||||
- title: "Format festlegen"
|
||||
detail: "CycloneDX oder SPDX wählen (maschinenlesbar). CycloneDX ist im Security-Kontext verbreitet."
|
||||
- title: "Automatisch im Build erzeugen"
|
||||
detail: "SBOM-Generierung (Syft/cdxgen/Trivy) als Schritt in die CI/CD-Pipeline einbauen — pro Build, nicht manuell."
|
||||
- title: "Transitive Abhängigkeiten + Versionen + Lizenzen erfassen"
|
||||
detail: "Nicht nur direkte Dependencies; gerade transitive Komponenten tragen die meisten CVEs."
|
||||
- title: "Pro Release versionieren und ablegen"
|
||||
detail: "Jede ausgelieferte Produktversion bekommt ihre eigene, unveränderliche SBOM (Nachvollziehbarkeit)."
|
||||
- title: "An Schwachstellenüberwachung anbinden"
|
||||
detail: "SBOM in Dependency-Track laden -> kontinuierlicher Abgleich gegen neue CVEs/Advisories."
|
||||
- title: "Release-Gate setzen"
|
||||
detail: "Auslieferung nur mit gültiger SBOM (Reifegrad-Schritt) — verbindet SBOM mit dem Update-Prozess."
|
||||
|
||||
expected_evidence:
|
||||
- "Maschinenlesbare SBOM (CycloneDX/SPDX) je ausgelieferter Produktversion"
|
||||
- "CI-Job-Konfiguration, die die SBOM automatisch erzeugt"
|
||||
- "Dependency-Track-Projekt (oder gleichwertig) mit laufender Überwachung"
|
||||
|
||||
typical_controls: # INDIKATIV — echte Control-Zuordnung kommt aus der Execution-Schicht
|
||||
- "component_inventory"
|
||||
- "supply_chain_risk_management"
|
||||
|
||||
how_others_do_it: >
|
||||
Verbreitete Praxis: CycloneDX automatisch in der CI via Syft/cdxgen erzeugen und nach
|
||||
OWASP Dependency-Track pushen, das kontinuierlich gegen neue CVEs prüft. Reifere Organisationen
|
||||
gaten Releases auf das Vorhandensein einer SBOM und teilen sie auf Anfrage mit Kunden/Behörden.
|
||||
|
||||
disclaimer: >
|
||||
Kuratiertes Experten-Wissen (Erstentwurf), KEINE normative Anforderung. Werkzeug- und
|
||||
Schrittempfehlungen sind Beispiele bewährter Praxis, kein Pflichtkatalog. Review durch eine:n
|
||||
Product-Security-Expert:in ausstehend (status: draft).
|
||||
Reference in New Issue
Block a user