Diese Anfragen erreichen deine Laravel-App bereits. Dein Access-Log zeigt die URL
und den Statuscode — und sonst nichts: nicht den dekodierten Payload, nicht welche deiner
Routen angegriffen wurde, nicht ob dieselbe IP in dieser Stunde vierzig andere Dinge versucht hat.

Dieses Paket beantwortet diese Fragen. Füge es in eine beliebige Laravel-10–13-App ein, und es beginnt,
jede HTTP-Anfrage gegen über 150 Angriffsmuster zu prüfen, jede Übereinstimmung nach
Konfidenz zu bewerten und in deine Datenbank zu schreiben — mit einem integrierten Dashboard, Slack-Benachrichtigungen,
Geo-Anreicherung und fail2ban/Blocklisten-Exporten. Keine Anfrage wird jemals blockiert. Denk an eine
Überwachungskamera, nicht an ein Schloss: Es zeigt dir genau, wer deine Routen auskundschaftet, wie
oft und mit welchen Techniken.

> Aus einer Produktions-App extrahiert und mit echtem Traffic praxiserprobt. 335 Tests, keine Laufzeit-
> Abhängigkeiten über Laravel selbst hinaus, und keine Internetverbindung für die Erkennung erforderlich.
>
> Upgrade? Siehe [UPGRADING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/UPGRADING.md). Mitwirken? Siehe [CONTRIBUTING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/CONTRIBUTING.md).

## In unter einer Minute startklar```bash
composer require jayanta/laravel-threat-detection
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate

---

## Wo es einzuordnen ist: IDS vs. WAF vs. Edge

Dieses Paket ist eine **passive IDS auf Anwendungsebene** – es beobachtet und protokolliert, blockiert aber nicht.
Es ist dafür gedacht, *neben* einer WAF oder einem Edge-Dienst zu sitzen, nicht diese zu ersetzen. Jede Ebene sieht
etwas, das die anderen nicht sehen können:

| | **Dieses Paket** (App-IDS) | **WAF** (mod_security, Cloudflare WAF) | **Edge / CDN** (Cloudflare) |
|---|:---:|:---:|:---:|
| Blockiert bösartige Anfragen | ❌ nur Protokollierung | ✅ | ✅ |
| Vollständiger App-Kontext (exakte Route, dekodierte Payload, authentifizierter Benutzer) | ✅ | ⚠️ teilweise | ❌ |
| Integriertes Dashboard + Bedrohungsprotokoll in Ihrer DB | ✅ | ⚠️ variiert | ⚠️ nur Edge |
| App-spezifische Erkennungen (z. B. Aadhaar / PAN / IFSC PII) | ✅ benutzerdefinierte Muster | ❌ | ❌ |
| Funktioniert offline / ohne externen Dienst | ✅ | ⚠️ abhängig | ❌ |
| Stoppt Traffic, bevor er Ihre App erreicht | ❌ | ✅ Edge | ✅ |
| Einrichtung | ein `composer require` | mittel–hoch | niedrig–mittel |
| Kosten | kostenlos, MIT | variiert | kostenlose Stufe + kostenpflichtig |

**Die Kurzfassung:** Eine Edge/WAF ist Ihr Türschloss; dies ist die Überwachungskamera
*im Inneren*, mit dem App-Kontext, um Ihnen genau zu sagen, was auf welcher Route versucht wird, von
wem und wie oft. Nutzen Sie es, um echte Entscheidungen zu treffen – fail2ban-Sperren, Ratenbegrenzungen,
Geo-Blocking – mit Daten, die Ihre Edge-Ebene nie sieht.

### Was es bewusst NICHT ist

