breakpilot-core/docs-src/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
```

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

## 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
GET  /api/v1/security/health     - Health-Check
```

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

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