# Control Dependency Engine

Generische Engine zur Modellierung und Auswertung von Abhaengigkeiten zwischen Compliance Controls. Stellt sicher, dass Controls nicht isoliert bewertet werden, sondern im Kontext ihrer logischen Beziehungen.

**Datei:** `control-pipeline/services/dependency_engine.py`
**Generator:** `control-pipeline/services/dependency_generator.py`
**Domain Packs:** `control-pipeline/data/domain_packs/`
**API:** `/v1/dependencies/`

---

## Motivation

Ohne Dependency-Logik:

- System fordert Schulung obwohl Vertrag vorhanden
- Kunde verliert Vertrauen
- Falsche Findings, unnoetige Massnahmen

Mit Dependency-Logik:

- "Control B wurde nicht geprueft, weil Control A bestanden hat"
- "Control C ist fehlgeschlagen, aber durch Control E kompensiert"
- Korrekte Audit-Ergebnisse, weniger False Positives

---

## 5 Dependency-Typen (v1)

```mermaid
flowchart LR
    subgraph Stark
        A[supersedes Prio=10]
        B[scope_exclusion Prio=20]
    end
    subgraph Mittel
        C[prerequisite Prio=50]
        D[conditional_requirement Prio=70]
    end
    subgraph Schwach
        E[compensating_control Prio=80]
    end
```

| Typ | Prioritaet | Bedeutung | Beispiel |
|-----|-----------|-----------|---------|
| `supersedes` | 10 | A macht B ueberfluessig | GHV-Klausel → Schulung |
| `scope_exclusion` | 20 | A schliesst B aus | Kein KI → KI-Controls |
| `prerequisite` | 50 | A muss vor B existieren | Policy definieren → implementieren |
| `conditional_requirement` | 70 | B nur unter Bedingung | Enhanced Logging nur fuer Grosse |
| `compensating_control` | 80 | A kompensiert B-Failure | ISO-Cert → Einzelcontrols |

---

## Condition Language

Jede Dependency hat eine `condition` (JSONB) die gegen einen Kontext ausgewertet wird:

### Einfache Bedingung

```json
{"field": "source.status", "op": "==", "value": "pass"}
```

### Zusammengesetzte Bedingung

```json
{
  "operator": "AND",
  "clauses": [
    {"field": "source.status", "op": "==", "value": "pass"},
    {"field": "context.company_size", "op": "in", "value": ["large", "enterprise"]}
  ]
}
```

### Negation

```json
{
  "operator": "NOT",
  "clause": {"field": "context.scope_signals", "op": "contains", "value": "uses_ai"}
}
```

### Verfuegbare Felder

| Feld | Beschreibung |
|------|-------------|
| `source.status` | Status des Quell-Controls |
| `target.status` | Status des Ziel-Controls |
| `context.industry` | Branche des Unternehmens |
| `context.company_size` | Unternehmensgroesse |
| `context.scope_signals` | Scope-Signale (Liste) |

### Operatoren

`==`, `!=`, `in`, `not_in`, `>`, `<`, `>=`, `<=`, `contains`, `AND`, `OR`, `NOT`

---

## Evaluation-Algorithmus

```mermaid
flowchart TD
    A[Alle Dependencies laden] --> B[Zyklen erkennen DFS]
    B --> C{Zyklen?}
    C -->|Ja| D[Betroffene Controls = review_required]
    C -->|Nein| E[Topologisch sortieren]
    E --> F[Fuer jedes Control:]
    F --> G[Conditions pruefen]
    G --> H[Matching Effects sammeln]
    H --> I[Hoechste Prioritaet gewinnt]
    I --> J[Status setzen + Trace schreiben]
```

### Priority-basierte Konfliktloesung

Wenn mehrere Dependencies auf dasselbe Control wirken, gewinnt die mit der **niedrigsten** Prioritaetsnummer:

- `scope_exclusion` (Prio 20) schlaegt `compensating_control` (Prio 80)
- `supersedes` (Prio 10) schlaegt alles

### Cycle Detection

