breakpilot-compliance/docs-src/services/sdk-modules/control-provenance.md

# Control Provenance Wiki

Dokumentation der rechtlichen und methodischen Grundlage fuer die Control-Erstellung.

**Frontend:** `https://macmini:3007/sdk/control-provenance`
**Production:** `https://admin-dev.breakpilot.ai/sdk/control-provenance`

---

## Methodik der Control-Erstellung

Alle Controls in der Canonical Control Library wurden **eigenstaendig formuliert** und folgen einer
**unabhaengigen Taxonomie**. Es werden keine proprietaeren Bezeichner, Nummern oder Strukturen
aus geschuetzten Quellen uebernommen.

### Dreistufiger Prozess

1. **Offene Recherche** — Identifikation von Security-Anforderungen aus oeffentlichen, frei zugaenglichen
   Frameworks (OWASP, NIST, ENISA). Jede Anforderung wird aus mindestens 2 unabhaengigen offenen Quellen belegt.

2. **Eigenstaendige Formulierung** — Jedes Control wird mit eigener Sprache, eigener Struktur und eigener
   Taxonomie (z.B. AUTH-001, NET-001) verfasst. Kein Copy-Paste, keine Paraphrase geschuetzter Texte.

3. **Too-Close-Pruefung** — Automatisierte Aehnlichkeitspruefung gegen Quelltexte mit 5 Metriken
   (Token Overlap, N-Gram Jaccard, Embedding Cosine, LCS Ratio, Exact-Phrase). Nur Controls mit
   Status PASS oder WARN (+ Human Review) werden freigegeben.

### Rechtliche Grundlage

| Gesetz | Bezug |
|--------|-------|
| **UrhG §44b** | Text & Data Mining erlaubt fuer Analyse; Kopien werden danach geloescht |
| **UrhG §23** | Hinreichender Abstand zum Originalwerk durch eigene Formulierung |
| **BSI Nutzungsbedingungen** | Kommerzielle Nutzung nur mit Zustimmung; BSI-Dokumente nur als Analysegrundlage |

---

## Filter in der Control Library

Die Control Library bietet **7 Filter-Dropdowns**, um die ueber 3.000 Controls effizient zu durchsuchen:

### Schweregrad (Severity)

| Stufe | Farbe | Bedeutung |
|-------|-------|-----------|
| **Kritisch** | Rot | Sicherheitskritische Controls — Verstoesse fuehren zu schwerwiegenden Risiken |
| **Hoch** | Orange | Wichtige Controls — sollten zeitnah umgesetzt werden |
| **Mittel** | Gelb | Standardmaessige Controls — empfohlene Umsetzung |
| **Niedrig** | Gruen | Nice-to-have Controls — zusaetzliche Haertung |

### Domain

Das Praefix der Control-ID (z.B. `AUTH-001`, `SEC-042`). Kennzeichnet den thematischen Bereich.

| Domain | Anzahl | Thema |
|--------|--------|-------|
| SEC | ~700 | Allgemeine Sicherheit, Systemhaertung |
| COMP | ~470 | Compliance, Regulierung, Nachweispflichten |
| DATA | ~400 | Datenschutz, Datenklassifizierung, DSGVO |
| AI | ~290 | KI-Regulierung (AI Act, Transparenz, Erklaerbarkeit) |
| LOG | ~230 | Logging, Monitoring, SIEM |
| AUTH | ~200 | Authentifizierung, Zugriffskontrolle |
| NET | ~150 | Netzwerksicherheit, Transport, Firewall |
| CRYP | ~90 | Kryptographie, Schluesselmanagement |
| ACC | ~25 | Zugriffskontrolle (Access Control) |
| INC | ~25 | Incident Response, Vorfallmanagement |

Zusaetzlich existieren spezialisierte Domains wie CRA, ARC, API, PKI, SUP, VUL, BCP, PHY u.v.m.

### Status (Release State)

| Status | Bedeutung |
|--------|-----------|
| **Draft** | Entwurf — noch nicht freigegeben |
| **Approved** | Freigegeben fuer Kunden |
| **Review noetig** | Muss manuell geprueft werden (Pipeline-erzeugt) |
| **Zu aehnlich** | Too-Close-Check hat Warnung ausgeloest |
| **Duplikat** | Wurde als Duplikat eines anderen Controls erkannt |
| **Deprecated** | Veraltet/geloescht |

### Nachweis (Verification Method)

