jay123anta/laravel-threat-detectionPassive Laravel-Middleware, die SQL-Injection, XSS, RCE, Bot-Scanner und über 175 Angriffsmuster erkennt und protokolliert. Verfügt über ein integriertes Dashboard, Slack-Benachrichtigungen, REST-API und Geo-Anreicherung. IDS, kein WAF.
<p align="center">
<a href="https://packagist.org/packages/jayanta/laravel-threat-detection"><img src="https://img.shields.io/packagist/v/jayanta/laravel-threat-detection.svg?style=flat-square" alt="Latest Version"></a>
<a href="https://github.com/jay123anta/laravel-threat-detection/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/jay123anta/laravel-threat-detection/tests.yml?branch=main&style=flat-square&label=tests" alt="Tests"></a>
<a href="https://github.com/jay123anta/laravel-threat-detection/actions/workflows/tests.yml"><img src="https://img.shields.io/badge/PHPStan-level%205-brightgreen?style=flat-square" alt="PHPStan Level 5"></a>
<a href="https://github.com/jay123anta/laravel-threat-detection/actions/workflows/tests.yml"><img src="https://img.shields.io/badge/code%20style-Pint-orange?style=flat-square" alt="Code Style Pint"></a>
<a href="https://packagist.org/packages/jayanta/laravel-threat-detection"><img src="https://img.shields.io/packagist/dt/jayanta/laravel-threat-detection.svg?style=flat-square" alt="Total Downloads"></a>
<a href="https://packagist.org/packages/jayanta/laravel-threat-detection"><img src="https://img.shields.io/packagist/php-v/jayanta/laravel-threat-detection?style=flat-square" alt="PHP Version"></a>
<a href="https://github.com/jay123anta/laravel-threat-detection/blob/main/LICENSE"><img src="https://img.shields.io/packagist/l/jayanta/laravel-threat-detection.svg?style=flat-square" alt="License"></a>
</p>
# Laravel Threat Detection
**Sicherheitsüberwachung und Angriffsprotokollierung für Laravel. Erkennt und protokolliert SQL-Injection,
XSS, RCE, Directory Traversal, Bot-Scanner und `/wp-admin`-artige Recon-Probes —
jede feindliche Anfrage wird mit vollständigem Anwendungskontext in deiner Datenbank aufgezeichnet.
Es ist ein IDS, kein WAF: Es blockiert, filtert oder verändert niemals eine Anfrage.**
<p align="center">
<img src="https://raw.githubusercontent.com/jay123anta/laravel-threat-detection/main/art/demo.gif" alt="Installiere das Paket, sende drei Angriffe — SQL-Injection, Directory Traversal, XSS — jeder gibt HTTP 200 zurück, weil nichts blockiert wird, und alle drei sind bereits in threat-detection:stats gezählt" width="100%">
</p>
### Bist du hier, weil du so etwas gesehen hast?
```
GET /wp-admin/setup-config.php 404 — on a site that isn't WordPress
GET /.env 404 — someone wants your database password
GET /?id=1' UNION SELECT password FROM 200 — SQL injection against a real route
GET /phpmyadmin/index.php 404 — scanning for an admin panel
```
Diese Anfragen erreichen deine Laravel-App bereits. Dein Access-Log zeigt die URL
und den Statuscode, und sonst nichts — nicht die dekodierte Payload, nicht welche deiner
Routen angegriffen wurde, nicht ob dieselbe IP in dieser Stunde schon vierzig andere Dinge versucht hat.
Dieses Paket beantwortet diese Fragen. Integriere es in jede Laravel-10–13-App und es beginnt
jede HTTP-Anfrage gegen 150+ Angriffsmuster zu prüfen, jeden Treffer nach
Konfidenz zu bewerten und in deine Datenbank zu schreiben — mit integriertem Dashboard, Slack-Alerts,
Geo-Anreicherung und fail2ban/Blocklist-Exporten. Keine Anfrage wird jemals blockiert. Denk an
eine Überwachungskamera, nicht an ein Schloss: Sie zeigt dir genau, wer deine Routen sondiert, wie
oft und mit welchen Techniken.
> Aus einer Produktions-App extrahiert und im echten Traffic erprobt. 2.400+ Tests, keine Laufzeit-
> Abhängigkeiten außer Laravel selbst 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
```
Dann füge die Middleware zu deiner `web`-Gruppe hinzu (eine Zeile in `bootstrap/app.php` unter Laravel 11+,
oder `app/Http/Kernel.php` unter Laravel 10) — vollständiger Ausschnitt in [Quick Start](#quick-start) unten.
Das war's; die Erkennung ist aktiv.
```bash
php artisan threat-detection:doctor # confirms it is actually recording
```
---
## Wo es einzuordnen ist: IDS vs. WAF vs. Edge
Dieses Paket ist ein **passives IDS auf Anwendungsebene** — es beobachtet und protokolliert, es
blockiert nicht. Es ist dafür gedacht, *neben* einer WAF oder einem Edge-Dienst zu stehen, nicht einen zu ersetzen. Jede Schicht sieht
etwas, das die anderen nicht sehen können:
| | **Dieses Paket** (App-IDS) | **WAF** (ModSecurity + OWASP CRS, Cloudflare WAF) | **Edge / CDN** (Cloudflare) |
|---|:---:|:---:|:---:|
| Blockiert bösartige Anfragen | ❌ nur Protokollierung | ✅ | ✅ |
| Voller App-Kontext (exakte URL, dekodierte Payload, authentifizierter Benutzer) | ✅ | ⚠️ teilweise | ❌ |
| Integriertes Dashboard + Bedrohungsprotokoll in deiner DB | ✅ | ⚠️ variiert | ⚠️ nur Edge |
| App-spezifische Erkennungen (z. B. Aadhaar / PAN / IFSC PII) | ✅ integriert + benutzerdefiniert | ⚠️ eigene Regeln schreiben | ⚠️ benutzerdefinierte Regeln, planabhängig |
| Funktioniert offline / kein externer Dienst | ✅ | ⚠️ abhängig | ❌ |
| Stoppt Traffic, bevor er deinen Server erreicht | ❌ | ⚠️ nur Cloud-WAF | ✅ |
| Einrichtung | `composer require`, migrieren, eine Middleware-Zeile | mittel–hoch | niedrig–mittel |
| Kosten | kostenlos, MIT | variiert | kostenlose Stufe + kostenpflichtig |
**Die Kurzfassung:** Ein Edge/WAF ist dein Schloss an der Tür; dies ist die Überwachungskamera
*im Inneren*, mit dem App-Kontext, um dir genau zu sagen, was auf welcher Route versucht wird, von
wem und wie oft. Nutze es, um echte Entscheidungen zu speisen — fail2ban-Bans, Rate Limits,
Geo-Blocking — mit Daten, die deine Edge-Schicht nie sieht.
### Was es bewusst NICHT ist
- **Keine WAF.** Es blockiert, filtert oder verändert niemals eine Anfrage. Nutze Cloudflare,
mod_security oder eine echte WAF zur Durchsetzung. (Keine Edge-Schicht zum Weiterreichen? Die
[betreiberseitigen Helfer](#acting-on-the-data-operator-side-blocking) legen die
Entscheidungen des Pakets offen, sodass du deine eigene fünfzeilige Blocking-Middleware schreiben kannst —
der Durchsetzungscode bleibt deiner, nicht der des Pakets.)
- **Kein Ersatz für sicheres Programmieren.** Parametrisierte Abfragen, Eingabevalidierung und
Output-Escaping sind deine eigentlichen Verteidigungen. Dieses Paket geht davon aus, dass dein Code bereits
sicher ist, und gibt dir *Sichtbarkeit*, keinen Schutz.
- **Kein Edge-Dienst.** Wenn du Cloudflare davor setzen kannst, tu es — und füge dann dies für die
Details auf Anwendungsebene hinzu, die Edge-Dienste nicht sehen können.
- **Kein vollständiger Detektor, und das kann es nicht sein.** Musterabgleich fängt Angriffe ab, die
*wie* bekannte Angriffe *aussehen*. Eine neuartige Technik oder eine bekannte, ausreichend umgeschriebene, wird
unprotokolliert durchkommen — und dir wird nicht gesagt, dass sie es tat. Stille hier bedeutet
„nichts hat gepasst", niemals „nichts ist passiert". Wo es seinen Platz verdient, ist der
hochvolumige, aufwandsarme Traffic, der den Großteil dessen ausmacht, was tatsächlich eine öffentliche
Laravel-App trifft: Scanner, Recon-Sonden, Standard-Injection-Strings, Credential-
Sprays. Behandle ein ruhiges Protokoll als Abwesenheit von Beweisen, nicht als Beweis für Abwesenheit.
### Rechne damit, dass es am ersten Tag deine eigenen Inhalte markiert
Eine ungetunte Installation schlägt bei legitimen Inhalten an, und du solltest das wissen, bevor
du installierst, nicht danach. Diese sind gemessen, nicht hypothetisch. Die Zeilen
unten sind eine Stichprobe des Bodensatzes, der von
[`LegitimateTrafficCorpusTest`](https://github.com/jay123anta/laravel-threat-detection/blob/main/tests/Feature/LegitimateTrafficCorpusTest.php) festgelegt wird;
jede listet *alles* auf, was diese Anfrage protokolliert, und
[`ReadmeNoiseFloorTest`](https://github.com/jay123anta/laravel-threat-detection/blob/main/tests/Feature/ReadmeNoiseFloorTest.php) lässt den
Build fehlschlagen, wenn eine Zeile aufhört, dem zu entsprechen, was die Suite für sie misst.
<!-- noise-floor:start -->
| Vollkommen legitime Anfrage | Was eine ungetunte Installation protokolliert |
|---|---|
| `how to write a UNION SELECT in postgres` in ein Suchfeld eingegeben <!-- case: sql tutorial in a search box --> | `SQL Injection UNION` / high |
| Ein Blogbeitrag, der `<script>window.dataLayer=[];</script>` enthält <!-- case: javascript snippet in a blog post --> | `XSS Script Tag` / high · `Command Chain Injection` / medium |
| Ein Support-Ticket mit einem eingefügten `SELECT * FROM users WHERE id = 1`-Fehler <!-- case: a pasted sql error in a support ticket --> | `SQLi Variant` / high · `SQL SELECT Query` / low |
| Dokumentation, die erklärt, dass `../../etc/passwd` die klassische Traversal-Payload ist <!-- case: a traversal explainer in documentation --> | `Directory Traversal` / medium · `Sensitive File Access` / medium |
| Ein Profilformular, das eine echte indische Mobilfunknummer und PAN erfasst <!-- case: a profile form collecting genuine indian pii --> | `PAN Number Detected` / high · `Bank Account Number Detected` / high · `Mobile Number Detected` / low |
<!-- noise-floor:end -->
**Nichts davon sind Bugs.** Ein Blogbeitrag, der `<script>` enthält, ist Byte für Byte eine
Stored-XSS-Payload; eine Suche nach `UNION SELECT` ist nicht von einem Versuch
dazu zu unterscheiden; eine zehnstellige Mobilfunknummer ist auch eine plausible Bankkontonummer. Nichts
außer dem Anwendungskontext trennt sie, und keine Muster-Engine kann diesen
Kontext für dich liefern.
Ihn zu liefern ist eine einzeilige Konfigurationsänderung: Benenne das Feld, das legitim solche
Inhalte trägt, in `safe_fields` (oder `safe_paths`, für einen Pfad innerhalb verschachtelten JSONs) und
es wird nicht mehr gescannt. Das ist der Schalter, der die obigen Zeilen stumm schaltet — und es ist
ein echter Kompromiss, da ein Angriff, der über dieses Feld geliefert wird, ebenfalls ungesehen bleibt.
`content_paths` und der `relaxed`-Modus sind andere Werkzeuge. Sie verwerfen Rauschen mit niedriger und
mittlerer Schwere und **zeichnen bewusst weiterhin Treffer mit hoher Schwere auf** —
sie werden also die hohen Zeilen in dieser Tabelle nicht beruhigen, per Design. Siehe
[False Positives reduzieren](#reducing-false-positives), um zu erfahren, wann du zu welchem greifen solltest.
**Wenn deine App Rich Text, Codebeispiele oder Suchanfragen akzeptiert, tu das, bevor du
die Ausgabe beurteilst.** Der Standard ist bewusst rauschig-aber-ehrlich statt
still-und-unvollständig: Es ist einfacher, einen bekannten Treffer stumm zu schalten, als einen zu entdecken, der
nie ausgelöst hat.
### Also, was machst du eigentlich damit?
Die häufigste Frage zu einem Detektor, der nie blockiert. Vier Antworten, in
zunehmender Reihenfolge des Aufwands:
| Du willst | Nutze | Aufwand |
|---|---|---|
| Sehen, was dich trifft | Das [Dashboard](#dashboard) oder `threat-detection:stats` | keiner, es läuft bereits |
| Wiederholungstäter an der Firewall bannen | [`threat-detection:export-fail2ban`](#artisan-commands) — an einen Cron weiterleiten | eine Zeile |
| Am Webserver verweigern | [`threat-detection:export-blocklist`](#artisan-commands) → nginx/apache-Direktiven | eine Zeile |
| Anfragen in der App ablehnen | [Betreiberseitige Helfer](#acting-on-the-data-operator-side-blocking) — `isBlocklisted()`, `isDdosThresholdExceeded()` | ~10 Zeilen deiner eigenen Middleware |
| In Echtzeit reagieren | Das [`ThreatDetected`-Event](#threatdetected-event) — Telegram, SIEM, PagerDuty | ein Listener |
Das Paket liefert die Intelligenz; du lieferst die Ablehnung. Diese Aufteilung ist
bewusst — Durchsetzungscode, der in deiner App lebt, ist Code, den du lesen,
testen und abschalten kannst, und es bedeutet, dass ein Erkennungsfehler niemals deine Seite lahmlegen kann.
### Wie es sich mit anderen Laravel-Sicherheitspaketen vergleicht
Diese lösen unterschiedliche Probleme und ergänzen sich gut — die Tabelle geht darum, das
richtige Werkzeug zu wählen, nicht darum zu gewinnen.
| Paket | Was es tut | Blockiert? | Nutze es, wenn |
|---|---|:---:|---|
| **dieses Paket** | Scannt jede Anfrage gegen 150+ Muster, protokolliert mit vollem App-Kontext | ❌ | Du *sehen* willst, was auf deiner App versucht wird |
| `spatie/laravel-honeypot` | Verstecktes Formularfeld, das Spam-Bots fängt | ✅ nur Formular | Du öffentliche Formulare hast, die zugespammt werden |
| `graham-campbell/security` | Entfernt XSS-artiges Markup aus der Eingabe | ✅ verändert | Du naive Eingabebereinigung willst |
| `spatie/laravel-csp` | Sendet Content-Security-Policy-Header | ✅ Browser | Du einschränken willst, was der Browser lädt |
| `laravel/fortify` + Rate Limits | Auth-Drosselung und Sperrung | ✅ | Du Brute-Force-Schutz beim Login brauchst |
| Cloudflare / mod_security | Edge-WAF, blockiert bevor deine App erreicht wird | ✅ | Du Traffic gestoppt haben willst, bevor er ankommt |
Die ehrliche Zusammenfassung: Ein Honeypot fängt Formular-Spam, eine WAF blockiert bekannt-bösartigen Traffic
am Edge, und CSP schränkt den Browser ein. **Keines davon sagt dir, was ein
Angreifer gegen deine spezifischen Routen versucht hat, mit dekodierter Payload und angehängtem
authentifizierten Benutzer.** Diese Lücke ist es, was dies füllt — und deshalb
blockiert das Paket bewusst nicht: Du kannst es neben all dem oben genannten betreiben,
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). Gepufferte Schreibvorgänge sind optional und standardmäßig aus.
---
## Wie es funktioniert
1. Eine Middleware scannt jede eingehende HTTP-Anfrage
2. Die Anfrage wird gegen 158 Regex-Muster geprüft, die SQL-Injection, XSS, RCE, File Traversal, SSRF, LDAP, XPath, SSTI und mehr abdecken
3. Wenn ein Bedrohungsmuster passt, wird ein Datensatz in deine `threat_logs`-Datenbanktabelle geschrieben mit der IP, URL, dem Bedrohungstyp, dem Schweregrad und einem Konfidenzwert
4. Optional wird ein Slack-Alarm für Bedrohungen mit hohem Schweregrad gesendet
5. Die Anfrage läuft normal weiter - **nichts wird blockiert**
Für die Erkennung ist keine Internetverbindung erforderlich.
---
## Schnellstart
### 1. Das Paket installieren
```bash
composer require jayanta/laravel-threat-detection
```
### 2. Migrationen veröffentlichen und ausführen
> **Dieser Schritt ist erforderlich.** Ohne ihn erkennt das Paket Bedrohungen, kann sie aber nicht in der Datenbank speichern. Wenn Sie diesen Schritt überspringen, existiert Ihre `threat_logs`-Tabelle nicht und alle Erkennungen gehen stillschweigend verloren (Sie sehen Fehler nur in `storage/logs/laravel.log`).
```bash
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate
```
Dies erstellt zwei Tabellen: `threat_logs` (speichert erkannte Bedrohungen) und `threat_exclusion_rules` (speichert Regeln für falsch-positive Ergebnisse).
**Überprüfen, ob die Tabellen erstellt wurden:**
```bash
php artisan migrate:status
```
Suche nach `create_threat_logs_table`, `add_confidence_to_threat_logs_table` und `create_threat_exclusion_rules_table` – alle sollten `Ran` anzeigen.
### 3. Die Middleware registrieren
Die Middleware ist das, was Anfragen scannt. Du musst sie zu deiner `web`-Middleware-Gruppe hinzufügen.
**Wenn du Laravel 11 oder 12 verwendest** – öffne `bootstrap/app.php`:
```php
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
\JayAnta\ThreatDetection\Http\Middleware\ThreatDetectionMiddleware::class,
]);
})
```
> **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,
],
];
```
### 4. (Optional) Die Konfigurationsdatei veröffentlichen
```bash
php artisan vendor:publish --tag=threat-detection-config
```
Das Paket funktioniert mit sinnvollen Standardeinstellungen. Durch das Veröffentlichen der Konfiguration kannst du Erkennungsmuster, Empfindlichkeitsmodi, Slack-Benachrichtigungen und mehr anpassen. Wenn du diesen Schritt überspringst, funktioniert trotzdem alles.
**Das war's.** Deine App erkennt jetzt Bedrohungen.
---
## Überprüfen, ob es funktioniert
Löse nach der Installation eine Testbedrohung aus und bestätige, dass sie protokolliert wurde.
### Schritt 1: Starte deine App
```bash
php artisan serve
```
### Schritt 2: Öffnen Sie eine Test-URL in Ihrem Browser
Hängen Sie einen bösartigen Query-Parameter an **eine beliebige vorhandene Route** in Ihrer App an (Ihre Startseite, eine Produktseite usw.). Zum Beispiel:
**SQL-Injection:**
```
http://localhost:8000/?q=' UNION SELECT * FROM users--
```
**XSS (Cross-Site Scripting):**
```
http://localhost:8000/?q=<script>alert(1)</script>
```
**Directory Traversal:**
```
http://localhost:8000/?file=../../etc/passwd
```
**RCE (Remote Code Execution):**
```
http://localhost:8000/?cmd=system('ls -la')
```
**Shellshock (CVE-2014-6271):**
```
http://localhost:8000/?cmd=() { :;}; /bin/bash
```
**Windows-Befehlsinjektion:**
```
http://localhost:8000/?cmd=powershell -c whoami
```
**DROP TABLE (SQL DDL):**
```
http://localhost:8000/?q=DROP TABLE users
```
> Verwende eine Route, die tatsächlich in deiner App 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
```
Sie sollten eine Tabelle mit `Recorded Detections`, Schweregrad-Zählungen und den
Top-IPs sehen. Diese Zahl zählt *Zeilen*, nicht Versuche: Eine Detection wird
einmal pro IP pro Bedrohungstyp pro fünf Minuten geschrieben, und Wiederholungen
innerhalb dieses Fensters werden dedupliziert statt erneut gezählt.
**Option B - Tinker:**
```bash
php artisan tinker
```
```php
DB::table('threat_logs')->latest()->take(5)->get(['ip_address', 'type', 'threat_level', 'confidence_score']);
```
**Option C – Laravel-Protokolldatei:**
Jede erkannte Bedrohung wird als Warnung in `storage/logs/laravel.log` geschrieben:
```
[high] Threat Detected: [middleware] SQL Injection UNION from 127.0.0.1 (http://localhost:8000/?q=...) [confidence: 50%]
```
### Wichtiges beim Testen
| Verhalten | Erklärung |
|----------|-------------|
| Dieselbe Bedrohung wird nur einmal pro 5 Minuten protokolliert | Deduplizierung: Dieselbe IP + derselbe Bedrohungstyp wird 5 Minuten lang zwischengespeichert. Verwenden Sie **unterschiedliche Angriffstypen** für jeden Test oder warten Sie zwischen den Tests. |
| `curl`-Anfragen lösen eine zusätzliche Erkennung aus | Die Verwendung von `curl` protokolliert auch eine User-Agent-Erkennung für „cURL Command" (geringe Schwere). Dies ist zu erwarten – das Paket erkennt automatisierte Tools. |
| Das Paket blockiert niemals Anfragen | Ihre App funktioniert weiterhin normal. Die Erkennung ist passiv. |
| Keine Slack-Einrichtung erforderlich | Benachrichtigungen sind standardmäßig deaktiviert. |
| Keine Internetverbindung erforderlich | Die Kernerkennung ist zu 100 % lokal. Nur der optionale Befehl `threat-detection:enrich` ruft eine externe API für Geodaten auf. |
### Fehlerbehebung
**Hier beginnen – ein Befehl beantwortet das meiste davon:**
```bash
php artisan threat-detection:doctor
```
Es prüft die Dinge, die dazu führen, dass die Erkennung *stillschweigend* fehlschlägt – wo das Dashboard leer bleibt, was identisch mit „keine Angriffe“ aussieht – und gibt für jedes Problem die exakte Lösung aus. Bei einem echten Fehler beendet es sich mit einem von Null verschiedenen Exit-Code, sodass es sicher in CI oder einem Deploy-Schritt ausgeführt werden kann.
```
Threat Detection — health check
PASS Detection is enabled for this environment
FAIL 'threat_logs' is missing confidence_label — EVERY threat is being discarded
Run: php artisan vendor:publish --tag=threat-detection-migrations && php artisan migrate
WARN 1 custom pattern(s) shadow a built-in: Localhost SSRF
Your copy runs instead of the maintained one, so later fixes to it never reach you.
```
Was es abdeckt: die für diese Umgebung aktivierte Erkennung; jede Spalte, die der Writer
benötigt (eine fehlende verwirft **jede** Bedrohung); Dashboard-/API-Spalten; die
Ausschlussregel-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
integrierte überschreiben; einen Cache-Treiber, der kein DDoS-Zählen durchführen 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 wurde, ist die Installation in Ordnung und das Problem liegt in der Testanfrage
selbst. Drei Dinge kann er nicht für Sie prüfen:
| Prüfung | So überprüfen |
|-------|---------------|
| IP ist nicht auf der Whitelist | Wenn Sie `THREAT_DETECTION_WHITELISTED_IPS` zu `.env` hinzugefügt haben, entfernen Sie 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 zwischengespeichert – versuchen Sie einen anderen Angriffstyp |
> Nur `php artisan migrate` auszuführen ist nie ausreichend: Die Migrationsdateien liegen
> innerhalb des Pakets und müssen zuerst in das `database/migrations/`-Verzeichnis Ihrer 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ügen Sie `THREAT_DETECTION_DASHBOARD=true` zu `.env` hinzu und leeren Sie den Route-Cache:
```bash
php artisan route:clear
```
---
## Funktionen
- **Über 150 Erkennungsmuster** – SQL-Injection (UNION, DDL, DML, Dateioperationen), XSS (Script, SVG, CSS-Expression), RCE, Directory Traversal, SSRF, XXE, Log4Shell, NoSQL-Injection, Command Injection (Linux + Windows), LDAP-Injection, XPath-Injection, SSTI, CRLF-Injection, Java-Deserialisierung und mehr
- **83 Bot-/Scanner-Signaturen** – SQLMap, Nikto, Nmap, Burp Suite, FeroxBuster, FFUF, XSStrike, Dalfox, Netsparker und über 70 weitere Scanner- und Bot-Signaturen
- **KI-Scraper-Erkennung** – GPTBot, ClaudeBot, ByteSpider, Common Crawl und andere KI-Trainingsbots
- **Headless-Browser-Erkennung** – HeadlessChrome, PhantomJS, Selenium, Puppeteer, Playwright
- **404-Probe-Tracking** – Erkennt Reconnaissance-Probes auf bekannte verwundbare Pfade (`/wp-admin`, `/.env`, `/phpmyadmin`, `/actuator` usw.) mit über 50 Standard-Probe-Pfaden sowie ein optionales [KI-Infrastruktur-Paket](#ai-infrastructure-probes-opt-in) für exponierte LLM-Gateways
- **DDoS-Überwachung** – Ratenbasierte Schwellenwerterkennung mit konfigurierbaren Zeitfenstern
- **Konfidenzbewertung** – Jede Bedrohung erhält einen Konfidenzwert von 0–100 basierend auf Musteranzahl, Kontext und Signalen
- **Umgehungsresistenz** – Die Normalisierungspipeline vereitelt SQL-Kommentareinfügung, doppelte URL-Kodierung, HTML-Entity-Kodierung, Unicode-Escapes, Hex-Escapes und IIS-`%uXXXX`-Kodierung vor dem Musterabgleich – wiederholt, bis sich die Payload nicht mehr ändert, sodass das Stapeln zweier Techniken nicht durchkommt
- **CVE-Erkennung** – Shellshock (CVE-2014-6271), Spring4Shell (CVE-2022-22965), PHPUnit RCE (CVE-2017-9841), Drupalgeddon, Log4Shell
- **Kontextbewusste Erkennung** – Muster in Query-Strings werden höher bewertet als solche im Request-Body
- **Request-Body-Scanning** – Sowohl formular-kodierte als auch JSON-Request-Bodies (`application/json`) werden untersucht
- **Sichere Felder** – Bestimmte Formularfelder vom Scanning ausschließen (für CMS-Editoren, Code-Eingaben, Suchfelder)
- **Falsch-Positiv-Meldung** – Bedrohungen im Dashboard als Falsch-Positiv markieren; erstellt automatisch Ausschlussregeln
- **Drei Erkennungsmodi** – `strict`, `balanced` (Standard) und `relaxed` – einstellbare Sensitivität
- **Content-Pfad-Unterdrückung** – CMS-/Blog-Pfade auf die Whitelist setzen, um niedrige/mittlere Warnungen aus Rich Content zu unterdrücken
- **PII-Erkennung** – Muster für die Offenlegung sensibler Daten (pro Region konfigurierbar)
- **Geo-Anreicherung** – Identifikation von Land, Stadt, ISP und Cloud-Anbieter über eine kostenlose API
- **Slack-Benachrichtigungen** – Echtzeitbenachrichtigungen für Bedrohungen hoher Schwere (funktioniert mit Laravel 10 und 11+)
- **Integriertes Dashboard** – Dark-Mode-Blade-Dashboard (Alpine.js und Tailwind, Styles vorkompiliert, kein Build-Schritt)
- **Dashboard-Auth-Guard** – Konfigurierbare Authentifizierung für Dashboard und API (keine, auth, role oder IP-basiert)
- **15 API-Endpunkte** – Vollständige REST-API zum Erstellen benutzerdefinierter Vue-/React-/Mobile-Dashboards
- **Fail2ban-Export** – Erkannte IPs im fail2ban-kompatiblen Format oder als einfache Blockliste exportieren
- **Blocklist-Export** – IPs im nginx-deny-, Apache-deny-, CSV- oder einfachen Format exportieren
- **CSV-Export** – Bedrohungsprotokoll mit einem Klick exportieren (bis zu 10.000 Zeilen)
- **Korrelationsanalyse** – Koordinierte Angriffe und Angriffskampagnen über IPs hinweg erkennen
- **Leistungsoptimiert** – Kategoriebasiertes Lazy-Loading von Mustern (führt Regex nur für relevante Angriffskategorien aus), früher Abbruch bei sauberen Requests, Browser-UA-Kurzschluss (überspringt über 70 Prüfungen für normale Browser), Probe-Pfad-Hash-Lookup, Batch-DB-Inserts, konfigurierbare maximale Erkennungen pro Request
- **Datenbankunabhängig** – MySQL, PostgreSQL, SQLite, SQL Server
- **Zero Config** – Funktioniert sofort mit sinnvollen Standardwerten
- **Sicher by Design** – Die Middleware fängt ihre eigenen Fehler ab. Wenn die Erkennung fehlschlägt, läuft Ihre App weiter. Requests werden niemals blockiert.
---
## Konfiguration
Das Paket funktioniert ohne jegliche `.env`-Änderungen. Alle unten aufgeführten Werte sind optional – fügen Sie sie nur hinzu, wenn Sie die Standardwerte überschreiben möchten.
```env
# Enable/disable detection globally (default: true)
THREAT_DETECTION_ENABLED=true
# Detection sensitivity (default: balanced)
# Options: strict, balanced, relaxed
THREAT_DETECTION_MODE=balanced
# Custom table name (default: threat_logs)
# THREAT_DETECTION_TABLE=threat_logs
# Your ISO 3166-1 alpha-2 country code (default: IN)
# Drives the is_foreign flag on every enriched row — set this or every
# non-Indian address is reported as foreign.
# THREAT_DETECTION_HOME_COUNTRY=IN
# Geo-enrichment provider used by threat-detection:enrich (default shown).
# HTTPS since v1.8.0. A failed lookup is never retried over cleartext, and a
# run in which every lookup failed exits non-zero rather than reporting
# success. Enrichment is opt-in either way.
#
# ip-api.com's free tier rejects HTTPS, so on the free tier this command will
# now fail rather than quietly sending your visitors' IP addresses in the
# clear. Either point it at a provider you hold a key for, or set it back
# explicitly and accept the disclosure.
# THREAT_DETECTION_GEO_ENDPOINT=https://ip-api.com/json
# Dashboard URL path (default: threat-detection)
# THREAT_DETECTION_DASHBOARD_PATH=threat-detection
# API route prefix (default: api/threat-detection)
# THREAT_DETECTION_API_PREFIX=api/threat-detection
# Role required when the API guard is 'role' (default: admin)
# THREAT_DETECTION_API_ROLE=admin
# Allowed IPs when the API guard is 'ip'. Comma-separated, CIDR supported.
# THREAT_DETECTION_API_IPS=127.0.0.1,10.0.0.0/8
# Username shown on Slack alerts (default: ThreatBot)
# THREAT_DETECTION_SLACK_USERNAME=ThreatBot
# Whitelist IPs to skip detection entirely (default: empty)
# Supports CIDR notation. Comma-separated.
# THREAT_DETECTION_WHITELISTED_IPS=10.0.0.0/8,192.168.1.0/24
# Static operator denylist read by ThreatDetection::isBlocklisted() (default: empty)
# The package itself never blocks — see "Acting on the Data" for the
# enforcement recipe. Supports CIDR. Whitelist wins on overlap.
# THREAT_DETECTION_BLOCKLISTED_IPS=203.0.113.0/24,198.51.100.7
# DDoS detection thresholds (defaults shown)
# THREAT_DETECTION_DDOS_THRESHOLD=300
# THREAT_DETECTION_DDOS_WINDOW=60
# Minimum confidence score to log a threat (default: 0)
# Threats below this score are silently ignored.
# THREAT_DETECTION_MIN_CONFIDENCE=0
# Slack notifications (disabled by default)
# THREAT_DETECTION_NOTIFICATIONS=true
# THREAT_DETECTION_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
# THREAT_DETECTION_SLACK_CHANNEL=#threat-alerts
# Dashboard (disabled by default)
# THREAT_DETECTION_DASHBOARD=true
# API endpoints (enabled by default)
# THREAT_DETECTION_API=true
# API rate limiting (default: 60 requests per minute)
# THREAT_DETECTION_API_THROTTLE=60,1
# Queue support - offload DB writes to a queue (disabled by default).
# OPTIONAL: only enable if your app already runs a queue worker. When false
# (default), threats are written synchronously with a plain DB insert - no
# Redis, no worker, nothing extra to run.
# THREAT_DETECTION_QUEUE=false
# THREAT_DETECTION_QUEUE_CONNECTION=redis
# THREAT_DETECTION_QUEUE_NAME=default
# Auto-purge old logs (disabled by default)
# Requires Laravel scheduler to be running.
# THREAT_DETECTION_RETENTION=false
# THREAT_DETECTION_RETENTION_DAYS=90
# 404 probe tracking (enabled by default)
# Detects bots hitting /wp-admin, /.env, /phpmyadmin, etc.
# THREAT_DETECTION_PROBE_TRACKING=true
# Max detections per request (default: 0 = unlimited)
# Stop scanning after N pattern matches per request.
# THREAT_DETECTION_MAX_DETECTIONS=0
# Dashboard auth guard (default: none)
# Options: none, auth, role, ip
# THREAT_DETECTION_DASHBOARD_GUARD=none
# THREAT_DETECTION_DASHBOARD_ROLE=admin
# THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1
# API auth guard (default: none - uses existing middleware config)
# THREAT_DETECTION_API_GUARD=none
```
### 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, Standardschwellenwerte. Gut für die meisten Apps. |
| `relaxed` | 25 | Nur Muster mit hohem Schweregrad werden überhaupt ausgeführt. Am besten für inhaltsreiche Websites mit häufigen Fehlalarmen. (War 40 vor v1.8.0 — ein Mindestwert, den keine einzelne Erkennung erreichen konnte, sodass der Modus stillschweigend nichts protokollierte.) |
### 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'],
```
Um die Erkennung in Ihrer Testsuite zu deaktivieren, setzen Sie `APP_ENV=testing` (nicht in der obigen Liste) oder fügen Sie Folgendes zu Ihrer `phpunit.xml` hinzu:
```xml
<env name="THREAT_DETECTION_ENABLED" value="false"/>
```
### Konfigurationsreferenz
Veröffentlichen Sie die Konfigurationsdatei, um alle verfügbaren Optionen zu sehen:
```bash
```
---
[Read more](https://github.com/jay123anta/laravel-threat-detection)