docs: rewrite Control Generator Pipeline + add Dependency Engine docs
- Complete rewrite of control-generator-pipeline.md covering all 6 phases: RAG Ingestion, Control Generation, Pass 0a, Pass 0b, Dedup, Dependencies - New: dependency-engine.md with full documentation of 5 dependency types, condition language, evaluation algorithm, auto-generation, domain packs - Updated mkdocs.yml navigation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
File diff suppressed because it is too large
Load Diff
228
docs-src/services/sdk-modules/dependency-engine.md
Normal file
228
docs-src/services/sdk-modules/dependency-engine.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user