"""Use-Case-Register — Single Source of Truth fuer Use Cases × Verifikations- Methoden. Jede Master Control wird auf >=1 Use Case (n:m) und genau eine Verifikations- Methode gemappt. Use Cases sind NICHT nur dokumenten-basiert: >=50% sind Source-Code / IT-Prozess (Code Security, Network Security, CRA, ISMS, TISAX). Neuer Use Case = 1 Eintrag in `_USE_CASES`. Kein DB-Schema-Change noetig. Dieses Modul ist die kanonische Quelle; die heute verstreuten doc_type-Listen (rag_document_checker._DOC_TYPE_MAP, legacy_url_discovery._SLUG_FAMILY, doc_type_classifier, Migration 145) werden spaeter test-gated darauf reduziert. """ from __future__ import annotations import hashlib import json from dataclasses import dataclass # Wie wird eine MC geprueft? — kanonische Verifikations-Methoden-Taxonomie. VERIFICATION_METHODS: tuple[str, ...] = ( "document", # veroeffentlichtes Dokument lesen (Impressum, DSE, ...) "source_code", # Repo/Code scannen (SAST, Secrets, Dependencies, Review) "network", # Netzwerk/Infra scannen (Ports, TLS, Header, Config) "it_process", # Prozess-/Nachweis-Review (Verfahren, Evidence) "hybrid", # Kombination mehrerer Methoden "manual", # menschliche Attestierung ) USE_CASE_GROUPS: tuple[str, ...] = ("document", "security", "cross_cutting") @dataclass(frozen=True) class UseCase: key: str # stabil, snake_case label: str group: str # USE_CASE_GROUPS regulations: tuple[str, ...] = () verification_methods: tuple[str, ...] = () doc_types: tuple[str, ...] = () # operative doc_type-Aliase (Doku-UCs) scope_tokens: tuple[str, ...] = () # canonical_controls.scope_doc_type categories: tuple[str, ...] = () # canonical_controls.category keyword_tokens: tuple[str, ...] = () # canonical_name/title-Stichwoerter enabled: bool = True _USE_CASES: tuple[UseCase, ...] = ( # ── Dokument-Use-Cases ────────────────────────────────────────── UseCase("impressum", "Impressum (§5 TMG/DDG)", "document", regulations=("TMG", "DDG", "MStV"), verification_methods=("document",), doc_types=("impressum",), scope_tokens=("impressum",), categories=("compliance",), keyword_tokens=("impressum", "anbieterkennzeichnung")), UseCase("dse", "Datenschutzerklärung", "document", regulations=("DSGVO",), verification_methods=("document",), doc_types=("dse",), scope_tokens=("dse",), categories=("privacy", "data_protection"), keyword_tokens=("datenschutz", "privacy")), UseCase("agb", "AGB", "document", regulations=("BGB",), verification_methods=("document",), doc_types=("agb",), scope_tokens=("agb",), categories=("compliance",), keyword_tokens=("geschäftsbedingungen", "agb")), UseCase("cookie_banner", "Cookie-Banner & -Richtlinie", "document", regulations=("TDDDG", "ePrivacy", "DSGVO"), verification_methods=("document", "source_code"), doc_types=("cookie",), scope_tokens=("cookie_richtlinie", "banner_implementation", "cmp_audit"), categories=("privacy",), keyword_tokens=("cookie", "consent", "einwilligung")), UseCase("widerruf", "Widerrufsbelehrung", "document", regulations=("BGB",), verification_methods=("document",), doc_types=("widerruf",), scope_tokens=("widerruf",), categories=("compliance",), keyword_tokens=("widerruf", "widerrufsbelehrung")), UseCase("dsr", "Betroffenenrechte (DSR)", "document", regulations=("DSGVO",), verification_methods=("document", "it_process"), scope_tokens=("process",), categories=("privacy", "operations"), keyword_tokens=("betroffenenrecht", "auskunft", "löschung", "dsr")), UseCase("loeschkonzept", "Löschkonzept", "document", regulations=("DSGVO",), verification_methods=("document", "it_process"), doc_types=("loeschkonzept",), scope_tokens=("process", "accounting"), categories=("data_protection",), keyword_tokens=("löschung", "löschfrist", "aufbewahrung")), UseCase("avv", "Auftragsverarbeitung (AVV)", "document", regulations=("DSGVO",), verification_methods=("document",), doc_types=("avv",), scope_tokens=("avv", "jc"), categories=("compliance",), keyword_tokens=("auftragsverarbeitung", "avv")), UseCase("dsfa", "Datenschutz-Folgenabschätzung", "document", regulations=("DSGVO",), verification_methods=("document", "it_process"), doc_types=("dsfa",), scope_tokens=("tom", "process"), categories=("risk", "privacy"), keyword_tokens=("folgenabschätzung", "dsfa")), # ── Security / Code-Use-Cases ─────────────────────────────────── UseCase("code_security", "Code Security", "security", regulations=("CRA", "OWASP", "ISO 27001"), verification_methods=("source_code", "hybrid"), categories=("testing", "application", "encryption", "authentication", "identity"), keyword_tokens=("sast", "secret", "dependency", "vulnerability", "injection", "code")), UseCase("network_security", "Network Security", "security", regulations=("ISO 27001", "BSI", "NIS2"), verification_methods=("network", "hybrid"), categories=("network", "system", "operations"), keyword_tokens=("firewall", "tls", "port", "segmentation", "network", "header")), # ── Querschnitt / Multi-Methode ───────────────────────────────── UseCase("cra", "Cyber Resilience Act", "cross_cutting", regulations=("CRA",), verification_methods=("document", "source_code", "network", "it_process"), categories=("security", "supply_chain", "testing", "incident"), keyword_tokens=("cra", "sbom", "konformität", "produktsicherheit")), UseCase("isms", "ISMS (ISO 27001)", "cross_cutting", regulations=("ISO 27001",), verification_methods=("it_process", "document", "hybrid"), categories=("governance", "security", "operations", "incident"), keyword_tokens=("isms", "risikomanagement", "soa")), UseCase("tisax", "TISAX", "cross_cutting", regulations=("VDA ISA", "TISAX"), verification_methods=("it_process", "document", "network", "hybrid"), categories=("security", "governance", "operations"), keyword_tokens=("tisax", "vda", "prototypenschutz")), ) REGISTRY: dict[str, UseCase] = {uc.key: uc for uc in _USE_CASES} # canonical_controls.evidence_type / .verification_method → unsere Methode # (fuer den deterministischen Seed; der LLM-Pass verfeinert). _EVIDENCE_TO_METHOD: dict[str, str] = { "document": "document", "code": "source_code", "code_review": "source_code", "process": "it_process", "tool": "network", "hybrid": "hybrid", } def _reverse(attr: str) -> dict[str, list[str]]: out: dict[str, list[str]] = {} for uc in _USE_CASES: if not uc.enabled: continue for tok in getattr(uc, attr): out.setdefault(tok, []).append(uc.key) return out scope_token_to_use_cases: dict[str, list[str]] = _reverse("scope_tokens") category_to_use_cases: dict[str, list[str]] = _reverse("categories") doc_type_to_use_cases: dict[str, list[str]] = _reverse("doc_types") def is_valid_use_case(key: str) -> bool: return key in REGISTRY and REGISTRY[key].enabled def is_valid_verification_method(method: str) -> bool: return method in VERIFICATION_METHODS def evidence_to_verification_method(value: str | None) -> str | None: """Heuristik-Mapping fuer den Seed (None wenn unbekannt).""" if not value: return None return _EVIDENCE_TO_METHOD.get(value.strip().lower()) def enabled_use_cases() -> list[UseCase]: return [uc for uc in _USE_CASES if uc.enabled] def seed_classify( scopes=(), categories=(), vmethods=(), etypes=(), ) -> tuple[list[str], str | None]: """Deterministischer Seed (kein LLM): (use_cases, verification_method) aus den aggregierten Member-Signalen einer Master Control — scope_doc_type + category → Use Cases; verification_method/evidence_type → Methode. Pure → testbar.""" ucs: set[str] = set() for s in scopes or (): if s: ucs.update(scope_token_to_use_cases.get(s, ())) for c in categories or (): if c: ucs.update(category_to_use_cases.get(c, ())) method: str | None = None for v in list(vmethods or ()) + list(etypes or ()): m = evidence_to_verification_method(v) if m: method = m break return sorted(ucs), method def taxonomy_for_prompt() -> str: """Kompakter Anker-Block fuer den LLM-Klassifizierer (gecacht).""" lines = ["USE CASES (key — Label — Regulierungen — Methoden):"] for uc in enabled_use_cases(): lines.append( f" {uc.key} — {uc.label} — {', '.join(uc.regulations) or '-'}" f" — {', '.join(uc.verification_methods)}" ) lines.append("VERIFIKATIONS-METHODEN: " + ", ".join(VERIFICATION_METHODS)) return "\n".join(lines) def frontend_list() -> list[dict]: """Schlanke Liste fuers Frontend-Dropdown (Twin: use-case-registry.ts).""" return [ {"key": uc.key, "label": uc.label, "group": uc.group, "verification_methods": list(uc.verification_methods)} for uc in enabled_use_cases() ] def registry_hash() -> str: """Stabiler Hash → Re-Klassifizierung bei Taxonomie-Aenderung.""" payload = json.dumps( [[uc.key, uc.group, list(uc.regulations), list(uc.verification_methods), list(uc.doc_types), list(uc.scope_tokens), list(uc.categories)] for uc in _USE_CASES], sort_keys=True, ensure_ascii=False, ) return hashlib.sha256(payload.encode("utf-8")).hexdigest()