Benjamin_Boenisch/breakpilot-compliance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b4d2be83ebe7295a89fb90780d1d03cb84ab2b3d
breakpilot-compliance/docs-src/services/sdk-modules/iace.md
Benjamin Admin efeacc1619
All checks were successful
CI / go-lint (push) Has been skipped
Details
CI / python-lint (push) Has been skipped
Details
CI / nodejs-lint (push) Has been skipped
Details
CI / test-go-ai-compliance (push) Successful in 35s
Details
CI / test-python-backend-compliance (push) Successful in 33s
Details
CI / test-python-document-crawler (push) Successful in 21s
Details
CI / test-python-dsms-gateway (push) Successful in 19s
Details
feat(iace): Hazard-Library v2, Controls-Library, SEPA Avoidance, CE RAG-Ingest 
- Hazard-Library: +79 neue Eintraege in 12 Kategorien (software_fault,
  hmi_error, mechanical_hazard, electrical_hazard, thermal_hazard,
  emc_hazard, configuration_error, safety_function_failure,
  logging_audit_failure, integration_error, environmental_hazard,
  maintenance_hazard) — Gesamtanzahl: ~116 Eintraege in 24 Kategorien
- Controls-Library: neue Datei controls_library.go mit 200 Eintraegen
  in 6 Domaenen (REQ/ARCH/SWDEV/VER/CYBER/DOC)
- Handler: GET /sdk/v1/iace/controls-library (?domain=, ?category=)
- SEPA: CalculateInherentRisk() + 4. Param Avoidance (0=disabled,
  1-5: 3=neutral); RiskComputeInput.Avoidance, RiskAssessment.Avoidance,
  AssessRiskRequest.Avoidance — backward-kompatibel (A=0 → S×E×P)
- Tests: engine_test.go + hazard_library_test.go aktualisiert
- Scripts: ingest-ce-corpus.sh — 15 CE/Safety-Dokumente (EUR-Lex,
  NIST, ENISA, NASA, OWASP, MITRE CWE) in bp_compliance_ce und
  bp_compliance_datenschutz
- Docs: docs-src/services/sdk-modules/iace.md + mkdocs.yml Nav-Eintrag

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-05 17:13:01 +01:00

349 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 |
Reference in New Issue View Git Blame Copy Permalink