# IACE — Industrial AI Compliance Engine

**Modul:** CE-Risikobeurteilung fuer Maschinen mit Software / Firmware / KI
**Service:** `ai-compliance-sdk` (Go/Gin, Port 8093)
**Base-URL:** `GET|POST https://macmini:8093/sdk/v1/iace/...`

---

## Ueberblick

Das IACE-Modul unterstuetzt die vollstaendige CE-Konformitaetsbewertung von Maschinen und Systemen mit Software-, Firmware- und KI-Anteilen gemaess:

- **Maschinenverordnung (EU) 2023/1230** (loest Maschinenrichtlinie 2006/42/EG ab)
- **AI Act (EU) 2024/1689** (fuer KI-Systeme in Hochrisikoklassen)
- **CRA (Cyber Resilience Act)** (fuer vernetzte Produkte)
- **NIS2** (fuer kritische Infrastrukturen)

---

## SEPA Risikomodell

IACE verwendet das **SEPA-Modell** (Severity × Exposure × Probability × Avoidance):

### Formel

| Avoidance | Formel | Beschreibung |
|-----------|--------|--------------|
| `0` (Standard) | `S × E × P` | Backward-kompatibel, kein Avoidance-Faktor |
| `1–5` | `S × E × P × (A / 3.0)` | Avoidance-faktor aktiv (3 = neutral) |

### Avoidance-Skala

| Wert | Bedeutung |
|------|-----------|
| 1 | Leicht vermeidbar (klare Warnung, langsame Bewegung) |
| 2 | Eher vermeidbar |
| 3 | Neutral (kein Einfluss) |
| 4 | Schwer vermeidbar |
| 5 | Nicht vermeidbar (sofortige Auswirkung) |

### Schwellwerte (Residualrisiko)

| Schwelle | Level |
|----------|-------|
| ≥ 75 | critical |
| ≥ 40 | high |
| ≥ 15 | medium |
| ≥ 5 | low |
| < 5 | negligible |

### ALARP-Akzeptanz

- `residualRisk < 15` → akzeptabel
- `residualRisk < 40` + alle Minderungsschritte verifiziert + Begruendung → akzeptabel (ALARP)
- `residualRisk ≥ 40` → nicht akzeptabel (blockiert CE-Export)

---

## Hazard-Library

Die eingebaute Hazard-Library enthaelt **~140 Eintraege** in 24 Kategorien:

### Urspruengliche Kategorien (12)

| Kategorie | Eintraege | Beschreibung |
|-----------|-----------|--------------|
| `false_classification` | 4 | Falsche KI-Klassifikation |
| `timing_error` | 3 | Echtzeit-Verletzungen |
| `data_poisoning` | 2 | Manipulierte Trainingsdaten |
| `model_drift` | 3 | Modell-Verschlechterung |
| `sensor_spoofing` | 3 | Sensor-Manipulation |
| `communication_failure` | 3 | Kommunikationsausfall |
| `unauthorized_access` | 4 | Unberechtigter Zugriff |
| `firmware_corruption` | 3 | Firmware-Beschaedigung |
| `safety_boundary_violation` | 4 | Sicherheitsgrenzwert-Verletzung |
| `mode_confusion` | 3 | Betriebsart-Verwechslung |
| `unintended_bias` | 2 | Unbeabsichtigte Diskriminierung |
| `update_failure` | 3 | Update-Fehler |

### Neue Kategorien (12, v2.0)

| Kategorie | Eintraege | Beschreibung |
|-----------|-----------|--------------|
| `software_fault` | 10 | Race Condition, Stack Overflow, Integer Overflow, Deadlock... |
| `hmi_error` | 8 | Falsche Einheit, fehlender Alarm, Quittierung ohne Ursache... |
| `mechanical_hazard` | 6 | Unerwarteter Anlauf, Restenergie, Teileauswurf... |
| `electrical_hazard` | 6 | Elektrischer Schlag, Lichtbogen, gespeicherte Energie... |
| `thermal_hazard` | 4 | Ueberhitzung, Brandgefahr, Einfrieren... |
| `emc_hazard` | 5 | EMV-Stoerabstrahlung, ESD, HF-Stoerung... |
| `configuration_error` | 8 | Falscher Safety-Param, Hard-coded Credentials, Debug-Mode... |
| `safety_function_failure` | 8 | Not-Halt, STO, Schutztuer, Zweihand-Taster... |
| `logging_audit_failure` | 5 | Fehlende Protokollierung, Log-Manipulation, Overflow... |
| `integration_error` | 8 | Datentyp-Mismatch, Endianness, Buffer Overflow, Heartbeat... |
| `environmental_hazard` | 5 | Temperatur, Feuchtigkeit, Vibration, Kontamination... |
| `maintenance_hazard` | 6 | LOTO fehlt, Wartung bei laufender Maschine, Wiederanlauf... |

