breakpilot-pwa/backend/compliance/data/README.md

# Compliance Data - Service Module Registry

Diese Dateien enthalten die Seed-Daten für das Compliance-Modul.

## Sprint 3: Service-Module Registry

### Dateien

- **`service_modules.py`**: Vollständige Registry aller 30+ Breakpilot Services mit:
  - Technische Details (Port, Stack, Repository)
  - Datenkategorien und PII-Verarbeitung
  - Anwendbare Regulierungen (GDPR, AI Act, BSI-TR, etc.)
  - Kritikalität und Ownership

### Service-Typen

| Typ | Beschreibung | Beispiele |
|-----|--------------|-----------|
| `backend` | API/Backend Services | consent-service, python-backend |
| `database` | Datenbanken | PostgreSQL, Qdrant, Valkey |
| `ai` | KI/ML Services | klausur-service, embedding-service |
| `communication` | Chat/Video | Matrix, Jitsi |
| `storage` | Speichersysteme | MinIO, DSMS |
| `infrastructure` | Infrastruktur | Vault, Mailpit, Backup |
| `monitoring` | Monitoring (geplant) | Loki, Grafana, Prometheus |
| `security` | Sicherheit | Vault |

### Relevanz-Stufen

| Stufe | Bedeutung |
|-------|-----------|
| `critical` | Non-Compliance = Shutdown |
| `high` | Hohes Risiko |
| `medium` | Mittleres Risiko |
| `low` | Geringes Risiko |

### Verwendung

```python
from compliance.data.service_modules import (
    BREAKPILOT_SERVICES,
    get_service_count,
    get_services_by_type,
    get_services_processing_pii,
    get_services_with_ai,
    get_critical_services
)

# Alle Services
total = get_service_count()

# Backend Services
backends = get_services_by_type("backend")

# PII-verarbeitende Services
pii_services = get_services_processing_pii()

# KI-Services
ai_services = get_services_with_ai()

# Kritische Services
critical = get_critical_services()
```

### Seeding

Services werden automatisch beim ersten Start geseedet:

```bash
# Nur Service-Module seeden
python -m compliance.scripts.seed_service_modules --mode modules

# Vollständige Compliance-DB seeden
python -m compliance.scripts.seed_service_modules --mode all
```

### Validierung

Vor dem Seeding können die Daten validiert werden:

```bash
python -m compliance.scripts.validate_service_modules
```

Prüft:
- Pflichtfelder vorhanden
- Keine Port-Konflikte
- Regulierungen existieren
- Datenkategorien bei PII-Services

## Service-Dokumentation

Jeder Service ist dokumentiert mit:

1. **Identifikation**
   - `name`: Technischer Name (Docker-Container)
   - `display_name`: Anzeigename
   - `description`: Kurzbeschreibung

2. **Technische Details**
   - `service_type`: Typ (backend, database, etc.)
   - `port`: Hauptport (falls vorhanden)
   - `technology_stack`: Verwendete Technologien
   - `repository_path`: Pfad im Repository
   - `docker_image`: Docker Image Name

3. **Datenschutz**
   - `data_categories`: Welche Datenkategorien werden verarbeitet
   - `processes_pii`: Verarbeitet personenbezogene Daten?
   - `processes_health_data`: Verarbeitet Gesundheitsdaten?
   - `ai_components`: Enthält KI-Komponenten?

4. **Compliance**
   - `criticality`: Kritikalität (critical, high, medium, low)
   - `owner_team`: Verantwortliches Team
   - `regulations`: Liste anwendbarer Regulierungen mit Relevanz

### Beispiel: consent-service

```python
{
    "name": "consent-service",
    "display_name": "Go Consent Service",
    "description": "Kernlogik für Consent-Management, Einwilligungsverwaltung und Versionierung",
    "service_type": "backend",
    "port": 8081,
    "technology_stack": ["Go", "Gin", "GORM", "PostgreSQL"],
    "repository_path": "/consent-service",
    "docker_image": "breakpilot-pwa-consent-service",
    "data_categories": ["consent_records", "user_preferences", "audit_logs"],
    "processes_pii": True,
    "processes_health_data": False,
    "ai_components": False,
    "criticality": "critical",
    "owner_team": "Backend Team",
    "regulations": [
        {"code": "GDPR", "relevance": "critical", "notes": "Art. 7 Einwilligung, Art. 30 VVZ"},
        {"code": "TDDDG", "relevance": "critical", "notes": "§ 25 Cookie-Consent"},
        {"code": "BSI-TR-03161-2", "relevance": "high", "notes": "Session-Management"}
    ]
}
```

## Datenbank-Schema

Die Service-Module werden in folgenden Tabellen gespeichert:

### `compliance_service_modules`

Haupttabelle für Services:
- `id`, `name`, `display_name`, `description`
- `service_type`, `port`, `technology_stack`
- `data_categories`, `processes_pii`, `ai_components`
- `criticality`, `owner_team`
- `compliance_score` (berechnet)

### `compliance_module_regulations`

Mapping Service ↔ Regulation:
- `module_id`, `regulation_id`
- `relevance_level` (critical, high, medium, low)
- `notes`
- `applicable_articles` (JSON Liste)

### `compliance_module_risks`

Service-spezifische Risikobewertungen:
- `module_id`, `risk_id`
- `module_likelihood`, `module_impact`
- `module_risk_level`
- `assessment_notes`

## API Endpoints

Nach dem Seeding stehen folgende Endpoints zur Verfügung:

```
GET /api/compliance/modules
    Liste aller Service-Module

GET /api/compliance/modules/{module_id}
    Details zu einem Service

GET /api/compliance/modules/{module_id}/regulations
    Anwendbare Regulierungen für einen Service

GET /api/compliance/modules/{module_id}/compliance-score
    Compliance-Score für einen Service
```

## Erweiterung

Um einen neuen Service hinzuzufügen:

1. Service zu `BREAKPILOT_SERVICES` in `service_modules.py` hinzufügen
2. Validierung ausführen: `python -m compliance.scripts.validate_service_modules`
3. Seeding ausführen: `python -m compliance.scripts.seed_service_modules`

Oder über die API (wenn aktiviert):

```bash
POST /api/compliance/modules
{
    "name": "new-service",
    "display_name": "New Service",
    ...
}
```

## Aktueller Stand (Sprint 3)

- ✅ 30+ Services dokumentiert
- ✅ Alle docker-compose.yml Services erfasst
- ✅ Regulation Mappings definiert
- ✅ Seeder implementiert
- ✅ Validierung verfügbar
- 🔄 Compliance-Score Berechnung (geplant)
- 🔄 Gap-Analyse pro Service (geplant)