breakpilot-compliance/zeroclaw/INSTRUCTION-usecase-compiler.md

Auftrag: Use-Case Compiler — MCs in interaktive Prüfungen verwandeln

Priorität: HOCH — nächster großer Baustein nach MC Quality Overhaul Repos: breakpilot-compliance (Hauptarbeit) + breakpilot-core (MC-Daten) Voraussetzung: 13.588 Master Controls in DB (lokal + Production), Gap-Engine funktioniert

---

Bestehende Use Cases (WICHTIG — darauf aufbauen!)

Wir haben bereits 3 Use Cases gebaut, jeder mit anderem Ansatz:

1. IACE CE-Compliance (/sdk/iace)

• Ansatz: Deterministisch, kein LLM
• Technologie: Tag-basiertes Pattern Matching (Go), 1.114 Hazard Patterns, 476 Maßnahmen
• Flow: Narrative Text → Parser → Tags → PatternEngine → Hazards → Mitigations → Tech-File
• Pfad: ai-compliance-sdk/internal/iace/
• Learnings: Pattern Matching skaliert und ist reproduzierbar. Kein LLM nötig für strukturierte Domänen.

2. Doc-Check Agent (/sdk/agent)

• Ansatz: LLM-gesteuert (ZeroClaw-artig)
• Technologie: LLM mit Tool Calling, RAG-Suche, binäre Prüffragen
• Flow: Dokument hochladen → LLM prüft gegen Controls → pass/fail pro Frage → Report
• Pfad: backend-compliance/compliance/api/agent_doc_check_routes.py
• Learnings: LLM kann Dokumente intelligent prüfen, braucht aber klare check_questions um präzise zu sein.

3. Gap-Analyse (/sdk/gap-analysis)

• Ansatz: Regelbasiert, kein LLM
• Technologie: Go Classifier + SQL-Queries gegen MCs + Priority Engine
• Flow: Produkt-Profil → Regulatory Classification → MC-Filter → IST-Zustand Assessment → Prioritätsliste
• Pfad: ai-compliance-sdk/internal/gap/
• Learnings: IST-Zustand (Normen, Zertifizierungen, Prozesse) reduziert Gaps massiv. Ohne IST = 500 Gaps, mit IST = 308.

Was der Use-Case Compiler davon übernimmt

Von	Übernehmen
IACE	Deterministisches Pattern Matching für strukturierte Fragen, Completeness Gates als Vorlage
Doc-Check Agent	LLM-basierte Verifikation für unstrukturierte Fragen, Tool Calling Pattern
Gap-Analyse	MC-Filtering nach Regulation + Scope, IST-Zustand Assessment, Priority Engine
Alle drei	Das generische Frontend-Pattern (Wizard → Fragebogen → Result)

Der Compiler ist die GENERALISIERUNG

IACE funktioniert nur für CE/Maschinen. Doc-Check nur für Dokumente. Gap-Analyse zeigt Gaps aber keine konkreten Fragen. Der Use-Case Compiler kombiniert alle drei Ansätze in einem generischen System das JEDEN Use Case bedienen kann:

IACE (deterministisch)     + Doc-Check (LLM)        + Gap-Analyse (regelbasiert)
         ↓                          ↓                         ↓
    Pattern Matching          LLM-Verifikation          MC-Filtering + IST
         ↓                          ↓                         ↓
         └──────────── Use-Case Compiler ──────────────────────┘
                              ↓
              Generischer Fragebogen für JEDEN Use Case

---

Problem

Die 13.588 MCs sind eine Wissensbasis, aber kein Produkt. Wenn ein Nutzer "Vendor Check" machen will, bekommt er 4.036 Controls — aber keine konkreten Fragen, keinen Fragebogen, keine Nachweissammlung.

Ziel

Ein Use-Case Compiler der aus MCs automatisch interaktive Prüfungen generiert:

Use Case (z.B. "Vendor Check Cloud-Anbieter")
  → Relevante MCs filtern
  → Pro MC: 1-3 binäre Prüffragen ableiten
  → Fragebogen generieren (sortiert, gruppiert)
  → Nutzer beantwortet + lädt Nachweise hoch
  → Compliance-Score + Gap-Report
  → Fehlende Rechtsquellen automatisch identifizieren