**Filter:** `GET /sdk/v1/iace/hazard-library?category=software_fault&componentType=sw`

---

## Controls-Library

Die Controls-Library enthaelt **200 Eintraege** in 6 Domaenen:

### Domaenen-Uebersicht

| Domain | Eintraege | Beschreibung | ReductionType |
|--------|-----------|--------------|---------------|
| `REQ` | 30 | Safety Requirements — HARA, SIL/PL, Traceability | design |
| `ARCH` | 30 | Architektur & Design — Redundanz, Fail-Safe, Watchdog | design |
| `SWDEV` | 40 | Software-Entwicklung — MISRA-C, Statische Analyse, WCET | design/protective |
| `VER` | 30 | Verifikation & Validation — Fault Injection, HIL, SIL-Nachweis | design/protective |
| `CYBER` | 40 | OT-Cybersecurity — Netzwerksegmentierung, Signed Updates, SBOM | design/protective |
| `DOC` | 30 | Dokumentation & CE-Akte — Technical File, DoC, Betriebsanleitung | information |

**Filter:** `GET /sdk/v1/iace/controls-library?domain=CYBER&category=unauthorized_access`

---

## API-Endpunkte (30+)

### Libraries (projektunabhaengig)

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| GET | `/sdk/v1/iace/hazard-library` | Alle Gefaehrdungen (~140) |
| GET | `/sdk/v1/iace/controls-library` | Alle Controls (200) |

### Projektmanagement

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects` | Neues Projekt erstellen |
| GET | `/sdk/v1/iace/projects` | Alle Projekte auflisten |
| GET | `/sdk/v1/iace/projects/:id` | Projekt-Details |
| PUT | `/sdk/v1/iace/projects/:id` | Projekt aktualisieren |
| DELETE | `/sdk/v1/iace/projects/:id` | Projekt archivieren |

### Onboarding

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/init-from-profile` | Projekt aus Company-Profile initialisieren |
| POST | `/sdk/v1/iace/projects/:id/completeness-check` | 25-Gates-Pruefung |

### Komponenten

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/components` | Komponente hinzufuegen |
| GET | `/sdk/v1/iace/projects/:id/components` | Alle Komponenten |
| PUT | `/sdk/v1/iace/projects/:id/components/:cid` | Komponente aktualisieren |
| DELETE | `/sdk/v1/iace/projects/:id/components/:cid` | Komponente loeschen |

### Klassifizierung

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/classify` | Alle Regulierungen klassifizieren |
| GET | `/sdk/v1/iace/projects/:id/classifications` | Klassifizierungen abrufen |
| POST | `/sdk/v1/iace/projects/:id/classify/:regulation` | Einzelne Regulierung |

### Gefaehrdungen & Risikobewertung

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/hazards` | Gefaehrdung anlegen |
| GET | `/sdk/v1/iace/projects/:id/hazards` | Alle Gefaehrdungen |
| PUT | `/sdk/v1/iace/projects/:id/hazards/:hid` | Gefaehrdung aktualisieren |
| POST | `/sdk/v1/iace/projects/:id/hazards/suggest` | KI-gestuetzte Vorschlaege |
| POST | `/sdk/v1/iace/projects/:id/hazards/:hid/assess` | Risikobewertung (SEPA) |
| POST | `/sdk/v1/iace/projects/:id/hazards/:hid/reassess` | Neubewertung nach Minderung |
| GET | `/sdk/v1/iace/projects/:id/risk-summary` | Aggregierte Risikoübersicht |

### Minderung & Verifikation

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/hazards/:hid/mitigations` | Massnahme anlegen |
| GET | `/sdk/v1/iace/projects/:id/hazards/:hid/mitigations` | Alle Massnahmen |
| PUT | `/sdk/v1/iace/projects/:id/hazards/:hid/mitigations/:mid` | Massnahme aktualisieren |
| POST | `/sdk/v1/iace/projects/:id/verification-plans` | Verifikationsplan erstellen |
| GET | `/sdk/v1/iace/projects/:id/verification-plans` | Alle Plaene |
| PUT | `/sdk/v1/iace/projects/:id/verification-plans/:vid` | Plan aktualisieren |