| Methode | Farbe | Beschreibung |
|---------|-------|-------------|
| **Code Review** | Blau | Nachweis durch Quellcode-Inspektion |
| **Dokument** | Amber | Nachweis durch Richtlinien, Prozesse, Schulungen |
| **Tool** | Teal | Nachweis durch automatisierte Scans/Monitoring |
| **Hybrid** | Lila | Kombination aus mehreren Methoden |

### Kategorie

Thematische Einordnung (23 Kategorien). Kategorien sind **thematisch**, Domains **strukturell**.
Ein AUTH-Control kann z.B. die Kategorie "Netzwerksicherheit" haben.

### Zielgruppe (Target Audience)

| Zielgruppe | Bedeutung |
|------------|-----------|
| **Unternehmen** | Fuer Endkunden/Firmen relevant |
| **Behoerden** | Spezifisch fuer oeffentliche Verwaltung |
| **Anbieter** | Fuer SaaS/Plattform-Anbieter |
| **Alle** | Allgemein anwendbar |
| **Entwickler** | Software-Entwickler |
| **DSB** | Datenschutzbeauftragte |
| **GF** | Geschaeftsfuehrung |
| **IT** | IT-Abteilung |
| **Recht** | Rechtsabteilung |
| **Compliance** | Compliance-Officer |
| **Personal** | Personalwesen |
| **Einkauf** | Beschaffung |
| **Produktion** | Fertigung |
| **Vertrieb** | Sales |
| **Gesundheit** | Gesundheitswesen |
| **Finanzen** | Finanzwesen |
| **Oeffentl. Dienst** | Oeffentlicher Dienst |

### Dokumentenursprung (Source)

Filtert nach der Quelldokument-Herkunft des Controls. Die wichtigsten Quellen:

| Quelle | Typ |
|--------|-----|
| KI-Verordnung (EU) 2024/1689 | EU-Recht |
| Cyber Resilience Act (EU) 2024/2847 | EU-Recht |
| DSGVO (EU) 2016/679 | EU-Recht |
| NIS2-Richtlinie (EU) 2022/2555 | EU-Recht |
| NIST SP 800-53, CSF 2.0, SSDF | US-Standards |
| OWASP Top 10, ASVS, SAMM | Open Source |
| ENISA Guidelines | EU-Agentur |
| CISA Secure by Design | US-Behoerde |
| BDSG, TKG, GewO, HGB | Deutsche Gesetze |
| EDPB Leitlinien | EU Datenschutz |

---

## Badges & Lizenzregeln

### Lizenzregel-Badge (Rule 1 / 2 / 3)

Die Lizenzregel bestimmt, wie ein Control erstellt und genutzt werden darf:

| Badge | Farbe | Regel | Bedeutung |
|-------|-------|-------|-----------|
| **Free Use** | Gruen | Rule 1 | Quelle ist Public Domain oder EU-Recht — Originaltext darf gezeigt werden |
| **Zitation** | Blau | Rule 2 | Quelle ist CC-BY oder aehnlich — Zitation + Quellenangabe erforderlich |
| **Reformuliert** | Amber | Rule 3 | Quelle hat eingeschraenkte Lizenz — eigenstaendig reformuliert, kein Originaltext |

### Processing Path

| Pfad | Bedeutung |
|------|-----------|
| `structured` / `structured_batch` | Control direkt aus dem Quelltext strukturiert (Rule 1/2) |
| `llm_reform` / `llm_reform_batch` | Control vollstaendig reformuliert (Rule 3) |
| `no_control` | LLM konnte kein Control ableiten (null im Array) |

### Generation Strategy Badge

| Badge | Farbe | Bedeutung |
|-------|-------|-----------|
| **v1** | Grau | Original-Pipeline (ungrouped) |
| **v2** | Emerald | Document-grouped Pipeline |

### Weitere Badges

| Badge | Bedeutung |
|-------|-----------|
| Score | Risiko-Score (0-10) |
| Severity-Badge | Schweregrad (Kritisch/Hoch/Mittel/Niedrig) |
| State-Badge | Freigabestatus (Draft/Approved/etc.) |
| Kategorie-Badge | Thematische Kategorie |
| Zielgruppe-Badge | Enterprise/Behoerden/Anbieter/Alle/etc. |

---

## Unabhaengige Taxonomie

### Eigenes Klassifikationssystem

Die Canonical Control Library verwendet ein **eigenes Domain-Schema**, das sich bewusst von
proprietaeren Frameworks unterscheidet. Die Domains werden **automatisch** durch den
Control Generator vergeben, basierend auf dem Inhalt der Quelldokumente.

### 16 Standard-Domains

