diff --git a/docs-src/services/sdk-modules/canonical-control-library.md b/docs-src/services/sdk-modules/canonical-control-library.md index d218a2d..7fe2491 100644 --- a/docs-src/services/sdk-modules/canonical-control-library.md +++ b/docs-src/services/sdk-modules/canonical-control-library.md @@ -91,6 +91,13 @@ erDiagram uuid framework_id FK varchar control_id varchar severity + varchar release_state + varchar category + varchar verification_method + varchar target_audience + varchar generation_strategy + smallint pipeline_version + integer license_rule jsonb open_anchors } canonical_control_mappings { @@ -121,18 +128,26 @@ erDiagram | `GET` | `/v1/canonical/frameworks` | Alle Frameworks | | `GET` | `/v1/canonical/frameworks/{id}` | Framework-Details | | `GET` | `/v1/canonical/frameworks/{id}/controls` | Controls eines Frameworks | -| `GET` | `/v1/canonical/controls` | Alle Controls (Filter: `severity`, `domain`, `release_state`) | +| `GET` | `/v1/canonical/controls` | Alle Controls (Filter: `severity`, `domain`, `release_state`, `category`) | | `GET` | `/v1/canonical/controls/{control_id}` | Einzelnes Control (z.B. AUTH-001) | +| `POST` | `/v1/canonical/controls` | Neues Control anlegen | +| `PUT` | `/v1/canonical/controls/{control_id}` | Control aktualisieren | +| `DELETE` | `/v1/canonical/controls/{control_id}` | Control loeschen (Soft Delete) | +| `GET` | `/v1/canonical/controls-customer` | Kunden-View: verbirgt generation_metadata, Rule-3-Quellen | | `GET` | `/v1/canonical/sources` | Quellenregister mit Berechtigungen | | `GET` | `/v1/canonical/licenses` | Lizenz-Matrix | +| `GET` | `/v1/canonical/categories` | Alle 23 Kategorien | | `POST` | `/v1/canonical/controls/{id}/similarity-check` | Too-Close-Pruefung | | `POST` | `/v1/canonical/generate` | Generator-Job starten | | `GET` | `/v1/canonical/generate/jobs` | Alle Generator-Jobs | +| `GET` | `/v1/canonical/generate/status/{job_id}` | Einzelnen Job-Status abfragen | | `GET` | `/v1/canonical/generate/processed-stats` | Verarbeitungsstatistik pro Collection | -| `GET` | `/v1/canonical/generate/review-queue` | Controls zur Pruefung | -| `POST` | `/v1/canonical/generate/review/{control_id}` | Review abschliessen | +| `GET` | `/v1/canonical/generate/review-queue` | Controls zur Pruefung (needs_review, too_close, duplicate) | +| `POST` | `/v1/canonical/generate/review/{control_id}` | Review abschliessen (approve/reject) | | `POST` | `/v1/canonical/generate/bulk-review` | Bulk-Review (approve/reject nach State) | | `POST` | `/v1/canonical/generate/qa-reclassify` | QA-Reklassifizierung bestehender Controls | +| `POST` | `/v1/canonical/generate/backfill-citations` | Article/Paragraph-Referenzen nachpflegen | +| `POST` | `/v1/canonical/generate/backfill-domain` | Domain/Category/Target-Audience nachpflegen (Anthropic) | | `GET` | `/v1/canonical/blocked-sources` | Gesperrte Quellen (Rule 3) | | `POST` | `/v1/canonical/blocked-sources/cleanup` | Cleanup-Workflow starten | @@ -207,6 +222,65 @@ Jede Quelle hat definierte Berechtigungen: --- +## Release States (7 Werte) + +| State | Frontend-Label | Farbe | Beschreibung | +|-------|---------------|-------|-------------| +| `draft` | Draft | Grau | Entwurf — noch nicht freigegeben | +| `review` | Review | Blau | Wartet auf manuelle Pruefung | +| `approved` | Approved | Gruen | Freigegeben fuer Kunden | +| `needs_review` | Review noetig | Gelb | Vom Generator erzeugt, QA-Pruefung noetig | +| `too_close` | Zu aehnlich | Rot | Too-Close-Detektor hat Warnung ausgeloest | +| `duplicate` | Duplikat | Orange | Wurde als Duplikat eines bestehenden Controls erkannt | +| `deprecated` | Deprecated | Rot | Veraltet/geloescht (Soft Delete) | + +!!! note "Pipeline-erzeugte States" + `needs_review`, `too_close` und `duplicate` werden automatisch vom Generator vergeben. + `draft`, `review` und `approved` sind manuelle Workflow-States. + +--- + +## Target Audience (Zielgruppe) + +Jedes Control kann eine oder mehrere Zielgruppen haben. Die Zielgruppe bestimmt, fuer welchen Organisationstyp das Control relevant ist. + +| Key | Label | Farbe | +|-----|-------|-------| +| `enterprise` / `unternehmen` | Unternehmen | Cyan | +| `authority` / `behoerden` | Behoerden | Rose | +| `provider` | Anbieter | Violet | +| `all` | Alle | Grau | +| `entwickler` | Entwickler | Sky | +| `datenschutzbeauftragte` | DSB | Purple | +| `geschaeftsfuehrung` | GF | Amber | +| `it-abteilung` | IT | Blau | +| `rechtsabteilung` | Recht | Fuchsia | +| `compliance-officer` | Compliance | Indigo | +| `personalwesen` | Personal | Pink | +| `einkauf` | Einkauf | Lime | +| `produktion` | Produktion | Orange | +| `vertrieb` | Vertrieb | Teal | +| `gesundheitswesen` | Gesundheit | Rot | +| `finanzwesen` | Finanzen | Emerald | +| `oeffentlicher_dienst` | Oeffentl. Dienst | Rose | + +**DB-Feld:** `target_audience` (VARCHAR, kann Array sein als JSONB) +**Migration:** 049_target_audience.sql + +--- + +## Generation Strategy + +| Strategy | Badge | Farbe | Bedeutung | +|----------|-------|-------|-----------| +| `ungrouped` (Default/null) | v1 | Grau | Einzelverarbeitung (Original-Ansatz) | +| `document_grouped` | v2 | Emerald | Dokumentgruppenweise Verarbeitung (v2 Pipeline) | + +**DB-Feld:** `generation_strategy` (TEXT, Default: `'ungrouped'`) +**Migration:** 058_generation_strategy.sql + +--- + ## CI/CD Validation Der Validator (`scripts/validate-controls.py`) prueft bei jedem Commit: @@ -223,19 +297,77 @@ Der Validator (`scripts/validate-controls.py`) prueft bei jedem Commit: ### Control Library Browser (`/sdk/control-library`) +**Listen-Ansicht:** + - Framework-Info mit Version und Beschreibung -- Filterable Control-Tabelle (Domain, Severity, Freitext) -- Detail-Ansicht mit: Ziel, Begruendung, Anforderungen, Pruefverfahren, Nachweise -- **Open-Source-Referenzen** prominent dargestellt (gruener Kasten) -- Tags und Scope-Informationen +- Filterable Control-Tabelle mit **7 Filter-Dropdowns:** + 1. Schweregrad (critical, high, medium, low) + 2. Domain (aus Meta-Daten, alle vorhandenen Domains) + 3. Status (draft, approved, needs_review, too_close, duplicate, deprecated) + 4. Nachweis (code_review, document, tool, hybrid) + 5. Kategorie (23 thematische Kategorien) + 6. Zielgruppe (17 Audience-Werte) + 7. Dokumentenursprung (nach Quellen-Regulation) +- Sortierung: ID, Quelle, Neueste/Aelteste +- Pagination: 50 Controls pro Seite +- Freitext-Suche (ID, Titel, Ziel) + +**Detail-Ansicht:** + +- Ziel, Begruendung, Geltungsbereich +- Anforderungen, Pruefverfahren, Nachweise +- **Gesetzliche Grundlage** (blaue Box): source_citation mit Artikel, Paragraph, Lizenz, Link +- **Open-Source-Referenzen** (gruener Kasten): Verlinkte Open Anchors +- Generierungsdetails: processing_path, similarity_status +- Tags, Risk Score, Implementation Effort +- **Badges:** Severity, State, LicenseRule, VerificationMethod, Category, TargetAudience, GenerationStrategy + +**Review-Modus:** + +Der Review-Modus wird aktiviert wenn `needs_review`-Controls vorhanden sind. +Er teilt die Review-Queue in zwei Tabs: + +| Tab | Inhalt | Ansicht | +|-----|--------|---------| +| **Duplikat-Verdacht** | Controls mit `similar_controls` in generation_metadata | Side-by-Side Vergleich (ReviewCompare) | +| **Rule 3 ohne Anchor** | Controls ohne Open Anchors | Einzel-Detail-Ansicht | + +**Duplikat-Vergleich (ReviewCompare):** + +- Linke Seite: Zu pruefendes Control (gelb hervorgehoben) +- Rechte Seite: Verdaechtiges Duplikat (aus `generation_metadata.similar_controls[0]`) +- Aehnlichkeits-Prozentsatz im Header +- Aktionen: Behalten (approve), Duplikat (reject), Bearbeiten + +**Weitere Aktionen:** + +- Generator-Modal: Job starten (Domain, Collections, Dry-Run, max_controls) +- Bulk-Review: Alle gefilterten Controls genehmigen/ablehnen +- Statistik-Dialog: Verarbeitungsstatistik pro Collection ### Control Provenance Wiki (`/sdk/control-provenance`) -- Dokumentation der Methodik -- Unabhaengige Taxonomie erklaert -- Offene Referenzquellen aufgelistet -- Geschuetzte Quellen und Trennungsprinzip -- **Live-Daten:** Lizenz-Matrix und Quellenregister aus der Datenbank +Wiki-artige Dokumentation der rechtlichen und methodischen Grundlage fuer die Control-Erstellung: + +**Statische Sektionen (10):** + +1. **Methodik der Control-Erstellung** — Dreistufiger Prozess, rechtliche Basis (UrhG §44b, §23) +2. **Filter in der Control Library** — Erklaerung aller 7 Filter + Sortierung +3. **Badges & Lizenzregeln** — Rule 1/2/3, Processing Paths, Referenzen +4. **Unabhaengige Taxonomie** — Top-10 Domains, ID-Format, spezialisierte Domains +5. **Offene Referenzquellen** — OWASP, NIST, ENISA, SLSA, CIS +6. **Geschuetzte Quellen** — BSI, ISO, ETSI + Trennungsprinzip +7. **Verifikationsmethoden** — 4 Methoden + Kundenbedeutung +8. **Thematische Kategorien** — 17 Kategorien mit Beschreibung +9. **Master Library Strategie** — RAG-First, Dedup, Wellen-Ansatz +10. **Automatisierte Validierung** — CI/CD-Checks, Too-Close-Detektor + +**Live-Daten (API-gespeist):** + +- **Lizenz-Matrix:** Tabelle aller `canonical_control_licenses` mit Berechtigungsbadges +- **Quellenregister:** Karten fuer jede `canonical_control_sources` mit 4 Berechtigungsstufen + +Siehe auch: [Control Provenance Dokumentation](control-provenance.md) --- @@ -684,21 +816,27 @@ curl -X POST https://api-dev.breakpilot.ai/api/compliance/v1/canonical/controls | `backend-compliance/tests/test_canonical_control_routes.py` | Python | 14 Tests | REST API Endpoints | | `backend-compliance/tests/test_license_gate.py` | Python | 12 Tests | Lizenz-Klassifikation | | `backend-compliance/tests/test_validate_controls.py` | Python | 14 Tests | CI/CD Validator | -| `backend-compliance/tests/test_control_generator.py` | Python | 15 Tests | Pipeline, Batch, Lizenzregeln | -| **Gesamt** | | **82 Tests** | +| `backend-compliance/tests/test_control_generator.py` | Python | 81 Tests | Pipeline, Batch, Lizenzregeln, QA, Recital | +| **Gesamt** | | **149+ Tests** | ### Control Generator Tests (test_control_generator.py) Die Generator-Tests decken folgende Bereiche ab: -- **`TestLicenseMapping`** (12 Tests) — Korrekte Zuordnung von `regulation_code` zu Lizenzregeln (Rule 1/2/3), - Case-Insensitivity, Rule 3 darf keine Quellennamen exponieren -- **`TestDomainDetection`** (5 Tests) — Erkennung von AUTH, CRYPT, NET, DATA Domains aus Chunk-Text -- **`TestJsonParsing`** (4 Tests) — Robustes Parsing von LLM-Antworten (plain JSON, Markdown-Fenced, mit Preamble) -- **`TestGeneratedControlRules`** (3 Tests) — Rule 1 hat Originaltext, Rule 2 hat Citation, Rule 3 hat **nichts** -- **`TestAnchorFinder`** (2 Tests) — RAG-Suche filtert Rule 3 Quellen aus, Web-Suche erkennt Frameworks -- **`TestPipelineMocked`** (5 Tests) — End-to-End mit Mocks: Lizenz-Klassifikation, Rule 3 Blocking, - Hash-Deduplizierung, Config-Defaults (`batch_size: 5`), Rule 1 Citation-Generierung +| Klasse | Tests | Prueft | +|--------|-------|--------| +| `TestLicenseMapping` | 12 | Lizenz-Klassifikation (Rule 1/2/3), Case-Insensitivitaet | +| `TestDomainDetection` | 5 | Keyword-basierte Domain-Erkennung (AUTH, CRYP, NET, DATA) | +| `TestJsonParsing` | 4 | JSON-Parser fuer LLM-Responses (Markdown-Fencing, Preamble) | +| `TestGeneratedControlRules` | 3 | Rule-spezifische Felder (original_text, citation, source_info) | +| `TestAnchorFinder` | 2 | RAG-Suche + Web-Framework-Erkennung | +| `TestPipelineMocked` | 5 | End-to-End Pipeline mit Mocks (Lizenz, Hash-Dedup, Config) | +| `TestParseJsonArray` | 15 | JSON-Array-Parser (Wrapper-Objekte, Bracket-Extraction, Fallbacks) | +| `TestBatchSizeConfig` | 5 | Batch-Groesse-Konfiguration + Defaults | +| `TestBatchProcessingLoop` | 10 | Batch-Verarbeitung (Rule-Split, Mixed-Rules, Too-Close, Null-Handling) | +| `TestRegulationFilter` | 5 | regulation_filter Prefix-Matching, leere regulation_codes | +| `TestPipelineVersion` | 5 | pipeline_version=2 in DB-Writes, null-Handling in Structure/Reform | +| `TestRecitalDetection` | 10 | Erwaegungsgrund-Erkennung in Quelltexten (Regex, Phrasen, Kombiniert) | --- diff --git a/docs-src/services/sdk-modules/control-provenance.md b/docs-src/services/sdk-modules/control-provenance.md new file mode 100644 index 0000000..7036c90 --- /dev/null +++ b/docs-src/services/sdk-modules/control-provenance.md @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml index 97566cf..015c3f3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -104,6 +104,7 @@ nav: - Policy-Bibliothek (29 Richtlinien): services/sdk-modules/policy-bibliothek.md - Canonical Control Library (CP-CLIB): services/sdk-modules/canonical-control-library.md - Control Generator Pipeline: services/sdk-modules/control-generator-pipeline.md + - Control Provenance Wiki: services/sdk-modules/control-provenance.md - Strategie: - Wettbewerbsanalyse & Roadmap: strategy/wettbewerbsanalyse.md - Entwicklung: