Benjamin_Boenisch/breakpilot-pwa
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
This repository has been archived on 2026-02-15. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
34f3dbdfc3c7ad90189ac36478bab21bdca4e44e
breakpilot-pwa/backend/compliance/README.md
Benjamin Admin 21a844cb8a fix: Restore all files lost during destructive rebase 
A previous `git pull --rebase origin main` dropped 177 local commits,
losing 3400+ files across admin-v2, backend, studio-v2, website,
klausur-service, and many other services. The partial restore attempt
(660295e2) only recovered some files.

This commit restores all missing files from pre-rebase ref 98933f5e
while preserving post-rebase additions (night-scheduler, night-mode UI,
NightModeWidget dashboard integration).

Restored features include:
- AI Module Sidebar (FAB), OCR Labeling, OCR Compare
- GPU Dashboard, RAG Pipeline, Magic Help
- Klausur-Korrektur (8 files), Abitur-Archiv (5+ files)
- Companion, Zeugnisse-Crawler, Screen Flow
- Full backend, studio-v2, website, klausur-service
- All compliance SDKs, agent-core, voice-service
- CI/CD configs, documentation, scripts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 09:51:32 +01:00

308 lines
9.4 KiB
Markdown
Raw Blame History

# Breakpilot Compliance & Audit Framework
## Uebersicht
Enterprise-ready GRC (Governance, Risk, Compliance) Framework fuer die Breakpilot EdTech-Plattform.
### Kernfunktionen
| Feature | Status | Beschreibung |
|---------|--------|--------------|
| **19 EU-Regulations** | Aktiv | DSGVO, AI Act, CRA, NIS2, Data Act, etc. |
| **558 Requirements** | Aktiv | Automatisch extrahiert aus EUR-Lex + BSI-TR PDFs |
| **44 Controls** | Aktiv | Technische und organisatorische Massnahmen |
| **474 Control-Mappings** | Aktiv | Keyword-basiertes Auto-Mapping |
| **KI-Interpretation** | Aktiv | Claude API fuer Anforderungsanalyse |
| **Executive Dashboard** | Aktiv | Ampel-Status, Trends, Top-Risiken |
## Architektur
```
backend/compliance/
├── api/
│ ├── routes.py # 52 FastAPI Endpoints
│ └── schemas.py # Pydantic Response Models
├── db/
│ ├── models.py # SQLAlchemy Models
│ └── repository.py # CRUD Operations
├── data/
│ ├── regulations.py # 19 Regulations Seed
│ ├── controls.py # 44 Controls Seed
│ ├── requirements.py # Requirements Seed
│ └── service_modules.py # 30 Service-Module
├── services/
│ ├── ai_compliance_assistant.py # Claude Integration
│ ├── llm_provider.py # LLM Abstraction Layer
│ ├── pdf_extractor.py # BSI-TR PDF Parser
│ └── regulation_scraper.py # EUR-Lex Scraper
└── tests/ # Pytest Tests (in /backend/tests/)
```
## Schnellstart
### 1. Backend starten
```bash
cd backend
docker-compose up -d
# ODER
uvicorn main:app --reload --port 8000
```
### 2. Datenbank initialisieren
```bash
# Regulations, Controls, Requirements seeden
curl -X POST http://localhost:8000/api/v1/compliance/seed \
-H "Content-Type: application/json" \
-d '{"force": false}'
# Service-Module seeden
curl -X POST http://localhost:8000/api/v1/compliance/modules/seed \
-H "Content-Type: application/json" \
-d '{"force": false}'
```
### 3. KI-Interpretation aktivieren
```bash
# Vault-gesteuerte API-Keys
export VAULT_ADDR=http://localhost:8200
export VAULT_TOKEN=breakpilot-dev-token
# Status pruefen
curl http://localhost:8000/api/v1/compliance/ai/status
# Einzelne Anforderung interpretieren
curl -X POST http://localhost:8000/api/v1/compliance/ai/interpret \
-H "Content-Type: application/json" \
-d '{"requirement_id": "REQ-ID", "save_to_db": true}'
```
## API-Endpoints
### Dashboard & Executive View
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/dashboard` | Dashboard-Daten mit Scores |
| GET | `/api/v1/compliance/dashboard/executive` | Executive Dashboard (Ampel, Trends) |
| GET | `/api/v1/compliance/dashboard/trend` | Score-Trend (12 Monate) |
### Regulations & Requirements
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/regulations` | Alle 19 Regulations |
| GET | `/api/v1/compliance/regulations/{code}` | Eine Regulation |
| GET | `/api/v1/compliance/requirements` | 558 Requirements (paginiert) |
| GET | `/api/v1/compliance/requirements/{id}` | Einzelnes Requirement |
### Controls & Mappings
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/controls` | Alle 44 Controls |
| GET | `/api/v1/compliance/controls/{id}` | Ein Control |
| GET | `/api/v1/compliance/controls/by-domain/{domain}` | Controls nach Domain |
| GET | `/api/v1/compliance/mappings` | 474 Control-Mappings |
### KI-Features
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/ai/status` | LLM Provider Status |
| POST | `/api/v1/compliance/ai/interpret` | Requirement interpretieren |
| POST | `/api/v1/compliance/ai/batch` | Batch-Interpretation |
| POST | `/api/v1/compliance/ai/suggest-controls` | Control-Vorschlaege |
### Scraper & Import
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/compliance/scraper/fetch` | EUR-Lex Live-Fetch |
| POST | `/api/v1/compliance/scraper/extract-pdf` | BSI-TR PDF Extraktion |
| GET | `/api/v1/compliance/scraper/status` | Scraper-Status |
### Evidence & Risks
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/evidence` | Alle Nachweise |
| POST | `/api/v1/compliance/evidence/collect` | CI/CD Evidence Upload |
| GET | `/api/v1/compliance/risks` | Risk Register |
| GET | `/api/v1/compliance/risks/matrix` | Risk Matrix View |
## Datenmodell
### RegulationDB
```python
class RegulationDB(Base):
id: str # UUID
code: str # "GDPR", "AIACT", etc.
name: str # Kurzname
full_name: str # Vollstaendiger Name
regulation_type: enum # eu_regulation, bsi_standard, etc.
source_url: str # EUR-Lex URL
effective_date: date # Inkrafttreten
```
### RequirementDB
```python
class RequirementDB(Base):
id: str # UUID
regulation_id: str # FK zu Regulation
article: str # "Art. 32"
paragraph: str # "(1)(a)"
title: str # Kurztitel
requirement_text: str # Original-Text
breakpilot_interpretation: str # KI-Interpretation
priority: int # 1-5
```
### ControlDB
```python
class ControlDB(Base):
id: str # UUID
control_id: str # "PRIV-001"
domain: enum # gov, priv, iam, crypto, sdlc, ops, ai
control_type: enum # preventive, detective, corrective
title: str # Kontroll-Titel
pass_criteria: str # Messbare Kriterien
code_reference: str # z.B. "middleware/pii_redactor.py:45"
status: enum # pass, partial, fail, planned
```
## Frontend-Integration
### Compliance Dashboard
```
/admin/compliance # Haupt-Dashboard
/admin/compliance/controls # Control Catalogue
/admin/compliance/evidence # Evidence Management
/admin/compliance/risks # Risk Matrix
/admin/compliance/scraper # Regulation Scraper
/admin/compliance/audit-workspace # Audit Workspace
```
### Neue Komponenten (Sprint 1+2)
- `ComplianceTrendChart.tsx` - Recharts-basierter Trend-Chart
- `TrafficLightIndicator.tsx` - Ampel-Status Anzeige
- `LanguageSwitch.tsx` - DE/EN Terminologie-Umschaltung
- `GlossaryTooltip.tsx` - Erklaerungen fuer Fachbegriffe
### i18n-System
```typescript
import { getTerm, Language } from '@/lib/compliance-i18n'
// Nutzung
const label = getTerm('de', 'control') // "Massnahme"
const label = getTerm('en', 'control') // "Control"
```
## Tests
```bash
# Alle Compliance-Tests ausfuehren
cd backend
pytest tests/test_compliance_*.py -v
# Einzelne Test-Dateien
pytest tests/test_compliance_api.py -v # API Endpoints
pytest tests/test_compliance_ai.py -v # KI-Integration
pytest tests/test_compliance_repository.py -v # Repository
pytest tests/test_compliance_pdf_extractor.py -v # PDF Parser
```
## Umgebungsvariablen
```bash
# LLM Provider
COMPLIANCE_LLM_PROVIDER=anthropic # oder "mock" fuer Tests
ANTHROPIC_API_KEY=sk-ant-... # Falls nicht ueber Vault
# Vault Integration
VAULT_ADDR=http://localhost:8200
VAULT_TOKEN=breakpilot-dev-token
# Datenbank
DATABASE_URL=postgresql://user:pass@localhost:5432/breakpilot
```
## Regulations-Uebersicht
| Code | Name | Typ | Requirements |
|------|------|-----|--------------|
| GDPR | DSGVO | EU-Verordnung | ~50 |
| AIACT | AI Act | EU-Verordnung | ~80 |
| CRA | Cyber Resilience Act | EU-Verordnung | ~60 |
| NIS2 | NIS2-Richtlinie | EU-Richtlinie | ~40 |
| DATAACT | Data Act | EU-Verordnung | ~35 |
| DGA | Data Governance Act | EU-Verordnung | ~30 |
| DSA | Digital Services Act | EU-Verordnung | ~25 |
| EUCSA | EU Cybersecurity Act | EU-Verordnung | ~20 |
| EAA | European Accessibility Act | EU-Richtlinie | ~15 |
| BSI-TR-03161-1 | Mobile Anwendungen Teil 1 | BSI-Standard | ~30 |
| BSI-TR-03161-2 | Mobile Anwendungen Teil 2 | BSI-Standard | ~100 |
| BSI-TR-03161-3 | Mobile Anwendungen Teil 3 | BSI-Standard | ~50 |
| ... | 7 weitere | ... | ~50 |
## Control-Domains
| Domain | Beschreibung | Anzahl Controls |
|--------|--------------|-----------------|
| `gov` | Governance & Organisation | 5 |
| `priv` | Datenschutz & Privacy | 7 |
| `iam` | Identity & Access Management | 5 |
| `crypto` | Kryptografie | 4 |
| `sdlc` | Secure Development | 6 |
| `ops` | Betrieb & Monitoring | 5 |
| `ai` | KI-spezifisch | 5 |
| `cra` | CRA & Supply Chain | 4 |
| `aud` | Audit & Nachvollziehbarkeit | 3 |
## Erweiterungen
### Neue Regulation hinzufuegen
1. Eintrag in `data/regulations.py`
2. Requirements ueber Scraper importieren
3. Control-Mappings generieren
```bash
# EUR-Lex Regulation importieren
curl -X POST http://localhost:8000/api/v1/compliance/scraper/fetch \
-H "Content-Type: application/json" \
-d '{"regulation_code": "NEW_REG", "url": "https://eur-lex.europa.eu/..."}'
```
### Neues Control hinzufuegen
1. Eintrag in `data/controls.py`
2. Re-Seed ausfuehren
3. Mappings werden automatisch generiert
## Changelog
### v2.0 (2026-01-17)
- Executive Dashboard mit Ampel-Status
- Trend-Charts (Recharts)
- DE/EN Terminologie-Umschaltung
- 52 API-Endpoints
- 558 Requirements aus 19 Regulations
- 474 Auto-Mappings
- KI-Interpretation (Claude API)
### v1.0 (2026-01-16)
- Basis-Dashboard
- EUR-Lex Scraper
- BSI-TR PDF Parser
- Control Catalogue
- Evidence Management
Reference in New Issue View Git Blame Copy Permalink