### CE-Technische Akte

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| GET | `/sdk/v1/iace/projects/:id/tech-file` | Technische Akte abrufen |
| POST | `/sdk/v1/iace/projects/:id/tech-file/generate` | Akte generieren |
| GET | `/sdk/v1/iace/projects/:id/tech-file/export` | Akte exportieren (PDF/Markdown) |
| PUT | `/sdk/v1/iace/projects/:id/tech-file/sections/:sid` | Abschnitt aktualisieren |

### Post-Market Monitoring

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/monitoring-events` | Ereignis protokollieren |
| GET | `/sdk/v1/iace/projects/:id/monitoring-events` | Alle Ereignisse |

### Audit-Trail

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| GET | `/sdk/v1/iace/projects/:id/audit-trail` | Unveraenderliches Audit-Log |

---

## Completeness Gates (25)

Das Modul prueft 25 Vollstaendigkeitstore vor dem CE-Export:

| Gate | Kategorie | Pflicht |
|------|-----------|---------|
| G01 | Projekt-Grunddaten vollstaendig | ✅ Required |
| G02 | CE-Markierungsziel definiert | ✅ Required |
| G03 | Mind. 1 Komponente erfasst | ✅ Required |
| G04 | Regulatorische Klassifizierung abgeschlossen | ✅ Required |
| G05 | HARA-Dokument vorhanden (Evidence) | ✅ Required |
| G06 | Mind. 1 Gefaehrdung identifiziert | ✅ Required |
| G07 | Alle Gefaehrdungen bewertet | ✅ Required |
| G08 | Kein Restrisiko > critical ohne Akzeptanz | ✅ Required |
| G09 | Mind. 1 Minderungsmassnahme je Gefaehrdung | ✅ Required |
| G10 | Minderungsmassnahmen verifiziert | ✅ Required |
| G11 | Verifikationsplan vorhanden | ✅ Required |
| G12 | SIL/PL-Dokumentation (Evidence) | ✅ Required |
| G13 | Technische Akte generiert | ✅ Required |
| G14 | Konformitaetserklaerung bereit | ✅ Required |
| G15 | Betriebsanleitung vorhanden | ✅ Required |
| G16 | Wartungsanleitung vorhanden | Recommended |
| G17 | Post-Market Monitoring aktiv | Recommended |
| G18 | Cybersecurity-Massnahmen dokumentiert | Recommended |
| G19 | AI-spezifische Anforderungen erfuellt | Recommended (bei AI) |
| G20 | Kalibrierprotokolle vorhanden | Recommended |
| G21 | SBOM generiert | Optional |
| G22 | Penetrationstest durchgefuehrt | Optional |
| G23 | EMV-Pruefung dokumentiert | Optional |
| G24 | Lebenszyklusplan vorhanden | Optional |
| G25 | Monitoring-Ereignisse protokolliert | Optional |

**Completeness Score:** `(passed_required/total_required)*80 + (passed_recommended/total_recommended)*15 + (passed_optional/total_optional)*5`

---

## CE RAG-Corpus

Die folgenden 15 Dokumente werden via `scripts/ingest-ce-corpus.sh` ingestiert:

### Collection: bp_compliance_ce

| # | Dokument | Kategorie | Lizenz |
|---|----------|-----------|--------|
| 1 | Machinery Regulation (EU) 2023/1230 | ce_machinery | EU Public Law |
| 2 | Machinery Directive 2006/42/EC | ce_machinery | EU Public Law |
| 3 | Low Voltage Directive 2014/35/EU | ce_electrical | EU Public Law |
| 4 | EMC Directive 2014/30/EU | ce_emc | EU Public Law |
| 5 | Radio Equipment Directive 2014/53/EU | ce_radio | EU Public Law |
| 6 | AI Act (EU) 2024/1689 | ce_ai | EU Public Law |
| 7 | EC Guide to the Machinery Directive | ce_machinery_guidance | EU Public |
| 8 | NIST SP 800-218 (SSDF) | ce_software_safety | US Gov Public Domain |
| 9 | NIST AI RMF 1.0 | ce_ai_safety | US Gov Public Domain |
| 10 | ENISA Guidelines for Securing the IoT | ce_ot_cybersecurity | EU Public |
| 12 | NASA Software Safety Guidebook | ce_software_safety | US Gov Public Domain |
| 13 | OWASP Top 10 (2021) | ce_software_security | CC BY-SA 4.0 |
| 15 | MITRE CWE Top 25 (2023) | ce_software_weaknesses | MIT |

### Collection: bp_compliance_datenschutz

| # | Dokument | Kategorie | Lizenz |
|---|----------|-----------|--------|
| 11 | ENISA Securing Machine Learning Algorithms | ai_cybersecurity | EU Public |
| 14 | OECD AI Principles | ai_governance | OECD Public |

### Ingest-Script ausfuehren

```bash
# Auf dem Mac Mini:
bash ~/Projekte/breakpilot-compliance/scripts/ingest-ce-corpus.sh

