breakpilot-pwa/docs/architecture/devsecops.md

BreakPilot DevSecOps Architecture

Uebersicht

BreakPilot implementiert einen umfassenden DevSecOps-Ansatz mit Security-by-Design fuer die Entwicklung und den Betrieb der Bildungsplattform.

┌─────────────────────────────────────────────────────────────────────────────┐
│                        DEVSECOPS PIPELINE                                    │
│                                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │
│  │  Pre-Commit │───►│  CI/CD      │───►│  Build      │───►│  Deploy     │   │
│  │  Hooks      │    │  Pipeline   │    │  & Scan     │    │  & Monitor  │   │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘   │
│        │                  │                  │                  │           │
│        ▼                  ▼                  ▼                  ▼           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │
│  │ Gitleaks    │    │ Semgrep     │    │ Trivy       │    │ Falco       │   │
│  │ Bandit      │    │ OWASP DC    │    │ Grype       │    │ (optional)  │   │
│  │ Secrets     │    │ SAST/SCA    │    │ SBOM        │    │ Runtime     │   │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

Security Tools Stack

1. Secrets Detection

Tool	Version	Lizenz	Verwendung
Gitleaks	8.18.x	MIT	Pre-commit Hook, CI/CD
detect-secrets	1.4.x	Apache-2.0	Zusaetzliche Baseline-Pruefung

Konfiguration: .gitleaks.toml

# Lokal ausfuehren
gitleaks detect --source . -v

# Pre-commit (automatisch)
gitleaks protect --staged -v

2. Static Application Security Testing (SAST)

Tool	Version	Lizenz	Sprachen
Semgrep	1.52.x	LGPL-2.1	Python, Go, JavaScript, TypeScript
Bandit	1.7.x	Apache-2.0	Python (spezialisiert)

Konfiguration: .semgrep.yml

# Semgrep ausfuehren
semgrep scan --config auto --config .semgrep.yml

# Bandit ausfuehren
bandit -r backend/ -ll

3. Software Composition Analysis (SCA)

Tool	Version	Lizenz	Verwendung
Trivy	0.48.x	Apache-2.0	Filesystem, Container, IaC
Grype	0.74.x	Apache-2.0	Vulnerability Scanning
OWASP Dependency-Check	9.x	Apache-2.0	CVE/NVD Abgleich

Konfiguration: .trivy.yaml

# Filesystem-Scan
trivy fs . --severity HIGH,CRITICAL

# Container-Scan
trivy image breakpilot-pwa-backend:latest

4. SBOM (Software Bill of Materials)

Tool	Version	Lizenz	Formate
Syft	0.100.x	Apache-2.0	CycloneDX, SPDX

# SBOM generieren
syft dir:. -o cyclonedx-json=sbom.json
syft dir:. -o spdx-json=sbom-spdx.json

5. Dynamic Application Security Testing (DAST)

Tool	Version	Lizenz	Verwendung
OWASP ZAP	2.14.x	Apache-2.0	Staging-Scans (nightly)

# ZAP Scan gegen Staging
docker run -t owasp/zap2docker-stable zap-baseline.py \
    -t http://staging.breakpilot.app -r zap-report.html

Pre-Commit Hooks

Die Pre-Commit-Konfiguration (.pre-commit-config.yaml) fuehrt automatisch bei jedem Commit aus:

1. Schnelle Checks (< 10 Sekunden):

   • Gitleaks (Secrets)
   • Trailing Whitespace
   • YAML/JSON Validierung

2. Code Quality (< 30 Sekunden):

   • Black/Ruff (Python Formatting)
   • Go fmt/vet
   • ESLint (JavaScript)

3. Security Checks (< 60 Sekunden):

   • Bandit (Python Security)
   • Semgrep (Error-Severity)

Installation

# Pre-commit installieren
pip install pre-commit

# Hooks aktivieren
pre-commit install

# Alle Checks manuell ausfuehren
pre-commit run --all-files

CI/CD Integration

GitHub Actions Pipeline

# .github/workflows/security.yml
name: Security Scan

on: [push, pull_request]

jobs:
  secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: gitleaks/gitleaks-action@v2

  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: returntocorp/semgrep-action@v1
        with:
          config: >-
            auto
            .semgrep.yml

  sca:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          severity: 'HIGH,CRITICAL'

  sbom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anchore/sbom-action@v0
        with:
          format: cyclonedx-json