- **Keine WAF.** Es blockiert, filtert oder modifiziert niemals eine Anfrage. Verwenden Sie Cloudflare,
  mod_security oder eine echte WAF für die Durchsetzung. (Keine Edge-Ebene zum Weiterreichen? Die
  [operator-seitigen Helfer](#acting-on-the-data-operator-side-blocking) legen die
  Entscheidungen des Pakets offen, sodass Sie Ihre eigene fünfzeilige Blocking-Middleware schreiben können –
  der Durchsetzungscode bleibt Ihrer, nicht der des Pakets.)
- **Kein Ersatz für sicheres Programmieren.** Parametrisierte Abfragen, Eingabevalidierung und
  Ausgabe-Escaping sind Ihre eigentlichen Verteidigungslinien. Dieses Paket geht davon aus, dass Ihr Code bereits
  sicher ist, und gibt Ihnen *Sichtbarkeit*, keinen Schutz.
- **Kein Edge-Dienst.** Wenn Sie Cloudflare davorstellen können, tun Sie das – und fügen Sie dies dann für die
  Details auf Anwendungsebene hinzu, die Edge-Dienste nicht sehen können.

### Was machen Sie also tatsächlich damit?

Die häufigste Frage zu einem Detektor, der nie blockiert. Vier Antworten, in
aufsteigender Reihenfolge des Aufwands:

| Sie möchten | Verwenden Sie | Aufwand |
|---|---|---|
| Sehen, was Sie trifft | Das [Dashboard](#dashboard) oder `threat-detection:stats` | keiner, es läuft bereits |
| Wiederholungstäter an der Firewall sperren | [`threat-detection:export-fail2ban`](#artisan-commands) – an einen Cron weiterleiten | eine Zeile |
| Auf Webserver-Ebene verweigern | [`threat-detection:export-blocklist`](#artisan-commands) → nginx/apache-Direktiven | eine Zeile |
| Anfragen in der App ablehnen | [Operator-seitige Helfer](#acting-on-the-data-operator-side-blocking) – `isBlocklisted()`, `isDdosThresholdExceeded()` | ~10 Zeilen eigener Middleware |
| In Echtzeit reagieren | Das [`ThreatDetected`-Event](#threatdetected-event) – Telegram, SIEM, PagerDuty | ein Listener |

Das Paket liefert die Intelligenz; Sie liefern die Ablehnung. Diese Trennung ist
bewusst – Durchsetzungscode, der in Ihrer App lebt, ist Code, den Sie lesen,
testen und abschalten können, und das bedeutet, dass ein Erkennungsfehler Ihre Website niemals lahmlegen kann.

### Wie es im Vergleich zu anderen Laravel-Sicherheitspaketen abschneidet

Diese lösen unterschiedliche Probleme und ergänzen sich gut – die Tabelle dient der Auswahl des
richtigen Werkzeugs, nicht dem Gewinnen.

| Paket | Was es tut | Blockiert? | Verwenden Sie es, wenn |
|---|---|:---:|---|
| **dieses Paket** | Scannt jede Anfrage gegen 150+ Muster, protokolliert mit vollem App-Kontext | ❌ | Sie *sehen* möchten, was gegen Ihre App versucht wird |
| `spatie/laravel-honeypot` | Verstecktes Formularfeld, das Spam-Bots abfängt | ✅ nur Formular | Sie öffentliche Formulare haben, die gespammt werden |
| `graham-campbell/security` | Entfernt XSS-ähnliches Markup aus Eingaben | ✅ mutiert | Sie naive Eingabebereinigung möchten |
| `spatie/laravel-csp` | Sendet Content-Security-Policy-Header | ✅ Browser | Sie einschränken möchten, was der Browser lädt |
| `laravel/fortify` + Ratenbegrenzungen | Auth-Drosselung und Sperrung | ✅ | Sie Brute-Force-Schutz beim Login benötigen |
| Cloudflare / mod_security | Edge-WAF, blockiert vor Ihrer App | ✅ | Sie möchten, dass Traffic gestoppt wird, bevor er ankommt |

Die ehrliche Zusammenfassung: Ein Honeypot fängt Formular-Spam, eine WAF blockiert bekannten schlechten Traffic
an der Edge, und CSP schränkt den Browser ein. **Keines davon sagt Ihnen, was ein
Angreifer gegen Ihre spezifischen Routen versucht hat, mit dekodierter Payload und dem
authentifizierten Benutzer.** Diese Lücke füllt dieses Paket – und deshalb blockiert das
Paket bewusst nicht: Sie können es neben allen oben genannten ausführen,
ohne dass sie sich gegenseitig bekämpfen.

---

## Anforderungen

- PHP 8.2+ (Laravel 13 erfordert PHP 8.3+)
- Laravel 10.x, 11.x, 12.x oder 13.x
- Jede von Laravel unterstützte Datenbank (MySQL, PostgreSQL, SQLite, SQL Server)
- Jeder Cache-Treiber – **kein Redis- oder Queue-Worker erforderlich**. Redis/Memcached wird
  nur *empfohlen*, um die optionale DDoS-Prüfung zu aktivieren (die sich bei
  nicht-atomaren Treibern automatisch deaktiviert). Queued-Writes sind optional und standardmäßig deaktiviert.

---

## So funktioniert es

1. Eine Middleware scannt jede eingehende HTTP-Anfrage
2. Die Anfrage wird gegen 158 Regex-Muster geprüft, die SQL-Injection, XSS, RCE, Dateitraversal, SSRF, LDAP, XPath, SSTI und mehr abdecken
3. Wenn ein Bedrohungsmuster übereinstimmt, wird ein Datensatz in Ihre `threat_logs`-Datenbanktabelle geschrieben, mit IP, URL, Bedrohungstyp, Schweregrad und einem Konfidenzwert
4. Optional wird eine Slack-Benachrichtigung für Bedrohungen mit hohem Schweregrad gesendet
5. Die Anfrage wird normal fortgesetzt – **es wird nichts blockiert**

Für die Erkennung ist keine Internetverbindung erforderlich.

---

## Schnellstart

### 1. Das Paket installieren```bash
composer require jayanta/laravel-threat-detection

Dies erstellt zwei Tabellen: `threat_logs` (speichert erkannte Bedrohungen) und `threat_exclusion_rules` (speichert Regeln für Fehlalarme).

**Überprüfen, dass die Tabellen erstellt wurden:**```bash
php artisan migrate:status

> **So überprüfen Sie Ihre Laravel-Version:** Führen Sie `php artisan --version` in Ihrem Terminal aus.

**Wenn Sie Laravel 10 verwenden** – öffnen Sie `app/Http/Kernel.php`:```php
protected $middlewareGroups = [
    'web' => [
        // ... existing middleware
        \JayAnta\ThreatDetection\Http\Middleware\ThreatDetectionMiddleware::class,
    ],
];

Das Paket funktioniert mit sinnvollen Standardeinstellungen. Durch das Veröffentlichen der Konfiguration kannst du Erkennungsmuster, Sensibilitätsmodi, Slack-Benachrichtigungen und mehr anpassen. Wenn du diesen Schritt überspringst, funktioniert trotzdem alles.

**Das war's.** Deine App erkennt jetzt Bedrohungen.

---

## Überprüfen, dass es funktioniert

Nach der Installation löse eine Testbedrohung aus und bestätige, dass sie protokolliert wurde.

### Schritt 1: Starte deine App```bash
php artisan serve

**XSS (Cross-Site Scripting):**```
http://localhost:8000/?q=<script>alert(1)</script>

**RCE (Remote Code Execution):**```
http://localhost:8000/?cmd=system('ls -la')

**Windows-Befehlsinjektion:**```
http://localhost:8000/?cmd=powershell -c whoami

> Verwende eine Route, die in deiner App tatsächlich existiert (wie `/`). Wenn die URL einen 404 zurückgibt, wurde die Middleware möglicherweise nicht ausgeführt.

### Schritt 3: Prüfen, ob Bedrohungen protokolliert wurden

**Option A – Artisan-Befehl (am schnellsten):**```bash
php artisan threat-detection:stats

```php
DB::table('threat_logs')->latest()->take(5)->get(['ip_address', 'type', 'threat_level', 'confidence_score']);

### Wissenswertes beim Testen

| Verhalten | Erklärung |
|----------|-------------|
| Gleiche Bedrohung wird nur einmal pro 5 Minuten protokolliert | Deduplizierung: gleiche IP + gleicher Bedrohungstyp wird 5 Minuten lang zwischengespeichert. Verwenden Sie für jeden Test **verschiedene Angriffstypen** oder warten Sie zwischen den Tests. |
| `curl`-Anfragen lösen zusätzliche Erkennung aus | Die Verwendung von `curl` protokolliert ebenfalls eine „cURL Command“-User-Agent-Erkennung (niedriger Schweregrad). Das ist zu erwarten – das Paket erkennt automatisierte Tools. |
| Das Paket blockiert niemals Anfragen | Ihre Anwendung funktioniert weiterhin normal. Die Erkennung ist passiv. |
| Keine Slack-Einrichtung erforderlich | Benachrichtigungen sind standardmäßig deaktiviert. |
| Keine Internetverbindung erforderlich | Die Kernerkennung erfolgt zu 100 % lokal. Nur der optionale Befehl `threat-detection:enrich` ruft eine externe API für Geodaten auf. |

### Fehlerbehebung

**Beginnen Sie hier – ein Befehl beantwortet das meiste davon:**```bash
php artisan threat-detection:doctor

Was es abdeckt: Erkennung für diese Umgebung aktiviert; jede Spalte, die der
Autor benötigt (eine fehlende verwirft **jede** Bedrohung); Dashboard/API-Spalten; die
Ausschlussregeln-Tabelle; ob die Middleware tatsächlich an eine Route oder
Gruppe angebunden ist; veröffentlichte Konfiguration, die älter als diese Version ist; benutzerdefinierte Muster, die
eingebaute überschatten; einen Cache-Treiber, der kein DDoS-Zählen kann; und ein Dashboard oder
eine API, die ohne Authentifizierung offen gelassen wurde.

**„Ich habe getestet, aber `threat-detection:stats` zeigt null Bedrohungen“ / „Bedrohungen werden nicht in der Datenbank gespeichert“**

Wenn der Doctor bestanden hat, ist die Installation in Ordnung und das Problem liegt an der Testanfrage
selbst. Drei Dinge kann er nicht für dich prüfen:

| Prüfung | So verifizierst du |
|-------|---------------|
| IP ist nicht auf der Whitelist | Wenn du `THREAT_DETECTION_WHITELISTED_IPS` zu `.env` hinzugefügt hast, entferne es während des Tests |
| Eine vorhandene Route verwendet | Die Test-URL muss mit einer echten Route übereinstimmen (z. B. `/`). Ein 404 bedeutet, dass die Middleware nie ausgeführt wurde |
| Dedup-Cache | Gleiche IP + gleicher Angriffstyp wird 5 Minuten lang gecacht – versuche einen anderen Angriffstyp |

> Die alleinige Ausführung von `php artisan migrate` reicht nie aus: Die Migrationsdateien liegen
> im Paket und müssen zuerst in `database/migrations/` deiner App veröffentlicht werden.
> Der Doctor gibt den genauen Befehl aus, wenn dies das Problem ist.

**„API gibt 401 Unauthorized zurück“**

Siehe [API-Authentifizierung](#api-authentication) unten.

**„Dashboard zeigt 404“**

Das Dashboard ist standardmäßig deaktiviert. Füge `THREAT_DETECTION_DASHBOARD=true` zu `.env` hinzu und leere den Routen-Cache:```bash
php artisan route:clear

### Erkennungsmodi

| Modus | Konfidenzschwelle | Verhalten |
|------|---------------------|----------|
| `strict` | 0 (protokolliert alles) | Alle Muster aktiv, niedrigste Schwellenwerte. Erfasst alles, kann aber legitimen Datenverkehr markieren. |
| `balanced` | 10 | Standard. Konfidenzbewertung aktiv, Standard-Schwellenwerte. Gut für die meisten Apps. |
| `relaxed` | 40 | Nur Muster mit hoher Schwere lösen aus. Am besten für inhaltslastige Websites mit häufigen Fehlalarmen. |

### Aktivierte Umgebungen

Standardmäßig läuft die Erkennung in `production`, `staging` und `local`. Um dies zu ändern, veröffentlichen Sie die Konfiguration und bearbeiten Sie:```php
'enabled_environments' => ['production', 'staging', 'local'],

### Config-Referenz

Veröffentlichen Sie die Konfigurationsdatei, um alle verfügbaren Optionen zu sehen:```bash
php artisan vendor:publish --tag=threat-detection-config

Leer lassen (Standard), um alle Routen zu scannen (abhängig von `skip_paths`). Wenn beide konfiguriert sind, wird zuerst `only_paths` geprüft, dann gilt `skip_paths` innerhalb der übereinstimmenden Menge.

### Warteschlangenunterstützung

Standardmäßig erfolgt die Bedrohungsprotokollierung synchron im Anforderungszyklus. Für Anwendungen mit hohem Datenverkehr können Sie DB-Schreibvorgänge und Slack-Benachrichtigungen an eine Warteschlange auslagern:```env
THREAT_DETECTION_QUEUE=true
THREAT_DETECTION_QUEUE_CONNECTION=redis
THREAT_DETECTION_QUEUE_NAME=threat-logs

Erfordert, dass der Scheduler von Laravel ausgeführt wird (`php artisan schedule:run`). Läuft täglich um 02:00 Uhr über `threat-detection:purge`.

### ThreatDetected-Ereignis

Jede bestätigte Bedrohung löst ein `ThreatDetected`-Ereignis aus, auf das Sie hören können:```php
// app/Providers/EventServiceProvider.php
use JayAnta\ThreatDetection\Events\ThreatDetected;

protected $listen = [
    ThreatDetected::class => [
        YourCustomListener::class,
    ],
];

Das Ereignis trägt `$ipAddress`, `$requestCount`, `$threshold` und `$windowSeconds`. Es wird
auf einmal pro IP pro Dedup-Fenster gedrosselt (gleiche Drosselung wie bei der Log-Zeile), sodass eine Flut
deine Listener nicht überwältigen kann. Verwende es für Warnungen oder um einen externen Bann-Speicher zu speisen; um
über dem Schwellenwert liegende Clients zu *verweigern*, verwende stattdessen `ThreatDetection::isDdosThresholdExceeded($ip)` aus deiner eigenen
Middleware — siehe [Handeln auf Basis der Daten](#acting-on-the-data-operator-side-blocking).

---

## Slack-Benachrichtigungen

Slack-Warnungen sind standardmäßig deaktiviert. Zum Aktivieren:```env
THREAT_DETECTION_NOTIFICATIONS=true
THREAT_DETECTION_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
THREAT_DETECTION_SLACK_CHANNEL=#threat-alerts

---

## Dashboard

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12500/fc7950bd0cc6323bcc2d62b03e31c99edc7450b0ef76f9cbfa5133b527b25269.png" alt="Threat Detection Dashboard — Statistiken, 7-Tage-Zeitverlauf, Live-Bedrohungsprotokoll, häufigste angreifende IPs und Bedrohungen nach Land" width="100%">
</p>

Das Paket wird mit einem integrierten Dark-Mode-Dashboard geliefert (Alpine.js + Tailwind CDN – kein Build-Schritt erforderlich).```
+-------------------------------------------------------------------------+
|  Threat Detection Dashboard                                              |
+-------------------------------------------------------------------------+
|  Total: 847  |  High: 23  |  Med: 156  |  Low: 668  |  IPs: 94         |
+-------------------------------------------------------------------------+
|  [Timeline Chart - 7 Day Stacked Bar]                                   |
+-------------------------------------------------------------------------+
|  Search: [___________]  Level: [All]                                    |
|  Time         IP             Type            Level  Confidence  Actions  |
|  Mar 2 14:02  185.220.101.4  SQL Injection   HIGH   80%         [FP]    |
|  Mar 2 13:58  45.33.32.156   XSS Script Tag  HIGH   65%         [FP]    |
|  Mar 2 13:45  192.168.1.10   Scanner: Nikto  MED    35%         [FP]    |
+-------------------------------------------------------------------------+
|  Top IPs              |  Threats by Country                              |
|  185.220.101.4  [23]  |  US  234                                        |
|  45.33.32.156   [18]  |  CN  156                                        |
|  103.152.220.1  [12]  |  RU  98                                         |
+-------------------------------------------------------------------------+

Besuchen Sie: `http://your-app.test/threat-detection`

### Zugang während der lokalen Entwicklung

Das Dashboard verwendet standardmäßig die Middleware `['web', 'auth']`, sodass Benutzer angemeldet sein müssen. Wenn Ihre Anwendung noch keine Authentifizierung hat, beschränken Sie sie stattdessen auf Ihren eigenen Rechner:```env
THREAT_DETECTION_DASHBOARD_GUARD=ip
THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1

**Option 2 – Ändern Sie die Middleware direkt:**```php
// config/threat-detection.php
'api' => [
    'enabled' => true,
    'prefix' => 'api/threat-detection',
    'middleware' => ['api', 'auth'],  // or 'auth:your-guard'
],

> Stellen Sie die Authentifizierung wieder her, bevor Sie in die Produktion bereitstellen.

### Endpunkt-Referenz

| Methode | Endpunkt | Beschreibung |
|---------|----------|--------------|
| GET | `/api/threat-detection/threats` | Bedrohungen auflisten (paginiert, filterbar) |
| GET | `/api/threat-detection/threats/{id}` | Details einer einzelnen Bedrohung |
| POST | `/api/threat-detection/threats/{id}/false-positive` | Bedrohung als Fehlalarm markieren |
| GET | `/api/threat-detection/stats` | Gesamtstatistiken |
| GET | `/api/threat-detection/summary` | Detaillierte Aufschlüsselung nach Typ, Stufe, IP |
| GET | `/api/threat-detection/live-count` | Bedrohungen in der letzten Stunde |
| GET | `/api/threat-detection/by-country` | Nach Land gruppiert |
| GET | `/api/threat-detection/by-cloud-provider` | Nach Cloud-Anbieter gruppiert |
| GET | `/api/threat-detection/top-ips` | Hauptverursachende IPs |
| GET | `/api/threat-detection/timeline` | Bedrohungs-Zeitverlauf (für Diagramme) |
| GET | `/api/threat-detection/ip-stats?ip=x.x.x.x` | Statistiken für eine bestimmte IP |
| GET | `/api/threat-detection/correlation` | Korrelationsanalyse |
| GET | `/api/threat-detection/export` | Als CSV exportieren |
| GET | `/api/threat-detection/exclusion-rules` | Ausschlussregeln auflisten |
| DELETE | `/api/threat-detection/exclusion-rules/{id}` | Eine Ausschlussregel löschen |

### Abfrageparameter für `/threats`

| Parameter | Beschreibung |
|-----------|--------------|
| `keyword` | Suche in IP, URL, Typ |
| `ip` | Nach IP-Adresse filtern |
| `level` | Nach Bedrohungsstufe filtern (`high`, `medium`, `low`) |
| `type` | Nach Bedrohungstyp filtern |
| `country` | Nach Ländercode filtern |
| `is_foreign` | Ausländische IPs filtern (`true`/`false`) |
| `cloud_provider` | Nach Cloud-Anbieter filtern |
| `is_false_positive` | Nach Fehlalarm-Status filtern (`true`/`false`) |
| `date_from` / `date_to` | Datumsbereichsfilter |
| `per_page` | Einträge pro Seite (Standard: 20, max: 100) |

### Beispiel einer API-Antwort

**GET `/api/threat-detection/stats`:**```json
{
  "success": true,
  "data": {
    "total_threats": 847,
    "high_severity": 23,
    "medium_severity": 156,
    "low_severity": 668,
    "unique_ips": 94,
    "foreign_ips": 67,
    "cloud_attacks": 12,
    "today": 34,
    "last_hour": 5
  }
}

const threats = await fetch('/api/threat-detection/threats?per_page=20');
this.threats = await threats.json();

**React:**```jsx
useEffect(() => {
    fetch('/api/threat-detection/stats')
        .then(res => res.json())
        .then(data => setStats(data));
}, []);

---

## Reagieren auf die Daten (Blockierung auf Betreiberseite)

Das Paket blockiert niemals eine Anfrage – das ist seine Identität, kein Standard. Die obigen
Exporte speisen Durchsetzungsebenen, die Sie bereits betreiben (fail2ban, nginx, eine Edge-WAF). Aber einige Bereitstellungen
haben keine solche Ebene, die gespeist werden könnte – Shared Hosting, PaaS, Container hinter einem Load Balancer, den Sie
nicht kontrollieren. Für diese stellt das Paket seine *Entscheidungen* als Helfer bereit, und Sie schreiben die
Durchsetzungs-Middleware selbst. Gleiche Architektur wie die Exporte: **Wir liefern die
Intelligenz, Sie liefern die Verweigerung.**```php
// app/Http/Middleware/EnforceThreatDecisions.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use JayAnta\ThreatDetection\Facades\ThreatDetection;

class EnforceThreatDecisions
{
    public function handle(Request $request, Closure $next)
    {
        $ip = (string) $request->ip();

        // Static operator denylist (config: blocklisted_ips).
        // CIDR supported; whitelisted_ips wins on overlap.
        if (ThreatDetection::isBlocklisted($ip)) {
            abort(403);
        }

        // Volumetric flood: refuse over-threshold clients until the window resets.
        if (ThreatDetection::isDdosThresholdExceeded($ip)) {
            return response('Too Many Requests', 429, [
                'Retry-After' => (string) config('threat-detection.ddos.window', 60),
            ]);
        }

        return $next($request);
    }
}

Die Helfer:

| Helfer | Rückgabe | Unterstützt durch |
|---|---|---|
| `ThreatDetection::isBlocklisted($ip)` | `bool` | `blocklisted_ips`-Konfiguration (CIDR über `IpUtils`; Whitelist gewinnt) |
| `ThreatDetection::isWhitelisted($ip)` | `bool` | `whitelisted_ips`-Konfiguration |
| `ThreatDetection::ddosRequestCount($ip)` | `int` | den Flood-Zähler, den die Erkennungs-Middleware verwaltet |
| `ThreatDetection::isDdosThresholdExceeded($ip)` | `bool` | diesen Zähler im Vergleich zu `ddos.threshold` |

Hinweise:

- **Die Denylist ist statisch und wird vom Betreiber gepflegt.** Nichts im Paket fügt ihr jemals
  etwas hinzu — sie führt dieselbe Entscheidung aus, die ein fail2ban-Jail treffen würde („Ich habe das Dashboard gelesen; dieses /24
  ist feindselig"), nur innerhalb der App.
- Der DDoS-Zähler zählt nur Anfragen, die die Erkennung erreicht haben (`skip_paths`, whitelisted
  IPs und deaktivierte Umgebungen werden nie gezählt) und bleibt bei Cache-Treibern, bei denen die
  DDoS-Erkennung deaktiviert ist (`file`, `database`, `null`), bei 0.
- Wenn ein Client den Schwellenwert überschreitet, wird zusätzlich ein [`DdosThresholdExceeded`-Ereignis](#ddosthresholdexceeded-event)
  ausgelöst — nützlich für Alarmierung oder die Speisung einer externen Bannliste. Rufe jedoch kein `abort()`
  aus dem Listener auf: Listener laufen innerhalb des fail-open
  `try/catch` der Erkennungs-Middleware, daher gehört die Verweigerung wie oben in deine eigene Middleware.

---

## 404-Probe-Verfolgung

Das Paket erkennt Aufklärungs-Probes — Bots, die bekannte verwundbare Pfade wie `/wp-admin`, `/.env` oder `/phpmyadmin` auf deiner Nicht-WordPress-, Nicht-phpMyAdmin-Seite ansteuern. Diese haben keine bösartige Nutzlast; der Pfad selbst ist das Signal.

Protokolliert mit einem `[probe]`-Typtag, getrennt von der nutzlastbasierten Erkennung. Wenn eine Probe-Anfrage auch eine bösartige Nutzlast enthält, werden beide unabhängig voneinander protokolliert.

Standardmäßig mit über 50 Probe-Pfaden aktiviert. Anpassbar in `config/threat-detection.php`:```php
'probe_tracking' => [
    'enabled' => true,
    'default_level' => 'medium',
    'paths' => [
        '/wp-admin' => 'WordPress Admin',
        '/wp-admin/*' => 'WordPress Admin',
        '/.env' => 'Environment File',
        '/phpmyadmin' => 'phpMyAdmin',
        '/actuator/*' => 'Spring Actuator',
        // Add your own probe paths...
    ],
],

Hier sind die hier aufgeführten Felder aus den Query-Parametern und dem Request-Body entfernt – sowohl formularcodiert als auch JSON (`application/json`) – bevor die Erkennung ausgeführt wird. Andere Felder in derselben Anfrage werden weiterhin vollständig gescannt.

### Sichere Pfade (pfadbewusst, für verschachtelte JSON-APIs)

`safe_fields` gleicht einen Schlüsselnamen **überall** ab, wo er vorkommt. Für verschachtelte JSON-APIs ist das oft zu weit gefasst – Sie möchten möglicherweise nur den Wert eines bestimmten Felds ausnehmen, ohne diesen Schlüssel überall auszunehmen. Verwenden Sie `safe_paths`, das über die Punktnotation **Pfade** abgleicht und `fnmatch`-Wildcards unterstützt:```php
// config/threat-detection.php
'safe_paths' => ['search.query', 'filters.*.value'],

Verfügbare Validatoren:

| Validator  | Prüfsumme | Typische Verwendung |
|------------|----------|-------------|
| `verhoeff` | Verhoeff | Aadhaar-Nummern |
| `luhn`     | Luhn     | Kredit-/Debitkartennummern |

Mit der mitgelieferten Zuordnung werden Zeitstempel, Bestell-IDs und Barcodes, die zufällig 12 Ziffern lang sind, nicht mehr als personenbezogene Daten (PII) protokolliert — während echte Aadhaar-Nummern weiterhin erkannt werden. Wenn mehrere Werte übereinstimmen und nur einer die Prüfsumme besteht, wird die Erkennung dennoch ausgelöst: Eine echte Nummer im Rauschen ist immer noch ein Leck.

Kombinieren Sie einen Validator mit Ihrem eigenen Muster für eine prüfsummengesteuerte Kartenerkennung:```php
'custom_patterns'    => ['/\b(?:\d[ -]?){13,19}\b/' => 'Card Number Detected'],
'pattern_validators' => ['Card Number Detected' => 'luhn'],

Die Warnung, der Endpunkt, die Feldnamen und die angreifende IP bleiben erhalten – nur der Wert wird entfernt. Die Schwärzung erfolgt *nach* der Erkennung, sodass nichts übersehen wird.```php
// config/threat-detection.php
'redact' => [
    'enabled' => env('THREAT_DETECTION_REDACT', true),
    'mask'    => '[REDACTED]',
    'labels'  => ['Aadhaar Number Detected', 'PAN Number Detected', /* ... */],
],

Die gleichen Optionen sind für API-Routen mit `THREAT_DETECTION_API_GUARD` verfügbar.

Wenn `guard=none` (Standard) gesetzt ist, protokolliert das Paket einmal pro Tag eine Warnung, um Sie daran zu erinnern, die Authentifizierung zu konfigurieren.

Die Guard **schließt sicher ab**: Ein nicht erkannter Guard-Wert (z. B. ein Tippfehler) wird mit einem 403 und einer protokollierten Warnung verweigert, anstatt stillschweigend Zugriff zu gewähren, und `guard=role` verweigert (mit einer Warnung) den Zugriff, wenn das authentifizierte Benutzermodell keine `hasRole()`-Methode besitzt.

### Das Deaktivieren einer Erkennung erfordert mehr als nur Lesezugriff

Das Markieren einer Bedrohung als Fehlalarm und das Löschen einer Ausschlussregel unterdrücken beide einen Erkennungstyp für alle – eine andere Berechtigung als das Lesen des Protokolls. Diese beiden Endpunkte werden gegen eine separate Guard geprüft:```env
# Options: none, auth, role, ip. Default: role
THREAT_DETECTION_API_WRITE_GUARD=role

**Beispiel – Erkennung einer Sondierung eines benutzerdefinierten Admin-Endpunkts:**```php
'/\/my-admin-panel/i' => 'Custom Admin Panel Probe',

- **`level`** setzt die Bedrohungsstufe direkt fest, anstatt sie aus den `threat_levels`-Schlüsselwörtern im Label abzuleiten.
- **`contexts`** schränkt das Scannen auf bestimmte Anfrageabschnitte ein – z. B. stoppt ein Kartenmuster, das nur im Body sinnvoll ist, das Abgleichen von Ziffernfolgen in Headern.
- **`validator`** benennt eine Inline-Prüfung nach dem Treffer (siehe [Post-Match-Validatoren](#post-match-validators-checksum-aware-false-positive-reduction)); sie hat Vorrang vor der `pattern_validators`-Label-Zuordnung.

String- und Array-Einträge mischen sich frei in derselben Konfiguration. Fehlerhafte Optionen **schlagen offen fehl** – das Muster scannt weiterhin uneingeschränkt, und eine Warnung wird protokolliert –, sodass ein Konfigurationsfehler eine Erkennung niemals stillschweigend deaktivieren oder einschränken kann.

> **Hinweis:** Häufige Probe-Pfade wie `/wp-login.php`, `/.env`, `/phpmyadmin` werden jetzt automatisch von der Funktion [404-Probe-Verfolgung](#404-probe-tracking) behandelt. Dafür sind keine benutzerdefinierten Muster erforderlich.

Die Bedrohungsstufe für jedes Muster wird automatisch bestimmt, indem Schlüsselwörter im Label gegen die `threat_levels`-Konfiguration abgeglichen werden:```php
'threat_levels' => [
    'high' => ['XSS', 'SQL Injection', 'SQL DDL', 'SQL DML', 'SQL File', 'SQL Hex', 'RCE', ..., 'Shellshock', 'Spring4Shell', 'PowerShell', 'CRLF', 'Null Byte', 'SSTI', 'Java', 'LDAP', 'XPath', 'PHP assert', ...],
    'medium' => ['Directory Traversal', 'LFI', 'SSRF', 'Sensitive', 'Config', ..., 'Open Redirect', 'LF Injection', 'GraphQL', 'Spring Boot Actuator', ...],
    'low' => ['User-Agent', 'JS Redirect', 'SEO Bot', 'Empty', 'Rate', 'Command-line Downloader', 'DNS Rebinding'],
],

---

## Übergang in die Produktion

Das Paket ist von Natur aus passiv – es blockiert, lehnt oder verändert niemals eine Anfrage, und die Erkennungs-Middleware umschließt ihren gesamten Körper mit `try/catch`, sodass ein Erkennungsfehler Ihre App niemals zum Absturz bringen kann. Es wird mit sinnvollen Standardeinstellungen ausgeliefert und benötigt keine externen Dienste zum Ausführen. Bevor Sie live gehen, ist diese kurze Checkliste einen Blick wert:

1. **Schützen Sie das Dashboard und die API.** Beide verwenden standardmäßig `guard = none` für einen Erststart ohne Konfiguration und protokollieren eine tägliche Warnung, solange sie ungeschützt sind. Setzen Sie vor der Produktion eine Guard – `THREAT_DETECTION_DASHBOARD_GUARD` und `THREAT_DETECTION_API_GUARD` (`auth`, `role` oder `ip`). Ein nicht erkannter Wert oder eine `role`-Guard bei einem Benutzermodell ohne `hasRole()` schlägt jetzt **fail-closed** (403) fehl, sodass ein Tippfehler keine Daten stillschweigend offenlegt. Das Deaktivieren einer Erkennung wird separat durch `THREAT_DETECTION_API_WRITE_GUARD` gesteuert, das standardmäßig `role` verwendet. Siehe [Dashboard- und API-Authentifizierung](#dashboard-and-api-authentication).
2. **Führen Sie die Migrationen aus** (`vendor:publish --tag=threat-detection-migrations && migrate`). Das erneute Veröffentlichen ist sicher – bereits veröffentlichte Migrationen werden übersprungen.
3. **Wählen Sie einen Erkennungsmodus.** `balanced` (Standard) passt für die meisten Apps; verwenden Sie `relaxed` für inhaltslastige Websites, `strict` für sicherheitskritische Oberflächen. Optimieren Sie mit `content_paths`, `safe_fields` und `min_confidence` – siehe [Reduzierung falsch positiver Ergebnisse](#reducing-false-positives).
4. **Überprüfen Sie die regionalen PII-/benutzerdefinierten Muster.** Die Standardeinstellungen sind Indien-zentriert (Aadhaar, PAN, IFSC), und die breiten numerischen Muster (z. B. Bankkonto) können lange numerische IDs außerhalb von Auth-Routen abgleichen. Ersetzen oder kürzen Sie `custom_patterns` für Ihre Region und App, und fügen Sie inhaltslastige Routen zu `auth_paths` / `content_paths` hinzu.
5. **Aktivieren Sie die Aufbewahrung**, wenn Sie Volumen erwarten: `THREAT_DETECTION_RETENTION=true` (automatische Bereinigung über den Scheduler). Erfordert Laravels Scheduler (`schedule:run`), der per Cron ausgeführt wird.
6. **Optionale Extras, alle standardmäßig deaktiviert:** Slack-Benachrichtigungen (`THREAT_DETECTION_NOTIFICATIONS`), Geo-Anreicherung (`php artisan threat-detection:enrich` – die einzige Funktion, die einen ausgehenden Anruf an das kostenlose ip-api.com tätigt), und in die Warteschlange gestellte Schreibvorgänge (`THREAT_DETECTION_QUEUE` – nur aktivieren, wenn Sie bereits einen Queue-Worker ausführen; andernfalls sind Schreibvorgänge synchron und benötigen kein Redis).

Für die Kernerkennung und -protokollierung sind kein Redis, kein Queue-Worker und keine ausgehenden Netzwerkaufrufe erforderlich.

---

## Reduzierung falsch positiver Ergebnisse

Das Paket bietet mehrere Werkzeuge zur Reduzierung falsch positiver Ergebnisse. Verwenden Sie, was zu Ihrer Situation passt:

### Sichere Felder und sichere Pfade

Schließen Sie ein Feld vollständig von der Überprüfung aus, entweder überall nach Namen (`safe_fields`) oder über Punktnotation für verschachteltes JSON (`safe_paths`). Der einfachste Ansatz und der direkteste – das Feld wird übersprungen, sodass darauf keine Erkennung ausgeführt wird.

Vollständige Details und Beispiele: [Sichere Felder](#safe-fields-false-positive-reduction).

### Unterdrückung von Inhalts-Pfaden

Wenn Sie CMS-Editoren, Blog-Post-Formulare oder Kommentarbereiche haben, in denen Benutzer umfangreiche Inhalte einreichen, lösen diese Pfade oft falsch positive Ergebnisse aus (z. B. ein Blog-Post mit `<script>`-Codebeispielen). Fügen Sie diese Pfade hinzu, um niedrige/mittlere Warnungen zu unterdrücken:```php
// config/threat-detection.php
'content_paths' => [
    'admin/posts/*',
    'admin/pages/*',
    'blog/*/edit',
    'comments',
],

### Konfidenz-Scoring

Jede Bedrohung erhält einen Konfidenz-Score (0-100), basierend auf:
- Anzahl der Pattern-Übereinstimmungen in derselben Anfrage
- Schweregrad des übereinstimmenden Patterns
- Wo das Pattern gefunden wurde (Query-String > Header > Body)
- Ob der User-Agent mit einem bekannten Angriffstool übereinstimmt
- Aktueller Erkennungsmodus

Bedrohungen unterhalb der Konfidenzschwelle für Ihren Erkennungsmodus werden nicht protokolliert (siehe [Erkennungsmodi](#detection-modes)).

---

## Erkannte Angriffstypen

| Kategorie | Beispiele |
|----------|---------|
| **SQL-Injection** | UNION, boolean, time-based, CHAR-Encoding, DDL (DROP/ALTER/CREATE), DML (INSERT/UPDATE/DELETE), Dateioperationen (INTO OUTFILE, LOAD_FILE), ORDER-BY-Enumeration, Hex-Strings, UNHEX |
| **NoSQL-Injection** | MongoDB $ne, $gt, $regex, $where-Operatoren |
| **XSS** | Script-Tags, SVG-Event-Handler (`<svg onload=`), HTML-Event-Handler (`<body onload=`, `<img onerror=`), CSS-Ausdrücke, JavaScript-URIs, DOM-Manipulation |
| **Code-Ausführung** | RCE-Shell-Funktionen, PHP-Deserialisierung, Java-Deserialisierung (base64 + Hex-Magic-Bytes), Template-Injection (Blade, JSP, ASP, Jinja2, Velocity), eval(), base64-Decode, PHP assert(), create_function(), preg_replace /e |
| **SSTI** | Mathematische Sonden (`{{7*7}}`), Jinja2-Import/Config, Velocity-Templates, Expression Language |
| **Befehlsinjektion** | Linux (Shell-Funktionen, Befehlsketten, curl, wget, nc), Windows (cmd.exe, PowerShell, wscript, cscript, net user) |
| **Dateizugriff** | Directory-Traversal, LFI/RFI-Protokolle, Sonden auf sensible Dateien (.env, .git, composer.json) |
| **SSRF** | Localhost (127.0.0.1, 0.0.0.0, ::1), AWS/GCP-Metadaten, private IPs, hex/dezimal kodierter Localhost, DNS-Rebinding (xip.io, nip.io, sslip.io) |
| **LDAP-Injection** | LDAP-Filter-Manipulation, OR-Injection |
| **XPath-Injection** | Attribut-Selektoren, XPath-Funktionen (contains, substring) |
| **CRLF / Header-Injection** | URL-kodiertes CRLF (`%0d%0a`), LF-Injection, Null-Byte-Injection |
| **Protokollangriffe** | HTTP-Request-Smuggling (CL+TE), SSI-Injection |
| **CVE-Exploits** | Shellshock (CVE-2014-6271), Spring4Shell (CVE-2022-22965), PHPUnit-RCE (CVE-2017-9841), Drupalgeddon, Log4Shell |
| **Proben-Tracking** | WordPress (`/wp-admin`, `/wp-login.php`), Konfigurationsdateien (`/.env`, `/.git`), Datenbanktools (`/phpmyadmin`), Technologie-Sonden (`.asp`, `.jsp`), Spring-Actuator, Swagger/API-Dokumentation - 50+ Pfade |
| **Scanner** | SQLMap, Nikto, Nmap, Burp Suite, FeroxBuster, FFUF, XSStrike, Dalfox, Netsparker, Qualys, Nuclei und 20+ weitere (insgesamt 53) |
| **KI-Scraper** | GPTBot, ClaudeBot, ChatGPT, ByteSpider, Cohere, Common Crawl |
| **Headless-Browser** | HeadlessChrome, PhantomJS, Selenium, Puppeteer, Playwright |
| **Bots** | Python-Skripte, Go-HTTP-Clients, cURL, wget, AhrefsBot, SEMRushBot, leere User-Agents |
| **Authentifizierung** | Brute-Force-Erkennung, Token-Leaks, Passwort-Offenlegung, Session-ID-Offenlegung |
| **DDoS** | Ratenbasierte Erkennung übermäßiger Anfragen |
| **Umgehung** | SQL-Kommentar-Einfügung, doppelte URL-Kodierung, HTML-Entity-Kodierung, Unicode-Escapes, IIS-Unicode, Hex-Escapes |
| **Sonstiges** | GraphQL-Introspection, Prototype-Pollution, Open Redirect, XXE, Web-Shells, Krypto-Mining, PII-Erkennung |

---

## Ausführen der Testsuite```bash
composer test