michaelschiemer/docs/components/waf/machine-learning.md

# WAF Machine Learning

> **Dokumentationshinweis:** Diese Dokumentation ist vollständig aktualisiert und stellt die aktuelle Implementierung der Machine-Learning-Komponente der WAF korrekt dar.

## Übersicht

Die Machine-Learning-Komponente ist das Herzstück des WAF-Systems und ermöglicht die intelligente Erkennung von Bedrohungen und Anomalien in Echtzeit. Sie verwendet fortschrittliche Algorithmen, um normales Verhalten zu lernen und Abweichungen zu identifizieren, die auf potenzielle Angriffe hindeuten könnten.

## MachineLearningEngine

Die `MachineLearningEngine`-Klasse ist die zentrale Komponente des Machine-Learning-Systems:

```php
// Initialisierung
$engine = new MachineLearningEngine(
    $enabled,
    $extractors,
    $detectors,
    $clock,
    $analysisTimeout,
    $confidenceThreshold,
    $enableParallelProcessing,
    $enableFeatureCaching,
    $maxFeaturesPerRequest
);

// Analyse eines Requests
$result = $engine->analyzeRequest($requestData, $context);
```

### Hauptfunktionen

- **Request-Analyse**: Analysiert eingehende Requests auf Anomalien
- **Feature-Extraktion**: Extrahiert relevante Features aus Requests
- **Anomalie-Erkennung**: Identifiziert Abweichungen vom normalen Verhalten
- **Baseline-Management**: Verwaltet und aktualisiert Verhaltensbaselines
- **Modell-Aktualisierung**: Passt Modelle kontinuierlich an neue Daten an
- **Leistungsüberwachung**: Überwacht und optimiert die Leistung des Systems

## Prozessablauf

Der Machine-Learning-Prozess umfasst folgende Schritte:

1. **Feature-Extraktion** (`extractFeatures`):
   - Extrahiert relevante Features aus dem Request
   - Validiert und normalisiert Features
   - Wendet Feature-Caching an, wenn aktiviert

2. **Baseline-Abruf** (`getBaselines`):
   - Ruft relevante Baselines für die extrahierten Features ab
   - Erstellt neue Baselines, wenn keine existieren
   - Verwaltet Baseline-Cache für optimale Leistung

3. **Anomalie-Erkennung** (`detectAnomalies`):
   - Wendet verschiedene Detektoren auf die Features an
   - Vergleicht Features mit Baselines
   - Berechnet Anomalie-Scores und Konfidenzwerte

4. **Konfidenzberechnung** (`calculateOverallConfidence`):
   - Aggregiert Ergebnisse verschiedener Detektoren
   - Berechnet Gesamtkonfidenz basierend auf gewichteten Scores
   - Vergleicht mit Schwellenwert für Entscheidungsfindung

5. **Modell-Aktualisierung** (`updateModels`):
   - Aktualisiert Modelle mit neuen Daten
   - Passt Baselines an sich ändernde Muster an
   - Optimiert Detektoren basierend auf Feedback

## Feature-Extraktion

Die Feature-Extraktion ist ein kritischer Schritt im Machine-Learning-Prozess:

```php
$features = $engine->extractFeatures($requestData, $context);
```

### Feature-Typen

- **Request-Features**: URL-Struktur, Parameter, Header
- **Inhalts-Features**: Payload-Struktur, Entropie, Zeichenverteilung
- **Verhaltens-Features**: Anfragemuster, Sitzungsverhalten, Timing
- **Kontext-Features**: IP-Reputation, Geolocation, Benutzeragent

### Feature-Validierung

Alle extrahierten Features werden validiert, um Qualität und Konsistenz zu gewährleisten:

- Überprüfung auf Vollständigkeit und Gültigkeit
- Normalisierung für konsistente Verarbeitung
- Filterung irrelevanter oder redundanter Features

## Anomalie-Detektoren

Das System verwendet verschiedene Detektoren für unterschiedliche Arten von Anomalien:

### StatisticalAnomalyDetector

Erkennt statistische Abweichungen in numerischen Features:

- Berechnet Z-Scores für numerische Features
- Identifiziert Ausreißer basierend auf statistischen Verteilungen
- Erkennt ungewöhnliche Wertekombinationen

### ClusteringAnomalyDetector

Gruppiert ähnliche Requests und identifiziert Ausreißer:

- Verwendet Clustering-Algorithmen zur Gruppierung ähnlicher Requests
- Berechnet Distanz zu Cluster-Zentren
- Identifiziert isolierte Punkte als potenzielle Anomalien

### Erweiterbarkeit

Das System ist erweiterbar für zusätzliche Detektoren:

```php
// Eigenen Detektor registrieren
$config->registerDetector(new CustomAnomalyDetector());
```

## Baselines

Baselines repräsentieren normales Verhalten und dienen als Referenz für die Anomalie-Erkennung:

### Baseline-Typen

- **Statistische Baselines**: Mittelwerte, Standardabweichungen, Verteilungen
- **Verhaltensbaselines**: Typische Anfragemuster und Sequenzen
- **Inhaltsbaselines**: Normale Payload-Strukturen und Charakteristiken

### Baseline-Management

Baselines werden kontinuierlich aktualisiert und optimiert:

- Automatische Erstellung für neue Feature-Kombinationen
- Regelmäßige Aktualisierung basierend auf neuen Daten
- Gewichtete Historisierung für Stabilität und Aktualität

## Leistungsoptimierung

Die Machine-Learning-Komponente enthält verschiedene Optimierungen:

### Feature-Caching

```php
// Konfiguration
$config->setEnableFeatureCaching(true);
```

Speichert extrahierte Features für ähnliche Requests, um Rechenaufwand zu reduzieren.

### Parallele Verarbeitung

```php
// Konfiguration
$config->setEnableParallelProcessing(true);
```

Verarbeitet Features und Detektoren parallel für verbesserte Leistung.

### Leistungsmetriken

Das System sammelt Leistungsmetriken zur Überwachung und Optimierung:

- Verarbeitungszeiten für verschiedene Phasen
- Feature- und Anomaliezahlen
- Cache-Trefferquoten und Speichernutzung

## Konfiguration

Die Machine-Learning-Komponente bietet umfangreiche Konfigurationsmöglichkeiten:

```php
// config/waf_ml.php
return [
    'enabled' => true,
    'confidence_threshold' => 0.75,
    'analysis_timeout' => 100, // ms
    'enable_parallel_processing' => true,
    'enable_feature_caching' => true,
    'max_features_per_request' => 50,
    'detectors' => [
        'statistical' => [
            'enabled' => true,
            'weight' => 0.6
        ],
        'clustering' => [
            'enabled' => true,
            'weight' => 0.4
        ]
    ]
];
```

## Integration mit WAF

Die Machine-Learning-Komponente ist nahtlos in das WAF-System integriert:

```php
// In WAF-Klasse
public function analyzeRequest(Request $request): WafResult
{
    $requestData = $this->analyzer->analyze($request);
    $mlResult = $this->mlEngine->analyzeRequest($requestData, $this->context);
    
    return new WafResult($requestData, $mlResult);
}
```

## Fehlerbehebung

### Häufige Probleme

1. **Hohe Falsch-Positiv-Rate**:
   - Erhöhen Sie den Konfidenz-Schwellenwert
   - Aktivieren Sie den Lernmodus für einen längeren Zeitraum
   - Überprüfen Sie die Gewichtung der Detektoren

2. **Leistungsprobleme**:
   - Aktivieren Sie Feature-Caching
   - Reduzieren Sie die maximale Anzahl von Features pro Request
   - Optimieren Sie die Detektorkonfiguration

3. **Fehlende Erkennung**:
   - Senken Sie den Konfidenz-Schwellenwert
   - Aktivieren Sie zusätzliche Detektoren
   - Überprüfen Sie die Feature-Extraktion

## Weiterentwicklung

### Geplante Erweiterungen

1. **Feedback-System**:
   - Integration von Administratorfeedback
   - Automatische Anpassung basierend auf Feedback
   - Kontinuierliches Lernen aus Fehlklassifikationen

2. **Erweiterte Detektoren**:
   - Deep-Learning-basierte Anomalieerkennung
   - Sequenzanalyse für komplexe Angriffsmuster
   - Verhaltensbasierte Benutzerprofilierung

3. **Verbesserte Visualisierung**:
   - Dashboard für Anomalietrends
   - Feature-Wichtigkeitsanalyse
   - Echtzeit-Monitoring von Bedrohungen

## Weiterführende Informationen

- [WAF-Übersicht](index.md)
- [WAF-Konfiguration](configuration.md)
- [Sicherheitsrichtlinien](/guides/security.md)