Was bereits existiert (WIEDERVERWENDEN!)

Master Controls (Core DB)

-- 13.588 MCs mit 83.073 Members
SELECT mc.canonical_name, mc.total_controls, mc.phases_covered
FROM compliance.master_controls mc;

-- Members mit Regulation Source
SELECT cc.control_id, cc.title, cc.objective, mcm.phase, mcm.action,
       pc.source_citation::jsonb->>'source' as regulation
FROM compliance.master_control_members mcm
JOIN compliance.canonical_controls cc ON cc.id = mcm.control_uuid
LEFT JOIN compliance.canonical_controls pc ON pc.id = cc.parent_control_uuid;

doc_check_controls (1.874 Controls mit check_question)

-- Bereits existierende binäre Prüffragen
SELECT doc_type, control_id, check_question, pass_criteria, fail_criteria, severity
FROM compliance.doc_check_controls WHERE doc_type = 'dse';

→ Das ist das TEMPLATE: Für jeden Use Case brauchen wir das Gleiche.

Gap-Engine (Compliance SDK)

• internal/gap/ — Product Profile, Classifier, Priority Engine
• internal/gap/gap_engine.go — assessGapStatus mit IST-Zustand
• internal/gap/norm_mapping.go — 20 Normen → MC-Topic Mapping
• API: POST /sdk/v1/gap/analyze

IACE Pattern Engine

• Tag-basiertes Pattern Matching → domain-agnostisch
• PatternEngine.Match(input) → requirements
• Completeness Gates (25 Prüfpunkte)

ZeroClaw Agent

• backend-compliance/compliance/api/agent_doc_check_routes.py — Doc-Check Agent
• LLM-basierte Verifikation mit Tool Calling
• ai-compliance-sdk/internal/llm/ — Ollama/Claude Adapter

Tenant Document Upload (Core RAG)

• rag-service/api/tenant_documents.py — tenant-isolierter Upload
• Funktioniert auf Mac Mini

---

Architektur

Neue Dateien (Go, im Compliance-Repo)

ai-compliance-sdk/internal/usecase/
├── models.go              — UseCaseTemplate, Question, Evidence, ComplianceResult
├── compiler.go            — MC → Fragen kompilieren
├── question_generator.go  — Aus MC + Controls Prüffragen ableiten
├── scoring.go             — Antworten → Compliance-Score
├── gap_detector.go        — Fehlende Rechtsquellen identifizieren
├── store.go               — DB CRUD (Audits, Antworten, Evidence)
└── templates.go           — Vordefinierte Use-Case Templates

ai-compliance-sdk/internal/api/handlers/
└── usecase_handler.go     — API Endpoints

ai-compliance-sdk/migrations/
└── 026_usecase_audits.sql  — Tabellen für Audits + Antworten

Frontend (Next.js, im Compliance-Repo)

admin-compliance/app/sdk/use-case-audit/
├── page.tsx               — Use Case auswählen oder erstellen
├── [auditId]/
│   └── page.tsx           — Fragebogen ausfüllen + Ergebnis
└── _components/
    ├── UseCaseSelector.tsx — Template-Auswahl oder Custom
    ├── QuestionnaireView.tsx — Dynamischer Fragebogen
    └── AuditResult.tsx    — Score + Gaps + Report

---

Datenmodell

UseCaseTemplate

type UseCaseTemplate struct {
    ID          string   // "vendor_check", "sast_dast_audit", "dsgvo_quick_check"
    Name        string   // "Vendor Check (Cloud-Anbieter)"
    Description string
    MCFilters   []string // ["third_party_management_*", "data_processing_agreement_*"]
    Regulations []string // ["dsgvo", "nis2"] — welche Regulierungen relevant
    Questions   []Question // vorgenerierte Fragen (oder leer → LLM generiert)
}

Question (kompiliert aus MC)

type Question struct {
    ID              string   // "Q1"
    MCID            string   // "MC-19012"
    MCName          string   // "third_party_management_vendor_assessment"
    Question        string   // "Hat der Anbieter ISO 27001?"
    QuestionType    string   // "yes_no", "file_upload", "text", "multi_select"
    EvidenceRequired bool   // true → Nutzer muss Nachweis hochladen
    PassCriteria    []string // ["Gültiges ISO 27001 Zertifikat vorhanden"]
    FailCriteria    []string // ["Kein Zertifikat, nur Selbstauskunft"]
    Severity        string   // "HIGH", "MEDIUM", "LOW"
    Regulation      string   // "DSGVO Art. 28"
    DependsOn       string   // "Q3" → nur anzeigen wenn Q3 = "Ja"
}

