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

Canonical Control Library (CP-CLIB)

Eigenstaendig formulierte Security Controls basierend auf offenem Wissen (OWASP, NIST, ENISA). Unabhaengige Taxonomie — kein Bezug zu proprietaeren Frameworks.

Prefix: CP-CLIB · Frontend: https://macmini:3007/sdk/control-library Provenance Wiki: https://macmini:3007/sdk/control-provenance Proxy: /api/sdk/v1/canonical → backend-compliance:8002/api/compliance/v1/canonical/...

---

Motivation

Wir benoetigen ein System, um aus verschiedenen Security-Guidelines eigenstaendige, rechtlich defensible Controls zu extrahieren, ohne proprietaere Texte im Produkt zu verwenden.

Kernprinzipien

1. Unabhaengige Taxonomie — Eigene Domain-IDs (AUTH, NET, SUP, etc.), eigenes ID-Format (DOMAIN-NNN)
2. Open-Source-Verankerung — Jedes Control hat mindestens 1 Open Anchor (OWASP/NIST/ENISA)
3. Strikte Quellentrennung — Geschuetzte Quellen nur intern zur Analyse, nie im Produkt
4. Automatisierte Pruefung — Too-Close-Detektor + No-Leak-Scanner in CI/CD

---

Rechtliche Basis

Gesetz	Bezug
UrhG §44b	Text & Data Mining — Kopien loeschen
UrhG §23	Hinreichender Abstand zum Originalwerk
BSI Nutzungsbedingungen	Kommerziell nur mit Zustimmung

---

Domains (Unabhaengige Taxonomie)

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, Betriebsverfassung
FIN	Financial Regulation	Finanzregulierung, Rechnungslegung, BaFin
TRD	Trade Regulation	Gewerbe, Handelsrecht, Produktsicherheit
ENV	Environmental	Umweltschutz, Nachhaltigkeit, Emissionen
HLT	Health	Gesundheit, Medizinprodukte, Hygiene

!!! warning "Keine BSI-Nomenklatur" Die Domains verwenden bewusst KEINE BSI-Bezeichner (O.Auth_, O.Netz_). Das ID-Format DOMAIN-NNN ist eine gaengige, nicht-proprietaere Konvention.

---

Datenmodell (Migration 044)

