diff --git a/docs-src/development/controls-measures-interface.md b/docs-src/development/controls-measures-interface.md new file mode 100644 index 00000000..571fa6ab --- /dev/null +++ b/docs-src/development/controls-measures-interface.md @@ -0,0 +1,69 @@ +# Schnittstelle: Controls-/Muster-Schicht → Maßnahmen-Schicht + +> Status: Vorschlag / Abstimmung mit der Controls-Session (Stand 2026-06-16) +> Kontext: Die Controls-Pipeline (master controls, Topic-Mapping) wird in +> `breakpilot-core/control-pipeline/` überarbeitet. Diese Notiz definiert, was +> die Maßnahmen-Schicht (CRA/Compliance) als stabilen Andock-Punkt braucht. + +## Ziel + +Maßnahmen werden **pro Abhilfe-Muster** geschrieben (wiederverwendbar, viele +Controls → eine Maßnahme), **nicht** pro Control. Es sollen also keine ~100k +Einzel-Maßnahmen entstehen, sondern wenige hundert standard-gestützte Maßnahmen, +die an eine saubere, **stabile** Muster-/Topic-Schicht andocken. + +## Was die Maßnahmen-Schicht von der Controls-Schicht braucht + +### 1. Stabile „Abhilfe-Muster"-Einheit mit fester ID (wichtigste Bitte) + +- Kandidaten für die kanonische Einheit: verbesserter `master_control_id`, + `sub_topic`, oder ein neues „obligation-pattern"-Cluster. **Bitte festlegen, + welche Einheit kanonisch ist.** +- **Kritisch:** die ID muss eine Re-Generierung überleben (deterministisch) + **oder** es gibt einen stabilen natürlichen Schlüssel + (z. B. Hash des normalisierten `canonical_obligation`, oder + `use_case + sub_topic + framework`). Sonst brechen die + Maßnahme↔Muster-Verknüpfungen bei jedem Re-Run (dasselbe Problem wie damals + mit `chunk_hash`). + +### 2. Mapping `control_uuid → pattern_id` (viele zu eins) + +Von der Controls-Schicht gepflegt, damit ein Befund vom Control aufs Muster +(→ Maßnahme) aufgelöst werden kann. + +### 3. Felder pro Muster (oder pro Control) + +- `sub_topic` / Topic (z. B. authentication, cryptography) — die Muster-Achse +- **Framework-Crosswalk:** NIST 800-53, OWASP (ASVS/Top 10), ISO 27002, + IEC 62443 — der inhaltliche Anker der Maßnahme (Substanz aus Standards + referenzieren, nicht neu schreiben) +- `canonical_obligation` — normalisiertes „was ist zu tun" (Saat-Text) +- `source_regulation` + `source_article` — Provenienz/Zitat +- `severity`, `use_case`, `tier` (core/review) + +## Was die Controls-Schicht NICHT anfassen muss + +Die **CRA-Annex-I-Spine + die kuratierten Maßnahmen M540–M548** (40 Anforderungen, +in `compliance/api/cra_annex_i_data.py`) hängen an CRA-**Anforderungen**, liegen in +der Compliance-Session und sind vom Control-Rework **unabhängig**. Die +CRA-Maßnahmen laufen parallel weiter. + +## Bitte NICHT brechen (liest die Breadth-Schicht heute schon) + +- `atom_classification` (`use_case`, `sub_topic`, `relevant`, `canonical_obligation`) +- `canonical_controls` (`control_id`, `title`, `objective`, `severity`, `license_rule`) +- `control_parent_links` (`source_regulation`, **`source_article`**) +- die Response-Form von `UseCaseControlsService.controls_for_use_case` (atom-grain) + +## Aufgabenteilung + +- **Controls-Session (core/control-pipeline):** MC-/Control-Neuerzeugung + + Topic/Muster-Mapping + Framework-Crosswalk pro Muster, mit stabilen IDs. +- **Compliance-Session:** Maßnahmen-Schicht (Muster → ausformulierte, + standard-gestützte Maßnahme) + CRA-Integration auf diesem Output. + +## Die eine Entscheidung, die uns entblockt + +Bitte nennen: **(a) die kanonische Muster-Einheit** und **(b) die +ID-Stabilitäts-Garantie**. Das allein reicht, damit die Maßnahmen-Schicht darauf +ausgerichtet werden kann.