breakpilot-compliance/docs-src/services/sdk-modules/compliance-kern.md

# Compliance-Kern-Module (Paket 3)

Vier Module bilden das technische Rückgrat der Compliance-Plattform:
**Anforderungen**, **Controls**, **Nachweise** und **Risiken**.

Sie sind miteinander verknüpft: Anforderungen erzeugen Controls → Controls verlangen Nachweise → Risiken werden durch Controls gemindert.

---

## Überblick

| Modul | Prefix | Endpunkte | Besonderheiten |
|-------|--------|-----------|----------------|
| **CP-ANF** Anforderungen | `/compliance/requirements` | 6 | Pagination, RAG-Kontext, Audit-Tracking |
| **CP-CTR** Controls | `/compliance/controls` | 6 | Domain-Enum, Status-Enum, Evidence-Count |
| **CP-NAC** Nachweise | `/evidence` | 6 | CI/CD-Ingest, File-Upload, Auto-Risk-Update |
| **CP-RSK** Risiken | `/risks` | 5 | Risikomatrix, Likelihood × Impact |

**Frontend:** `https://macmini:3007/sdk/anforderungen`, `/sdk/controls`, `/sdk/evidence`, `/sdk/risks`

**Proxy:** `/api/sdk/v1/compliance/[[...path]]` → `backend-compliance:8002/compliance/...`

---

## CP-ANF — Anforderungen

Verwaltet regulatorische Anforderungen (DSGVO, AI Act, CRA, NIS2 etc.).

### Endpunkte

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/compliance/requirements` | Paginierte Liste (page, page_size, search, is_applicable) |
| `GET` | `/compliance/requirements/{id}` | Einzelne Anforderung + optionaler RAG-Rechtskontext |
| `GET` | `/compliance/regulations/{code}/requirements` | Alle Anforderungen einer Regulierung |
| `POST` | `/compliance/requirements` | Neue Anforderung anlegen |
| `PUT` | `/compliance/requirements/{id}` | Implementation-Status, Audit-Notizen aktualisieren |
| `DELETE` | `/compliance/requirements/{id}` | Anforderung löschen |

### Request-Beispiel (POST)

```json
{
  "regulation_id": "uuid-der-regulierung",
  "article": "Art. 32",
  "title": "Sicherheit der Verarbeitung",
  "is_applicable": true,
  "priority": 1
}
```

### Response-Felder (RequirementResponse)

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `id` | string | UUID |
| `regulation_code` | string | z.B. "GDPR", "AI_ACT" |
| `article` | string | Artikel-Referenz |
| `implementation_status` | string | not_started / implemented / partial |
| `audit_status` | string | pending / passed / failed |
| `last_audit_date` | datetime? | Letztes Audit-Datum |

### RAG-Rechtskontext

```http
GET /compliance/requirements/{id}?include_legal_context=true
```

Gibt zusätzlich `legal_context[]` mit RAG-Ergebnissen zurück:

```json
{
  "legal_context": [
    {
      "text": "...",
      "regulation_code": "GDPR",
      "article": "Art. 32",
      "score": 0.92,
      "source_url": "https://eur-lex.europa.eu/..."
    }
  ]
}
```

---

## CP-CTR — Controls

Verwaltet technische und organisatorische Kontrollen (TOMs, Prozesse).

### Status-Enum

| Wert | Bedeutung |
|------|-----------|
| `pass` | Vollständig implementiert und geprüft |
| `partial` | Teilweise implementiert |
| `fail` | Nicht bestanden |
| `planned` | In Planung |
| `n/a` | Nicht anwendbar |

### Domain-Enum

`gov` · `priv` · `iam` · `crypto` · `sdlc` · `ops` · `ai` · `cra` · `aud`

### Endpunkte

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/compliance/controls` | Liste (domain, status, is_automated, search) |
| `GET` | `/compliance/controls/paginated` | Paginiert (page, page_size) |
| `GET` | `/compliance/controls/{control_id}` | Einzelne Kontrolle + Evidence-Count |
| `PUT` | `/compliance/controls/{control_id}` | Titel, Status, Notizen aktualisieren |
| `PUT` | `/compliance/controls/{control_id}/review` | Kontrolle als geprüft markieren |
| `GET` | `/compliance/controls/by-domain/{domain}` | Alle Controls einer Domain |

### KI-Controls aus RAG vorschlagen

```http
POST /compliance/ai/suggest-controls
{
  "requirement_id": "uuid-der-anforderung"
}
```