Zyklen (A → B → A) werden via DFS erkannt. Betroffene Controls erhalten `review_required` mit Confidence 0.5.

---

## Automatische Generierung

### 1. Ontology-basiert

Controls mit gleichem `normalized_object` und verschiedenen Lifecycle-Phasen:

```
define:access_policy (Phase 2)
  → prerequisite fuer →
implement:access_policy (Phase 4)
  → prerequisite fuer →
test:access_policy (Phase 8)
```

### 2. Pattern-basiert

| Regel | Source | Target | Dependency |
|-------|--------|--------|-----------|
| define_before_implement | define | implement | prerequisite |
| implement_before_monitor | implement/configure | monitor/test | prerequisite |
| define_before_enforce | define | enforce | prerequisite |
| train_before_review | train | review/assess | prerequisite |

### 3. Domain Packs (YAML)

Regulierungsspezifische Regeln in YAML-Dateien:

**DSGVO (`gdpr.yaml`):**
- Verarbeitungsverzeichnis → DSFA (prerequisite)
- Rechtsgrundlage → Datenverarbeitung (prerequisite)

**Security (`security.yaml`):**
- MFA → Passwortkomplexitaet (compensating_control)
- ISO-Cert → Einzelcontrols (compensating_control)

**AI Act (`ai_act.yaml`):**
- Risikoklassifizierung → High-Risk-Anforderungen (prerequisite)
- FRIA → KI-Einsatz (prerequisite)

**CRA (`cra.yaml`):**
- SBOM → Vulnerability Monitoring (prerequisite)
- CE-Zertifizierung → Einzelnachweise (compensating_control)

**Arbeitsrecht (`labor_contracts.yaml`):**
- GHV-Klausel → Schulung (supersedes)
- Erstschulung → Nachschulung (prerequisite)

---

## API Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|-------------|
| `GET` | `/v1/dependencies/` | Dependencies auflisten (filterbar) |
| `POST` | `/v1/dependencies/` | Dependency manuell erstellen |
| `DELETE` | `/v1/dependencies/{id}` | Dependency deaktivieren |
| `POST` | `/v1/dependencies/generate` | Auto-Generierung (dry_run default) |
| `POST` | `/v1/dependencies/evaluate` | Controls evaluieren |
| `GET` | `/v1/dependencies/evaluate/{run_id}` | Ergebnisse abrufen |
| `POST` | `/v1/dependencies/validate` | Zyklen pruefen |
| `GET` | `/v1/dependencies/graph` | Graph (Nodes + Edges) |

---

## DB-Schema

### `control_dependencies`

| Spalte | Typ | Beschreibung |
|--------|-----|-------------|
| `id` | UUID | Primaerschluessel |
| `source_control_id` | UUID FK | Quell-Control |
| `target_control_id` | UUID FK | Ziel-Control (wird beeinflusst) |
| `dependency_type` | VARCHAR(30) | Typ (5 Werte) |
| `condition` | JSONB | Generische Bedingung |
| `effect` | JSONB | Effekt bei Bedingung=true |
| `priority` | INT | Niedrig = hohe Prioritaet |
| `generation_method` | VARCHAR(30) | manual / ontology / pattern / domain_pack |
| `is_active` | BOOLEAN | Soft-Delete |

### `control_evaluation_results`

| Spalte | Typ | Beschreibung |
|--------|-----|-------------|
| `control_id` | UUID FK | Ausgewertetes Control |
| `evaluation_run_id` | UUID | Gruppiert einen Lauf |
| `raw_status` | VARCHAR(30) | Status vor Dependencies |
| `resolved_status` | VARCHAR(30) | Status nach Dependencies |
| `dependency_resolution` | JSONB | Vollstaendiger Trace |
| `confidence` | FLOAT | 0.0-1.0 |

---

## Tests

| Testdatei | Tests | Beschreibung |
|-----------|-------|-------------|
| `test_dependency_engine.py` | 39 | Condition Evaluator, Effect Applier, Cycle Detection, Topological Sort, GHV-Szenario |
| `test_dependency_generator.py` | 14 | Ontology, Pattern, Domain Pack Generation |