| Domain | Name | Beschreibung |
|--------|------|-------------|
| AUTH | Identity & Access Management | Authentisierung, MFA, Token-Management |
| CRYP | Cryptographic Operations | Key Management, Rotation, HSM |
| NET | Network & Transport Security | TLS, Zertifikate, Netzwerk-Haertung |
| DATA | Data Governance & Classification | Datenklassifikation, Schutzmassnahmen |
| LOG | Security Operations & Logging | Privacy-Aware Logging, SIEM |
| ACC | Access Control | Zugriffskontrolle, Berechtigungen |
| SEC | IT Security | Schwachstellen, Haertung, Konfiguration |
| INC | Incident Management | Vorfallmanagement, Wiederherstellung |
| AI | Artificial Intelligence | KI-Compliance, Bias, Transparenz |
| COMP | Compliance | Konformitaet, Audit, Zertifizierung |
| GOV | Government & Public Administration | Behoerden, Verwaltung, Aufsicht |
| LAB | Labor Law | Arbeitsrecht, Arbeitsschutz |
| FIN | Financial Regulation | Finanzregulierung, BaFin |
| TRD | Trade Regulation | Gewerbe, Handelsrecht |
| ENV | Environmental | Umweltschutz, Nachhaltigkeit |
| HLT | Health | Gesundheit, Medizinprodukte |

### Spezialisierte Domains

Neben den 16 Standard-Domains gibt es ueber 80 weitere Domains fuer spezifische Themen:
CRA, ARC (Architektur), API, PKI, SUP (Supply Chain), VUL, BCP, PHY u.v.m.

### ID-Format

Control-IDs folgen dem Muster `DOMAIN-NNN` (z.B. AUTH-001, SEC-042). Dieses Format ist
**nicht von BSI oder anderen proprietaeren Standards abgeleitet**, sondern folgt einem
allgemein ueblichen Nummerierungsschema.

!!! warning "Keine BSI-Nomenklatur"
    Die Domains verwenden bewusst KEINE BSI-Bezeichner (O.Auth_*, O.Netz_*).

---

## Offene Referenzquellen

Alle Controls sind in mindestens einer der folgenden **frei zugaenglichen** Quellen verankert:

### OWASP (CC BY-SA 4.0 — kommerziell erlaubt)

- **ASVS** — Application Security Verification Standard v4.0.3
- **MASVS** — Mobile Application Security Verification Standard v2.1
- **Top 10** — OWASP Top 10 (2021)
- **Cheat Sheets** — OWASP Cheat Sheet Series
- **SAMM** — Software Assurance Maturity Model

### NIST (Public Domain — keine Einschraenkungen)

- **SP 800-53 Rev.5** — Security and Privacy Controls
- **SP 800-63B** — Digital Identity Guidelines (Authentication)
- **SP 800-57** — Key Management Recommendations
- **SP 800-52 Rev.2** — TLS Implementation Guidelines
- **SP 800-92** — Log Management Guide
- **SP 800-218 (SSDF)** — Secure Software Development Framework

### ENISA (CC BY 4.0 — kommerziell erlaubt)

- Good Practices for IoT/Mobile Security
- Data Protection Engineering
- Algorithms, Key Sizes and Parameters Report

### Weitere offene Quellen

- **SLSA** (Supply-chain Levels for Software Artifacts) — Google Open Source
- **CIS Controls v8** (CC BY-NC-ND — nur fuer interne Analyse)
- **CISA Secure by Design** — US-Behoerde (Public Domain)

---

## Geschuetzte Quellen — Nur interne Analyse

Die folgenden Quellen werden **ausschliesslich intern zur Analyse** verwendet.
Kein Text, keine Struktur, keine Bezeichner aus diesen Quellen erscheinen im Produkt.

### BSI (Nutzungsbedingungen — kommerziell eingeschraenkt)

- TR-03161 Teil 1-3 (Mobile, Web, Hintergrunddienste)
- Nutzung: TDM unter UrhG §44b, Kopien werden geloescht
- Kein Shipping von Zitaten, Embeddings oder Strukturen

### ISO/IEC (Kostenpflichtig — kein Shipping)

- ISO 27001, ISO 27002
- Nutzung: Nur als Referenz fuer Mapping, kein Text im Produkt

### ETSI (Restriktiv — kein kommerzieller Gebrauch)

- Nutzung: Nur als Hintergrundwissen, kein direkter Einfluss

### Trennungsprinzip