Security Reports

Alle Security-Reports werden in security-reports/ gespeichert:

Report	Format	Tool
gitleaks-*.json	JSON	Gitleaks
semgrep-*.json	SARIF/JSON	Semgrep
bandit-*.json	JSON	Bandit
trivy-fs-*.json	JSON	Trivy
trivy-image-*.json	JSON	Trivy
grype-*.json	JSON	Grype
sbom-*.json	CycloneDX	Syft

Security-Scan Script

# Alle Scans ausfuehren
./scripts/security-scan.sh --all

# Nur Secrets-Scan
./scripts/security-scan.sh --secrets

# CI-Modus (Exit bei Critical Findings)
./scripts/security-scan.sh --all --ci

Severity-Gates

Phase	Severity	Aktion
Pre-Commit	ERROR	Commit blockiert
PR/CI	CRITICAL, HIGH	Pipeline blockiert
Nightly Scan	MEDIUM+	Report generiert
Production Deploy	CRITICAL	Deploy blockiert

Compliance

Die DevSecOps-Pipeline unterstuetzt folgende Compliance-Anforderungen:

• DSGVO/GDPR: Automatische Erkennung von PII-Leaks
• OWASP Top 10: SAST/DAST-Scans gegen bekannte Schwachstellen
• Supply Chain Security: SBOM-Generierung fuer Audit-Trails
• CVE Tracking: Automatischer Abgleich mit NVD/CVE-Datenbanken

Dateien

Datei	Beschreibung
.gitleaks.toml	Gitleaks Konfiguration
.semgrep.yml	Semgrep Custom Rules
.trivy.yaml	Trivy Konfiguration
.trivyignore	Trivy Ignore-Liste
.pre-commit-config.yaml	Pre-Commit Hooks
scripts/security-scan.sh	Security-Scan Script

Tool-Installation

macOS (Homebrew)

# Security Tools
brew install gitleaks
brew install trivy
brew install syft
brew install grype

# Python Tools
pip install semgrep bandit pre-commit

Linux (apt/snap)

# Gitleaks
sudo snap install gitleaks

# Trivy
sudo apt-get install trivy

# Python Tools
pip install semgrep bandit pre-commit

Security Dashboard

Das BreakPilot Admin Panel enthaelt ein integriertes Security Dashboard unter Verwaltung > Security.

Features

Fuer Entwickler:

• Scan-Ergebnisse auf einen Blick
• Pre-commit Hook Status
• Quick-Fix Suggestions
• SBOM Viewer mit Suchfunktion

Fuer Security-Experten:

• Vulnerability Severity Distribution (Critical/High/Medium/Low)
• CVE-Tracking mit Fix-Verfuegbarkeit
• Compliance-Status (OWASP Top 10, DSGVO)
• Secrets Detection History

Fuer Ops:

• Container Image Scan Results
• Dependency Update Status
• Security Scan Scheduling
• Auto-Refresh alle 30 Sekunden

API Endpoints

GET  /api/v1/security/tools      - Tool-Status
GET  /api/v1/security/findings   - Alle Findings
GET  /api/v1/security/summary    - Severity-Zusammenfassung
GET  /api/v1/security/sbom       - SBOM-Daten
GET  /api/v1/security/history    - Scan-Historie
GET  /api/v1/security/reports/{tool} - Tool-spezifischer Report
POST /api/v1/security/scan/{type} - Scan starten (secrets/sast/deps/containers/sbom/all)
GET  /api/v1/security/health     - Health-Check

Frontend-Integration

Das Security-Modul ist unter backend/frontend/modules/security.py implementiert und folgt der modularen Studio-Architektur mit:

• SecurityModule.get_css() - Dashboard-Styles
• SecurityModule.get_html() - Panel-Struktur
• SecurityModule.get_js() - Dashboard-Logik

Weiterentwicklung

Geplante Erweiterungen:

1. OPA/Conftest: Policy-as-Code fuer Terraform/Kubernetes
2. Falco: Runtime-Security fuer Kubernetes
3. OWASP ZAP: Automatisierte DAST-Scans
4. Dependency-Track: SBOM-basiertes Vulnerability Management