diff --git a/docs-src/development/capability_model_v1.md b/docs-src/development/capability_model_v1.md new file mode 100644 index 00000000..864306e8 --- /dev/null +++ b/docs-src/development/capability_model_v1.md @@ -0,0 +1,203 @@ +# Capability Model v1 — Objektarten & Beziehungstypen (Schema-Papier, NICHT materialisiert) + +Status: **OFFEN / Entscheidung erforderlich (2026-06-26).** Dies ist Schritt **#5a** (Papier). +Schritt **#5b** (Materialisierung: `capabilities.json`, Migration, Obligation→Capability-Links, +Guidance-Mapping, Runtime) ist **GEGATED** auf die Annahme dieses Papiers. **Es wurde noch keine +Zeile Daten verschoben.** + +Baut auf [legal_obligation_layer_v1.md](legal_obligation_layer_v1.md), +[obligation_registry_v1.md](obligation_registry_v1.md) und dem Cross-Domain-Review +(`obligations/cross_domain_relationships.json`, Commit `ed31fdc0`). + +--- + +## 0. Warum ein Papier statt `capabilities.json` + +Die Plattform hat drei empirische Architektur-Sprünge gemacht: +1. **Control ≠ Wissensobjekt** → Legal Obligation (sofort implementiert, datenbestätigt). +2. **Procedure ist eigenständig** (implementiert: `cra_procedures.json`). +3. **Capabilities tauchen domänenübergreifend wieder auf** (Cross-Domain-Review). + +(1) und (2) waren breit datenbelegt → sofort umgesetzt. Bei (3) ist die **Objektart selbst noch +nicht definiert.** Wir wissen NICHT genau, was eine Capability ist. Materialisieren wir jetzt, +riskieren wir, in drei Wochen festzustellen: „Attack Surface war gar keine Capability" → Umbau. + +--- + +## 1. Der Auslöser: die 8 „Capabilities" sind NICHT eine Objektart + +Der Cross-Domain-Review fand 16 `SHARED_CAPABILITY`-Paare → 8 Cluster. Bei Inspektion zerfallen +sie in **zwei verschiedene Objektarten**: + +| Cluster (Opus-Benennung) | Art | Begründung | +|---|---|---| +| `mfa` | **Capability** | implementierbar als Funktion | +| `session_management` | **Capability** | implementierbar | +| `transport_encryption` (tls/mutual_tls/cert) | **Capability** | implementierbar (vom Klassifikator fein gesplittet → 1 Capability) | +| `code_signing` | **Capability** | implementierbar | +| `anomaly_detection` | **Capability** | implementierbar | +| `access_control` | **Ziel** (schwach) | abstraktes Ziel, kein Baustein — eher OVERLAP (siehe Konsolidierung) | + +Dazu die **zwei Gap-„Obligations" aus Handoff #4** (NIST SI-7/CM-7 waren breiter als jeder +einzelne Treffer): + +| Kandidat | Art | Begründung | +|---|---|---| +| `software_integrity_protection` (SI-7) | **Sicherheitsziel** | wird NICHT direkt gebaut; erreicht durch code_signing + hash_verification + secure_boot | +| `attack_surface_minimization` (CM-7) | **Sicherheitsziel** | erreicht durch least_functionality + Port-Deaktivierung + Interface-Reduktion | + +**Kernbeobachtung (User):** Es gibt **Typ 1 — technische Fähigkeiten** (implementierbar) und +**Typ 2 — Sicherheitsziele** (nicht direkt implementierbar, durch mehrere Capabilities erreicht). +Sie in eine `capabilities.json` zu werfen wäre der Fehler. + +``` +Integrity Protection (Ziel) Access Protection (Ziel) + ↑ erreicht durch ↑ erreicht durch +code_signing · hash_verification · mfa · session_management · +secure_boot (Capabilities) credential_storage (Capabilities) +``` + +Das erklärt rückwirkend auch das **systematische Synth-Über-Tiering** (Auth 14→6, Remote 14→5): +das LLM mischte ziel-nahe Obligations mit fähigkeits-nahen Mechanismen, weil die Modellsprache +die Ebenen nicht trennte. + +--- + +## 2. Kandidat-Objektarten + +| Objektart | Definition | Diskriminator-Test | +|---|---|---| +| **Regulation** | Rechtsakt (CRA, NIS2, DSGVO, MaschVO) | „Ist es ein Gesetz/VO?" | +| **Legal Obligation** | rechtlich verankerte Pflicht. **CORE** (abstrakt, oft = Sicherheitsziel) ⊇ **DOMAIN** (spezialisiert) — die CORE/DOMAIN-Achse existiert bereits (portability). | „Steht das so (sinngemäß) im Recht? Kann ein Prüfer FEHLT/ERFÜLLT sagen?" | +| **Capability** *(NEU)* | implementierbare, **regulierungs-agnostische** technische Funktion, als Einheit baubar & testbar | „Kann ein Hersteller GENAU DAS bauen/konfigurieren?" → ja | +| **Procedure** | wiederholbarer operativer Prozess, der eine Capability ausbringt/erhält (bereits modelliert) | „Ist es eine Tätigkeit/ein Ablauf?" | +| **Control** | testbare Prüfanweisung | „Kann man es prüfen (pass/fail)?" | +| **Evidence** | Nachweis-Artefakt (Audit-Log, SBOM, Release Notes) | „Ist es ein Beleg-Dokument/Datum?" | +| **Guidance** *(quer)* | externe Empfehlung WIE (NIST/OWASP/ENISA/BSI). **Nicht-bindend.** | „Beschreibt es eine empfohlene Umsetzung, kein Primärrecht?" | + +--- + +## 3. DER ZENTRALE KNACKPUNKT: Ist „Security Objective" eine eigene Klasse? + +### Modell A — flach (Objektive = Obligations) +``` +Regulation → Legal Obligation → Capability → Procedure → Control → Evidence +``` +Sicherheitsziele sind einfach **CORE Legal Obligations**; domänen-scoped Pflichten sind DOMAIN- +Obligations, die per `specializes` an die CORE hängen. + +### Modell B — mit eigener Security-Objective-Klasse +``` +Regulation → Legal Obligation → Security Objective → Capability → Procedure → Control → Evidence +``` + +### Modell C — hybrid (Capability als einzige neue Klasse) ← **EMPFEHLUNG** +``` +Regulation → Legal Obligation (CORE ⊇ DOMAIN) --realized_by--> Capability → Procedure → Control → Evidence + ▲ ▲ + └── specializes (DOMAIN→CORE) └── described_by ── Guidance (NIST/OWASP/…) +``` + +**Empfehlung: Modell C.** Begründung aus den Daten: +- Die „Sicherheitsziele" (`software_integrity_protection`, `attack_surface_minimization`, CIA, + access-protection) **SIND im CRA bindende Pflichten** (Annex I (2)(a–m) ist Primärrecht). Ein + Sicherheitsziel ist also eine **CORE Legal Obligation**, kein neuer Objekttyp. +- Die **CORE/DOMAIN-Achse existiert schon** (portability_core ⊇ health/data_act). `attack_surface_ + minimization` (CORE) ⊇ `remote_access_attack_surface_min` (DOMAIN) ist exakt dasselbe Muster. + → keine neue Klasse, nur konsequente Nutzung des Vorhandenen. +- **Genau EINE** wirklich neue Klasse (**Capability**) ist sparsam und niedrig-risiko. +- Modell B verdoppelt die normative Ebene (Obligation vs Objective), die im CRA 1:1 zusammenfällt + → Klasse, die niemand sauber befüllt. + +**Konsequenz für die #4-Gap:** `software_integrity_protection` + `attack_surface_minimization` +werden als **CORE Legal Obligations** angelegt (nicht als Capabilities), und die domänen-scoped +Treffer (`signed_update_integrity`, `remote_access_attack_surface_min`) `specializes` → CORE. +NIST SI-7/CM-7 mappen dann `primary_implementation` auf die CORE. + +**Offen für den User:** Modell C akzeptieren? Oder ist die regulierungs-AGNOSTISCHE Vereinheitlichung +(eine „confidentiality" über CRA+NIS2+ISO) so wertvoll, dass „Security Objective" doch eine eigene +Klasse verdient (Modell B)? Das ist die einzige wirklich offene Architekturentscheidung. + +--- + +## 4. Beziehungstypen — das Modell ist ein GRAPH, keine flache Ebene + +Der Review fand **vier distinkte Cross-Domain-Strukturrelationen** (nicht eine): +`SUPPORTED_BY` 23 · `SHARED_CAPABILITY` 16 · `SHARED_EVIDENCE` 7 · `SHARED_PROCEDURE` 5 (+ 1 Merge). +Das ist kein Baum. Vorgeschlagenes gerichtetes Kanten-Vokabular: + +| Kante | von → nach | aus Review-Relation | +|---|---|---| +| `specializes` | DOMAIN-Obligation → CORE-Obligation | (SUPPORTED_BY, Spezialfall) | +| `contributes_to` | Obligation → Obligation | (SUPPORTED_BY, Beitrag) | +| `realized_by` | Obligation → Capability | (SHARED_CAPABILITY ⇒ 2 Obl. teilen 1 Capability) | +| `deployed_via` | Capability → Procedure | (SHARED_PROCEDURE) | +| `verified_by` | Procedure/Capability → Control | — | +| `produces` | Procedure → Evidence | (SHARED_EVIDENCE ⇒ 2 Obl. teilen 1 Nachweis) | +| `described_by` | Capability → Guidance | (guidance_basis) | +| `same_as` | Obligation ↔ Obligation | (SAME_OBLIGATION, Merge) | + +`SHARED_CAPABILITY`/`SHARED_EVIDENCE`/`SHARED_PROCEDURE` sind also **keine Obligation-Obligation- +Kanten**, sondern Belege, dass zwei Obligations **denselben Knoten einer tieferen Ebene** teilen +(Capability / Evidence / Procedure). Genau das ist der Mehrwert gegenüber „sieht ähnlich aus". + +--- + +## 5. Die 8 offenen Fragen (Antwort + Tradeoff) + +1. **Was ist eine Capability?** Eine implementierbare, regulierungs-agnostische technische Funktion, + als Einheit baubar/konfigurierbar/testbar (MFA, TLS, Code Signing, Session-Mgmt, Anomaly-Detection). +2. **Unterschied zur Obligation?** Obligation = rechtliche Pflicht (WAS das Recht verlangt, regulierungs- + verankert, normativ). Capability = technisches Mittel (WIE man sie erfüllt, agnostisch). n:m. +3. **Unterschied zum Security Objective?** Ziel = erwünschter Sicherheitszustand (CIA, attack-surface-min); + Capability = Mittel dorthin. **Empfehlung (Modell C):** das Ziel ist eine CORE Obligation, kein + eigener Typ → Unterschied reduziert sich auf Obligation(abstrakt) vs Capability(Mittel). +4. **Wann Guidance?** Wenn es eine **nicht-bindende externe Empfehlung zur Umsetzung** ist (NIST AC-12, + OWASP ASVS V6). Hängt an der **Capability** (meist) bzw. Procedure — NIE als `legal_basis` einer + LEGAL_MINIMUM-Obligation (Primärrecht-Regel bleibt). +5. **Wann Procedure?** Wenn es ein **wiederholbarer operativer Ablauf** ist, der eine Capability + ausbringt/erhält (MFA konfigurieren, Schlüssel rotieren, Patch-Zyklus fahren). +6. **Capability → mehrere Obligations?** **JA, belegt:** `mfa` erfüllt 6 Obligations (auth+remote), + `code_signing` 2 (auth+updates). n:m. +7. **Obligation → mehrere Capabilities?** **JA, belegt:** access-protection ← mfa + session_management + + credential_storage. n:m. +8. **Wo hängen NIST/OWASP/ENISA/BSI?** Primär an der **Capability** (sie beschreiben deren Umsetzung), + teils an Procedure. **Das erklärt, warum die über-getierten BP-Obligations `guidance_basis` trugen: + sie waren in Wahrheit Capabilities.** Sauberer Sitz von `guidance_basis` = Capability. + +--- + +## 6. Worked Examples (4 Domänen, echte IDs) + +**Authentication** — `user_authentication_required` (Obl, CORE: access-protection) +`--realized_by-->` { `mfa`, `session_management`, `credential_storage` } (Capabilities) +`--described_by-->` NIST IA-2 / OWASP ASVS V6 (Guidance). + +**Updates** — `provide_security_updates` (Obl, LEGAL_MINIMUM) `--realized_by-->` +{ `code_signing` (= signed_update_integrity-Capability), `automatic_update_delivery`, `rollback` } +— exakt die `capability_candidate`-Marker aus `cra_updates.json`. + +**Remote Access** — CORE `attack_surface_minimization` (NEU, = CM-7-Ziel) `⊇ specializes ⊇` +`remote_access_attack_surface_min` (DOMAIN) `--realized_by-->` { `least_functionality`, `port_disabling` }. + +**SBOM** — Sonderfall: die SBOM-Familie ist im Cross-Review der **Evidence-/Procedure-Input** für +`vuln_identification_inventory` (5× SUPPORTED_BY-Hub), weniger Capability. → bestätigt, dass nicht +jede Domäne primär Capabilities beisteuert; manche liefern **Evidence**. Stützt den Graph-Charakter. + +--- + +## 7. Entscheidung, die ich vom User brauche (vor #5b) + +1. **Modell C** (Capability = einzige neue Klasse; Sicherheitsziele = CORE-Obligations) — akzeptiert? + Oder Modell B (Security Objective als eigene Klasse für regulierungs-agnostische Vereinheitlichung)? +2. **Kanten-Vokabular** aus §4 — so einfrieren? +3. **`guidance_basis` wandert konzeptionell an die Capability** — einverstanden? (Bricht nichts sofort; + die Obligations behalten den Verweis bis #5b.) +4. Erst danach **#5b**: `capabilities.json` (capability_id, fulfills_obligations[] via `realized_by`, + guidance_basis hochgezogen), die 2 CORE-Gap-Obligations, der Merge (`vuln_remediation_patching` ≈ + `provide_security_updates`), und die 2 Remote-Grenzfälle final tiern. + +## 8. Bewusst NICHT in #5a (gegated) + +Keine `capabilities.json`, keine Migration, kein Obligation-Rewrite, kein Guidance-Move, kein Runtime. +Erst Modell-Annahme, dann Daten. „Erst das Schema, dann verschieben."