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`

```bash
# 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`

```bash
# 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`

```bash
# 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 |

```bash
# 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) |

```bash
# 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

```bash
# 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

```yaml
# .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

```bash
# 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)

```bash
# 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)

```bash
# 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