Benjamin_Boenisch/breakpilot-compliance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update control library taxonomy, add provenance wiki page
Some checks failed
CI/CD / go-lint (push) Has been skipped
Details
CI/CD / python-lint (push) Has been skipped
Details
CI/CD / nodejs-lint (push) Has been skipped
Details
CI/CD / test-go-ai-compliance (push) Failing after 36s
Details
CI/CD / test-python-backend-compliance (push) Successful in 33s
Details
CI/CD / test-python-document-crawler (push) Successful in 24s
Details
CI/CD / test-python-dsms-gateway (push) Successful in 16s
Details
CI/CD / validate-canonical-controls (push) Successful in 10s
Details
CI/CD / Deploy (push) Has been skipped
Details

Browse Source 
- canonical-control-library.md: add 7 release_states (was 4), target_audience
  (17 values), generation_strategy, missing API endpoints (controls-customer,
  backfill-citations, backfill-domain), updated test counts (81+)
- NEW control-provenance.md: extracted from frontend page.tsx — methodology,
  legal basis, filters, badges, taxonomy, open/restricted sources,
  verification methods, 23 categories, license matrix, source registry
- mkdocs.yml: add Control Provenance Wiki to navigation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
2026-03-18 08:49:42 +01:00
parent 148c7ba3af
commit 3bb9fffab6
3 changed files with 624 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

463
docs-src/services/sdk-modules/control-provenance.md Normal file
View File

@@ -0,0 +1,463 @@
# 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