Audit (laufende Prüfung)

CREATE TABLE compliance.usecase_audits (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    template_id VARCHAR(100) NOT NULL,
    name VARCHAR(200) NOT NULL,        -- "Vendor Check: AWS"
    target_name VARCHAR(200),          -- "Amazon Web Services"
    status VARCHAR(20) DEFAULT 'draft', -- draft, in_progress, completed
    total_questions INT DEFAULT 0,
    answered_questions INT DEFAULT 0,
    compliance_score FLOAT DEFAULT 0,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    completed_at TIMESTAMPTZ
);

CREATE TABLE compliance.usecase_answers (
    id UUID PRIMARY KEY,
    audit_id UUID REFERENCES usecase_audits(id),
    question_id VARCHAR(50) NOT NULL,
    mc_id VARCHAR(50),
    answer JSONB NOT NULL,             -- {"value": true, "comment": "..."}
    evidence_ids JSONB DEFAULT '[]',   -- UUIDs von hochgeladenen Dateien
    status VARCHAR(20) DEFAULT 'answered', -- answered, skipped, escalated
    answered_at TIMESTAMPTZ DEFAULT NOW()
);

---

Use-Case Templates (Erstausstattung)

1. Vendor Check (Cloud-Anbieter)

id: vendor_check_cloud
mc_filters: ["third_party_management_*", "data_processing_agreement_*", "data_transfer_*"]
regulations: ["dsgvo", "nis2"]
questions:
  - "Hat der Anbieter ISO 27001 oder vergleichbare Zertifizierung?"
  - "Ist ein AVV nach Art. 28 DSGVO geschlossen?"
  - "Werden Daten in Drittländer übermittelt?"
  - "Gibt es SCC oder Angemessenheitsbeschluss?"
  - "Hat der Anbieter ein Schwachstellenmanagement?"
  - "Gibt es einen Incident-Response-Prozess?"
  - "Sind Sub-Auftragsverarbeiter dokumentiert?"
  ...

2. SAST/DAST Security Audit

id: sast_dast_audit
mc_filters: ["secure_development_*", "vulnerability_*", "input_validation_*", "api_security_*"]
regulations: ["cra", "owasp"]

3. DSGVO Quick-Check

id: dsgvo_quick_check
mc_filters: ["personal_data_*", "consent_*", "data_subject_rights_*", "dpia_*", "data_retention_*"]
regulations: ["dsgvo"]

4. NIS2 Readiness

id: nis2_readiness
mc_filters: ["critical_infrastructure_*", "incident_*", "network_security_*", "risk_management_*"]
regulations: ["nis2"]

5. CRA Product Check

id: cra_product_check
mc_filters: ["vulnerability_*", "patch_management_*", "encryption_*", "asset_management_inventory*"]
regulations: ["cra"]

---

Lücken-Erkennung

Automatische Identifikation fehlender Rechtsquellen

func (d *GapDetector) DetectMissingRegulations(templateID string) []MissingSource {
    // 1. Lade alle MCs für diesen Use Case
    // 2. Für jeden MC: zähle Controls mit source_citation
    // 3. Wenn MC >20 Controls aber <3 mit Source → LÜCKE
    // 4. Wenn MC-Topic eine bekannte Regulation hat die nicht 
    //    in source_citation vorkommt → FEHLENDE QUELLE
    //
    // Beispiel:
    //   MC "aml_transaction_monitoring" → 18 Controls
    //   Source Citations: nur "Geldwäschegesetz (GwG)"
    //   FEHLEND: "5. Geldwäscherichtlinie (EU) 2024/1624"
    //   → Ingestion-Auftrag: EUR-Lex CELEX:32024L1624
}

Output: Ingestion-Aufträge

{
  "missing_sources": [
    {
      "regulation": "5. Geldwäscherichtlinie (EU) 2024/1624",
      "affects_mcs": ["aml_transaction_monitoring", "aml_customer_due_diligence"],
      "estimated_controls": 50,
      "source_url": "https://eur-lex.europa.eu/legal-content/DE/TXT/?uri=CELEX:32024L1624",
      "priority": "high"
    }
  ]
}