Gibt bis zu 5 KI-generierte Control-Vorschläge zurück, die auf dem Inhalt des RAG-Corpus basieren:

```json
{
  "requirement_id": "...",
  "suggestions": [
    {
      "control_id": "GOV-KI-001",
      "domain": "gov",
      "title": "Datenschutzbeauftragter für KI-Systeme",
      "description": "...",
      "pass_criteria": "DSB nachweislich ernannt",
      "is_automated": false,
      "priority": 1,
      "confidence_score": 0.87
    }
  ]
}
```

---

## CP-NAC — Nachweise (Evidence)

Verknüpft Prüfnachweise mit Controls. Unterstützt CI/CD-Automatisierung.

### Nachweistypen

`test_results` · `audit_report` · `penetration_test` · `sast` · `dependency_scan` · `sbom` · `container_scan` · `secret_scan` · `code_review`

### Endpunkte

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/evidence` | Liste (control_id, evidence_type, status, page, limit) |
| `POST` | `/evidence` | Nachweis manuell anlegen |
| `DELETE` | `/evidence/{id}` | Nachweis löschen |
| `POST` | `/evidence/upload` | Datei hochladen (PDF, ZIP, ...) |
| `POST` | `/evidence/collect` | CI/CD-Nachweis automatisch erfassen |
| `GET` | `/evidence/ci-status` | CI-Nachweisstand für eine Kontrolle |

### CI/CD-Integration

```json
POST /evidence/collect
{
  "control_id": "SDLC-001",
  "evidence_type": "test_results",
  "title": "Pytest Run 2024-03-01",
  "ci_job_id": "gh-actions-12345",
  "artifact_url": "https://github.com/.../artifacts/report.xml"
}
```

Nach dem Collect wird automatisch der Control-Status aktualisiert (`AutoRiskUpdater`).

---

## CP-RSK — Risiken

Verwaltet Datenschutz- und KI-Risiken (Risikobewertung nach Likelihood × Impact).

### Endpunkte

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/risks` | Liste (category, status, risk_level) |
| `POST` | `/risks` | Neues Risiko anlegen |
| `PUT` | `/risks/{risk_id}` | Risiko aktualisieren (Status, Restrisiko) |
| `DELETE` | `/risks/{risk_id}` | Risiko löschen |
| `GET` | `/risks/matrix` | Risikomatrix (Likelihood × Impact) |

### Risikomatrix

```http
GET /risks/matrix
```

```json
{
  "matrix": {
    "3": { "4": ["RISK-001", "RISK-007"] },
    "1": { "1": [] }
  },
  "risks": [...]
}
```

Die Matrix ist nach `likelihood` (1–5) → `impact` (1–5) → `[risk_ids]` strukturiert.

### Risikobewertung

| Inherent Risk | Likelihood × Impact |
|---------------|---------------------|
| `low` | ≤ 4 |
| `medium` | 5–9 |
| `high` | 10–19 |
| `critical` | ≥ 20 |

---

## Tests

```bash
cd backend-compliance

# Anforderungen
python3 -m pytest tests/test_requirement_routes.py -v

# Controls
python3 -m pytest tests/test_control_routes.py -v

# Nachweise
python3 -m pytest tests/test_evidence_routes.py -v

# Risiken
python3 -m pytest tests/test_risk_routes.py -v

# Alle 4 Module
python3 -m pytest tests/test_requirement_routes.py tests/test_control_routes.py \
    tests/test_evidence_routes.py tests/test_risk_routes.py -v
```

**Testabdeckung (Stand 2026-03-05):** 74 Tests, alle bestanden.

| Datei | Tests | Status |
|-------|-------|--------|
| `test_requirement_routes.py` | 18 | ✅ |
| `test_control_routes.py` | 21 | ✅ |
| `test_evidence_routes.py` | 11 | ✅ |
| `test_risk_routes.py` | 16 | ✅ (+ 8 aus Paket 2) |

---

## Datenbank-Schema

```sql
-- Anforderungen
compliance_requirements (id, regulation_id, article, title, implementation_status, ...)

-- Controls
compliance_controls (id, control_id, domain, control_type, title, status, ...)

-- Nachweise
compliance_evidence (id, control_id, evidence_type, title, artifact_path, status, ...)

-- Risiken
compliance_risks (id, risk_id, title, category, likelihood, impact, inherent_risk, ...)
```

Alle Tabellen werden beim Start via `SQLAlchemy Base.metadata.create_all()` angelegt.