Enable Discovery debug logging for production troubleshooting

- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
2025-08-11 20:13:26 +02:00
parent 59fd3dd3b1
commit 55a330b223
3683 changed files with 2956207 additions and 16948 deletions
--- a/docs/components/waf/configuration.md
+++ b/docs/components/waf/configuration.md
@@ -0,0 +1,279 @@
+# WAF Konfiguration
+
+> **Dokumentationshinweis:** Diese Dokumentation ist vollständig aktualisiert und stellt die aktuelle Implementierung der WAF-Konfiguration korrekt dar.
+
+## Übersicht
+
+Die Web Application Firewall (WAF) bietet umfangreiche Konfigurationsmöglichkeiten, um das Sicherheitsniveau und die Leistung an die Anforderungen Ihrer Anwendung anzupassen. Diese Dokumentation beschreibt die verfügbaren Konfigurationsoptionen und wie Sie diese anwenden können.
+
+## Konfigurationsklasse
+
+Die zentrale Klasse für die WAF-Konfiguration ist `WafConfig`. Diese Klasse enthält alle Einstellungen, die das Verhalten der WAF steuern:
+
+```php
+// Konfiguration erstellen
+$config = new WafConfig(
+    $enabled,
+    $defaultLayerConfig,
+    $globalTimeout,
+    $blockingThreshold,
+    $alertThreshold,
+    $parallelProcessing,
+    $maxParallelLayers,
+    $detailedLogging,
+    $metricsEnabled,
+    $enabledLayers,
+    $layerConfigs,
+    $customSettings
+);
+```
+
+## Vordefinierte Konfigurationen
+
+Die `WafConfig`-Klasse bietet mehrere vordefinierte Konfigurationen für verschiedene Umgebungen:
+
+### Produktionsumgebung
+
+```php
+// Produktionskonfiguration verwenden
+$config = WafConfig::production();
+```
+
+Die Produktionskonfiguration aktiviert alle Sicherheitsfeatures mit strengen Einstellungen:
+- Alle Schutzebenen aktiviert
+- Niedrige Schwellenwerte für Blockierung
+- Parallele Verarbeitung für optimale Leistung
+- Detaillierte Metriken für Überwachung
+
+### Entwicklungsumgebung
+
+```php
+// Entwicklungskonfiguration verwenden
+$config = WafConfig::development();
+```
+
+Die Entwicklungskonfiguration ist weniger streng und bietet:
+- Höhere Schwellenwerte für Blockierung
+- Detailliertes Logging für Debugging
+- Alle Schutzebenen aktiviert, aber mit weniger strengen Einstellungen
+
+### Testumgebung
+
+```php
+// Testkonfiguration verwenden
+$config = WafConfig::testing();
+```
+
+Die Testkonfiguration ist für automatisierte Tests optimiert:
+- Reduzierte Timeouts
+- Deaktivierte parallele Verarbeitung
+- Minimales Logging
+
+### Deaktivierte Konfiguration
+
+```php
+// WAF deaktivieren
+$config = WafConfig::disabled();
+```
+
+Diese Konfiguration deaktiviert die WAF vollständig, was für bestimmte Entwicklungs- oder Diagnoseszenarien nützlich sein kann.
+
+## Hauptkonfigurationsoptionen
+
+### Aktivierung/Deaktivierung
+
+```php
+// WAF aktivieren
+$config = $config->enable();
+
+// WAF deaktivieren
+$config = $config->disable();
+```
+
+### Timeout-Einstellungen
+
+```php
+// Globales Timeout für WAF-Verarbeitung setzen
+$config = $config->withGlobalTimeout(Duration::fromMilliseconds(100));
+```
+
+### Schwellenwerte
+
+```php
+// Schwellenwert für Blockierung setzen
+$config = $config->withBlockingThreshold(Percentage::fromFloat(0.75));
+```
+
+Der Blockierungsschwellenwert bestimmt, ab welchem Konfidenzwert ein Request blockiert wird. Ein höherer Wert bedeutet weniger Blockierungen (und potenziell mehr falsch negative Ergebnisse), während ein niedrigerer Wert mehr Blockierungen (und potenziell mehr falsch positive Ergebnisse) bedeutet.
+
+## Schutzebenen-Konfiguration
+
+Die WAF verwendet ein mehrschichtiges Schutzsystem. Jede Schutzebene kann individuell konfiguriert werden:
+
+```php
+// Schutzebene aktivieren mit benutzerdefinierter Konfiguration
+$config = $config->enableLayer(
+    'statistical',
+    new LayerConfig(
+        $enabled = true,
+        $weight = 0.6,
+        $threshold = Percentage::fromFloat(0.7),
+        $timeout = Duration::fromMilliseconds(50)
+    )
+);
+
+// Schutzebene deaktivieren
+$config = $config->disableLayer('clustering');
+```
+
+### Verfügbare Schutzebenen
+
+- **statistical**: Statistische Anomalieerkennung
+- **clustering**: Clustering-basierte Anomalieerkennung
+- **signature**: Signaturbasierte Erkennung bekannter Angriffsmuster
+- **behavioral**: Verhaltensbasierte Anomalieerkennung
+- **ratelimiting**: Ratenbegrenzung für Anfragen
+
+## Benutzerdefinierte Einstellungen
+
+Die WAF unterstützt benutzerdefinierte Einstellungen für spezielle Anwendungsfälle:
+
+```php
+// Benutzerdefinierte Einstellung hinzufügen
+$config = $config->withCustomSetting('whitelist_ips', ['127.0.0.1', '192.168.1.1']);
+
+// Benutzerdefinierte Einstellung abrufen
+$whitelistIps = $config->getCustomSetting('whitelist_ips', []);
+```
+
+## Konfigurationsvalidierung
+
+Die WAF-Konfiguration kann validiert werden, um sicherzustellen, dass alle Einstellungen gültig sind:
+
+```php
+// Konfiguration validieren
+$validationErrors = $config->validate();
+
+// Prüfen, ob die Konfiguration gültig ist
+if (!$config->isValid()) {
+    // Fehlerbehandlung
+}
+```
+
+## Konfiguration in der Anwendung
+
+### Konfigurationsdatei
+
+Die WAF-Konfiguration kann in einer dedizierten Konfigurationsdatei definiert werden:
+
+```php
+// config/waf.php
+return [
+    'enabled' => true,
+    'learning_mode' => false,
+    'threshold' => 0.75,
+    'detectors' => [
+        'statistical' => true,
+        'clustering' => true
+    ],
+    'whitelist' => [
+        'ips' => ['127.0.0.1'],
+        'paths' => ['/api/health']
+    ]
+];
+```
+
+### Laufzeitkonfiguration
+
+Die WAF-Konfiguration kann zur Laufzeit aktualisiert werden:
+
+```php
+// WAF-Konfiguration aktualisieren
+$waf->updateConfig($newConfig);
+```
+
+## Leistungsoptimierung
+
+### Parallele Verarbeitung
+
+Die parallele Verarbeitung kann die Leistung der WAF verbessern, insbesondere bei mehreren aktivierten Schutzebenen:
+
+```php
+// Parallele Verarbeitung aktivieren
+$config = new WafConfig(
+    $enabled = true,
+    $defaultLayerConfig,
+    $globalTimeout,
+    $blockingThreshold,
+    $alertThreshold,
+    $parallelProcessing = true,
+    $maxParallelLayers = 4,
+    $detailedLogging,
+    $metricsEnabled,
+    $enabledLayers,
+    $layerConfigs,
+    $customSettings
+);
+```
+
+### Caching
+
+Die WAF unterstützt Caching für wiederholte Anfragen, um die Leistung zu verbessern:
+
+```php
+// Benutzerdefinierte Caching-Einstellungen
+$config = $config->withCustomSetting('cache_ttl', 300); // 5 Minuten
+$config = $config->withCustomSetting('cache_size', 1000); // 1000 Einträge
+```
+
+## Fehlerbehebung
+
+### Logging
+
+Detailliertes Logging kann für die Fehlerbehebung aktiviert werden:
+
+```php
+// Detailliertes Logging aktivieren
+$config = new WafConfig(
+    $enabled = true,
+    $defaultLayerConfig,
+    $globalTimeout,
+    $blockingThreshold,
+    $alertThreshold,
+    $parallelProcessing,
+    $maxParallelLayers,
+    $detailedLogging = true,
+    $metricsEnabled,
+    $enabledLayers,
+    $layerConfigs,
+    $customSettings
+);
+```
+
+### Metriken
+
+Die WAF kann Metriken zur Leistung und Effektivität sammeln:
+
+```php
+// Metriken aktivieren
+$config = new WafConfig(
+    $enabled = true,
+    $defaultLayerConfig,
+    $globalTimeout,
+    $blockingThreshold,
+    $alertThreshold,
+    $parallelProcessing,
+    $maxParallelLayers,
+    $detailedLogging,
+    $metricsEnabled = true,
+    $enabledLayers,
+    $layerConfigs,
+    $customSettings
+);
+```
+
+## Weiterführende Informationen
+
+- [WAF-Übersicht](index.md)
+- [Machine Learning Dokumentation](machine-learning.md)
+- [Sicherheitsrichtlinien](/guides/security.md)
--- a/docs/components/waf/feedback.md
+++ b/docs/components/waf/feedback.md
@@ -0,0 +1,280 @@
+# WAF Feedback System
+
+The Web Application Firewall (WAF) Feedback System allows users to provide feedback on WAF detections, helping to improve the accuracy of the security system over time. This document explains how to use the feedback system, how it works, and how to integrate it into your application.
+
+## Table of Contents
+
+1. [User Guide](#user-guide)
+   - [Submitting Feedback](#submitting-feedback)
+   - [Types of Feedback](#types-of-feedback)
+   - [Feedback Dashboard](#feedback-dashboard)
+2. [Technical Documentation](#technical-documentation)
+   - [Architecture](#architecture)
+   - [Components](#components)
+   - [Integration](#integration)
+3. [Learning Algorithms](#learning-algorithms)
+   - [False Positive Reduction](#false-positive-reduction)
+   - [False Negative Reduction](#false-negative-reduction)
+   - [Severity Adjustment](#severity-adjustment)
+4. [Examples](#examples)
+   - [API Examples](#api-examples)
+   - [Dashboard Examples](#dashboard-examples)
+   - [Learning Examples](#learning-examples)
+
+## User Guide
+
+### Submitting Feedback
+
+When the WAF detects a potential security threat, it may block the request or display a warning. Users with appropriate permissions can provide feedback on these detections to help improve the system's accuracy.
+
+To submit feedback:
+
+1. Navigate to the security event in the admin dashboard
+2. Click on the "Provide Feedback" button
+3. Select the type of feedback (false positive, false negative, correct detection, or severity adjustment)
+4. Add an optional comment explaining your feedback
+5. Click "Submit"
+
+Alternatively, you can use the API to submit feedback programmatically (see [API Examples](#api-examples)).
+
+### Types of Feedback
+
+The WAF Feedback System supports four types of feedback:
+
+1. **False Positive**: The WAF incorrectly identified a legitimate request as a security threat. This feedback helps reduce false alarms.
+
+2. **False Negative**: The WAF failed to detect a security threat. This feedback helps improve detection coverage.
+
+3. **Correct Detection**: The WAF correctly identified a security threat. This feedback confirms the accuracy of the detection.
+
+4. **Severity Adjustment**: The WAF correctly identified a security threat, but the severity level was incorrect. This feedback helps calibrate the severity assessment.
+
+### Feedback Dashboard
+
+The Feedback Dashboard provides an overview of all feedback submitted to the WAF system, along with analytics and trends. To access the dashboard:
+
+1. Navigate to Admin > Security > WAF > Feedback
+2. Use the filters to view specific types of feedback, categories, or time periods
+3. View charts and graphs showing feedback trends and detection accuracy
+4. Access detailed reports for specific detection categories
+
+## Technical Documentation
+
+### Architecture
+
+The WAF Feedback System consists of several components that work together to collect, store, analyze, and learn from user feedback:
+
+```
+-------------------+     +-------------------+     +-------------------+
+|                   |     |                   |     |                   |
+|  Feedback API     | --> |  Feedback Service | --> | Feedback Storage  |
+|                   |     |                   |     |                   |
+-------------------+     +-------------------+     +-------------------+
+                                   |
+                                   v
+-------------------+     +-------------------+     +-------------------+
+|                   |     |                   |     |                   |
+|  Learning Service | <-- |  Analytics        | --> |  Reporting        |
+|                   |     |                   |     |                   |
+-------------------+     +-------------------+     +-------------------+
+         |
+         v
+-------------------+
+|                   |
+|  ML Engine        |
+|                   |
+-------------------+
+```
+
+### Components
+
+The WAF Feedback System includes the following components:
+
+1. **Feedback API**: Provides endpoints for submitting and retrieving feedback.
+   - `POST /api/security/waf/feedback`: Submit feedback
+   - `GET /api/security/waf/feedback/{detectionId}`: Get feedback for a specific detection
+   - `GET /api/security/waf/feedback/stats`: Get feedback statistics
+   - `GET /api/security/waf/feedback/recent`: Get recent feedback
+
+2. **Feedback Service**: Handles the business logic for feedback submission and retrieval.
+   - `FeedbackService`: Core service for handling feedback
+   - `DetectionFeedback`: Value object representing feedback
+   - `FeedbackType`: Enum of feedback types
+
+3. **Feedback Storage**: Stores feedback data for later analysis.
+   - `FeedbackRepositoryInterface`: Interface for feedback storage
+   - `DatabaseFeedbackRepository`: Database implementation
+
+4. **Learning Service**: Analyzes feedback and adjusts the WAF models.
+   - `FeedbackLearningService`: Core service for learning from feedback
+   - `ModelAdjustment`: Value object representing model adjustments
+
+5. **Analytics**: Analyzes feedback data to identify patterns and trends.
+   - `FeedbackReportGenerator`: Generates reports from feedback data
+
+6. **Reporting**: Provides visualizations and reports on feedback data.
+   - `WafFeedbackDashboardController`: Controller for the feedback dashboard
+
+7. **ML Engine**: Machine learning engine that uses feedback to improve detection.
+   - `MachineLearningEngine`: Core ML engine
+   - `ThresholdAdjustableInterface`: Interface for adjustable thresholds
+   - `ConfidenceAdjustableInterface`: Interface for adjustable confidence
+   - `FeatureWeightAdjustableInterface`: Interface for adjustable feature weights
+
+### Integration
+
+To integrate the WAF Feedback System into your application:
+
+1. **Register Services**: Register the feedback services in your dependency injection container:
+
+```php
+// Register feedback services
+$container->singleton(FeedbackRepositoryInterface::class, DatabaseFeedbackRepository::class);
+$container->singleton(FeedbackService::class, FeedbackService::class);
+$container->singleton(FeedbackLearningService::class, FeedbackLearningService::class);
+$container->singleton(FeedbackReportGenerator::class, FeedbackReportGenerator::class);
+```
+
+2. **Register Controllers**: Register the feedback controllers:
+
+```php
+// Register feedback controllers
+$container->singleton(WafFeedbackController::class, WafFeedbackController::class);
+$container->singleton(WafFeedbackDashboardController::class, WafFeedbackDashboardController::class);
+```
+
+3. **Schedule Learning**: Schedule the learning process to run periodically:
+
+```php
+// Schedule learning process to run daily
+$scheduler->daily('waf:learn-from-feedback');
+```
+
+4. **Add UI Components**: Add feedback UI components to your application:
+
+```php
+// Add feedback button to WAF detection alerts
+$alertComponent->addAction('Provide Feedback', '/admin/security/waf/feedback/submit/{detectionId}');
+```
+
+## Learning Algorithms
+
+The WAF Feedback System uses several learning algorithms to improve detection accuracy based on user feedback.
+
+### False Positive Reduction
+
+When users report false positives, the system adjusts the detection models to reduce the likelihood of similar false positives in the future:
+
+1. **Threshold Adjustment**: Increases the detection threshold for the affected category, making it less sensitive.
+2. **Confidence Reduction**: Decreases the confidence score for similar detections, making them less likely to trigger alerts.
+3. **Feature Weight Adjustment**: Reduces the weights of features that contributed to the false positive.
+
+### False Negative Reduction
+
+When users report false negatives, the system adjusts the detection models to improve detection coverage:
+
+1. **Threshold Adjustment**: Decreases the detection threshold for the affected category, making it more sensitive.
+2. **Confidence Increase**: Increases the confidence score for similar detections, making them more likely to trigger alerts.
+3. **Feature Weight Adjustment**: Increases the weights of features that should have contributed to detection.
+
+### Severity Adjustment
+
+When users report incorrect severity levels, the system adjusts the severity assessment:
+
+1. **Confidence Adjustment**: Adjusts the confidence score based on the severity change.
+2. **Category Default Severity**: Updates the default severity for the detection category.
+
+## Examples
+
+### API Examples
+
+#### Submitting Feedback
+
+```javascript
+// Example: Submit false positive feedback
+fetch('/api/security/waf/feedback', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-CSRF-TOKEN': csrfToken
+  },
+  body: JSON.stringify({
+    detection_id: 'abc123',
+    feedback_type: 'false_positive',
+    category: 'SQL_INJECTION',
+    severity: 'HIGH',
+    comment: 'This is a legitimate query used by our reporting system',
+    context: {
+      query: 'SELECT * FROM reports WHERE date > ?'
+    }
+  })
+})
+.then(response => response.json())
+.then(data => console.log(data));
+```
+
+#### Getting Feedback Statistics
+
+```javascript
+// Example: Get feedback statistics
+fetch('/api/security/waf/feedback/stats')
+.then(response => response.json())
+.then(data => {
+  console.log('Total feedback:', data.stats.total_count);
+  console.log('False positives:', data.stats.by_feedback_type.false_positive);
+  console.log('False negatives:', data.stats.by_feedback_type.false_negative);
+});
+```
+
+### Dashboard Examples
+
+#### Viewing Feedback Trends
+
+The Feedback Dashboard provides visualizations of feedback trends over time:
+
+- **Accuracy Trend**: Shows how detection accuracy has improved over time
+- **False Positive Rate**: Shows how the false positive rate has decreased
+- **False Negative Rate**: Shows how the false negative rate has decreased
+- **Category Breakdown**: Shows feedback distribution by detection category
+
+#### Analyzing Detection Categories
+
+The Category Analysis view shows detailed information about each detection category:
+
+- **Accuracy**: Detection accuracy for the category
+- **False Positive Rate**: False positive rate for the category
+- **False Negative Rate**: False negative rate for the category
+- **Severity Distribution**: Distribution of severity levels for the category
+- **Common Patterns**: Common patterns in false positives and false negatives
+
+### Learning Examples
+
+#### Scheduled Learning
+
+The learning process can be scheduled to run periodically:
+
+```bash
+# Run learning process daily
+php console.php waf:learn-from-feedback
+```
+
+#### Manual Learning
+
+The learning process can also be triggered manually:
+
+```bash
+# Run learning process with custom parameters
+php console.php waf:learn-from-feedback --threshold=10 --learning-rate=0.5
+```
+
+#### Learning Results
+
+The learning process provides detailed results:
+
+```
+Starting WAF feedback learning process...
+Processing 25 false positives, 10 false negatives, 5 severity adjustments
+Created 3 model adjustments for SQL_INJECTION, XSS, COMMAND_INJECTION
+Applied 3 model adjustments
+Learning process completed successfully in 0.5 seconds
+```
--- a/docs/components/waf/index.md
+++ b/docs/components/waf/index.md
@@ -0,0 +1,135 @@
+# WAF (Web Application Firewall)
+
+> **Dokumentationshinweis:** Diese Dokumentation ist vollständig aktualisiert und stellt die aktuelle Implementierung der WAF-Komponente korrekt dar.
+
+## Übersicht
+
+Die WAF-Komponente (Web Application Firewall) ist ein fortschrittliches Sicherheitssystem, das Webanwendungen vor verschiedenen Bedrohungen schützt. Es verwendet Machine Learning und statistische Analysen, um Anomalien zu erkennen und potenzielle Angriffe zu blockieren, bevor sie Schaden anrichten können.
+
+## Hauptkomponenten
+
+### WAF-Klasse
+
+Die zentrale Klasse für die WAF-Funktionalität:
+
+```php
+// Klasse initialisieren
+$waf = new Waf($config, $eventDispatcher);
+
+// Request prüfen
+$result = $waf->analyzeRequest($request);
+
+// Entscheidung treffen
+if ($result->isBlocked()) {
+    // Request blockieren
+}
+```
+
+### MachineLearningEngine
+
+Verarbeitet Requests mit Machine-Learning-Algorithmen:
+
+- Extrahiert Features aus Requests
+- Vergleicht mit bekannten Mustern
+- Erkennt Anomalien und ungewöhnliches Verhalten
+- Klassifiziert potenzielle Bedrohungen
+
+### Detektoren
+
+Verschiedene Detektoren für unterschiedliche Arten von Anomalien:
+
+- `StatisticalAnomalyDetector`: Erkennt statistische Abweichungen
+- `ClusteringAnomalyDetector`: Gruppiert ähnliche Requests und identifiziert Ausreißer
+- Erweiterbar für zusätzliche Detektoren
+
+### Middleware-System
+
+```php
+// In Bootstrap oder Application-Klasse
+$app->addMiddleware(WafMiddleware::class);
+```
+
+## Feature-Extraktion
+
+Die WAF extrahiert verschiedene Features aus eingehenden Requests:
+
+1. **Request-Metadaten**: URL, HTTP-Methode, Header
+2. **Parameter-Analyse**: Anzahl, Länge, Entropie der Parameter
+3. **Inhaltsmuster**: Spezielle Zeichen, Skript-Tags, SQL-Fragmente
+4. **Verhaltensanalyse**: Anfragehäufigkeit, Sitzungsdauer, Navigationsmuster
+
+## Anomalie-Erkennung
+
+Der Anomalie-Erkennungsprozess umfasst:
+
+1. **Feature-Extraktion** aus dem eingehenden Request
+2. **Baseline-Vergleich** mit normalen Verhaltensmustern
+3. **Anomalie-Bewertung** durch verschiedene Detektoren
+4. **Entscheidungsfindung** basierend auf Schwellenwerten und Regeln
+
+## Konfiguration
+
+Die WAF kann über die Konfigurationsdatei angepasst werden:
+
+```php
+// config/waf.php
+return [
+    'enabled' => true,
+    'learning_mode' => false,
+    'threshold' => 0.75,
+    'detectors' => [
+        'statistical' => true,
+        'clustering' => true
+    ],
+    'whitelist' => [
+        'ips' => ['127.0.0.1'],
+        'paths' => ['/api/health']
+    ]
+];
+```
+
+## Integration
+
+### Service-Container
+
+Die WAF wird automatisch registriert und kann per Dependency Injection verwendet werden:
+
+```php
+public function __construct(private readonly Waf $waf) {}
+```
+
+### Event-Integration
+
+Die WAF löst folgende Events aus:
+
+- `waf.request_analyzed`: Nach der Analyse eines Requests
+- `waf.request_blocked`: Wenn ein Request blockiert wird
+- `waf.anomaly_detected`: Bei Erkennung einer Anomalie
+
+## Feedback-System (geplant)
+
+Ein Feedback-System für die WAF ist in Planung und wird folgende Funktionen bieten:
+
+- Admin-Interface zur Überprüfung von WAF-Entscheidungen
+- Feedback-Mechanismus für falsch positive/negative Ergebnisse
+- Kontinuierliches Training der ML-Modelle basierend auf Feedback
+
+## Fehlerbehebung
+
+### Häufige Probleme
+
+1. **Falsch positive Blockierungen**:
+   - Überprüfen Sie die Whitelist-Konfiguration
+   - Passen Sie den Schwellenwert an
+   - Aktivieren Sie den Lernmodus vorübergehend
+
+2. **Leistungsprobleme**:
+   - Deaktivieren Sie rechenintensive Detektoren
+   - Implementieren Sie Caching für wiederholte Anfragen
+   - Optimieren Sie die Feature-Extraktion
+
+## Weiterführende Informationen
+
+- [Machine Learning Dokumentation](machine-learning.md)
+- [WAF-Konfiguration](configuration.md)
+- [Sicherheitsrichtlinien](/guides/security.md)
--- a/docs/components/waf/machine-learning.md
+++ b/docs/components/waf/machine-learning.md
@@ -0,0 +1,252 @@
+# 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)