erDiagram
    canonical_control_licenses ||--o{ canonical_control_sources : "hat"
    canonical_control_frameworks ||--o{ canonical_controls : "enthaelt"
    canonical_controls ||--o{ canonical_control_mappings : "hat"
    canonical_control_sources ||--o{ canonical_control_mappings : "referenziert"

    canonical_control_licenses {
        varchar license_id PK
        varchar name
        varchar commercial_use
        boolean deletion_required
    }
    canonical_control_sources {
        uuid id PK
        varchar source_id UK
        varchar title
        boolean allowed_ship_in_product
    }
    canonical_control_frameworks {
        uuid id PK
        varchar framework_id UK
        varchar name
        varchar version
    }
    canonical_controls {
        uuid id PK
        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 source_citation
        jsonb open_anchors
    }
    canonical_control_mappings {
        uuid id PK
        uuid control_id FK
        uuid source_id FK
        varchar mapping_type
        varchar attribution_class
    }

Tabellen

Tabelle	Zweck	Produktfaehig?
canonical_control_licenses	Lizenz-Metadaten	Ja (read-only)
canonical_control_sources	Quellen-Register	Nein (nur intern)
canonical_control_frameworks	Framework-Registry	Ja
canonical_controls	Die eigentlichen Controls	Ja
canonical_control_mappings	Provenance-Trail	Nein (nur Audit)

---

API Endpoints

Methode	Pfad	Beschreibung
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, 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 (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

Beispiel: Control abrufen

curl -s https://macmini:8002/api/v1/canonical/controls/AUTH-001 | jq

Beispiel: Similarity Check

curl -X POST https://macmini:8002/api/v1/canonical/controls/AUTH-001/similarity-check \
  -H 'Content-Type: application/json' \
  -d '{
    "source_text": "Die Anwendung muss MFA implementieren.",
    "candidate_text": "Privileged accounts require multi-factor authentication."
  }' | jq

Response:

{
  "max_exact_run": 0,
  "token_overlap": 0.0714,
  "ngram_jaccard": 0.0323,
  "embedding_cosine": 0.0,
  "lcs_ratio": 0.0714,
  "status": "PASS",
  "details": {
    "max_exact_run": "PASS",
    "token_overlap": "PASS",
    "ngram_jaccard": "PASS",
    "embedding_cosine": "PASS",
    "lcs_ratio": "PASS"
  }
}

---

Too-Close-Detektor

5 Metriken mit Schwellwerten:

Metrik	Warn	Fail	Beschreibung
Exact Phrase	≥8 Tokens	≥12 Tokens	Laengste identische Token-Sequenz
Token Overlap	≥0.20	≥0.30	Jaccard 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
• FAIL — Irgendein Fail → Block, Umformulierung noetig

---

License Gate

Jede Quelle hat definierte Berechtigungen:

Nutzungsart	Spalte	Beispiel OWASP	Beispiel BSI
Analyse	allowed_analysis	✅	✅
Excerpt speichern	allowed_store_excerpt	✅	❌
Embeddings shippen	allowed_ship_embeddings	✅	❌
Im Produkt shippen	allowed_ship_in_product	✅	❌

---

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:

1. Schema Validation — Alle Pflichtfelder, ID-Format, Severity
2. No-Leak Scanner — Regex gegen BSI-Muster (O.Auth_*, TR-03161, etc.)
3. Open Anchor Check — Jedes Control hat ≥1 Open Anchor
4. Taxonomy Check — Keine BSI-style ID-Prefixe
5. Evidence Structure — Alle Evidence-Items haben type + description

---

Frontend

Control Library Browser (/sdk/control-library)

Listen-Ansicht:

• Framework-Info mit Version und Beschreibung
• 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
• Quellennachweis (dynamische Farbe): source_type-basiert — blau fuer Gesetze, indigo fuer Leitlinien, teal fuer Standards
• 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)

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 Generator Pipeline

Automatische Generierung von Controls aus dem gesamten RAG-Korpus (~105.000 Chunks aus Gesetzen, Verordnungen und Standards). Aktueller Stand: ~4.738 Controls generiert.

!!! tip "Ausfuehrliche Dokumentation" Siehe Control Generator Pipeline fuer die vollstaendige Referenz inkl. API-Endpoints, Konfiguration, Kosten und Pipeline-Versionen.

7-Stufen-Pipeline (v2)

flowchart TD
    A[1. RAG Scan] -->|Alle Chunks laden| B[2. License Classify]
    B -->|Rule 1/2| C[3a. Structure Batch]
    B -->|Rule 3| D[3b. Reform Batch]
    C --> E[4. Harmonize]
    D --> E
    E -->|Duplikat| F[Als Duplikat markieren]
    E -->|Neu| G[5. Anchor Search]
    G --> H[6. Store Control]
    H --> I[7. Mark Processed]

!!! info "Pipeline-Version v2 (seit 2026-03-17)" - Kein lokaler Vorfilter mehr — Anthropic API entscheidet selbst ueber Chunk-Relevanz via null-Returns - Annexe geschuetzt — Technische Anforderungen in Anhaengen werden nicht mehr uebersprungen - pipeline_version Spalte in DB unterscheidet v1- von v2-Controls

Stufe 1: RAG Scan

Scrollt durch ALLE Chunks in den konfigurierten RAG-Collections mittels Qdrant Scroll-API. Optionaler regulation_filter beschraenkt auf bestimmte Regulierungen per Prefix-Matching.

Bereits verarbeitete Chunks werden per SHA-256-Hash uebersprungen (canonical_processed_chunks).

Stufe 3: Lizenz-Klassifikation (3-Regel-System)

Regel	Lizenz	Original erlaubt?	Beispiel
Rule 1 (free_use)	EU-Gesetze, NIST, DE-Gesetze	Ja	DSGVO, BDSG, NIS2
Rule 2 (citation_required)	CC-BY, CC-BY-SA	Ja, mit Zitation	OWASP ASVS
Rule 3 (restricted)	Proprietaer	Nein, volle Reformulierung	BSI TR-03161

Stufe 4a/4b: Strukturierung / Reformulierung

• Rule 1+2: Anthropic strukturiert den Originaltext in Control-Format (Titel, Ziel, Anforderungen)
• Rule 3: Anthropic reformuliert vollstaendig — kein Originaltext, keine Quellennamen

Batch Processing (Stufe 4 — Optimierung)

Die Pipeline verarbeitet Chunks nicht einzeln, sondern sammelt sie in Batches von 5 Chunks pro API-Call. Das reduziert die Anzahl der Anthropic-API-Aufrufe um ~80% und beschleunigt die Generierung erheblich.

Ablauf

1. Chunks sammeln: Nach dem Prefilter werden relevante Chunks mit ihrer Lizenz-Info in pending_batch gesammelt
2. Batch voll? Sobald batch_size (Default: 5) erreicht ist, wird _flush_batch() aufgerufen
3. _process_batch() trennt den Batch nach Lizenzregel:
   • Rule 1+2 Chunks → _structure_batch() — ein einziger Anthropic-Call fuer alle
   • Rule 3 Chunks → _reformulate_batch() — ein einziger Anthropic-Call fuer alle
4. Ergebnis: JSON-Array mit genau N Controls, zurueck-gemappt per chunk_index

_structure_batch() (Rule 1+2)

Sendet alle freien/CC-BY Chunks in einem einzigen Prompt an Anthropic. Der Originaltext darf verwendet werden. Jeder Chunk wird als --- CHUNK N --- Block formatiert, das LLM gibt ein JSON-Array mit chunk_index zurueck.

# Prompt-Auszug:
"Strukturiere die folgenden 5 Gesetzestexte jeweils als eigenstaendiges Control."
"Gib ein JSON-Array zurueck mit GENAU 5 Objekten."

Processing Path: structured_batch (in generation_metadata)

_reformulate_batch() (Rule 3)

Sendet alle eingeschraenkten Chunks in einem Prompt. Der Originaltext darf nicht kopiert werden. Quellennamen und proprietaere Bezeichner werden im Prompt explizit verboten.

# Prompt-Auszug:
"KOPIERE KEINE Saetze. Verwende eigene Begriffe und Struktur."
"NENNE NICHT die Quellen. Keine proprietaeren Bezeichner."

Processing Path: llm_reform_batch (in generation_metadata)

Fallback bei Batch-Fehler

Falls ein Batch-Call fehlschlaegt (z.B. Timeout, Parsing-Error), faellt die Pipeline automatisch auf Einzelverarbeitung zurueck:

except Exception as e:
    logger.error("Batch processing failed: %s — falling back to single-chunk mode", e)
    for chunk, _lic in batch:
        ctrl = await self._process_single_chunk(chunk, config, job_id)

!!! info "Batch-Konfiguration" | Parameter | Wert | Beschreibung | |-----------|------|-------------| | batch_size | 5 (Default) | Chunks pro API-Call | | max_tokens | 8192 | Maximale Token-Laenge der LLM-Antwort | | LLM_TIMEOUT | 180s | Timeout pro Anthropic-Call |

Die `batch_size` ist ueber `GeneratorConfig` konfigurierbar.
Bei grosser Batch-Size steigt die Wahrscheinlichkeit fuer Parsing-Fehler.

Stufe 5: QA Validation (Automatische Qualitaetspruefung)

Die QA-Stufe validiert die Klassifizierung jedes Controls automatisch. Sie vergleicht die LLM-Klassifizierung mit Keyword-basierter Erkennung und loest bei Abweichungen eine Arbitrierung durch das lokale Ollama-Modell aus.

Ablauf

1. LLM-Category auswerten: Der Anthropic-Prompt fragt jetzt explizit nach category und domain
2. Keyword-Detection als Cross-Check: _detect_category(chunk.text) liefert eine zweite Meinung
3. Stimmen beide ueberein? → Kein QA noetig (schneller Pfad)
4. Bei Disagreement: Lokales LLM (Ollama qwen3.5:35b-a3b) arbitriert
5. Auto-Fix: Bei hoher Konfidenz wird Category/Domain automatisch korrigiert

Beispiel

Control: "Offenlegung von Risikokonzentrationen bei Finanzinstrumenten"
LLM sagt:     domain=AUTH, category=authentication
Keyword sagt:  domain=FIN,  category=finance
→ QA via Ollama: domain=FIN, category=finance (Grund: IFRS-Thema)
→ Auto-Fix: AUTH-315 → FIN-xxx

QA-Metriken in generation_metadata

{
  "qa_category_fix": {"from": "authentication", "to": "finance", "reason": "IFRS-Thema"},
  "qa_domain_fix": {"from": "AUTH", "to": "FIN", "reason": "Finanzregulierung"}
}

QA-Reklassifizierung bestehender Controls

Fuer bereits generierte Controls gibt es den Backfill-Endpoint:

# Dry Run: Welche AUTH-Controls sind falsch klassifiziert?
curl -X POST https://macmini:8002/api/compliance/v1/canonical/generate/qa-reclassify \
  -H 'Content-Type: application/json' \
  -d '{"limit": 50, "dry_run": true, "filter_domain_prefix": "AUTH"}'

# Korrekturen anwenden:
curl -X POST https://macmini:8002/api/compliance/v1/canonical/generate/qa-reclassify \
  -H 'Content-Type: application/json' \
  -d '{"limit": 50, "dry_run": false, "filter_domain_prefix": "AUTH"}'

!!! info "Performance" Die QA-Stufe nutzt das lokale Ollama-Modell (kostenlos, ~2s/Control). Sie wird nur bei Disagreement zwischen LLM und Keyword getriggert (~10-15% der Controls), sodass der Overhead minimal bleibt.

Stufe 6: Harmonisierung (Embedding-basiert)

Prueft per bge-m3 Embeddings (Cosine Similarity > 0.85), ob ein aehnliches Control existiert. Embeddings werden in Batches vorgeladen (32 Texte/Request) fuer maximale Performance.

Stufe 7-9: Anchor Search, Store, Mark Processed

• Anchor Search: Findet Open-Source-Referenzen (OWASP, NIST, ENISA)
• Store: Persistiert Control mit verification_method und category
• Mark Processed: Markiert JEDEN Chunk als verarbeitet (auch bei Skip/Error/Duplikat)

Automatische Klassifikation

Bei der Generierung werden automatisch zugewiesen:

Category wird seit 2026-03-16 dreigleisig bestimmt:

1. LLM-Klassifikation (primaer): Anthropic liefert category im JSON-Response
2. Keyword-Detection (fallback): Falls LLM keine Category liefert, greift _detect_category()
3. QA-Arbitrierung (bei Mismatch): Lokales LLM entscheidet bei Widerspruch

Verification Method (Nachweis-Methode):

Methode	Beschreibung
code_review	Im Source Code pruefbar
document	Dokument/Prozess-Nachweis
tool	Tool-basierte Pruefung
hybrid	Kombination mehrerer Methoden

Category (22 thematische Kategorien):

Kategorie	Beschreibung
encryption	Verschluesselung, Kryptographie
authentication	Authentifizierung, Login, MFA
network	Netzwerk, Firewall, VPN
data_protection	Datenschutz, DSGVO
logging	Protokollierung, Monitoring
incident	Vorfallmanagement
continuity	Business Continuity, Backup
compliance	Konformitaet, Audit, Zertifizierung
supply_chain	Lieferkette, Dienstleister
physical	Physische Sicherheit
personnel	Schulung, Mitarbeiter
application	Software, Code Review, API
system	Haertung, Patch, Konfiguration
risk	Risikobewertung, -management
governance	Sicherheitsorganisation, Richtlinien
hardware	Hardware, Firmware, TPM
identity	IAM, SSO, Verzeichnisdienste
public_administration	Behoerden, Verwaltung
labor_law	Arbeitsrecht, Arbeitsschutz
finance	Finanzregulierung, Rechnungslegung
trade_regulation	Gewerbe, Handelsrecht
environmental	Umweltschutz, Nachhaltigkeit
health	Gesundheit, Medizinprodukte

Konfiguration

ENV-Variable	Default	Beschreibung
ANTHROPIC_API_KEY	—	API-Key fuer Anthropic Claude
CONTROL_GEN_ANTHROPIC_MODEL	claude-sonnet-4-6	Anthropic-Modell fuer Formulierung
OLLAMA_URL	http://host.docker.internal:11434	Lokaler Ollama-Server (Vorfilter)
CONTROL_GEN_OLLAMA_MODEL	qwen3.5:35b-a3b	Lokales LLM fuer Vorfilter + QA
CONTROL_GEN_LLM_TIMEOUT	180	Timeout in Sekunden (erhoet fuer Batch-Calls)

Pipeline-Konfiguration (via GeneratorConfig):

Parameter	Default	Beschreibung
batch_size	5	Chunks pro Anthropic-API-Call
max_controls	0	Limit (0 = alle Chunks verarbeiten)
max_chunks	1000	Max Chunks pro Job (respektiert Dokumentgrenzen)
skip_processed	true	Bereits verarbeitete Chunks ueberspringen
dry_run	false	Trockenlauf ohne DB-Schreibzugriffe
skip_web_search	false	Web-Suche fuer Anchor-Finder ueberspringen

Architektur-Entscheidung: Gesetzesverweise

Controls leiten sich aus vier Quellentypen ab (Feld source_citation.source_type):

source_type	Beschreibung	Beispiele	Frontend-Darstellung
law	Bindendes EU/DE/AT-Recht	DSGVO, AI Act, BDSG, NIS2	Blaue Box "Gesetzliche Grundlage" + Badge "Direkte gesetzliche Pflicht"
guideline	Behoerdliche Leitlinien (Soft Law)	EDPB, WP29, Blue Guide	Indigo Box "Behoerdliche Leitlinie" + Badge "Aufsichtsbehoerdliche Empfehlung"
standard	Freiwillige Standards/Frameworks	NIST, OWASP, ENISA, CISA, OECD	Teal Box "Standard / Best Practice" + Badge "Freiwilliger Standard"
restricted	Geschuetzte Normen (Rule 3)	BSI, ISO, ETSI	Amber Box "Abgeleitet aus regulatorischen Anforderungen" (kein Originaltext)

!!! warning "source_type vs license_rule" source_type klassifiziert die rechtliche Verbindlichkeit (Ist es ein Gesetz?). license_rule klassifiziert das Urheberrecht (Darf man den Text zitieren?). Beispiel: NIST ist Rule 1 (Public Domain = freie Nutzung) aber source_type = "standard" (kein EU-Gesetz).

API

# Job starten (laeuft im Hintergrund)
curl -X POST https://macmini:8002/api/compliance/v1/canonical/generate \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000' \
  -d '{"collections": ["bp_compliance_gesetze"]}'

# Job-Status abfragen
curl https://macmini:8002/api/compliance/v1/canonical/generate/jobs \
  -H 'X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000'

RAG Collections

Collection	Inhalte	Erwartete Regel
bp_compliance_gesetze	Deutsche Gesetze (BDSG, TTDSG, TKG etc.)	Rule 1
bp_compliance_datenschutz	Datenschutz-Leitlinien + EU-Verordnungen	Rule 1/2
bp_compliance_ce	CE/Sicherheitsstandards	Rule 1/2/3
bp_dsfa_corpus	DSFA-Korpus	Rule 1/2
bp_legal_templates	Rechtsvorlagen	Rule 1

!!! warning "bp_compliance_recht entfernt (2026-03-16)" Die Collection bp_compliance_recht wurde geloescht, da sie mit bp_compliance_datenschutz ueberlappte (~20.000 Duplikat-Chunks). Alle relevanten EU-Verordnungen sind in den anderen Collections enthalten.

---

Processed Chunks Tracking

Die Tabelle canonical_processed_chunks trackt JEDEN verarbeiteten RAG-Chunk per SHA-256-Hash. Dadurch werden Chunks bei erneutem Pipeline-Lauf automatisch uebersprungen (skip_processed: true).

Tabelle: canonical_processed_chunks (Migration 046 + 048)

Spalte	Typ	Beschreibung
id	UUID	Primary Key
chunk_hash	VARCHAR(64)	SHA-256 Hash des Chunk-Textes
collection	VARCHAR(100)	Qdrant-Collection (z.B. bp_compliance_gesetze)
regulation_code	VARCHAR(100)	Quell-Regulation (z.B. bdsg, eu_2016_679)
document_version	VARCHAR(50)	Versions-Tracking
source_license	VARCHAR(50)	Lizenz der Quelle
license_rule	INTEGER	1, 2 oder 3
processing_path	VARCHAR(20)	Verarbeitungspfad (siehe unten)
generated_control_ids	JSONB	UUIDs der generierten Controls
job_id	UUID	Referenz auf canonical_generation_jobs
processed_at	TIMESTAMPTZ	Zeitstempel

UNIQUE Constraint: (chunk_hash, collection, document_version) — verhindert Doppelverarbeitung.

Processing Paths

Wert	Stufe	Bedeutung
prefilter_skip	2	Lokaler LLM-Vorfilter: Chunk nicht sicherheitsrelevant
structured	4a	Einzelner Chunk strukturiert (Rule 1/2)
llm_reform	4b	Einzelner Chunk reformuliert (Rule 3)
structured_batch	4a	Batch-Strukturierung (Rule 1/2, in generation_metadata)
llm_reform_batch	4b	Batch-Reformulierung (Rule 3, in generation_metadata)
no_control	4	LLM konnte kein Control ableiten
store_failed	7	DB-Speichern fehlgeschlagen
error	—	Unerwarteter Fehler bei der Verarbeitung

!!! note "Batch-Pfade in generation_metadata" Die Werte structured_batch und llm_reform_batch werden im processing_path der Datenbank gespeichert und im generation_metadata JSON-Feld des Controls. So ist nachvollziehbar, ob ein Control einzeln oder im Batch generiert wurde.

Beispiel-Query: Verarbeitungsstatistik

SELECT
    processing_path,
    COUNT(*) as count
FROM canonical_processed_chunks
GROUP BY processing_path
ORDER BY count DESC;

---

Statistiken (processed-stats Endpoint)

Der Endpoint GET /v1/canonical/generate/processed-stats liefert Verarbeitungsstatistiken pro RAG-Collection.

curl -s https://macmini:8002/api/compliance/v1/canonical/generate/processed-stats | jq

Response:

{
  "stats": [
    {
      "collection": "bp_compliance_gesetze",
      "processed_chunks": 45200,
      "direct_adopted": 1850,
      "llm_reformed": 120,
      "skipped": 43230,
      "total_chunks_estimated": 0,
      "pending_chunks": 0
    }
  ]
}

Aktuelle Groessenordnung

Metrik	Wert
RAG-Chunks gesamt	~105.000 (nach Dedup 2026-03-16)
Verarbeitete Chunks	~105.000
Generierte Controls	~4.738
Konversionsrate	~4,5% (nur sicherheitsrelevante Chunks erzeugen Controls)

!!! info "Warum so wenige Controls?" Die meisten RAG-Chunks sind Definitionen, Begriffsbestimmungen, Inhaltsverzeichnisse oder Uebergangsvorschriften. Der Prefilter (Stufe 2) sortiert >50% aus, die Harmonisierung (Stufe 5) entfernt weitere Duplikate. Nur konkrete, einzigartige Anforderungen werden zu Controls.

---

Migration von Controls (Lokal → Production)

Controls koennen ueber die REST-API von der lokalen Entwicklungsumgebung in die Production migriert werden. Jedes Control wird einzeln per POST mit der Referenz auf das Framework erstellt.

# 1. Control aus lokaler Umgebung exportieren
curl -s https://macmini:8002/api/compliance/v1/canonical/controls/AUTH-001 | jq > control.json

# 2. In Production importieren (mit framework_id)
curl -X POST https://api-dev.breakpilot.ai/api/compliance/v1/canonical/controls \
  -H 'Content-Type: application/json' \
  -d '{
    "framework_id": "bp_security_v1",
    "control_id": "AUTH-001",
    "title": "Multi-Faktor-Authentifizierung",
    "objective": "...",
    "severity": "high",
    "open_anchors": [...]
  }'

!!! warning "Framework muss existieren" Das Ziel-Framework (bp_security_v1) muss in der Production-DB bereits angelegt sein. Falls nicht, zuerst das Framework erstellen: bash curl -X POST https://api-dev.breakpilot.ai/api/compliance/v1/canonical/frameworks \ -H 'Content-Type: application/json' \ -d '{"framework_id": "bp_security_v1", "name": "BreakPilot Security", "version": "1.0"}'

---

Dateien

Datei	Typ	Beschreibung
backend-compliance/migrations/044_canonical_control_library.sql	SQL	5 Tabellen + Seed-Daten
backend-compliance/migrations/046_control_generator.sql	SQL	Job-Tracking, Chunk-Tracking, Blocked Sources
backend-compliance/migrations/047_verification_method_category.sql	SQL	verification_method + category Felder
backend-compliance/migrations/048_processing_path_expand.sql	SQL	Erweiterte processing_path Werte
backend-compliance/compliance/api/canonical_control_routes.py	Python	REST API (8+ Endpoints)
backend-compliance/compliance/api/control_generator_routes.py	Python	Generator API (Start/Status/Jobs/Stats)
backend-compliance/compliance/services/control_generator.py	Python	8-Stufen-Pipeline mit Batch Processing
backend-compliance/compliance/services/license_gate.py	Python	Lizenz-Gate-Logik
backend-compliance/compliance/services/similarity_detector.py	Python	Too-Close-Detektor (5 Metriken)
backend-compliance/compliance/services/rag_client.py	Python	RAG-Client (Search + Scroll)
ai-compliance-sdk/internal/ucca/legal_rag.go	Go	RAG Search + Scroll (Qdrant)
ai-compliance-sdk/internal/api/handlers/rag_handlers.go	Go	RAG HTTP-Handler
ai-compliance-sdk/policies/canonical_controls_v1.json	JSON	10 Seed Controls, 39 Open Anchors
ai-compliance-sdk/internal/ucca/canonical_control_loader.go	Go	Control Loader mit Multi-Index
admin-compliance/app/sdk/control-library/page.tsx	TSX	Control Library Browser
admin-compliance/app/sdk/control-provenance/page.tsx	TSX	Provenance Wiki
admin-compliance/app/api/sdk/v1/canonical/route.ts	TS	Next.js API Proxy
scripts/validate-controls.py	Python	CI/CD Validator

---

Tests

Datei	Sprache	Tests	Schwerpunkt
ai-compliance-sdk/internal/ucca/canonical_control_loader_test.go	Go	8 Tests	Control Loader, Multi-Index
backend-compliance/compliance/tests/test_similarity_detector.py	Python	19 Tests	Too-Close-Detektor, 5 Metriken
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	98 Tests	Pipeline, Batch, Lizenzregeln, QA, Recital, Source-Type
Gesamt		166+ Tests

Control Generator Tests (test_control_generator.py)

Die Generator-Tests decken folgende Bereiche ab:

Klasse	Tests	Prueft
TestLicenseMapping	13	Lizenz-Klassifikation (Rule 1/2/3), Case-Insensitivitaet, source_type
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)
TestSourceTypeClassification	16	law/guideline/standard/restricted Klassifizierung aller Quellentypen

---

Multi-Layer Control Architecture

Erweitert die bestehende Pipeline um ein 5-Schichten-Modell:

Legal Source → Obligation → Control Pattern → Master Control → Customer Instance

Architektur-Uebersicht

Layer	Asset	Beschreibung
1: Legal Sources	Qdrant 5 Collections, 105K+ Chunks	RAG-Rohdaten
2: Obligations	v2 Framework (325 Pflichten, 9 Verordnungen)	Rechtliche Pflichten
3: Control Patterns	50 YAML Patterns (30 Core + 20 IT-Security)	Umsetzungsmuster
4: Master Controls	canonical_controls (atomare Controls nach Dedup)	Kanonische Controls
5: Customer Instance	TOM Controls + Gap Mapping	Kundenspezifisch

Control-Ebenen

Ebene	Beschreibung	Nutzen
Rich Controls	Narrativ, erklaerend, kontextreich (~25.000)	Schulung, Audit-Fragen, Massnahmenplaene
Atomare Controls	1 Pflicht = 1 Control (nach Decomposition + Dedup)	Systemaudits, Code-Checks, Gap-Analyse, Traceability

Pipeline-Erweiterung (10-Stage)

Stage 1:  RAG SCAN                (unveraendert)
Stage 2:  LICENSE CLASSIFY        (unveraendert)
Stage 3:  PREFILTER               (unveraendert)
Stage 4:  OBLIGATION EXTRACT      (NEU — 3-Tier: exact → embedding → LLM)
Stage 5:  PATTERN MATCH           (NEU — Keyword + Embedding + Domain-Bonus)
Stage 6:  CONTROL COMPOSE         (NEU — Pattern + Obligation → Control)
Stage 7:  HARMONIZE               (unveraendert)
Stage 8:  ANCHOR SEARCH           (unveraendert)
Stage 9:  STORE + CROSSWALK       (erweitert — Crosswalk-Matrix)
Stage 10: MARK PROCESSED          (unveraendert)

---

Obligation Extractor (Stage 4)

3-Tier Extraktion (schnellste zuerst):

Tier	Methode	Latenz	Trefferquote
1	Exact Match (regulation_code + article → obligation_id)	<1ms	~40%
2	Embedding Match (Cosine > 0.80 gegen 325 Obligations)	~50ms	~30%
3	LLM Extraction (lokales Ollama, nur Fallback)	~2s	~25%

Datei: compliance/services/obligation_extractor.py

Pattern Library (Stage 5)

50 YAML-basierte Control Patterns in 16 Domains:

Datei	Patterns	Domains
core_patterns.yaml	30	AUTH, CRYP, NET, DATA, LOG, ACC, SEC, INC, COMP, GOV, RES
domain_it_security.yaml	20	SEC, NET, AUTH, LOG, CRYP

Pattern ID Format: CP-{DOMAIN}-{NNN} (z.B. CP-AUTH-001)

Matching: 2-Tier (Keyword-Index + Embedding), Domain-Bonus (+0.10)

Dateien:

• ai-compliance-sdk/policies/control_patterns/core_patterns.yaml
• ai-compliance-sdk/policies/control_patterns/domain_it_security.yaml
• compliance/services/pattern_matcher.py

Control Composer (Stage 6)

Drei Kompositions-Modi:

Modus	Wann	Qualitaet
Pattern-guided	Pattern gefunden, LLM antwortet	Hoch
Template-only	LLM-Fehler, aber Pattern vorhanden	Mittel
Fallback	Kein Pattern-Match	Basis

Datei: compliance/services/control_composer.py

---

Decomposition Pass (Pass 0)

Zerlegt Rich Controls in atomare Controls. Laeuft VOR den Migration Passes 1-5.

Pass 0a — Obligation Extraction

Extrahiert einzelne normative Pflichten aus einem Rich Control per LLM.

6 Guardrails:

1. Nur normative Aussagen (müssen, sicherzustellen, verpflichtet, ...)
2. Ein Hauptverb pro Pflicht
3. Testpflichten separat
4. Meldepflichten separat
5. Nicht auf Evidence-Ebene zerlegen
6. Parent-Link immer erhalten

Quality Gate: Jeder Kandidat wird gegen 6 Kriterien geprueft:

• has_normative_signal — Normatives Sprachsignal erkannt
• single_action — Nur eine Handlung
• not_rationale — Keine blosse Begruendung
• not_evidence_only — Kein reines Evidence-Fragment
• min_length — Mindestlaenge erreicht
• has_parent_link — Referenz zum Rich Control

Kritische Checks: has_normative_signal, not_evidence_only, min_length, has_parent_link

Pass 0b — Atomic Control Composition

Erstellt aus jedem validierten Obligation Candidate ein atomares Control (LLM-gestuetzt mit Template-Fallback).

Datei: compliance/services/decomposition_pass.py

---

Migration Passes (1-5)

Nicht-destruktive Passes fuer bestehende Controls:

Pass	Beschreibung	Methode
1	Obligation Linkage	source_citation → article → obligation_id (deterministisch)
2	Pattern Classification	Keyword-Matching gegen Pattern Library
3	Quality Triage	Kategorisierung: review / needs_obligation / needs_pattern / legacy_unlinked
4	Crosswalk Backfill	crosswalk_matrix Zeilen fuer verlinkte Controls
5	Deduplication	Gleiche obligation_id + pattern_id → Duplikat markieren

Datei: compliance/services/pipeline_adapter.py

---

Crosswalk Matrix

Der "goldene Faden" von Gesetz bis Umsetzung:

Regulation → Article → Obligation → Pattern → Master Control → TOM

Ein atomares Control kann von mehreren Gesetzen gleichzeitig gefordert sein. Die Crosswalk-Matrix bildet diese N:M-Beziehung ab.

---

DB-Schema (Migrations 060 + 061)

Migration 060: Multi-Layer Basistabellen

Tabelle	Beschreibung
obligation_extractions	Chunk→Obligation Verknuepfungen (3-Tier Tracking)
control_patterns	DB-Spiegel der YAML-Patterns fuer SQL-Queries
crosswalk_matrix	Goldener Faden: Regulation→Obligation→Pattern→Control
canonical_controls.pattern_id	Pattern-Zuordnung (neues Feld)
canonical_controls.obligation_ids	Obligation-IDs als JSONB-Array (neues Feld)

Migration 061: Decomposition-Tabellen

Tabelle	Beschreibung
obligation_candidates	Extrahierte atomare Pflichten aus Rich Controls
canonical_controls.parent_control_uuid	Self-Referenz zum Rich Control (neues Feld)
canonical_controls.decomposition_method	Zerlegungsmethode (neues Feld)

---

API Endpoints (Crosswalk Routes)

Alle Endpoints unter /api/compliance/v1/canonical/:

Pattern Library

Methode	Pfad	Beschreibung
GET	/patterns	Alle Patterns (Filter: domain, category, tag)
GET	/patterns/{pattern_id}	Einzelnes Pattern mit Details
GET	/patterns/{pattern_id}/controls	Controls aus einem Pattern

Obligation Extraction

Methode	Pfad	Beschreibung
POST	/obligations/extract	Obligation aus Text extrahieren + Pattern matchen

Crosswalk Matrix

Methode	Pfad	Beschreibung
GET	/crosswalk	Query (Filter: regulation, article, obligation, pattern)
GET	/crosswalk/stats	Abdeckungs-Statistiken

Migration + Decomposition

Methode	Pfad	Beschreibung
POST	/migrate/decompose	Pass 0a: Obligation Extraction aus Rich Controls
POST	/migrate/compose-atomic	Pass 0b: Atomare Control-Komposition
POST	/migrate/link-obligations	Pass 1: Obligation-Linkage
POST	/migrate/classify-patterns	Pass 2: Pattern-Klassifikation
POST	/migrate/triage	Pass 3: Quality Triage
POST	/migrate/backfill-crosswalk	Pass 4: Crosswalk-Backfill
POST	/migrate/deduplicate	Pass 5: Deduplizierung
GET	/migrate/status	Migrations-Fortschritt
GET	/migrate/decomposition-status	Decomposition-Fortschritt

Route-Datei: compliance/api/crosswalk_routes.py

---

Multi-Layer Tests

Datei	Tests	Schwerpunkt
tests/test_obligation_extractor.py	107	3-Tier Extraktion, Helpers, Regex
tests/test_pattern_matcher.py	72	Keyword-Index, Embedding, Domain-Affinity
tests/test_control_composer.py	54	Composition, Templates, License-Rules
tests/test_pipeline_adapter.py	36	Pipeline Integration, 5 Migration Passes
tests/test_crosswalk_routes.py	57	15 API Endpoints, Pydantic Models
tests/test_decomposition_pass.py	68	Pass 0a/0b, Quality Gate, 6 Guardrails
tests/test_migration_060.py	12	Schema-Validierung
tests/test_control_patterns.py	18	YAML-Validierung, Pattern-Schema
Gesamt Multi-Layer		424 Tests

Geplanter Migrationsflow

Rich Controls (~25.000, release_state=raw)
  ↓
Pass 0a: Obligation Extraction (LLM + Quality Gate)
  ↓
Pass 0b: Atomic Control Composition (LLM + Template Fallback)
  ↓
Pass 1: Obligation Linking (deterministisch)
  ↓
Pass 2: Pattern Classification (Keyword + Embedding)
  ↓
Pass 3: Quality Triage
  ↓
Pass 4: Crosswalk Backfill
  ↓
Pass 5: Dedup / Merge
  ↓
Master Controls (~15.000-20.000 mit voller Traceability)