---

API Endpoints

POST   /sdk/v1/use-case/templates           — Neues Template erstellen
GET    /sdk/v1/use-case/templates           — Verfügbare Templates
GET    /sdk/v1/use-case/templates/:id       — Template Detail + Fragen
POST   /sdk/v1/use-case/compile             — MC → Fragen kompilieren (ad-hoc)
POST   /sdk/v1/use-case/audits              — Neuen Audit starten
GET    /sdk/v1/use-case/audits              — Meine Audits
GET    /sdk/v1/use-case/audits/:id          — Audit Detail + Antworten
POST   /sdk/v1/use-case/audits/:id/answer   — Frage beantworten
GET    /sdk/v1/use-case/audits/:id/score    — Compliance-Score berechnen
GET    /sdk/v1/use-case/audits/:id/report   — Gap-Report generieren
GET    /sdk/v1/use-case/audits/:id/gaps     — Fehlende Rechtsquellen

---

Fragen-Generierung (2 Modi)

Modus A: Deterministisch (kein LLM nötig)

Für MCs die bereits doc_check_controls haben → direkt check_question nutzen. Für MCs mit scanner_hint → in Prüffrage umwandeln (Regex/Template).

Modus B: LLM-basiert (für neue Use Cases)

Wenn kein check_question existiert → Haiku/Qwen generiert aus MC-Title + Objective:

Input:  MC "third_party_management_vendor_assessment", 
        Title: "Cybersicherheitsrichtlinien kritischer Lieferanten prüfen"
Output: {
  "question": "Hat der Lieferant formalisierte Cybersicherheitsrichtlinien?",
  "pass_criteria": ["Dokumentierte Security Policy vorhanden", "Letzte Aktualisierung < 12 Monate"],
  "fail_criteria": ["Keine dokumentierte Policy", "Policy älter als 2 Jahre"]
}

Kosten: ~$0.001/Frage mit Haiku → $0.05 für 50 Fragen pro Template.

---

Implementierungs-Reihenfolge

Phase	Was	Aufwand
1	Datenmodell + Store + Migration	1h
2	Compiler (MC → Fragen) + Templates (5 Stück)	2h
3	API Endpoints (8 Stück)	1.5h
4	Frontend: Template-Auswahl + Fragebogen	2h
5	Scoring Engine + Report	1h
6	Lücken-Erkennung	1h
7	LLM-basierte Fragen-Generierung	1h
Gesamt		~10h (2 Sessions)

---

Verifikation

Test-Szenario: Vendor Check für AWS

1. Template "vendor_check_cloud" auswählen
2. System generiert 25 Fragen aus MCs
3. Nutzer beantwortet alle Fragen + lädt AVV hoch
4. Score: 85% (3 Gaps: SCC fehlt, Sub-Processor-Liste unvollständig, Löschkonzept fehlt)
5. Report als PDF exportieren
6. Lücken-Erkennung: "Für NIS2 Supply Chain fehlen Controls aus ENISA Guidelines"

---

Verbindung zur bestehenden Infrastruktur

Bestehend	Nutzt der Compiler für
Master Controls (13.588)	MC → Fragen Mapping
doc_check_controls (1.874)	Fertige Prüffragen (DSE, Cookie, etc.)
Gap-Engine	IST-Zustand Assessment + Priority
IACE Pattern Engine	CE-spezifische Prüfungen
Applicability Engine	Scope-Filter (Branche, Größe, Signale)
RAG Service	Kontext für LLM-Fragen-Generierung
Tenant Document Upload	Evidence-Speicherung
ZeroClaw Agent	LLM-basierte Verifikation
DSMS/IPFS	Revisionssichere Archivierung

---

DB-Zugang

# Lokal (Mac Mini)
ssh macmini "/usr/local/bin/docker exec bp-core-postgres psql -U breakpilot -d breakpilot_db"

# Production
PROD_DB="postgresql://postgres:GmyFD3wnU1NrKBdpU1nwLdE8MLts0A0eez8L5XXdvUCe05lWnWfVp3C6JJ8Yrmt2@46.225.100.82:54321/postgres?sslmode=require"