| Ebene | Geschuetzte Quelle | Offene Quelle |
|-------|--------------------|---------------|
| Analyse | Darf gelesen werden | Darf gelesen werden |
| Inspiration | Darf Ideen liefern | Darf Ideen liefern |
| Formulierung | Keine Uebernahme | Darf zitiert werden |
| Struktur | Keine Uebernahme | Darf verwendet werden |
| Produkttext | Nicht erlaubt | Erlaubt |

---

## Verifikationsmethoden

Jedes Control wird einer von vier Verifikationsmethoden zugeordnet. Dies bestimmt,
**wie** ein Kunde den Nachweis fuer die Einhaltung erbringen kann:

| Methode | Beschreibung | Beispiele |
|---------|-------------|-----------|
| **Code Review** | Quellcode-Inspektion | Input-Validierung, Encryption-Konfiguration, Auth-Logic |
| **Dokument** | Richtlinien, Prozesse, Schulungen | Notfallplaene, Schulungsnachweise, Datenschutzkonzepte |
| **Tool** | Automatisierte Tools/Scans | SIEM-Logs, Vulnerability-Scans, Monitoring-Dashboards |
| **Hybrid** | Kombination mehrerer Methoden | Zugriffskontrollen (Code + Policy + Tool) |

### Bedeutung fuer Kunden

- **Code Review Controls** koennen direkt im SDK-Scan geprueft werden
- **Dokument Controls** erfordern manuelle Uploads (PDFs, Links)
- **Tool Controls** koennen per API-Integration automatisch nachgewiesen werden
- **Hybrid Controls** benoetigen mehrere Nachweisarten

---

## Thematische Kategorien (23)

Controls sind in thematische Kategorien gruppiert:

| Kategorie | Beschreibung |
|-----------|-------------|
| `encryption` | Verschluesselung, Kryptographie, Key Management |
| `authentication` | Authentifizierung, Login, MFA, Session-Management |
| `network` | Netzwerk, Firewall, VPN, Segmentierung |
| `data_protection` | Datenschutz, DSGVO, Anonymisierung |
| `logging` | Protokollierung, Monitoring, SIEM |
| `incident` | Vorfallmanagement, Meldepflichten |
| `continuity` | Business Continuity, Disaster Recovery, Backups |
| `compliance` | Konformitaet, Audit, Zertifizierung |
| `supply_chain` | Lieferkette, Vendor Risk, SBOM |
| `physical` | Physische Sicherheit, Zutritt |
| `personnel` | Schulung, Security Awareness |
| `application` | Software, Code Review, API, SAST/DAST |
| `system` | Haertung, Patch, Konfiguration |
| `risk` | Risikobewertung, -analyse, -management |
| `governance` | ISMS, Richtlinien, Sicherheitsorganisation |
| `hardware` | Hardware, Firmware, TPM, Secure Boot |
| `identity` | IAM, SSO, Federation, Verzeichnisdienste |
| `public_administration` | Behoerden, Verwaltung |
| `labor_law` | Arbeitsrecht, Arbeitsschutz |
| `finance` | Finanzregulierung, Rechnungslegung |
| `trade_regulation` | Gewerbe, Handelsrecht |
| `environmental` | Umweltschutz, Nachhaltigkeit |
| `health` | Gesundheit, Medizinprodukte |

!!! info "Abgrenzung zu Domains"
    Kategorien sind **thematisch**, Domains (AUTH, NET, etc.) sind **strukturell**.
    Ein Control AUTH-005 (Domain AUTH) hat die Kategorie "authentication",
    aber ein Control NET-012 (Domain NET) koennte ebenfalls die Kategorie
    "authentication" haben, wenn es um Netzwerk-Authentifizierung geht.

---

## Master Library Strategie

### RAG-First Ansatz

Die Canonical Control Library folgt einer **RAG-First-Strategie** in Wellen:

| Welle | Quellen | Lizenzregel | Vorteil |
|-------|---------|------------|---------|
| 1 | OWASP (ASVS, MASVS, Top10) | Rule 2 (CC-BY-SA, Zitation) | Originaltext + Zitation |
| 2 | NIST (SP 800-53, CSF, SSDF) | Rule 1 (Public Domain) | Voller Text, keine Einschraenkungen |
| 3 | EU-Verordnungen (DSGVO, AI Act, NIS2, CRA) | Rule 1 (EU Law) | Gesetzestext + Erklaerung |
| 4 | Deutsche Gesetze (BDSG, TTDSG, TKG) | Rule 1 (DE Law) | Gesetzestext + Erklaerung |

### Dedup gegen BSI Rule-3 Controls

Die BSI Rule-3 Controls werden gegen die neuen Rule 1+2 Controls abgeglichen:

