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

Initial commit: breakpilot-core - Shared Infrastructure

Browse Source 
Docker Compose with 24+ services:
- PostgreSQL (PostGIS), Valkey, MinIO, Qdrant
- Vault (PKI/TLS), Nginx (Reverse Proxy)
- Backend Core API, Consent Service, Billing Service
- RAG Service, Embedding Service
- Gitea, Woodpecker CI/CD
- Night Scheduler, Health Aggregator
- Jitsi (Web/XMPP/JVB/Jicofo), Mailpit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
2026-02-11 23:47:13 +01:00
commit ad111d5e69
244 changed files with 84288 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

947
docs-src/services/ai-compliance-sdk/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,947 @@
# UCCA - Use-Case Compliance & Feasibility Advisor
## Systemarchitektur
### 1. Übersicht
Das UCCA-System ist ein **deterministisches Compliance-Bewertungssystem** für KI-Anwendungsfälle. Es kombiniert regelbasierte Evaluation mit optionaler LLM-Erklärung und semantischer Rechtstextsuche.
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ UCCA System │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Frontend │───>│ SDK API │───>│ PostgreSQL │ │
│ │ (Next.js) │ │ (Go) │ │ Database │ │
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Policy │ │ Escalation │ │ Legal RAG │ │
│ │ Engine │ │ Workflow │ │ (Qdrant) │ │
│ │ (45 Regeln) │ │ (E0-E3) │ │ 2,274 Chunks │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └────────────────────┴────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ LLM Provider │ │
│ │ (Ollama/API) │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 2. Kernprinzip
> **"LLM ist NICHT die Quelle der Wahrheit. Wahrheit = Regeln + Evidenz. LLM = Übersetzer + Subsumptionshelfer"**
Das System folgt einem strikten **Human-in-the-Loop** Ansatz:
1. **Deterministische Regeln** treffen alle Compliance-Entscheidungen
2. **LLM** erklärt nur Ergebnisse, überschreibt nie BLOCK-Entscheidungen
3. **Menschen** (DSB, Legal) treffen finale Entscheidungen bei kritischen Fällen
---
## 3. Komponenten
### 3.1 Policy Engine (`internal/ucca/rules.go`)
Die Policy Engine evaluiert Use-Cases gegen ~45 deterministische Regeln.
```
┌─────────────────────────────────────────────────────────────────┐
│ Policy Engine │
├─────────────────────────────────────────────────────────────────┤
│ │
│ UseCaseIntake ──────────────────────────────────────────────> │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Regelkategorien (A-J) │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ A. Datenklassifikation │ R-001 bis R-006 │ 6 Regeln │ │
│ │ B. Zweck & Kontext │ R-010 bis R-013 │ 4 Regeln │ │
│ │ C. Automatisierung │ R-020 bis R-025 │ 6 Regeln │ │
│ │ D. Training vs Nutzung │ R-030 bis R-035 │ 6 Regeln │ │
│ │ E. Speicherung │ R-040 bis R-042 │ 3 Regeln │ │
│ │ F. Hosting │ R-050 bis R-052 │ 3 Regeln │ │
│ │ G. Transparenz │ R-060 bis R-062 │ 3 Regeln │ │
│ │ H. Domain-spezifisch │ R-070 bis R-074 │ 5 Regeln │ │
│ │ I. Aggregation │ R-090 bis R-092 │ 3 Regeln │ │
│ │ J. Erklärung │ R-100 │ 1 Regel │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ AssessmentResult │
│ ├── feasibility: YES | CONDITIONAL | NO │
│ ├── risk_score: 0-100 │
│ ├── risk_level: MINIMAL | LOW | MEDIUM | HIGH | CRITICAL │
│ ├── triggered_rules: []TriggeredRule │
│ ├── required_controls: []RequiredControl │
│ ├── recommended_architecture: []PatternRecommendation │
│ └── forbidden_patterns: []ForbiddenPattern │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Regel-Severities:**
- `INFO`: Informativ, kein Risiko-Impact
- `WARN`: Warnung, erhöht Risk Score
- `BLOCK`: Kritisch, führt zu `feasibility=NO`
### 3.2 Escalation Workflow (`internal/ucca/escalation_*.go`)
Das Eskalationssystem routet kritische Assessments zur menschlichen Prüfung.
```
┌─────────────────────────────────────────────────────────────────┐
│ Escalation Workflow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AssessmentResult ─────────────────────────────────────────────> │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Escalation Level Determination │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ E0: Nur INFO-Regeln, Risk < 20 │ │
│ │ → Auto-Approve, keine menschliche Prüfung │ │
│ │ │ │
│ │ E1: WARN-Regeln, Risk 20-39 │ │
│ │ → Team-Lead Review (SLA: 24h) │ │
│ │ │ │
│ │ E2: Art.9 Daten ODER Risk 40-59 ODER DSFA empfohlen │ │
│ │ → DSB Consultation (SLA: 8h) │ │
│ │ │ │
│ │ E3: BLOCK-Regel ODER Risk ≥60 ODER Art.22 Risiko │ │
│ │ → DSB + Legal Review (SLA: 4h) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ DSB Pool Assignment │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ Role │ Level │ Max Concurrent │ Auto-Assign │ │
│ │ ──────────────┼───────┼────────────────┼────────────────── │ │
│ │ team_lead │ E1 │ 10 │ Round-Robin │ │
│ │ dsb │ E2,E3 │ 5 │ Workload-Based │ │
│ │ legal │ E3 │ 3 │ Workload-Based │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Escalation Status Flow: │
│ │
│ pending → assigned → in_review → approved/rejected/returned │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 3.3 Legal RAG (`internal/llm/legal_rag.go`)
Semantische Suche in 19 EU-Regulierungen für kontextbasierte Erklärungen.
```
┌─────────────────────────────────────────────────────────────────┐
│ Legal RAG System │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Explain Request ──────────────────────────────────────────────> │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Qdrant Vector DB │ │
│ │ Collection: bp_legal_corpus │ │
│ │ 2,274 Chunks, 1024-dim BGE-M3 │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ EU-Verordnungen: │ │
│ │ ├── DSGVO (128) ├── AI Act (96) ├── NIS2 (128) │ │
│ │ ├── CRA (256) ├── Data Act (256) ├── DSA (256) │ │
│ │ ├── DGA (32) ├── EUCSA (32) ├── DPF (714) │ │
│ │ └── ... │ │
│ │ │ │
│ │ Deutsche Gesetze: │ │
│ │ ├── TDDDG (1) ├── SCC (32) ├── ... │ │
│ │ │ │
│ │ BSI-Standards: │ │
│ │ ├── TR-03161-1 (6) ├── TR-03161-2 (6) ├── TR-03161-3 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Hybrid Search (Dense + Sparse) │
│ │ Re-Ranking (Cross-Encoder) │
│ ▼ │
│ Top-K Relevant Passages ─────────────────────────────────────> │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ LLM Explanation │ │
│ │ Provider: Ollama (local) / Anthropic (fallback) │ │
│ │ Prompt: Assessment + Legal Context → Erklärung │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 4. Datenfluss
### 4.1 Assessment-Erstellung
```
User Input (Frontend)
│
▼
POST /sdk/v1/ucca/assess
│
├──────────────────────────────────────────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Policy │ │ Escalation │
│ Engine │ │ Trigger │
│ Evaluation │ │ Check │
└──────┬───────┘ └──────┬───────┘
│ │
│ AssessmentResult │ EscalationLevel
│ │
▼ ▼
┌──────────────────────────────────────────────────────┐
│ PostgreSQL │
│ ├── ucca_assessments (Assessment + Result) │
│ └── ucca_escalations (wenn Level > E0) │
└──────────────────────────────────────────────────────┘
│
│ If Level > E0
▼
┌──────────────┐
│ DSB Pool │
│ Auto-Assign │
└──────────────┘
│
▼
Notification (E-Mail/Webhook)
```
### 4.2 Erklärung mit Legal RAG
```
POST /sdk/v1/ucca/assessments/:id/explain
│
▼
┌──────────────┐
│ Load │
│ Assessment │
└──────┬───────┘
│
▼
┌──────────────┐ Query Vector ┌──────────────┐
│ Extract │ ──────────────────>│ Qdrant │
│ Keywords │ │ bp_legal_ │
│ from Rules │<───────────────────│ corpus │
└──────┬───────┘ Top-K Docs └──────────────┘
│
│ Assessment + Legal Context
▼
┌──────────────┐
│ LLM │
│ Provider │
│ Registry │
└──────┬───────┘
│
▼
Explanation (DE) + Legal References
```
---
## 5. Entscheidungsdiagramm
### 5.1 Feasibility-Entscheidung
```
UseCaseIntake
│
▼
┌─────────────────────┐
│ Hat BLOCK-Regeln? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌─────────────────────┐
│ NO │ │ Hat WARN-Regeln? │
│ (blocked) │ └──────────┬──────────┘
└───────────┘ │ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│CONDITIONAL│ │ YES │
│(mit │ │(grünes │
│Auflagen) │ │Licht) │
└───────────┘ └───────────┘
```
### 5.2 Escalation-Level-Entscheidung
```
AssessmentResult
│
▼
┌─────────────────────┐
│ BLOCK-Regel oder │
│ Art.22 Risiko? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ │
┌───────────┐ │
│ E3 │ │
│ DSB+Legal │ │
└───────────┘ ▼
┌─────────────────────┐
│ Risk ≥40 oder │
│ Art.9 Daten oder │
│ DSFA empfohlen? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ │
┌───────────┐ │
│ E2 │ │
│ DSB │ │
└───────────┘ ▼
┌─────────────────────┐
│ Risk ≥20 oder │
│ WARN-Regeln? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ E1 │ │ E0 │
│ Team-Lead │ │ Auto-OK │
└───────────┘ └───────────┘
```
---
## 6. Datenbank-Schema
### 6.1 ucca_assessments
```sql
CREATE TABLE ucca_assessments (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
namespace_id UUID,
title VARCHAR(500),
policy_version VARCHAR(50) NOT NULL,
status VARCHAR(50) DEFAULT 'completed',
-- Input
intake JSONB NOT NULL,
use_case_text_stored BOOLEAN DEFAULT FALSE,
use_case_text_hash VARCHAR(64),
domain VARCHAR(50),
-- Result
feasibility VARCHAR(20) NOT NULL,
risk_level VARCHAR(20) NOT NULL,
risk_score INT NOT NULL DEFAULT 0,
triggered_rules JSONB DEFAULT '[]',
required_controls JSONB DEFAULT '[]',
recommended_architecture JSONB DEFAULT '[]',
forbidden_patterns JSONB DEFAULT '[]',
example_matches JSONB DEFAULT '[]',
-- Flags
dsfa_recommended BOOLEAN DEFAULT FALSE,
art22_risk BOOLEAN DEFAULT FALSE,
training_allowed VARCHAR(50),
-- Explanation
explanation_text TEXT,
explanation_generated_at TIMESTAMPTZ,
explanation_model VARCHAR(100),
-- Audit
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
created_by UUID NOT NULL
);
```
### 6.2 ucca_escalations
```sql
CREATE TABLE ucca_escalations (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
assessment_id UUID NOT NULL REFERENCES ucca_assessments(id),
-- Level & Status
escalation_level VARCHAR(10) NOT NULL,
escalation_reason TEXT,
status VARCHAR(50) NOT NULL DEFAULT 'pending',
-- Assignment
assigned_to UUID,
assigned_role VARCHAR(50),
assigned_at TIMESTAMPTZ,
-- Review
reviewer_id UUID,
reviewer_notes TEXT,
reviewed_at TIMESTAMPTZ,
-- Decision
decision VARCHAR(50),
decision_notes TEXT,
decision_at TIMESTAMPTZ,
conditions JSONB DEFAULT '[]',
-- SLA
due_date TIMESTAMPTZ,
notification_sent BOOLEAN DEFAULT FALSE,
notification_sent_at TIMESTAMPTZ,
-- Audit
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
```
### 6.3 ucca_dsb_pool
```sql
CREATE TABLE ucca_dsb_pool (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
user_id UUID NOT NULL,
user_name VARCHAR(255) NOT NULL,
user_email VARCHAR(255) NOT NULL,
role VARCHAR(50) NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
max_concurrent_reviews INT DEFAULT 10,
current_reviews INT DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
```
---
## 7. API-Endpunkte
### 7.1 Assessment
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
| GET | `/sdk/v1/ucca/assessments` | Assessments auflisten |
| GET | `/sdk/v1/ucca/assessments/:id` | Assessment abrufen |
| DELETE | `/sdk/v1/ucca/assessments/:id` | Assessment löschen |
| POST | `/sdk/v1/ucca/assessments/:id/explain` | LLM-Erklärung generieren |
| GET | `/sdk/v1/ucca/export/:id` | Assessment exportieren |
### 7.2 Kataloge
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/patterns` | Architektur-Patterns |
| GET | `/sdk/v1/ucca/examples` | Didaktische Beispiele |
| GET | `/sdk/v1/ucca/rules` | Alle Regeln |
| GET | `/sdk/v1/ucca/controls` | Required Controls |
| GET | `/sdk/v1/ucca/problem-solutions` | Problem-Lösungen |
### 7.3 Eskalation
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/escalations` | Eskalationen auflisten |
| GET | `/sdk/v1/ucca/escalations/:id` | Eskalation abrufen |
| POST | `/sdk/v1/ucca/escalations` | Manuelle Eskalation |
| POST | `/sdk/v1/ucca/escalations/:id/assign` | Zuweisen |
| POST | `/sdk/v1/ucca/escalations/:id/review` | Review starten |
| POST | `/sdk/v1/ucca/escalations/:id/decide` | Entscheidung treffen |
| GET | `/sdk/v1/ucca/escalations/stats` | Statistiken |
### 7.4 DSB Pool
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/dsb-pool` | Pool-Mitglieder auflisten |
| POST | `/sdk/v1/ucca/dsb-pool` | Mitglied hinzufügen |
---
## 8. Sicherheit
### 8.1 Authentifizierung
- JWT-basierte Authentifizierung
- Header: `X-User-ID`, `X-Tenant-ID`
- Multi-Tenant-Isolation
### 8.2 Autorisierung
- RBAC (Role-Based Access Control)
- Permissions: `ucca:assess`, `ucca:review`, `ucca:admin`
- Namespace-Level Isolation
### 8.3 Datenschutz
- Use-Case-Text optional (Opt-in)
- SHA-256 Hash statt Klartext
- Audit-Trail für alle Operationen
- Legal RAG: `training_allowed: false`
---
## 9. Deployment
### 9.1 Container
```yaml
ai-compliance-sdk:
build: ./ai-compliance-sdk
ports:
- "8090:8090"
environment:
- DATABASE_URL=postgres://...
- OLLAMA_URL=http://ollama:11434
- QDRANT_URL=http://qdrant:6333
depends_on:
- postgres
- qdrant
```
### 9.2 Abhängigkeiten
- PostgreSQL 15+
- Qdrant 1.12+
- Embedding Service (BGE-M3)
- Ollama (optional, für LLM)
---
## 10. Monitoring
### 10.1 Health Check
```
GET /sdk/v1/health
→ {"status": "ok"}
```
### 10.2 Metriken
- Assessment-Durchsatz
- Escalation-SLA-Compliance
- LLM-Latenz
- RAG-Trefferqualität
---
## 11. Wizard & Legal Assistant
### 11.1 Wizard-Architektur
Der UCCA-Wizard führt Benutzer durch 9 Schritte zur Erfassung aller relevanten Compliance-Fakten.
```
┌─────────────────────────────────────────────────────────────────┐
│ UCCA Wizard v1.1 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: Grundlegende Informationen │
│ Step 2: Datenarten (Personal Data, Art. 9, etc.) │
│ Step 3: Verarbeitungszweck (Profiling, Scoring) │
│ Step 4: Hosting & Provider │
│ Step 5: Internationaler Datentransfer (SCC, TIA) │
│ Step 6: KI-Modell und Training │
│ Step 7: Verträge & Compliance (AVV, DSFA) │
│ Step 8: Automatisierung & Human Oversight │
│ Step 9: Standards & Normen (für Maschinenbauer) ← NEU │
│ │
│ Features: │
│ ├── Adaptive Subflows (visible_if Conditions) │
│ ├── Simple/Expert Mode Toggle │
│ ├── Legal Assistant Chat pro Step │
│ └── simple_explanation für Nicht-Juristen │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 11.2 Legal Assistant (Wizard Chat)
Integrierter Rechtsassistent für Echtzeit-Hilfe bei Wizard-Fragen.
```
┌─────────────────────────────────────────────────────────────────┐
│ Legal Assistant Flow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ User Question ─────────────────────────────────────────────────>│
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Build RAG Query │ │
│ │ + Step Context │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ Search ┌──────────────────┐ │
│ │ Legal RAG │ ────────────>│ Qdrant │ │
│ │ Client │ │ bp_legal_corpus │ │
│ │ │<────────────│ + SCC Corpus │ │
│ └────────┬─────────┘ Top-5 └──────────────────┘ │
│ │ │
│ │ Question + Legal Context │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Internal 32B LLM │ │
│ │ (Ollama) │ │
│ │ temp=0.3 │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ Answer + Sources + Related Fields │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**API-Endpunkte:**
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/wizard/schema` | Wizard-Schema abrufen |
| POST | `/sdk/v1/ucca/wizard/ask` | Frage an Legal Assistant |
---
## 12. License Policy Engine (Standards Compliance)
### 12.1 Übersicht
Die License Policy Engine verwaltet die Lizenz-/Urheberrechts-Compliance für Standards und Normen (DIN, ISO, VDI, etc.).
```
┌─────────────────────────────────────────────────────────────────┐
│ License Policy Engine │
├─────────────────────────────────────────────────────────────────┤
│ │
│ LicensedContentFacts ─────────────────────────────────────────>│
│ │ │
│ │ ├── present: bool │
│ │ ├── publisher: DIN_MEDIA | VDI | ISO | ... │
│ │ ├── license_type: SINGLE | NETWORK | ENTERPRISE | AI │
│ │ ├── ai_use_permitted: YES | NO | UNKNOWN │
│ │ ├── operation_mode: LINK | NOTES | FULLTEXT | TRAINING │
│ │ └── proof_uploaded: bool │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Operation Mode Evaluation ││
│ ├─────────────────────────────────────────────────────────────┤│
│ │ ││
│ │ LINK_ONLY ──────────── Always Allowed ───────────> OK ││
│ │ NOTES_ONLY ─────────── Usually Allowed ──────────> OK ││
│ │ FULLTEXT_RAG ────┬──── ai_use=YES + proof ───────> OK ││
│ │ └──── else ─────────────────────> BLOCK ││
│ │ TRAINING ────────┬──── AI_LICENSE + proof ───────> OK ││
│ │ └──── else ─────────────────────> BLOCK ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ LicensePolicyResult │
│ ├── allowed: bool │
│ ├── effective_mode: string (may be downgraded) │
│ ├── gaps: []LicenseGap │
│ ├── required_controls: []LicenseControl │
│ ├── stop_line: *StopLine (if hard blocked) │
│ └── output_restrictions: *OutputRestrictions │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 12.2 Betriebs-Modi (Operation Modes)
| Modus | Beschreibung | Lizenz-Anforderung | Ingest | Output |
|-------|--------------|-------------------|--------|--------|
| **LINK_ONLY** | Nur Verweise & Checklisten | Keine | Metadata only | Keine Zitate |
| **NOTES_ONLY** | Kundeneigene Zusammenfassungen | Standard | Notes only | Paraphrasen |
| **EXCERPT_ONLY** | Kurze Zitate (Zitatrecht) | Standard + Zitatrecht | Notes | Max 150 Zeichen |
| **FULLTEXT_RAG** | Volltext indexiert | AI-Lizenz + Proof | Fulltext | Max 500 Zeichen |
| **TRAINING** | Modell-Training | AI-Training-Lizenz | Fulltext | N/A |
### 12.3 Publisher-spezifische Regeln
**DIN Media (ehem. Beuth):**
- AI-Nutzung aktuell verboten (ohne explizite Genehmigung)
- AI-Lizenzmodell geplant ab Q4/2025
- Crawler/Scraper verboten (AGB)
- TDM-Vorbehalt nach §44b UrhG
### 12.4 Stop-Lines (Hard Deny)
```
STOP_DIN_FULLTEXT_AI_NOT_ALLOWED
WENN: publisher=DIN_MEDIA AND operation_mode in [FULLTEXT_RAG, TRAINING]
AND ai_use_permitted in [NO, UNKNOWN]
DANN: BLOCKIERT
FALLBACK: LINK_ONLY
STOP_TRAINING_WITHOUT_PROOF
WENN: operation_mode=TRAINING AND proof_uploaded=false
DANN: BLOCKIERT
```
---
## 13. SCC & Transfer Impact Assessment
### 13.1 Drittlandtransfer-Bewertung
Das System unterstützt die vollständige Bewertung internationaler Datentransfers.
```
┌─────────────────────────────────────────────────────────────────┐
│ SCC/Transfer Assessment Flow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ hosting.region ─────────────────────────────────────────────── │
│ │ │
│ ├── EU/EWR ────────────────────────────────> OK (no SCC) │
│ │ │
│ ├── Adequacy Country (UK, CH, JP) ─────────> OK (no SCC) │
│ │ │
│ └── Third Country (US, etc.) ──────────────────────────── │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ USA: DPF-Zertifizierung prüfen ││
│ │ ├── Zertifiziert ───> OK (SCC empfohlen als Backup) ││
│ │ └── Nicht zertifiziert ───> SCC + TIA erforderlich ││
│ └─────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Transfer Impact Assessment (TIA) ││
│ │ ├── Adequate ─────────────> Transfer OK ││
│ │ ├── Adequate + Measures ──> + Technical Supplementary ││
│ │ ├── Inadequate ───────────> Fix required ││
│ │ └── Not Feasible ─────────> Transfer NOT allowed ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 13.2 SCC-Versionen
- Neue SCC (EU 2021/914) - **erforderlich** seit 27.12.2022
- Alte SCC (vor 2021) - **nicht mehr gültig**
---
## 14. Controls Catalog
### 14.1 Übersicht
Der Controls Catalog enthält ~30 Maßnahmenbausteine mit detaillierten Handlungsanweisungen.
```
┌─────────────────────────────────────────────────────────────────┐
│ Controls Catalog v1.0 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Kategorien: │
│ ├── DSGVO (Rechtsgrundlagen, Betroffenenrechte, Dokumentation) │
│ ├── AI_Act (Transparenz, HITL, Risikoeinstufung) │
│ ├── Technical (Verschlüsselung, Anonymisierung, PII-Gateway) │
│ └── Contractual (AVV, SCC, TIA) │
│ │
│ Struktur pro Control: │
│ ├── id: CTRL-xxx │
│ ├── title: Kurztitel │
│ ├── when_applicable: Wann erforderlich? │
│ ├── what_to_do: Konkrete Handlungsschritte │
│ ├── evidence_needed: Erforderliche Nachweise │
│ ├── effort: low | medium | high │
│ └── gdpr_ref: Rechtsgrundlage │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 14.2 Beispiel-Controls
| ID | Titel | Kategorie |
|----|-------|-----------|
| CTRL-CONSENT-EXPLICIT | Ausdrückliche Einwilligung | DSGVO |
| CTRL-AI-TRANSPARENCY | KI-Transparenz-Hinweis | AI_Act |
| CTRL-DSFA | Datenschutz-Folgenabschätzung | DSGVO |
| CTRL-SCC | Standardvertragsklauseln | Contractual |
| CTRL-TIA | Transfer Impact Assessment | Contractual |
| CTRL-LICENSE-PROOF | Lizenz-/Rechte-Nachweis | License |
| CTRL-LINK-ONLY-MODE | Evidence Navigator | License |
| CTRL-PII-GATEWAY | PII-Redaction Gateway | Technical |
---
## 15. Policy-Dateien
### 15.1 Dateistruktur
```
policies/
├── ucca_policy_v1.yaml # Haupt-Policy (Regeln, Controls)
├── controls_catalog.yaml # Detaillierter Maßnahmenkatalog
├── gap_mapping.yaml # Facts → Gaps → Controls
├── wizard_schema_v1.yaml # Wizard-Fragen (9 Steps)
├── scc_legal_corpus.yaml # SCC/Transfer Rechtstexte
└── licensed_content_policy.yaml # Normen-Lizenz-Compliance (NEU)
```
### 15.2 Versions-Management
- Jedes Assessment speichert die `policy_version`
- Regeländerungen erzeugen neue Version
- Audit-Trail zeigt welche Policy-Version verwendet wurde
---
## 16. Generic Obligations Framework
### 16.1 Übersicht
Das Generic Obligations Framework ermöglicht die automatische Ableitung regulatorischer Pflichten aus mehreren Verordnungen basierend auf Unternehmensfakten.
```
┌─────────────────────────────────────────────────────────────────┐
│ Generic Obligations Framework │
├─────────────────────────────────────────────────────────────────┤
│ │
│ UnifiedFacts ───────────────────────────────────────────────── │
│ │ │
│ │ ├── organization: EmployeeCount, Revenue, Country │
│ │ ├── sector: PrimarySector, IsKRITIS, SpecialServices │
│ │ ├── data_protection: ProcessesPersonalData │
│ │ └── ai_usage: UsesAI, HighRiskCategories, IsGPAI │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Obligations Registry ││
│ │ (Module Registration & Evaluation) ││
│ └──────────────────────────┬──────────────────────────────────┘│
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ NIS2 │ │ DSGVO │ │ AI Act │ │
│ │ Module │ │ Module │ │ Module │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │ │
│ └───────────────────┴───────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ManagementObligationsOverview ││
│ │ ├── ApplicableRegulations[] ││
│ │ ├── Obligations[] (sortiert nach Priorität) ││
│ │ ├── RequiredControls[] ││
│ │ ├── IncidentDeadlines[] ││
│ │ ├── SanctionsSummary ││
│ │ └── ExecutiveSummary ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 16.2 Regulation Modules
Jede Regulierung wird als eigenständiges Modul implementiert:
**Implementierte Module:**
| Modul | ID | Datei | Pflichten | Kontrollen |
|-------|-----|-------|-----------|------------|
| NIS2 | `nis2` | `nis2_module.go` | ~15 | ~8 |
| DSGVO | `dsgvo` | `dsgvo_module.go` | ~12 | ~6 |
| AI Act | `ai_act` | `ai_act_module.go` | ~15 | ~6 |
---
## 17. Obligations API-Endpunkte
### 17.1 Assessment
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/obligations/assess` | Pflichten-Assessment erstellen |
| GET | `/sdk/v1/ucca/obligations/:id` | Assessment abrufen |
| GET | `/sdk/v1/ucca/obligations` | Assessments auflisten |
### 17.2 Export
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/obligations/export/memo` | Memo exportieren (gespeichert) |
| POST | `/sdk/v1/ucca/obligations/export/direct` | Direkt-Export ohne Speicherung |
### 17.3 Regulations
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/regulations` | Liste aller Regulierungsmodule |
| GET | `/sdk/v1/ucca/regulations/:id/decision-tree` | Decision Tree für Regulierung |
---
## 18. Dateien des Obligations Framework
### 18.1 Backend (Go)
```
internal/ucca/
├── obligations_framework.go # Interfaces, Typen, Konstanten
├── obligations_registry.go # Modul-Registry, EvaluateAll()
├── nis2_module.go # NIS2 Decision Tree + Pflichten
├── nis2_module_test.go # NIS2 Tests
├── dsgvo_module.go # DSGVO Pflichten
├── dsgvo_module_test.go # DSGVO Tests
├── ai_act_module.go # AI Act Risk Classification
├── ai_act_module_test.go # AI Act Tests
├── pdf_export.go # PDF/Markdown Export
└── pdf_export_test.go # Export Tests
```
### 18.2 Policy-Dateien (YAML)
```
policies/obligations/
├── nis2_obligations.yaml # ~15 NIS2-Pflichten
├── dsgvo_obligations.yaml # ~12 DSGVO-Pflichten
└── ai_act_obligations.yaml # ~15 AI Act-Pflichten
```
---
*Dokumentation erstellt: 2026-01-29*
*Version: 2.1.0*

387
docs-src/services/ai-compliance-sdk/AUDITOR_DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,387 @@
# UCCA - Dokumentation für externe Auditoren
## Systemdokumentation nach Art. 30 DSGVO
**Verantwortlicher:** [Name des Unternehmens]
**Datenschutzbeauftragter:** [Kontakt]
**Dokumentationsstand:** 2026-01-29
**Version:** 1.0.0
---
## 1. Zweck und Funktionsweise des Systems
### 1.1 Systembezeichnung
**UCCA - Use-Case Compliance & Feasibility Advisor**
### 1.2 Zweckbeschreibung
Das UCCA-System ist ein **Compliance-Prüfwerkzeug**, das Organisationen bei der Bewertung geplanter KI-Anwendungsfälle hinsichtlich ihrer datenschutzrechtlichen Zulässigkeit unterstützt.
**Kernfunktionen:**
- Automatisierte Vorprüfung von KI-Anwendungsfällen gegen EU-Regulierungen
- Identifikation erforderlicher technischer und organisatorischer Maßnahmen
- Eskalation kritischer Fälle zur menschlichen Prüfung
- Dokumentation und Nachvollziehbarkeit aller Prüfentscheidungen
### 1.3 Rechtsgrundlage
Die Verarbeitung erfolgt auf Basis von:
- **Art. 6 Abs. 1 lit. c DSGVO** - Erfüllung rechtlicher Verpflichtungen
- **Art. 6 Abs. 1 lit. f DSGVO** - Berechtigte Interessen (Compliance-Management)
---
## 2. Verarbeitete Datenkategorien
### 2.1 Eingabedaten (Use-Case-Beschreibungen)
| Datenkategorie | Beschreibung | Speicherung |
|----------------|--------------|-------------|
| Use-Case-Text | Freitextbeschreibung des geplanten Anwendungsfalls | Optional (Opt-in), ansonsten nur Hash |
| Domain | Branchenkategorie (z.B. "education", "healthcare") | Ja |
| Datentyp-Flags | Angaben zu verarbeiteten Datenarten | Ja |
| Automatisierungsgrad | assistiv/teil-/vollautomatisch | Ja |
| Hosting-Informationen | Region, Provider | Ja |
**Wichtig:** Der System speichert standardmäßig **keine Freitexte**, sondern nur:
- SHA-256 Hash des Textes (zur Deduplizierung)
- Strukturierte Metadaten (Checkboxen, Dropdowns)
### 2.2 Bewertungsergebnisse
| Datenkategorie | Beschreibung | Aufbewahrung |
|----------------|--------------|--------------|
| Risk Score | Numerischer Wert 0-100 | Dauerhaft |
| Triggered Rules | Ausgelöste Compliance-Regeln | Dauerhaft |
| Required Controls | Empfohlene Maßnahmen | Dauerhaft |
| Explanation | KI-generierte Erklärung | Dauerhaft |
### 2.3 Audit-Trail-Daten
| Datenkategorie | Beschreibung | Aufbewahrung |
|----------------|--------------|--------------|
| Benutzer-ID | UUID des ausführenden Benutzers | 10 Jahre |
| Timestamp | Zeitpunkt der Aktion | 10 Jahre |
| Aktionstyp | created/reviewed/decided | 10 Jahre |
| Entscheidungsnotizen | Begründungen bei Eskalationen | 10 Jahre |
---
## 3. Entscheidungslogik und Automatisierung
### 3.1 Regelbasierte Bewertung (Deterministische Logik)
Das System verwendet **ausschließlich deterministische Regeln** für Compliance-Entscheidungen. Diese Regeln sind:
1. **Transparent** - Alle Regeln sind im Quellcode einsehbar
2. **Nachvollziehbar** - Jede ausgelöste Regel wird dokumentiert
3. **Überprüfbar** - Regellogik basiert auf konkreten DSGVO-Artikeln
**Beispiel-Regel R-F001:**
```
WENN:
- Domain = "education" UND
- Automation = "fully_automated" UND
- Output enthält "rankings_or_scores"
DANN:
- Severity = BLOCK
- DSGVO-Referenz = Art. 22 Abs. 1
- Begründung = "Vollautomatisierte Bewertung von Schülern ohne menschliche Überprüfung"
```
### 3.2 Keine autonomen KI-Entscheidungen
**Das System trifft KEINE autonomen KI-Entscheidungen bezüglich:**
- Zulässigkeit eines Anwendungsfalls (immer regelbasiert)
- Freigabe oder Ablehnung (immer durch Mensch)
- Rechtliche Bewertungen (immer durch DSB/Legal)
**KI wird ausschließlich verwendet für:**
- Erklärung bereits getroffener Regelentscheidungen
- Zusammenfassung von Rechtstexten
- Sprachliche Formulierung von Hinweisen
### 3.3 Human-in-the-Loop
Bei allen kritischen Entscheidungen ist ein **menschlicher Prüfer** eingebunden:
| Eskalationsstufe | Auslöser | Prüfer | SLA |
|------------------|----------|--------|-----|
| E0 | Nur informative Regeln | Automatisch | - |
| E1 | Warnungen, geringes Risiko | Team-Lead | 24h |
| E2 | Art. 9-Daten, DSFA empfohlen | DSB | 8h |
| E3 | BLOCK-Regeln, hohes Risiko | DSB + Legal | 4h |
**BLOCK-Entscheidungen können NICHT durch KI überschrieben werden.**
---
## 4. Technische und organisatorische Maßnahmen (Art. 32 DSGVO)
### 4.1 Vertraulichkeit
| Maßnahme | Umsetzung |
|----------|-----------|
| Zugriffskontrolle | RBAC mit Tenant-Isolation |
| Verschlüsselung in Transit | TLS 1.3 |
| Verschlüsselung at Rest | AES-256 (PostgreSQL, Qdrant) |
| Authentifizierung | JWT-basiert, Token-Expiry |
### 4.2 Integrität
| Maßnahme | Umsetzung |
|----------|-----------|
| Audit-Trail | Unveränderlicher Verlauf aller Aktionen |
| Versionierung | Policy-Version in jedem Assessment |
| Input-Validierung | Schema-Validierung aller API-Eingaben |
### 4.3 Verfügbarkeit
| Maßnahme | Umsetzung |
|----------|-----------|
| Backup | Tägliche PostgreSQL-Backups |
| Redundanz | Container-Orchestrierung mit Auto-Restart |
| Monitoring | Health-Checks, SLA-Überwachung |
### 4.4 Belastbarkeit
| Maßnahme | Umsetzung |
|----------|-----------|
| Rate Limiting | API-Anfragenbegrenzung |
| Graceful Degradation | LLM-Fallback bei Ausfall |
| Ressourcenlimits | Container-Memory-Limits |
---
## 5. Datenschutz-Folgenabschätzung (Art. 35 DSGVO)
### 5.1 Risikobewertung
| Risiko | Bewertung | Mitigierung |
|--------|-----------|-------------|
| Fehleinschätzung durch KI | Mittel | Deterministische Regeln, Human Review |
| Datenverlust | Niedrig | Backup, Verschlüsselung |
| Unbefugter Zugriff | Niedrig | RBAC, Audit-Trail |
| Bias in Regellogik | Niedrig | Transparente Regeln, Review-Prozess |
### 5.2 DSFA-Trigger im System
Das System erkennt automatisch, wann eine DSFA erforderlich ist:
- Verarbeitung besonderer Kategorien (Art. 9 DSGVO)
- Systematische Bewertung natürlicher Personen
- Neue Technologien mit hohem Risiko
---
## 6. Betroffenenrechte (Art. 15-22 DSGVO)
### 6.1 Auskunftsrecht (Art. 15)
Betroffene können Auskunft erhalten über:
- Gespeicherte Assessments mit ihren Daten
- Audit-Trail ihrer Interaktionen
- Regelbasierte Entscheidungsbegründungen
### 6.2 Recht auf Berichtigung (Art. 16)
Betroffene können die Korrektur fehlerhafter Eingabedaten verlangen.
### 6.3 Recht auf Löschung (Art. 17)
Assessments können gelöscht werden, sofern:
- Keine gesetzlichen Aufbewahrungspflichten bestehen
- Keine laufenden Eskalationsverfahren existieren
### 6.4 Recht auf Einschränkung (Art. 18)
Die Verarbeitung kann eingeschränkt werden durch:
- Archivierung statt Löschung
- Sperrung des Datensatzes
### 6.5 Automatisierte Entscheidungen (Art. 22)
**Das System trifft keine automatisierten Einzelentscheidungen** im Sinne von Art. 22 DSGVO, da:
1. Regelauswertung ist **keine rechtlich bindende Entscheidung**
2. Alle kritischen Fälle werden **menschlich geprüft** (E1-E3)
3. BLOCK-Entscheidungen erfordern **immer menschliche Freigabe**
4. Betroffene haben **Anfechtungsmöglichkeit** über Eskalation
---
## 7. Auftragsverarbeitung
### 7.1 Unterauftragnehmer
| Dienst | Anbieter | Standort | Zweck |
|--------|----------|----------|-------|
| Embedding-Service | Lokal (Self-Hosted) | EU | Vektorisierung |
| Vector-DB (Qdrant) | Lokal (Self-Hosted) | EU | Ähnlichkeitssuche |
| LLM (Ollama) | Lokal (Self-Hosted) | EU | Erklärungsgenerierung |
**Hinweis:** Das System kann vollständig on-premise betrieben werden ohne externe Dienste.
### 7.2 Internationale Transfers
Bei Nutzung von Cloud-LLM-Anbietern:
- Anthropic Claude: US (DPF-zertifiziert)
- OpenAI: US (DPF-zertifiziert)
**Empfehlung:** Nutzung des lokalen Ollama-Providers für sensible Daten.
---
## 8. Audit-Trail und Nachvollziehbarkeit
### 8.1 Protokollierte Ereignisse
| Ereignis | Protokollierte Daten |
|----------|---------------------|
| Assessment erstellt | Benutzer, Timestamp, Intake-Hash, Ergebnis |
| Eskalation erstellt | Level, Grund, SLA |
| Zuweisung | Benutzer, Rolle |
| Review gestartet | Benutzer, Timestamp |
| Entscheidung | Benutzer, Entscheidung, Begründung |
### 8.2 Aufbewahrungsfristen
| Datenart | Aufbewahrung | Rechtsgrundlage |
|----------|--------------|-----------------|
| Assessments | 10 Jahre | § 147 AO |
| Audit-Trail | 10 Jahre | § 147 AO |
| Eskalationen | 10 Jahre | § 147 AO |
| Löschprotokolle | 3 Jahre | Art. 17 DSGVO |
---
## 9. Lizenzierte Inhalte & Normen-Compliance (§44b UrhG)
### 9.1 Zweck
Das System enthält einen spezialisierten **License Policy Engine** zur Compliance-Prüfung bei der Verarbeitung urheberrechtlich geschützter Inhalte, insbesondere:
- **DIN-Normen** (DIN Media / Beuth Verlag)
- **VDI-Richtlinien**
- **ISO/IEC-Standards**
- **VDE-Normen**
### 9.2 Rechtlicher Hintergrund
**§44b UrhG - Text und Data Mining:**
> "Die Vervielfältigung von rechtmäßig zugänglichen Werken für das Text und Data Mining ist zulässig."
**ABER:** Rechteinhaber können TDM gem. §44b Abs. 3 UrhG vorbehalten:
- **DIN Media:** Expliziter Vorbehalt in AGB – keine KI/TDM-Nutzung ohne Sonderlizenz
- **Geplante KI-Lizenzmodelle:** Ab Q4/2025 (DIN Media)
### 9.3 Operationsmodi im System
| Modus | Beschreibung | Lizenzanforderung |
|-------|--------------|-------------------|
| `LINK_ONLY` | Nur Verlinkung zum Original | Keine |
| `NOTES_ONLY` | Eigene Notizen/Zusammenfassungen | Keine (§51 UrhG) |
| `EXCERPT_ONLY` | Kurze Zitate (<100 Wörter) | Standard-Lizenz |
| `FULLTEXT_RAG` | Volltextsuche mit Embedding | Explizite KI-Lizenz |
| `TRAINING` | Modell-Training | Enterprise-Lizenz + Vertrag |
### 9.4 Stop-Lines (Automatische Sperren)
Das System **blockiert automatisch** folgende Kombinationen:
| Stop-Line ID | Bedingung | Aktion |
|--------------|-----------|--------|
| `STOP_DIN_FULLTEXT_AI_NOT_ALLOWED` | DIN Media + FULLTEXT_RAG + keine KI-Lizenz | Ablehnung |
| `STOP_LICENSE_UNKNOWN_FULLTEXT` | Lizenz unbekannt + FULLTEXT_RAG | Warnung + Eskalation |
| `STOP_TRAINING_WITHOUT_ENTERPRISE` | Beliebig + TRAINING + keine Enterprise-Lizenz | Ablehnung |
### 9.5 License Policy Engine - Entscheidungslogik
```
INPUT:
├── licensed_content.present = true
├── licensed_content.publisher = "DIN_MEDIA"
├── licensed_content.license_type = "SINGLE_WORKSTATION"
├── licensed_content.ai_use_permitted = "NO"
└── licensed_content.operation_mode = "FULLTEXT_RAG"
REGEL-EVALUATION:
├── Prüfe Publisher-spezifische Regeln
├── Prüfe Lizenztyp vs. gewünschter Modus
├── Prüfe AI-Use-Flag
└── Bestimme maximal zulässigen Modus
OUTPUT:
├── allowed: false
├── max_allowed_mode: "NOTES_ONLY"
├── required_controls: ["CTRL-LICENSE-PROOF", "CTRL-NO-CRAWLING-DIN"]
├── gaps: ["GAP_DIN_MEDIA_WITHOUT_AI_LICENSE"]
├── stop_lines: ["STOP_DIN_FULLTEXT_AI_NOT_ALLOWED"]
└── explanation: "DIN Media verbietet KI-Nutzung ohne explizite Lizenz..."
```
### 9.6 Erforderliche Controls bei lizenzierten Inhalten
| Control ID | Beschreibung | Evidence |
|------------|--------------|----------|
| `CTRL-LICENSE-PROOF` | Lizenznachweis dokumentieren | Lizenzvertrag, Rechnung |
| `CTRL-LICENSE-GATED-INGEST` | Technische Sperre vor Ingest | Konfiguration, Logs |
| `CTRL-NO-CRAWLING-DIN` | Kein automatisches Crawling | System-Konfiguration |
| `CTRL-OUTPUT-GUARD` | Ausgabe-Beschränkung (Zitatlimit) | API-Logs |
### 9.7 Audit-relevante Protokollierung
Bei jeder Verarbeitung lizenzierter Inhalte wird dokumentiert:
| Feld | Beschreibung | Aufbewahrung |
|------|--------------|--------------|
| `license_check_timestamp` | Zeitpunkt der Prüfung | 10 Jahre |
| `license_decision` | Ergebnis (allowed/denied) | 10 Jahre |
| `license_proof_hash` | Hash des Lizenznachweises | 10 Jahre |
| `operation_mode_requested` | Angefragter Modus | 10 Jahre |
| `operation_mode_granted` | Erlaubter Modus | 10 Jahre |
| `publisher` | Rechteinhaber | 10 Jahre |
### 9.8 On-Premise-Deployment für sensible Normen
Für Unternehmen mit strengen Compliance-Anforderungen:
| Komponente | Deployment | Isolation |
|------------|------------|-----------|
| Normen-Datenbank | Lokaler Mac Studio | Air-gapped |
| Embedding-Service | Lokal (bge-m3) | Keine Cloud |
| Vector-DB (Qdrant) | Lokaler Container | Tenant-Isolation |
| LLM (Ollama) | Lokal (Qwen2.5-Coder) | Keine API-Calls |
---
## 10. Kontakt und Verantwortlichkeiten
### 10.1 Verantwortlicher
[Name und Adresse des Unternehmens]
### 10.2 Datenschutzbeauftragter
Name: [Name]
E-Mail: [E-Mail]
Telefon: [Telefon]
### 10.3 Technischer Ansprechpartner
Name: [Name]
E-Mail: [E-Mail]
---
## 11. Änderungshistorie
| Version | Datum | Änderung | Autor |
|---------|-------|----------|-------|
| 1.1.0 | 2026-01-29 | License Policy Engine & Standards-Compliance (§44b UrhG) | [Autor] |
| 1.0.0 | 2026-01-29 | Erstversion | [Autor] |
---
*Diese Dokumentation erfüllt die Anforderungen nach Art. 30 DSGVO (Verzeichnis von Verarbeitungstätigkeiten) und dient als Grundlage für Audits nach Art. 32 DSGVO (Sicherheit der Verarbeitung).*

746
docs-src/services/ai-compliance-sdk/DEVELOPER.md Normal file
View File

@@ -0,0 +1,746 @@
# AI Compliance SDK - Entwickler-Dokumentation
## Inhaltsverzeichnis
1. [Schnellstart](#1-schnellstart)
2. [Architektur-Übersicht](#2-architektur-übersicht)
3. [Policy Engine](#3-policy-engine)
4. [License Policy Engine](#4-license-policy-engine)
5. [Legal RAG Integration](#5-legal-rag-integration)
6. [Wizard & Legal Assistant](#6-wizard--legal-assistant)
7. [Eskalations-System](#7-eskalations-system)
8. [API-Endpoints](#8-api-endpoints)
9. [Policy-Dateien](#9-policy-dateien)
10. [Tests ausführen](#10-tests-ausführen)
---
## 1. Schnellstart
### Voraussetzungen
- Go 1.21+
- PostgreSQL (für Eskalations-Store)
- Qdrant (für Legal RAG)
- Ollama oder Anthropic API Key (für LLM)
### Build & Run
```bash
# Build
cd ai-compliance-sdk
go build -o server ./cmd/server
# Run
./server --config config.yaml
# Alternativ: mit Docker
docker compose up -d
```
### Erste Anfrage
```bash
# UCCA Assessment erstellen
curl -X POST http://localhost:8080/sdk/v1/ucca/assess \
-H "Content-Type: application/json" \
-d '{
"use_case_text": "Chatbot für Kundenservice mit FAQ-Suche",
"domain": "utilities",
"data_types": {
"personal_data": false,
"public_data": true
},
"automation": "assistive",
"model_usage": {
"rag": true
},
"hosting": {
"region": "eu"
}
}'
```
---
## 2. Architektur-Übersicht
```
┌─────────────────────────────────────────────────────────────────┐
│ API Layer (Gin) │
│ internal/api/handlers/ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ UCCA │ │ License │ │ Eskalation │ │
│ │ Handler │ │ Handler │ │ Handler │ │
│ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
│ │ │ │ │
├─────────┼────────────────┼──────────────────────┼────────────────┤
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Policy │ │ License │ │ Escalation │ │
│ │ Engine │ │ Policy │ │ Store │ │
│ │ │ │ Engine │ │ │ │
│ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
│ │ │ │ │
│ └────────┬───────┴──────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Legal RAG System │ │
│ │ (Qdrant + LLM Integration) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Kernprinzip
**LLM ist NICHT die Quelle der Wahrheit!**
| Komponente | Entscheidet | LLM-Nutzung |
|------------|-------------|-------------|
| Policy Engine | Feasibility, Risk Level | Nein |
| License Engine | Operation Mode, Stop-Lines | Nein |
| Gap Mapping | Facts → Gaps → Controls | Nein |
| Legal RAG | Erklärung generieren | Ja (nur Output) |
---
## 3. Policy Engine
### Übersicht
Die Policy Engine (`internal/ucca/policy_engine.go`) evaluiert Use Cases gegen deterministische Regeln.
### Verwendung
```go
import "ai-compliance-sdk/internal/ucca"
// Engine erstellen
engine, err := ucca.NewPolicyEngineFromPath("policies/ucca_policy_v1.yaml")
if err != nil {
log.Fatal(err)
}
// Intake erstellen
intake := &ucca.UseCaseIntake{
UseCaseText: "Chatbot für Kundenservice",
Domain: ucca.DomainUtilities,
DataTypes: ucca.DataTypes{
PersonalData: false,
PublicData: true,
},
Automation: ucca.AutomationAssistive,
ModelUsage: ucca.ModelUsage{
RAG: true,
},
Hosting: ucca.Hosting{
Region: "eu",
},
}
// Evaluieren
result := engine.Evaluate(intake)
// Ergebnis auswerten
fmt.Println("Feasibility:", result.Feasibility) // YES, NO, CONDITIONAL
fmt.Println("Risk Level:", result.RiskLevel) // MINIMAL, LOW, MEDIUM, HIGH
fmt.Println("Risk Score:", result.RiskScore) // 0-100
```
### Ergebnis-Struktur
```go
type EvaluationResult struct {
Feasibility Feasibility // YES, NO, CONDITIONAL
RiskLevel RiskLevel // MINIMAL, LOW, MEDIUM, HIGH
RiskScore int // 0-100
TriggeredRules []TriggeredRule // Ausgelöste Regeln
RequiredControls []Control // Erforderliche Maßnahmen
RecommendedArchitecture []Pattern // Empfohlene Patterns
DSFARecommended bool // DSFA erforderlich?
Art22Risk bool // Art. 22 Risiko?
TrainingAllowed TrainingAllowed // YES, NO, CONDITIONAL
PolicyVersion string // Version der Policy
}
```
### Regeln hinzufügen
Neue Regeln werden in `policies/ucca_policy_v1.yaml` definiert:
```yaml
rules:
- id: R-CUSTOM-001
code: R-CUSTOM-001
category: custom
title: Custom Rule
title_de: Benutzerdefinierte Regel
description: Custom rule description
severity: WARN # INFO, WARN, BLOCK
gdpr_ref: "Art. 6 DSGVO"
condition:
all_of:
- field: domain
equals: custom_domain
- field: data_types.personal_data
equals: true
controls:
- C_CUSTOM_CONTROL
```
---
## 4. License Policy Engine
### Übersicht
Die License Policy Engine (`internal/ucca/license_policy.go`) prüft die Lizenz-Compliance für Standards und Normen.
### Operationsmodi
| Modus | Beschreibung | Lizenzanforderung |
|-------|--------------|-------------------|
| `LINK_ONLY` | Nur Verweise | Keine |
| `NOTES_ONLY` | Eigene Notizen | Keine |
| `EXCERPT_ONLY` | Kurzzitate (<150 Zeichen) | Standard-Lizenz |
| `FULLTEXT_RAG` | Volltext-Embedding | Explizite KI-Lizenz |
| `TRAINING` | Modell-Training | Enterprise + Vertrag |
### Verwendung
```go
import "ai-compliance-sdk/internal/ucca"
engine := ucca.NewLicensePolicyEngine()
facts := &ucca.LicensedContentFacts{
Present: true,
Publisher: "DIN_MEDIA",
LicenseType: "SINGLE_WORKSTATION",
AIUsePermitted: "NO",
ProofUploaded: false,
OperationMode: "FULLTEXT_RAG",
}
result := engine.Evaluate(facts)
if !result.Allowed {
fmt.Println("Blockiert:", result.StopLine.Message)
fmt.Println("Effektiver Modus:", result.EffectiveMode)
}
```
### Ingest-Entscheidung
```go
// Prüfen ob Volltext-Ingest erlaubt ist
canIngest := engine.CanIngestFulltext(facts)
// Oder detaillierte Entscheidung
decision := engine.DecideIngest(facts)
fmt.Println("Fulltext:", decision.AllowFulltext)
fmt.Println("Notes:", decision.AllowNotes)
fmt.Println("Metadata:", decision.AllowMetadata)
```
### Audit-Logging
```go
// Audit-Entry erstellen
entry := engine.FormatAuditEntry("tenant-123", "doc-456", facts, result)
// Human-readable Summary
summary := engine.FormatHumanReadableSummary(result)
fmt.Println(summary)
```
### Publisher-spezifische Regeln
DIN Media hat explizite Restriktionen:
```go
// DIN Media blockiert FULLTEXT_RAG ohne AI-Lizenz
if facts.Publisher == "DIN_MEDIA" && facts.AIUsePermitted != "YES" {
// → STOP_DIN_FULLTEXT_AI_NOT_ALLOWED
// → Downgrade auf LINK_ONLY
}
```
---
## 5. Legal RAG Integration
### Übersicht
Das Legal RAG System (`internal/ucca/legal_rag.go`) generiert Erklärungen mit rechtlichem Kontext.
### Verwendung
```go
import "ai-compliance-sdk/internal/ucca"
rag := ucca.NewLegalRAGService(qdrantClient, llmClient, "bp_legal_corpus")
// Erklärung generieren
explanation, err := rag.Explain(ctx, result, intake)
if err != nil {
log.Error(err)
}
fmt.Println("Erklärung:", explanation.Text)
fmt.Println("Rechtsquellen:", explanation.Sources)
```
### Rechtsquellen im RAG
| Quelle | Chunks | Beschreibung |
|--------|--------|--------------|
| DSGVO | 128 | EU Datenschutz-Grundverordnung |
| AI Act | 96 | EU AI-Verordnung |
| NIS2 | 128 | Netzwerk-Informationssicherheit |
| SCC | 32 | Standardvertragsklauseln |
| DPF | 714 | Data Privacy Framework |
---
## 6. Wizard & Legal Assistant
### Wizard-Schema
Das Wizard-Schema (`policies/wizard_schema_v1.yaml`) definiert die Fragen für das Frontend.
### Legal Assistant verwenden
```go
// Wizard-Frage an Legal Assistant stellen
type WizardAskRequest struct {
Question string `json:"question"`
StepNumber int `json:"step_number"`
FieldID string `json:"field_id,omitempty"`
CurrentData map[string]interface{} `json:"current_data,omitempty"`
}
// POST /sdk/v1/ucca/wizard/ask
```
### Beispiel API-Call
```bash
curl -X POST http://localhost:8080/sdk/v1/ucca/wizard/ask \
-H "Content-Type: application/json" \
-d '{
"question": "Was sind personenbezogene Daten?",
"step_number": 2,
"field_id": "data_types.personal_data"
}'
```
---
## 7. Eskalations-System
### Eskalationsstufen
| Level | Auslöser | Prüfer | SLA |
|-------|----------|--------|-----|
| E0 | Nur INFO | Automatisch | - |
| E1 | WARN, geringes Risiko | Team-Lead | 24h |
| E2 | Art. 9, DSFA empfohlen | DSB | 8h |
| E3 | BLOCK, hohes Risiko | DSB + Legal | 4h |
### Eskalation erstellen
```go
import "ai-compliance-sdk/internal/ucca"
store := ucca.NewEscalationStore(db)
escalation := &ucca.Escalation{
AssessmentID: "assess-123",
Level: ucca.EscalationE2,
TriggerReason: "Art. 9 Daten betroffen",
RequiredReviews: 1,
}
err := store.CreateEscalation(ctx, escalation)
```
### SLA-Monitor
```go
monitor := ucca.NewSLAMonitor(store, notificationService)
// Im Hintergrund starten
go monitor.Start(ctx)
```
---
## 8. API-Endpoints
### UCCA Endpoints
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
| GET | `/sdk/v1/ucca/assess/:id` | Assessment abrufen |
| POST | `/sdk/v1/ucca/explain` | Erklärung generieren |
| GET | `/sdk/v1/ucca/wizard/schema` | Wizard-Schema abrufen |
| POST | `/sdk/v1/ucca/wizard/ask` | Legal Assistant fragen |
### License Endpoints
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/license/evaluate` | Lizenz-Prüfung |
| POST | `/sdk/v1/license/decide-ingest` | Ingest-Entscheidung |
### Eskalations-Endpoints
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/escalations` | Offene Eskalationen |
| GET | `/sdk/v1/escalations/:id` | Eskalation abrufen |
| POST | `/sdk/v1/escalations/:id/decide` | Entscheidung treffen |
---
## 9. Policy-Dateien
### Dateistruktur
```
policies/
├── ucca_policy_v1.yaml # Haupt-Policy (Regeln, Controls, Patterns)
├── wizard_schema_v1.yaml # Wizard-Fragen und Legal Assistant
├── controls_catalog.yaml # Detaillierte Control-Beschreibungen
├── gap_mapping.yaml # Facts → Gaps → Controls
├── licensed_content_policy.yaml # Standards/Normen Compliance
└── scc_legal_corpus.yaml # SCC Rechtsquellen
```
### Policy-Version
Jede Policy hat eine Version:
```yaml
metadata:
version: "1.0.0"
effective_date: "2025-01-01"
author: "Compliance Team"
```
---
## 10. Tests ausführen
### Alle Tests
```bash
cd ai-compliance-sdk
go test -v ./...
```
### Spezifische Tests
```bash
# Policy Engine Tests
go test -v ./internal/ucca/policy_engine_test.go
# License Policy Tests
go test -v ./internal/ucca/license_policy_test.go
# Eskalation Tests
go test -v ./internal/ucca/escalation_test.go
```
### Test-Coverage
```bash
go test -cover ./...
# HTML-Report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```
### Beispiel: Neuen Test hinzufügen
```go
func TestMyNewFeature(t *testing.T) {
engine := NewLicensePolicyEngine()
facts := &LicensedContentFacts{
Present: true,
Publisher: "DIN_MEDIA",
OperationMode: "FULLTEXT_RAG",
}
result := engine.Evaluate(facts)
if result.Allowed {
t.Error("Expected blocked for DIN_MEDIA FULLTEXT_RAG")
}
}
```
---
## 11. Generic Obligations Framework
### Übersicht
Das Obligations Framework ermöglicht die automatische Ableitung regulatorischer Pflichten aus NIS2, DSGVO und AI Act.
### Verwendung
```go
import "ai-compliance-sdk/internal/ucca"
// Registry erstellen (lädt alle Module)
registry := ucca.NewObligationsRegistry()
// UnifiedFacts aufbauen
facts := &ucca.UnifiedFacts{
Organization: ucca.OrganizationFacts{
EmployeeCount: 150,
AnnualRevenue: 30000000,
Country: "DE",
EUMember: true,
},
Sector: ucca.SectorFacts{
PrimarySector: "digital_infrastructure",
SpecialServices: []string{"cloud", "msp"},
IsKRITIS: false,
},
DataProtection: ucca.DataProtectionFacts{
ProcessesPersonalData: true,
},
AIUsage: ucca.AIUsageFacts{
UsesAI: true,
HighRiskCategories: []string{"employment"},
IsGPAIProvider: false,
},
}
// Alle anwendbaren Pflichten evaluieren
overview := registry.EvaluateAll(facts, "Muster GmbH")
// Ergebnis auswerten
fmt.Println("Anwendbare Regulierungen:", len(overview.ApplicableRegulations))
fmt.Println("Gesamtzahl Pflichten:", len(overview.Obligations))
fmt.Println("Kritische Pflichten:", overview.ExecutiveSummary.CriticalObligations)
```
### Neues Regulierungsmodul erstellen
```go
// 1. Module-Interface implementieren
type MyRegulationModule struct {
obligations []ucca.Obligation
controls []ucca.ObligationControl
incidentDeadlines []ucca.IncidentDeadline
}
func (m *MyRegulationModule) ID() string { return "my_regulation" }
func (m *MyRegulationModule) Name() string { return "My Regulation" }
func (m *MyRegulationModule) IsApplicable(facts *ucca.UnifiedFacts) bool {
// Prüflogik implementieren
return facts.Organization.Country == "DE"
}
func (m *MyRegulationModule) DeriveObligations(facts *ucca.UnifiedFacts) []ucca.Obligation {
// Pflichten basierend auf Facts ableiten
return m.obligations
}
// 2. In Registry registrieren
func NewMyRegulationModule() (*MyRegulationModule, error) {
m := &MyRegulationModule{}
// YAML laden oder hardcoded Pflichten definieren
return m, nil
}
// In obligations_registry.go:
// r.Register(NewMyRegulationModule())
```
### YAML-basierte Pflichten
```yaml
# policies/obligations/my_regulation_obligations.yaml
regulation: my_regulation
name: "My Regulation"
obligations:
- id: "MYREG-OBL-001"
title: "Compliance-Pflicht"
description: "Beschreibung der Pflicht"
applies_when: "classification != 'nicht_betroffen'"
legal_basis:
- norm: "§ 1 MyReg"
category: "Governance"
responsible: "Geschäftsführung"
deadline:
type: "relative"
duration: "12 Monate"
sanctions:
max_fine: "1 Mio. EUR"
priority: "high"
controls:
- id: "MYREG-CTRL-001"
name: "Kontrollmaßnahme"
category: "Technical"
when_applicable: "immer"
what_to_do: "Maßnahme implementieren"
evidence_needed:
- "Dokumentation"
```
### PDF Export
```go
import "ai-compliance-sdk/internal/ucca"
// Exporter erstellen
exporter := ucca.NewPDFExporter("de")
// PDF generieren
response, err := exporter.ExportManagementMemo(overview)
if err != nil {
log.Fatal(err)
}
// base64-kodierter PDF-Inhalt
fmt.Println("Content-Type:", response.ContentType) // application/pdf
fmt.Println("Filename:", response.Filename)
// PDF speichern
decoded, _ := base64.StdEncoding.DecodeString(response.Content)
os.WriteFile("memo.pdf", decoded, 0644)
// Alternativ: Markdown
mdResponse, err := exporter.ExportMarkdown(overview)
fmt.Println(mdResponse.Content) // Markdown-Text
```
### API-Endpoints
```bash
# Assessment erstellen
curl -X POST http://localhost:8090/sdk/v1/ucca/obligations/assess \
-H "Content-Type: application/json" \
-d '{
"facts": {
"organization": {"employee_count": 150, "country": "DE"},
"sector": {"primary_sector": "healthcare"},
"data_protection": {"processes_personal_data": true},
"ai_usage": {"uses_ai": false}
},
"organization_name": "Test GmbH"
}'
# PDF Export (direkt)
curl -X POST http://localhost:8090/sdk/v1/ucca/obligations/export/direct \
-H "Content-Type: application/json" \
-d '{
"overview": { ... },
"format": "pdf",
"language": "de"
}'
```
---
## 12. Tests für Obligations Framework
```bash
# Alle Obligations-Tests
go test -v ./internal/ucca/..._module_test.go
# NIS2 Module Tests
go test -v ./internal/ucca/nis2_module_test.go
# DSGVO Module Tests
go test -v ./internal/ucca/dsgvo_module_test.go
# AI Act Module Tests
go test -v ./internal/ucca/ai_act_module_test.go
# PDF Export Tests
go test -v ./internal/ucca/pdf_export_test.go
```
### Beispiel-Tests
```go
func TestNIS2Module_LargeCompanyInAnnexISector(t *testing.T) {
module, _ := ucca.NewNIS2Module()
facts := &ucca.UnifiedFacts{
Organization: ucca.OrganizationFacts{
EmployeeCount: 500,
AnnualRevenue: 100000000,
Country: "DE",
},
Sector: ucca.SectorFacts{
PrimarySector: "energy",
},
}
if !module.IsApplicable(facts) {
t.Error("Expected NIS2 to apply to large energy company")
}
classification := module.Classify(facts)
if classification != "besonders_wichtige_einrichtung" {
t.Errorf("Expected 'besonders_wichtige_einrichtung', got '%s'", classification)
}
}
func TestAIActModule_HighRiskEmploymentAI(t *testing.T) {
module, _ := ucca.NewAIActModule()
facts := &ucca.UnifiedFacts{
AIUsage: ucca.AIUsageFacts{
UsesAI: true,
HighRiskCategories: []string{"employment"},
},
}
if !module.IsApplicable(facts) {
t.Error("Expected AI Act to apply")
}
riskLevel := module.ClassifyRisk(facts)
if riskLevel != ucca.AIActHighRisk {
t.Errorf("Expected 'high_risk', got '%s'", riskLevel)
}
}
```
---
## Anhang: Wichtige Dateien
| Datei | Beschreibung |
|-------|--------------|
| `internal/ucca/policy_engine.go` | Haupt-Policy-Engine |
| `internal/ucca/license_policy.go` | License Policy Engine |
| `internal/ucca/obligations_framework.go` | Obligations Interfaces & Typen |
| `internal/ucca/obligations_registry.go` | Modul-Registry |
| `internal/ucca/nis2_module.go` | NIS2 Decision Tree |
| `internal/ucca/dsgvo_module.go` | DSGVO Pflichten |
| `internal/ucca/ai_act_module.go` | AI Act Risk Classification |
| `internal/ucca/pdf_export.go` | PDF/Markdown Export |
| `internal/api/handlers/obligations_handlers.go` | Obligations API |
| `policies/obligations/*.yaml` | Pflichten-Kataloge |
---
*Dokumentationsstand: 2026-01-29*

220
docs-src/services/ai-compliance-sdk/SBOM.md Normal file
View File

@@ -0,0 +1,220 @@
# AI Compliance SDK - Software Bill of Materials (SBOM)
**Erstellt:** 2026-01-29
**Go-Version:** 1.24.0
---
## Zusammenfassung
| Kategorie | Anzahl | Status |
|-----------|--------|--------|
| Direkte Abhängigkeiten | 7 | ✅ Alle kommerziell nutzbar |
| Indirekte Abhängigkeiten | ~45 | ✅ Alle kommerziell nutzbar |
| **Gesamt** | ~52 | ✅ **Alle Open Source, kommerziell nutzbar** |
---
## Direkte Abhängigkeiten
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `github.com/gin-gonic/gin` | v1.10.1 | **MIT** | ✅ Ja |
| `github.com/gin-contrib/cors` | v1.7.6 | **MIT** | ✅ Ja |
| `github.com/google/uuid` | v1.6.0 | **BSD-3-Clause** | ✅ Ja |
| `github.com/jackc/pgx/v5` | v5.5.3 | **MIT** | ✅ Ja |
| `github.com/joho/godotenv` | v1.5.1 | **MIT** | ✅ Ja |
| `github.com/xuri/excelize/v2` | v2.9.1 | **BSD-3-Clause** | ✅ Ja |
| `gopkg.in/yaml.v3` | v3.0.1 | **MIT / Apache-2.0** | ✅ Ja |
---
## Indirekte Abhängigkeiten (Transitive)
### JSON / Serialisierung
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `github.com/bytedance/sonic` | v1.13.3 | **Apache-2.0** | ✅ Ja |
| `github.com/goccy/go-json` | v0.10.5 | **MIT** | ✅ Ja |
| `github.com/json-iterator/go` | v1.1.12 | **MIT** | ✅ Ja |
| `github.com/pelletier/go-toml/v2` | v2.2.4 | **MIT** | ✅ Ja |
| `gopkg.in/yaml.v3` | v3.0.1 | **MIT / Apache-2.0** | ✅ Ja |
| `github.com/ugorji/go/codec` | v1.3.0 | **MIT** | ✅ Ja |
### Web Framework (Gin-Ökosystem)
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `github.com/gin-contrib/sse` | v1.1.0 | **MIT** | ✅ Ja |
| `github.com/go-playground/validator/v10` | v10.26.0 | **MIT** | ✅ Ja |
| `github.com/go-playground/locales` | v0.14.1 | **MIT** | ✅ Ja |
| `github.com/go-playground/universal-translator` | v0.18.1 | **MIT** | ✅ Ja |
| `github.com/leodido/go-urn` | v1.4.0 | **MIT** | ✅ Ja |
### Datenbank (PostgreSQL)
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `github.com/jackc/pgpassfile` | v1.0.0 | **MIT** | ✅ Ja |
| `github.com/jackc/pgservicefile` | v0.0.0-... | **MIT** | ✅ Ja |
| `github.com/jackc/puddle/v2` | v2.2.1 | **MIT** | ✅ Ja |
### Excel-Verarbeitung
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `github.com/xuri/excelize/v2` | v2.9.1 | **BSD-3-Clause** | ✅ Ja |
| `github.com/xuri/efp` | v0.0.1 | **BSD-3-Clause** | ✅ Ja |
| `github.com/xuri/nfp` | v0.0.2-... | **BSD-3-Clause** | ✅ Ja |
| `github.com/richardlehane/mscfb` | v1.0.4 | **Apache-2.0** | ✅ Ja |
| `github.com/richardlehane/msoleps` | v1.0.4 | **Apache-2.0** | ✅ Ja |
### PDF-Generierung
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `github.com/jung-kurt/gofpdf` | v1.16.2 | **MIT** | ✅ Ja |
### Utilities
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `github.com/gabriel-vasile/mimetype` | v1.4.9 | **MIT** | ✅ Ja |
| `github.com/mattn/go-isatty` | v0.0.20 | **MIT** | ✅ Ja |
| `github.com/modern-go/concurrent` | v0.0.0-... | **Apache-2.0** | ✅ Ja |
| `github.com/modern-go/reflect2` | v1.0.2 | **Apache-2.0** | ✅ Ja |
| `github.com/klauspost/cpuid/v2` | v2.2.10 | **MIT** | ✅ Ja |
| `github.com/tiendc/go-deepcopy` | v1.7.1 | **MIT** | ✅ Ja |
| `github.com/twitchyliquid64/golang-asm` | v0.15.1 | **MIT** | ✅ Ja |
| `github.com/cloudwego/base64x` | v0.1.5 | **Apache-2.0** | ✅ Ja |
### Go Standardbibliothek Erweiterungen
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `golang.org/x/arch` | v0.18.0 | **BSD-3-Clause** | ✅ Ja |
| `golang.org/x/crypto` | v0.43.0 | **BSD-3-Clause** | ✅ Ja |
| `golang.org/x/net` | v0.46.0 | **BSD-3-Clause** | ✅ Ja |
| `golang.org/x/sync` | v0.17.0 | **BSD-3-Clause** | ✅ Ja |
| `golang.org/x/sys` | v0.37.0 | **BSD-3-Clause** | ✅ Ja |
| `golang.org/x/text` | v0.30.0 | **BSD-3-Clause** | ✅ Ja |
### Protokoll-Bibliotheken
| Package | Version | Lizenz | Kommerziell nutzbar |
|---------|---------|--------|---------------------|
| `google.golang.org/protobuf` | v1.36.6 | **BSD-3-Clause** | ✅ Ja |
---
## Lizenz-Übersicht
| Lizenz | Anzahl Packages | Kommerziell nutzbar | Copyleft |
|--------|-----------------|---------------------|----------|
| **MIT** | ~25 | ✅ Ja | ❌ Nein |
| **Apache-2.0** | ~8 | ✅ Ja | ❌ Nein (schwach) |
| **BSD-3-Clause** | ~12 | ✅ Ja | ❌ Nein |
| **BSD-2-Clause** | 0 | ✅ Ja | ❌ Nein |
### Keine problematischen Lizenzen!
| Lizenz | Status |
|--------|--------|
| GPL-2.0 | ❌ **Nicht verwendet** |
| GPL-3.0 | ❌ **Nicht verwendet** |
| AGPL | ❌ **Nicht verwendet** |
| LGPL | ❌ **Nicht verwendet** |
| SSPL | ❌ **Nicht verwendet** |
| Commons Clause | ❌ **Nicht verwendet** |
---
## Eigene Komponenten (Keine externen Abhängigkeiten)
Die folgenden Komponenten wurden im Rahmen des AI Compliance SDK entwickelt und haben **keine zusätzlichen Abhängigkeiten**:
| Komponente | Dateien | Externe Deps |
|------------|---------|--------------|
| Policy Engine | `internal/ucca/policy_engine.go` | Keine |
| License Policy Engine | `internal/ucca/license_policy.go` | Keine |
| Legal RAG | `internal/ucca/legal_rag.go` | Keine |
| Escalation System | `internal/ucca/escalation_*.go` | Keine |
| SLA Monitor | `internal/ucca/sla_monitor.go` | Keine |
| UCCA Handlers | `internal/api/handlers/ucca_handlers.go` | Gin (MIT) |
| **Obligations Framework** | `internal/ucca/obligations_framework.go` | Keine |
| **Obligations Registry** | `internal/ucca/obligations_registry.go` | Keine |
| **NIS2 Module** | `internal/ucca/nis2_module.go` | Keine |
| **DSGVO Module** | `internal/ucca/dsgvo_module.go` | Keine |
| **AI Act Module** | `internal/ucca/ai_act_module.go` | Keine |
| **PDF Export** | `internal/ucca/pdf_export.go` | gofpdf (MIT) |
| **Obligations Handlers** | `internal/api/handlers/obligations_handlers.go` | Gin (MIT) |
| **Funding Models** | `internal/funding/models.go` | Keine |
| **Funding Store** | `internal/funding/store.go`, `postgres_store.go` | pgx (MIT) |
| **Funding Export** | `internal/funding/export.go` | gofpdf (MIT), excelize (BSD-3) |
| **Funding Handlers** | `internal/api/handlers/funding_handlers.go` | Gin (MIT) |
### Policy-Dateien (Reine YAML/JSON)
| Datei | Format | Abhängigkeiten |
|-------|--------|----------------|
| `ucca_policy_v1.yaml` | YAML | Keine |
| `wizard_schema_v1.yaml` | YAML | Keine |
| `controls_catalog.yaml` | YAML | Keine |
| `gap_mapping.yaml` | YAML | Keine |
| `licensed_content_policy.yaml` | YAML | Keine |
| `financial_regulations_policy.yaml` | YAML | Keine |
| `financial_regulations_corpus.yaml` | YAML | Keine |
| `scc_legal_corpus.yaml` | YAML | Keine |
| **`obligations/nis2_obligations.yaml`** | YAML | Keine |
| **`obligations/dsgvo_obligations.yaml`** | YAML | Keine |
| **`obligations/ai_act_obligations.yaml`** | YAML | Keine |
| **`funding/foerderantrag_wizard_v1.yaml`** | YAML | Keine |
| **`funding/bundesland_profiles.yaml`** | YAML | Keine |
---
## Compliance-Erklärung
### Für kommerzielle Nutzung geeignet: ✅ JA
Alle verwendeten Abhängigkeiten verwenden **permissive Open-Source-Lizenzen**:
1. **MIT-Lizenz**: Erlaubt kommerzielle Nutzung, Modifikation, Distribution. Nur Lizenzhinweis erforderlich.
2. **Apache-2.0-Lizenz**: Erlaubt kommerzielle Nutzung, Modifikation, Distribution. Patentgewährung enthalten.
3. **BSD-3-Clause**: Erlaubt kommerzielle Nutzung, Modifikation, Distribution. Nur Lizenzhinweis erforderlich.
### Keine Copyleft-Lizenzen
Es werden **keine** Copyleft-Lizenzen (GPL, AGPL, LGPL) verwendet, die eine Offenlegung des eigenen Quellcodes erfordern würden.
### Empfohlene Maßnahmen
1. **NOTICE-Datei pflegen**: Alle Lizenztexte in einer NOTICE-Datei zusammenfassen
2. **Regelmäßige Updates**: Abhängigkeiten auf bekannte Schwachstellen prüfen
3. **License-Scanner**: Tool wie `go-licenses` oder `fossa` für automatisierte Prüfung
---
## Generierung des SBOM
```bash
# SBOM im SPDX-Format generieren
go install github.com/spdx/tools-golang/cmd/spdx-tvwriter@latest
go mod download
# Manuell: SPDX-Dokument erstellen
# Alternativ: CycloneDX Format
go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest
cyclonedx-gomod mod -output sbom.json
# Lizenz-Prüfung
go install github.com/google/go-licenses@latest
go-licenses csv github.com/breakpilot/ai-compliance-sdk/...
```
---
*Dokumentationsstand: 2026-01-29*

97
docs-src/services/ai-compliance-sdk/index.md Normal file
View File

@@ -0,0 +1,97 @@
# AI Compliance SDK
Das AI Compliance SDK ist ein Go-basierter Service zur Compliance-Bewertung von KI-Anwendungsfällen.
## Übersicht
| Eigenschaft | Wert |
|-------------|------|
| **Port** | 8090 |
| **Framework** | Go (Gin) |
| **Datenbank** | PostgreSQL |
| **Vector DB** | Qdrant (Legal RAG) |
## Kernkomponenten
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ UCCA System │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Frontend │───>│ SDK API │───>│ PostgreSQL │ │
│ │ (Next.js) │ │ (Go) │ │ Database │ │
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Policy │ │ Escalation │ │ Legal RAG │ │
│ │ Engine │ │ Workflow │ │ (Qdrant) │ │
│ │ (45 Regeln) │ │ (E0-E3) │ │ 2,274 Chunks │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
## Features
- **UCCA (Use-Case Compliance Advisor)**: Deterministische Bewertung von KI-Anwendungsfällen
- **Policy Engine**: 45 regelbasierte Compliance-Prüfungen
- **License Policy Engine**: Standards/Normen-Compliance (DIN, ISO, VDI)
- **Legal RAG**: Semantische Suche in EU-Verordnungen (DSGVO, AI Act, NIS2)
- **Eskalations-Workflow**: E0-E3 Stufen mit Human-in-the-Loop
- **Wizard & Legal Assistant**: Geführte Eingabe mit Rechtsassistent
- **Generic Obligations Framework**: NIS2, DSGVO, AI Act Module
## Kernprinzip
> **"LLM ist NICHT die Quelle der Wahrheit. Wahrheit = Regeln + Evidenz. LLM = Übersetzer + Subsumptionshelfer"**
Das System folgt einem strikten **Human-in-the-Loop** Ansatz:
1. **Deterministische Regeln** treffen alle Compliance-Entscheidungen
2. **LLM** erklärt nur Ergebnisse, überschreibt nie BLOCK-Entscheidungen
3. **Menschen** (DSB, Legal) treffen finale Entscheidungen bei kritischen Fällen
## API-Endpunkte
### Assessment
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
| GET | `/sdk/v1/ucca/assessments` | Assessments auflisten |
| GET | `/sdk/v1/ucca/assessments/:id` | Assessment abrufen |
| POST | `/sdk/v1/ucca/assessments/:id/explain` | LLM-Erklärung generieren |
### Eskalation
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/escalations` | Eskalationen auflisten |
| POST | `/sdk/v1/ucca/escalations/:id/decide` | Entscheidung treffen |
### Obligations Framework
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/obligations/assess` | Pflichten-Assessment |
| POST | `/sdk/v1/ucca/obligations/export/memo` | PDF-Export |
## Weiterführende Dokumentation
- [Architektur](./ARCHITECTURE.md) - Detaillierte Systemarchitektur
- [Entwickler-Guide](./DEVELOPER.md) - Entwickler-Dokumentation
- [Auditor-Dokumentation](./AUDITOR_DOCUMENTATION.md) - Dokumentation für externe Auditoren
## Tests
```bash
cd ai-compliance-sdk
go test -v ./...
# Mit Coverage
go test -cover ./...
```