breakpilot-compliance/docs-src/services/sdk-modules/freigabe-module.md

Freigabe-Module (Paket 2): Import, Screening, Modules, Quellen

Dieses Paket bringt vier SDK-Module auf Produktionsreife: Document Import (CP-IMP), System Screening (CP-SCR), Service Module Registry (CP-MOD) und RAG/Quellen-Verwaltung (CP-RAG).

---

CP-IMP — Document Import & Gap-Analyse

URL: /sdk/import Backend: backend-compliance:8002/v1/import/... (direkt in main.py registriert)

Endpoints

Methode	Pfad	Beschreibung
POST	/v1/import/analyze	Dokument hochladen, Typ erkennen, Gap-Analyse durchführen
GET	/v1/import/documents	Alle importierten Dokumente eines Tenants
GET	/v1/import/gap-analysis/{document_id}	Gap-Analyse für ein bestimmtes Dokument abrufen

POST /v1/import/analyze

POST /v1/import/analyze
Content-Type: multipart/form-data

file: <binary>
document_type: "OTHER"   # Optional; "OTHER" → automatische Erkennung
tenant_id: "<uuid>"

Response (200):

{
  "document_id": "uuid",
  "filename": "dsfa.pdf",
  "detected_type": "DSFA",
  "confidence": 0.85,
  "extracted_entities": ["DSGVO", "AI Act"],
  "recommendations": ["Risikoklassifizierung ergänzen"],
  "gap_analysis": {
    "id": "analysis-abc123",
    "total_gaps": 2,
    "critical_gaps": 1,
    "high_gaps": 1,
    "medium_gaps": 0,
    "low_gaps": 0,
    "gaps": [...],
    "recommended_packages": ["analyse", "dokumentation"]
  }
}

Unterstützte Dokument-Typen: DSFA, TOM, VVT, PRIVACY_POLICY, AGB, COOKIE_POLICY, RISK_ASSESSMENT, AUDIT_REPORT, OTHER

Erkennung: Keyword-Matching (Fallback) + optionale Klassifikation via LLM (COMPLIANCE_LLM_MODEL).

GET /v1/import/gap-analysis/{document_id}

Gibt die gespeicherte Gap-Analyse für ein zuvor analysiertes Dokument zurück.

Errors:

• 404: Kein Gap-Analyse-Eintrag für document_id im angegebenen Tenant

---

CP-SCR — System Screening (SBOM + Vulnerability Scan)

URL: /sdk/screening Backend: backend-compliance:8002/v1/screening/... (direkt in main.py registriert)

Endpoints

Methode	Pfad	Beschreibung
POST	/v1/screening/scan	Dependency-Datei hochladen, SBOM generieren, CVE-Scan via OSV.dev
GET	/v1/screening/{screening_id}	Scan-Ergebnis abrufen
GET	/v1/screening	Alle Scans eines Tenants auflisten

POST /v1/screening/scan

Unterstützte Dateiformate: package-lock.json, requirements.txt, yarn.lock

POST /v1/screening/scan
Content-Type: multipart/form-data

file: requirements.txt
tenant_id: "<uuid>"

Response (200):

{
  "id": "uuid",
  "status": "completed",
  "sbom_format": "CycloneDX",
  "sbom_version": "1.5",
  "total_components": 47,
  "total_issues": 3,
  "critical_issues": 0,
  "high_issues": 2,
  "medium_issues": 1,
  "low_issues": 0,
  "components": [...],
  "issues": [
    {
      "id": "uuid",
      "severity": "HIGH",
      "title": "Remote Code Execution in lodash",
      "cve": "CVE-2024-0001",
      "cvss": 7.5,
      "affected_component": "lodash",
      "affected_version": "4.17.20",
      "fixed_in": "4.17.21",
      "remediation": "Upgrade lodash to 4.17.21",
      "status": "OPEN"
    }
  ]
}

Errors:

• 400: Datei konnte nicht geparsed werden oder ist kein unterstütztes Format
• 422: Kein File im Request

---

CP-MOD — Service Module Registry

URL: /sdk/modules Backend: backend-compliance:8002/api/compliance/modules/... (via __init__.py registriert)

Endpoints

Methode	Pfad	Beschreibung
GET	/modules	Alle Service-Module auflisten (Filter: service_type, criticality, processes_pii, ai_components)
GET	/modules/overview	Aggregierte Statistiken aller Module
GET	/modules/{module_id}	Modul-Details inkl. Regulierungen und Risiken
POST	/modules/seed	Module aus Stammdaten einspielen
POST	/modules/{module_id}/activate	Modul aktivieren
POST	/modules/{module_id}/deactivate	Modul deaktivieren
POST	/modules/{module_id}/regulations	Regulierungs-Mapping hinzufügen

DB-Migration

# Tabellen anlegen (Migration 031):
ssh macmini "/usr/local/bin/docker exec bp-compliance-backend \
  python3 /app/migrations/run_migration.py 031_modules.sql"

Tabellen:

• compliance_service_modules — Service-Modul-Registry
• compliance_module_regulations — Modul ↔ Regulierungs-Mappings
• compliance_module_risks — Modul-spezifische Risikobewertungen

Detail-Seite

Die Detail-Seite unter /sdk/modules/{moduleId} zeigt:

• Modul-Header: Name, Typ-Badge, Active-Badge, Compliance-Score
• Anforderungen (Requirements)
• Kontrollen (Controls)
• Zugeordnete Regulierungen

---

CP-RAG — Quellen & Regulierungs-Suche

URL: /sdk/rag Backend: ai-compliance-sdk:8090/... (Proxy: /api/sdk/v1/rag/[[...path]])

Endpoints (via AI Compliance SDK)

Methode	Pfad	Beschreibung
GET	/regulations	Alle verfügbaren Regulierungen auflisten
POST	/search	Semantische Suche in Regulierungstexten

POST /search

{
  "query": "Datenschutz-Folgenabschätzung Pflicht",
  "corpus": "bp_dsfa_corpus",
  "top_k": 5
}

Response:

{
  "results": [
    {
      "id": "uuid",
      "text": "Art. 35 DSGVO – Datenschutz-Folgenabschätzung...",
      "score": 0.92,
      "metadata": {
        "source": "DSGVO",
        "article": "Art. 35"
      }
    }
  ]
}

Corpora: bp_dsfa_corpus (alle 16 Bundesländer + BfDI + WP248), weitere via RAG-Ingest-Script.

---

Tests & Verifikation

# Import-Routen (inkl. API-Endpoint-Tests)
cd backend-compliance && python3 -m pytest tests/test_import_routes.py -v

# Screening-Routen (inkl. API-Endpoint-Tests)
cd backend-compliance && python3 -m pytest tests/test_screening_routes.py -v

# Module-Registry
cd backend-compliance && python3 -m pytest tests/test_module_routes.py -v