- Wenn ein BSI-Control ein Duplikat eines OWASP/NIST-Controls ist → **OWASP/NIST bevorzugt**
  (weil Originaltext + Zitation erlaubt)
- BSI-Duplikate werden als `deprecated` markiert
- Tags und Anchors werden in den behaltenen Control zusammengefuehrt

---

## Automatisierte Validierung

Jedes Control wird bei jedem Commit automatisch geprueft:

### 1. Schema-Validierung

- Alle Pflichtfelder vorhanden
- Control-ID Format: `^[A-Z]{2,6}-[0-9]{3}$`
- Severity: low, medium, high, critical
- Risk Score: 0-10

### 2. No-Leak Scanner

Regex-Pruefung gegen verbotene Muster in produktfaehigen Feldern:

- `O.[A-Za-z]+_[0-9]+` — BSI Objective-IDs
- `TR-03161` — Direkte BSI-TR-Referenzen
- `BSI-TR-` — BSI-spezifische Locators
- `Anforderung [A-Z].[0-9]+` — BSI-Anforderungsformat

### 3. Open Anchor Check

Jedes freigegebene Control muss mindestens 1 Open-Source-Referenz haben.

### 4. Too-Close Detektor (5 Metriken)

| Metrik | Warn | Fail | Beschreibung |
|--------|------|------|-------------|
| Exact Phrase | ≥8 Tokens | ≥12 Tokens | Laengste identische Token-Sequenz |
| Token Overlap | ≥0.20 | ≥0.30 | Jaccard-Aehnlichkeit der Token-Mengen |
| 3-Gram Jaccard | ≥0.10 | ≥0.18 | Zeichenketten-Aehnlichkeit |
| Embedding Cosine | ≥0.86 | ≥0.92 | Semantische Aehnlichkeit (bge-m3) |
| LCS Ratio | ≥0.35 | ≥0.50 | Longest Common Subsequence |

**Entscheidungslogik:**

- **PASS** — Kein Fail + max 1 Warn
- **WARN** — Max 2 Warn, kein Fail → Human Review erforderlich
- **FAIL** — Irgendein Fail → Blockiert, Umformulierung noetig

---

## Live-Daten im Frontend

### Lizenz-Matrix

Tabelle aller `canonical_control_licenses` mit Berechtigungsbadges:

| Feld | Beschreibung |
|------|-------------|
| `license_id` | Eindeutige Lizenz-ID (z.B. `OWASP_CC_BY_SA`) |
| `name` | Lizenzname |
| `commercial_use` | `allowed` / `restricted` / `prohibited` / `unclear` |
| `ai_training_restriction` | KI-Training-Einschraenkung |
| `tdm_allowed_under_44b` | TDM nach UrhG §44b erlaubt? (`yes` / `no` / `unclear`) |
| `deletion_required` | Loeschpflicht nach Analyse? |

**API:** `GET /v1/canonical/licenses`

### Quellenregister

Karten fuer jede `canonical_control_sources` mit 4 Berechtigungsstufen:

| Feld | Beschreibung |
|------|-------------|
| `source_id` | Eindeutige Quell-ID (z.B. `OWASP_ASVS`) |
| `title` | Quellenname |
| `publisher` | Herausgeber |
| `license_name` | Verknuepfte Lizenz |
| `allowed_analysis` | Analyse erlaubt? |
| `allowed_store_excerpt` | Auszuege speichern erlaubt? |
| `allowed_ship_embeddings` | Embeddings im Produkt erlaubt? |
| `allowed_ship_in_product` | Text im Produkt erlaubt? |
| `vault_retention_days` | Aufbewahrungsfrist in Tagen |
| `vault_access_tier` | `restricted` / `internal` / `public` |

**API:** `GET /v1/canonical/sources`

---

## Quelldateien

| Datei | Beschreibung |
|-------|-------------|
| `admin-compliance/app/sdk/control-provenance/page.tsx` | Frontend (10 Sektionen + 2 Live-Daten-Tabellen) |
| `backend-compliance/migrations/044_canonical_control_library.sql` | DB-Schema (Licenses, Sources, Mappings) |
| `backend-compliance/compliance/api/canonical_control_routes.py` | API: `/v1/canonical/licenses`, `/v1/canonical/sources` |

---

## Verwandte Dokumentation

- [Canonical Control Library (CP-CLIB)](canonical-control-library.md) — Domains, Datenmodell, Pipeline, Tests
- [Control Generator Pipeline](control-generator-pipeline.md) — 7-Stufen-Pipeline, QA, Recital-Erkennung