# Nur bestimmte Phase:
bash .../ingest-ce-corpus.sh --only ce
bash .../ingest-ce-corpus.sh --only datenschutz
bash .../ingest-ce-corpus.sh --skip-download --only verify

# Ergebnis pruefen:
curl -sk https://macmini:8093/sdk/v1/iace/hazard-library | python3 -c "import sys,json; print(json.load(sys.stdin)['total'])"
curl -sk https://macmini:8093/sdk/v1/iace/controls-library | python3 -c "import sys,json; print(json.load(sys.stdin)['total'])"
```

---

## Beispiel: Risikobewertung mit Avoidance

```bash
# Risikobewertung mit Avoidance-Faktor (A=5: nicht vermeidbar)
curl -sk -X POST https://macmini:8093/sdk/v1/iace/projects/{id}/hazards/{hid}/assess \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: <tenant-uuid>" \
  -d '{
    "hazard_id": "<hid>",
    "severity": 5,
    "exposure": 3,
    "probability": 3,
    "avoidance": 5,
    "control_maturity": 2,
    "control_coverage": 0.6,
    "test_evidence_strength": 0.5,
    "acceptance_justification": "ALARP: STO implementiert und verifiziert"
  }'
```

Ohne Avoidance (A=0): `InherentRisk = 5×3×3 = 45`
Mit Avoidance A=5: `InherentRisk = 5×3×3×(5/3) = 75` (kritisch!)
Mit Avoidance A=1: `InherentRisk = 5×3×3×(1/3) = 15` (medium)

---

## Beispiel: Controls-Library abfragen

```bash
# Alle CYBER-Controls
curl -sk "https://macmini:8093/sdk/v1/iace/controls-library?domain=CYBER" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'{d[\"total\"]} Controls')"

# Controls fuer software_fault-Kategorie
curl -sk "https://macmini:8093/sdk/v1/iace/controls-library?category=software_fault" \
  | python3 -m json.tool | head -40
```

---

## Datenbank-Tabellen

| Tabelle | Beschreibung |
|---------|--------------|
| `iace_projects` | CE-Projekte |
| `iace_components` | System-Komponenten |
| `iace_regulatory_classifications` | Regulierungsklassifizierungen |
| `iace_hazard_library` | Benutzerdefinierte Hazard-Templates |
| `iace_hazards` | Projektspezifische Gefaehrdungen |
| `iace_risk_assessments` | SEPA-Risikobewertungen (inkl. avoidance) |
| `iace_mitigations` | Minderungsmassnahmen |
| `iace_verification_plans` | Verifikationsplaene |
| `iace_evidence` | Nachweise (Uploads) |
| `iace_tech_file_sections` | CE-Akte-Abschnitte |
| `iace_monitoring_events` | Post-Market-Ereignisse |
| `iace_audit_trail` | Unveraenderbares Audit-Log |