Ces requêtes atteignent déjà votre application Laravel. Votre journal d'accès affiche l'URL
et le code de statut, et rien d'autre — ni la charge utile décodée, ni laquelle de vos
routes a été ciblée, ni si la même IP a essayé quarante autres choses cette heure-ci.

Ce package répond à ces questions. Déposez-le dans n'importe quelle application Laravel 10–13 et il commence
à analyser chaque requête HTTP par rapport à plus de 150 motifs d'attaque, en évaluant chaque correspondance par
confiance et en l'écrivant dans votre base de données — avec un tableau de bord intégré, des alertes Slack,
un enrichissement géographique et des exports fail2ban/liste de blocage. Aucune requête n'est jamais bloquée. Pensez
caméra de surveillance, pas verrou : il vous montre exactement qui sonde vos routes, à quelle
fréquence, et avec quelles techniques.

> Extrait d'une application en production et éprouvé sur du trafic réel. 1 857 tests, aucune dépendance
> d'exécution en dehors de Laravel lui-même, et aucune connexion internet requise pour la détection.
>
> Vous mettez à jour ? Voir [UPGRADING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/UPGRADING.md). Vous contribuez ? Voir [CONTRIBUTING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/CONTRIBUTING.md).

## Démarrage en moins d'une minute```bash
composer require jayanta/laravel-threat-detection
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate

---

## Où cela s'intègre : IDS vs WAF vs edge

Ce package est un **IDS passif au niveau applicatif** — il observe et enregistre, il ne
bloque pas. Il est conçu pour se placer *aux côtés* d'un WAF ou d'un service edge, pas pour le remplacer. Chaque couche voit
quelque chose que les autres ne peuvent pas voir :

| | **Ce package** (IDS applicatif) | **WAF** (mod_security, Cloudflare WAF) | **Edge / CDN** (Cloudflare) |
|---|:---:|:---:|:---:|
| Bloque les requêtes malveillantes | ❌ journalise uniquement | ✅ | ✅ |
| Contexte applicatif complet (route exacte, payload décodé, utilisateur authentifié) | ✅ | ⚠️ partiel | ❌ |
| Tableau de bord intégré + journal des menaces dans votre base de données | ✅ | ⚠️ variable | ⚠️ edge uniquement |
| Détections spécifiques à l'application (ex. Aadhaar / PAN / IFSC PII) | ✅ motifs personnalisés | ❌ | ❌ |
| Fonctionne hors ligne / sans service externe | ✅ | ⚠️ selon le cas | ❌ |
| Stoppe le trafic avant qu'il n'atteigne votre application | ❌ | ✅ edge | ✅ |
| Installation | un `composer require` | moyenne–élevée | faible–moyenne |
| Coût | gratuit, MIT | variable | offre gratuite + payant |

**En résumé :** un edge/WAF est votre serrure sur la porte ; ceci est la caméra de surveillance
*à l'intérieur*, avec le contexte applicatif pour vous dire exactement ce qui est tenté sur quelle route, par
qui, et à quelle fréquence. Utilisez-le pour alimenter de vraies décisions — bans fail2ban, limites de débit,
géo-blocage — avec des données que votre couche edge ne voit jamais.

### Ce qu'il n'est délibérément PAS

- **Pas un WAF.** Il ne bloque, ne filtre et ne modifie jamais une requête. Utilisez Cloudflare,
  mod_security, ou un vrai WAF pour l'application des règles. (Pas de couche edge à qui déléguer ? Les
  [helpers côté opérateur](#acting-on-the-data-operator-side-blocking) exposent les
  décisions du package pour que vous puissiez écrire votre propre middleware de blocage en cinq lignes —
  le code d'application des règles reste le vôtre, pas celui du package.)
- **Pas un remplacement pour le codage sécurisé.** Les requêtes paramétrées, la validation des entrées, et
  l'échappement des sorties sont vos véritables défenses. Ce package suppose que votre code est déjà
  sécurisé et vous donne de la *visibilité*, pas de la protection.
- **Pas un service edge.** Si vous pouvez placer Cloudflare devant, faites-le — puis ajoutez ceci pour le
  niveau de détail applicatif que les services edge ne peuvent pas voir.
- **Pas un détecteur complet, et il ne peut pas l'être.** La correspondance de motifs attrape les attaques qui
  *ressemblent à* des attaques connues. Une technique nouvelle, ou une technique familière suffisamment réécrite,
  passera sans être journalisée — et vous ne serez pas informé qu'elle l'a fait. Le silence ici signifie
  « rien n'a correspondu », jamais « rien ne s'est produit ». Là où il gagne sa place, c'est sur le
  trafic à fort volume et à faible effort qui constitue la majeure partie de ce qui frappe réellement une application
  Laravel publique : scanners, sondes de reconnaissance, chaînes d'injection toutes faites, pulvérisations
  d'identifiants. Traitez un journal silencieux comme une absence de preuve, pas comme une preuve d'absence.

### Attendez-vous à ce qu'il signale votre propre contenu dès le premier jour

Une installation non réglée se déclenche sur du contenu légitime, et vous devriez le savoir avant
d'installer plutôt qu'après. Ces cas sont mesurés, pas hypothétiques — la suite épingle cette liste exacte pour qu'elle ne puisse pas dériver ([`LegitimateTrafficCorpusTest`](https://github.com/jay123anta/laravel-threat-detection/blob/main/tests/Feature/LegitimateTrafficCorpusTest.php)) :

<!-- noise-floor:start -->
| Requête parfaitement légitime | Ce qu'une installation non réglée journalise |
|---|---|
| `how to write a UNION SELECT in postgres` saisi dans un champ de recherche | `SQL Injection UNION` / high |
| Un article de blog contenant `<script>window.dataLayer=[];</script>` | `XSS Script Tag` / high |
| Un ticket de support avec un message d'erreur `SELECT * FROM users WHERE id = 1` collé | `SQLi Variant` / high |
| Une documentation expliquant que `../../etc/passwd` est le payload de traversée classique | `Directory Traversal` / medium |
| Un formulaire de profil collectant un véritable numéro de mobile indien et un PAN | `PAN Number Detected` / high |
<!-- noise-floor:end -->

**Aucun de ces cas n'est un bug.** Un article de blog contenant `<script>` est, octet pour octet, un
payload de XSS stocké ; une recherche de `UNION SELECT` est indiscernable d'une tentative
d'en faire une. Rien d'autre que le contexte applicatif ne les sépare, et aucun moteur de motifs ne peut
fournir ce contexte à votre place.

Le fournir est un changement de configuration d'une ligne — `safe_fields`, `safe_paths`,
`content_paths`, ou le mode `relaxed`. Voir [Réduire les faux positifs](#reducing-false-positives).
**Si votre application accepte du texte enrichi, des exemples de code, ou des requêtes de recherche, faites-le avant de
juger la sortie.** La valeur par défaut est délibérément bruyante-mais-honnête plutôt que
silencieuse-et-incomplète : il est plus facile de faire taire une correspondance connue que de découvrir une correspondance qui
ne s'est jamais déclenchée.

### Alors qu'en faites-vous concrètement ?

La question la plus fréquente à propos d'un détecteur qui ne bloque jamais. Quatre réponses, par ordre
croissant d'effort :

| Vous voulez | Utilisez | Effort |
|---|---|---|
| Voir ce qui vous frappe | Le [tableau de bord](#dashboard) ou `threat-detection:stats` | aucun, c'est déjà en cours d'exécution |
| Bannir les récidivistes au niveau du pare-feu | [`threat-detection:export-fail2ban`](#artisan-commands) — pipez vers un cron | une ligne |
| Refuser au niveau du serveur web | [`threat-detection:export-blocklist`](#artisan-commands) → directives nginx/apache | une ligne |
| Refuser les requêtes dans l'application | [Helpers côté opérateur](#acting-on-the-data-operator-side-blocking) — `isBlocklisted()`, `isDdosThresholdExceeded()` | ~10 lignes de votre propre middleware |
| Réagir en temps réel | L'[événement `ThreatDetected`](#threatdetected-event) — Telegram, SIEM, PagerDuty | un listener |

Le package fournit le renseignement ; vous fournissez le refus. Cette séparation est
délibérée — le code d'application des règles qui vit dans votre application est du code que vous pouvez lire,
tester et désactiver, et cela signifie qu'un bug de détection ne peut jamais faire tomber votre site.


### Comment il se compare aux autres packages de sécurité Laravel

Ceux-ci résolvent des problèmes différents et se composent bien — le tableau vise à choisir le
bon outil, pas à gagner.

| Package | Ce qu'il fait | Bloque ? | Utilisez-le quand |
|---|---|:---:|---|
| **ce package** | Analyse chaque requête contre plus de 150 motifs, journalise avec le contexte applicatif complet | ❌ | Vous voulez *voir* ce qui est tenté sur votre application |
| `spatie/laravel-honeypot` | Champ de formulaire caché qui attrape les bots de spam | ✅ formulaire uniquement | Vous avez des formulaires publics spammés |
| `graham-campbell/security` | Supprime le balisage de type XSS des entrées | ✅ modifie | Vous voulez un assainissement naïf des entrées |
| `spatie/laravel-csp` | Envoie des en-têtes Content-Security-Policy | ✅ navigateur | Vous voulez contraindre ce que le navigateur charge |
| `laravel/fortify` + limites de débit | Limitation et verrouillage de l'authentification | ✅ | Vous avez besoin d'une protection contre la force brute à la connexion |
| Cloudflare / mod_security | WAF edge, bloque avant votre application | ✅ | Vous voulez que le trafic soit stoppé avant d'arriver |

Le résumé honnête : un honeypot attrape le spam de formulaire, un WAF bloque le trafic connu comme malveillant
au niveau edge, et CSP contraint le navigateur. **Aucun d'entre eux ne vous dit ce qu'un
attaquant a tenté contre vos routes spécifiques, avec le payload décodé et l'utilisateur
authentifié attaché.** C'est ce vide que ce package comble — et c'est pourquoi le
package ne bloque délibérément pas : vous pouvez l'exécuter aux côtés de tout ce qui précède
sans qu'aucun d'entre eux ne se combatte.

---

## Prérequis

- PHP 8.2+ (Laravel 13 nécessite PHP 8.3+)
- Laravel 10.x, 11.x, 12.x, ou 13.x
- Toute base de données prise en charge par Laravel (MySQL, PostgreSQL, SQLite, SQL Server)
- N'importe quel driver de cache -  **aucun Redis ni worker de queue requis**. Redis/Memcached est
  seulement *recommandé* pour activer la vérification DDoS optionnelle (qui se désactive automatiquement sur
  les drivers non atomiques). Les écritures en queue sont opt-in et désactivées par défaut.

---

## Comment ça fonctionne

1. Un middleware analyse chaque requête HTTP entrante
2. La requête est vérifiée contre 158 motifs regex couvrant l'injection SQL, le XSS, le RCE, la traversée de fichiers, le SSRF, le LDAP, le XPath, le SSTI, et plus encore
3. Si un motif de menace correspond, un enregistrement est écrit dans votre table de base de données `threat_logs` avec l'IP, l'URL, le type de menace, le niveau de gravité, et un score de confiance
4. Optionnellement, une alerte Slack est envoyée pour les menaces de gravité élevée
5. La requête se poursuit normalement -  **rien n'est bloqué**

Aucune connexion internet n'est nécessaire pour la détection.

---

## Démarrage rapide

### 1. Installer le package```bash
composer require jayanta/laravel-threat-detection

Cela crée deux tables : `threat_logs` (stocke les menaces détectées) et `threat_exclusion_rules` (stocke les règles de faux positifs).

**Vérifier que les tables ont été créées :**```bash
php artisan migrate:status

> **Comment vérifier votre version de Laravel :** Exécutez `php artisan --version` dans votre terminal.

**Si vous utilisez Laravel 10** - ouvrez `app/Http/Kernel.php` :```php
protected $middlewareGroups = [
    'web' => [
        // ... existing middleware
        \JayAnta\ThreatDetection\Http\Middleware\ThreatDetectionMiddleware::class,
    ],
];

Le package fonctionne avec des valeurs par défaut sensées. Publier la configuration vous permet de personnaliser les motifs de détection, les modes de sensibilité, les notifications Slack, et plus encore. Si vous sautez cette étape, tout fonctionne toujours.

**C'est tout.** Votre application détecte désormais les menaces.

---

## Vérifier que cela fonctionne

Après l'installation, déclenchez une menace de test et confirmez qu'elle a été enregistrée.

### Étape 1 : Démarrer votre application```bash
php artisan serve

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

**RCE (exécution de code à distance) :**```
http://localhost:8000/?cmd=system('ls -la')

**Injection de commandes Windows :**```
http://localhost:8000/?cmd=powershell -c whoami

> Utilisez une route qui existe réellement dans votre application (comme `/`). Si l'URL renvoie un 404, le middleware n'a peut-être pas été exécuté.

### Étape 3 : Vérifier que les menaces ont été journalisées

**Option A - Commande Artisan (la plus rapide) :**```bash
php artisan threat-detection:stats

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

### Points à connaître lors des tests

| Comportement | Explication |
|----------|-------------|
| Une même menace n'est journalisée qu'une fois toutes les 5 minutes | Déduplication : même IP + même type de menace est mis en cache pendant 5 minutes. Utilisez **différents types d'attaques** pour chaque test, ou attendez entre les tests. |
| Les requêtes `curl` déclenchent une détection supplémentaire | L'utilisation de `curl` journalise également une détection de user-agent « cURL Command » (sévérité faible). C'est attendu - le package détecte les outils automatisés. |
| Le package ne bloque jamais les requêtes | Votre application continue de fonctionner normalement. La détection est passive. |
| Aucune configuration Slack nécessaire | Les notifications sont désactivées par défaut. |
| Aucune connexion internet nécessaire | La détection principale est 100 % locale. Seule la commande optionnelle `threat-detection:enrich` appelle une API externe pour les géo-données. |

### Dépannage

**Commencez ici — une seule commande répond à la plupart de ces points :**```bash
php artisan threat-detection:doctor

Ce qu'il couvre : la détection activée pour cet environnement ; chaque colonne dont le writer
a besoin (une colonne manquante élimine **toutes** les menaces) ; les colonnes dashboard/API ; la
table des règles d'exclusion ; si le middleware est réellement relié à une route ou à un
groupe ; une configuration publiée antérieure à cette version ; des patterns personnalisés qui masquent
ceux intégrés ; un driver de cache incapable d'assurer le comptage DDoS ; et un dashboard ou une
API laissé ouvert sans authentification.

**« J'ai testé mais `threat-detection:stats` affiche zéro menace » / « Les menaces ne sont pas stockées dans la base de données »**

Si le doctor est passé, l'installation est correcte et le problème vient de la requête de test
elle-même. Trois choses qu'il ne peut pas vérifier à votre place :

| Vérification | Comment vérifier |
|-------|---------------|
| L'IP n'est pas en liste blanche | Si vous avez ajouté `THREAT_DETECTION_WHITELISTED_IPS` à `.env`, retirez-le pendant les tests |
| Une route existante a été utilisée | L'URL de test doit correspondre à une route réelle (par ex., `/`). Un 404 signifie que le middleware ne s'est jamais exécuté |
| Cache de déduplication | Même IP + même type d'attaque est mis en cache pendant 5 minutes - essayez un autre type d'attaque |

> Exécuter `php artisan migrate` seul ne suffit jamais : les fichiers de migration se trouvent
> à l'intérieur du package et doivent d'abord être publiés dans le `database/migrations/`
> de votre application. Le doctor affiche la commande exacte lorsque c'est le problème.

**« L'API renvoie 401 Unauthorized »**

Voir [Authentification API](#api-authentication) ci-dessous.

**« Le dashboard affiche 404 »**

Le dashboard est désactivé par défaut. Ajoutez `THREAT_DETECTION_DASHBOARD=true` à `.env` et videz le cache des routes :```bash
php artisan route:clear

### Modes de détection

| Mode | Seuil de confiance | Comportement |
|------|---------------------|----------|
| `strict` | 0 (journalise tout) | Tous les motifs actifs, seuils les plus bas. Détecte tout mais peut signaler du trafic légitime. |
| `balanced` | 10 | Par défaut. Notation de confiance active, seuils standards. Adapté à la plupart des applications. |
| `relaxed` | 40 | Seuls les motifs de haute sévérité se déclenchent. Idéal pour les sites riches en contenu avec de fréquents faux positifs. |

### Environnements activés

Par défaut, la détection s'exécute en `production`, `staging` et `local`. Pour modifier, publiez la configuration et éditez :```php
'enabled_environments' => ['production', 'staging', 'local'],

### Référence de configuration

Publiez le fichier de configuration pour voir toutes les options disponibles :```bash
php artisan vendor:publish --tag=threat-detection-config

Laisser vide (par défaut) pour analyser toutes les routes (sous réserve de `skip_paths`). Lorsque les deux sont configurés, `only_paths` est vérifié en premier, puis `skip_paths` s'applique au sein de l'ensemble correspondant.

### Prise en charge des files d'attente

Par défaut, la journalisation des menaces s'effectue de manière synchrone dans le cycle de la requête. Pour les applications à fort trafic, vous pouvez déléguer les écritures en base de données et les notifications Slack à une file d'attente :```env
THREAT_DETECTION_QUEUE=true
THREAT_DETECTION_QUEUE_CONNECTION=redis
THREAT_DETECTION_QUEUE_NAME=threat-logs

Nécessite que le planificateur de Laravel soit en cours d'exécution (`php artisan schedule:run`). S'exécute quotidiennement à 02:00 via `threat-detection:purge`.

### Événement ThreatDetected

Chaque menace confirmée déclenche un événement `ThreatDetected` que vous pouvez écouter :```php
// app/Providers/EventServiceProvider.php
use JayAnta\ThreatDetection\Events\ThreatDetected;

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

L'événement contient `$ipAddress`, `$requestCount`, `$threshold` et `$windowSeconds`. Il est
limité à une fois par IP par fenêtre de déduplication (même limitation que la ligne de log), afin qu'un flood ne puisse pas
noyer vos listeners. Utilisez-le pour l'alerte ou pour alimenter un store de bannissement externe ; pour *refuser*
les clients dépassant le seuil, utilisez `ThreatDetection::isDdosThresholdExceeded($ip)` depuis votre propre
middleware à la place — voir [Acting on the Data](#acting-on-the-data-operator-side-blocking).

---

## Slack Notifications

Les alertes Slack sont désactivées par défaut. Pour activer :```env
THREAT_DETECTION_NOTIFICATIONS=true
THREAT_DETECTION_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
THREAT_DETECTION_SLACK_CHANNEL=#threat-alerts

---

## Tableau de bord

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12500/fc7950bd0cc6323bcc2d62b03e31c99edc7450b0ef76f9cbfa5133b527b25269.png" alt="Tableau de bord de détection des menaces — statistiques, chronologie sur 7 jours, journal des menaces en direct, principales IP fautives et menaces par pays" width="100%">
</p>

Le paquet est livré avec un tableau de bord intégré en mode sombre (Alpine.js + Tailwind CDN - aucune étape de build requise).```
+-------------------------------------------------------------------------+
|  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                                         |
+-------------------------------------------------------------------------+

Visitez : `http://your-app.test/threat-detection`

### Accéder au tableau de bord en développement local

Le tableau de bord utilise le middleware `['web', 'auth']` par défaut, les utilisateurs doivent donc être connectés. Si votre application n'a pas encore d'authentification, limitez plutôt l'accès à votre propre machine :```env
THREAT_DETECTION_DASHBOARD_GUARD=ip
THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1

**Option 2 - Modifier directement le middleware :**```php
// config/threat-detection.php
'api' => [
    'enabled' => true,
    'prefix' => 'api/threat-detection',
    'middleware' => ['api', 'auth'],  // or 'auth:your-guard'
],

> Restaurez l'authentification avant de déployer en production.

### Référence des points de terminaison

| Méthode | Point de terminaison | Description |
|--------|----------|-------------|
| GET | `/api/threat-detection/threats` | Lister les menaces (paginé, filtrable) |
| GET | `/api/threat-detection/threats/{id}` | Détails d'une menace |
| POST | `/api/threat-detection/threats/{id}/false-positive` | Marquer une menace comme faux positif |
| GET | `/api/threat-detection/stats` | Statistiques globales |
| GET | `/api/threat-detection/summary` | Répartition détaillée par type, niveau, IP |
| GET | `/api/threat-detection/live-count` | Menaces de la dernière heure |
| GET | `/api/threat-detection/by-country` | Regroupées par pays |
| GET | `/api/threat-detection/by-cloud-provider` | Regroupées par fournisseur cloud |
| GET | `/api/threat-detection/top-ips` | Principales IP fautives |
| GET | `/api/threat-detection/timeline` | Chronologie des menaces (pour les graphiques) |
| GET | `/api/threat-detection/ip-stats?ip=x.x.x.x` | Statistiques pour une IP spécifique |
| GET | `/api/threat-detection/correlation` | Analyse de corrélation |
| GET | `/api/threat-detection/export` | Exporter en CSV |
| GET | `/api/threat-detection/exclusion-rules` | Lister les règles d'exclusion |
| DELETE | `/api/threat-detection/exclusion-rules/{id}` | Supprimer une règle d'exclusion |

### Paramètres de requête pour `/threats`

| Paramètre | Description |
|-----------|-------------|
| `keyword` | Rechercher dans l'IP, l'URL, le type |
| `ip` | Filtrer par adresse IP |
| `level` | Filtrer par niveau de menace (`high`, `medium`, `low`) |
| `type` | Filtrer par type de menace |
| `country` | Filtrer par code pays |
| `is_foreign` | Filtrer les IP étrangères (`true`/`false`) |
| `cloud_provider` | Filtrer par fournisseur cloud |
| `is_false_positive` | Filtrer par statut de faux positif (`true`/`false`) |
| `date_from` / `date_to` | Filtre de plage de dates |
| `per_page` | Éléments par page (par défaut : 20, max : 100) |

### Exemple de réponse API

**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));
}, []);

---

## Agir sur les données (blocage côté opérateur)

Le paquet ne bloque jamais une requête — c'est son identité, pas un comportement par défaut. Les exports ci-dessus
alimentent les couches d'application que vous exécutez déjà (fail2ban, nginx, un WAF en périphérie). Mais certains déploiements
n'ont aucune de ces couches à alimenter — hébergement mutualisé, PaaS, conteneurs derrière un équilibreur de charge que vous
ne contrôlez pas. Pour ceux-là, le paquet expose ses *décisions* sous forme d'assistants, et vous écrivez vous-même le
middleware d'application. Même architecture que les exports : **nous fournissons
l'intelligence, vous fournissez le refus.**```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);
    }
}

Les helpers :

| Helper | Retourne | Basé sur |
|---|---|---|
| `ThreatDetection::isBlocklisted($ip)` | `bool` | configuration `blocklisted_ips` (CIDR via `IpUtils` ; la whitelist est prioritaire) |
| `ThreatDetection::isWhitelisted($ip)` | `bool` | configuration `whitelisted_ips` |
| `ThreatDetection::ddosRequestCount($ip)` | `int` | le compteur de flood maintenu par le middleware de détection |
| `ThreatDetection::isDdosThresholdExceeded($ip)` | `bool` | ce compteur comparé à `ddos.threshold` |

Notes :

- **La denylist est statique et maintenue par l'opérateur.** Rien dans le package ne l'alimente
  jamais — il exécute la même décision qu'une jail fail2ban prendrait (« J'ai lu le dashboard ; ce /24
  est hostile »), mais au sein de l'application.
- Le compteur DDoS ne compte que les requêtes ayant atteint la détection (`skip_paths`, IP
  whitelistées et environnements désactivés ne sont jamais comptés), et reste à 0 sur les drivers de cache
  où la détection DDoS est désactivée (`file`, `database`, `null`).
- Lorsqu'un client franchit le seuil, un [événement `DdosThresholdExceeded`](#ddosthresholdexceeded-event)
  est également dispatché — utile pour l'alerting ou pour alimenter une liste de bannissement externe. N'appelez pas `abort()`
  depuis le listener, cependant : les listeners s'exécutent à l'intérieur du `try/catch` fail-open du middleware de détection,
  donc le refus appartient à votre propre middleware comme ci-dessus.

---

## Suivi des sondes 404

Le package détecte les sondes de reconnaissance — des bots qui frappent des chemins vulnérables connus comme `/wp-admin`, `/.env` ou `/phpmyadmin` sur votre site non-WordPress et non-phpMyAdmin. Celles-ci n'ont aucune charge utile malveillante ; le chemin lui-même est le signal.

Journalisées avec un tag de type `[probe]`, distinct de la détection basée sur la charge utile. Si une requête de sonde contient également une charge utile malveillante, les deux sont journalisées indépendamment.

Activé par défaut avec plus de 50 chemins de sondes. Personnalisable dans `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...
    ],
],

Les champs listés ici sont retirés des paramètres de requête et du corps de la requête — à la fois encodés en formulaire et JSON (`application/json`) — avant que la détection ne s'exécute. Les autres champs de la même requête sont toujours entièrement analysés.

### Chemins sûrs (sensibles au chemin, pour les API JSON imbriquées)

`safe_fields` correspond à un nom de clé **n'importe où** où il apparaît. Pour les API JSON imbriquées, c'est souvent trop large — vous pouvez vouloir exempter la valeur d'un champ spécifique sans exempter cette clé partout. Utilisez `safe_paths`, qui correspond par **chemin** en notation pointée et prend en charge les jokers `fnmatch` :```php
// config/threat-detection.php
'safe_paths' => ['search.query', 'filters.*.value'],

Validateurs disponibles :

| Validateur | Somme de contrôle | Utilisation typique |
|------------|-------------------|---------------------|
| `verhoeff` | Verhoeff | Numéros Aadhaar |
| `luhn`     | Luhn     | Numéros de carte de crédit/débit |

Avec le mapping fourni, les horodatages, les identifiants de commande et les codes-barres qui font par hasard 12 chiffres ne sont plus journalisés comme PII — tandis que les véritables numéros Aadhaar le sont toujours. Si plusieurs valeurs correspondent et qu'une seule passe la somme de contrôle, la détection se déclenche quand même : un vrai numéro parmi le bruit reste une fuite.

Associez un validateur à votre propre motif pour une détection de carte contrôlée par somme de contrôle :```php
'custom_patterns'    => ['/\b(?:\d[ -]?){13,19}\b/' => 'Card Number Detected'],
'pattern_validators' => ['Card Number Detected' => 'luhn'],

L'alerte, le point de terminaison, les noms de champs et l'IP attaquante survivent tous - seule la valeur disparaît. La rédaction s'exécute *après* la détection, donc rien n'est manqué.```php
// config/threat-detection.php
'redact' => [
    'enabled' => env('THREAT_DETECTION_REDACT', true),
    'mask'    => '[REDACTED]',
    'labels'  => ['Aadhaar Number Detected', 'PAN Number Detected', /* ... */],
],

Les mêmes options sont disponibles pour les routes API avec `THREAT_DETECTION_API_GUARD`.

Lorsque `guard=none` (par défaut), le package enregistre un avertissement une fois par jour pour vous rappeler de configurer l'authentification.

Le guard **échoue en mode fermé** : une valeur de guard non reconnue (par exemple une faute de frappe) est refusée avec un 403 et un avertissement journalisé plutôt que d'accorder silencieusement l'accès, et `guard=role` refuse (avec un avertissement) lorsque le modèle d'utilisateur authentifié n'a pas de méthode `hasRole()`.

### Désactiver une détection nécessite plus qu'un accès en lecture

Marquer une menace comme faux positif et supprimer une règle d'exclusion désactivent tous deux un type de détection pour tout le monde, ce qui constitue un privilège différent de la lecture du journal. Ces deux endpoints sont vérifiés par rapport à un guard distinct :```env
# Options: none, auth, role, ip. Default: role
THREAT_DETECTION_API_WRITE_GUARD=role

**Exemple - détecter une sonde de point de terminaison d'administration personnalisée :**```php
'/\/my-admin-panel/i' => 'Custom Admin Panel Probe',

- **`level`** définit directement le niveau de menace au lieu de le dériver des mots-clés `threat_levels` dans le label.
- **`contexts`** restreint l'analyse à des segments de requête spécifiques — par exemple, un motif de carte qui n'a de sens que dans le body cesse de correspondre à des suites de chiffres dans les en-têtes.
- **`validator`** nomme une vérification post-correspondance inline (voir [Post-Match Validators](#post-match-validators-checksum-aware-false-positive-reduction)) ; elle a la priorité sur la map de labels `pattern_validators`.

Les entrées de type chaîne et tableau se mélangent librement dans la même configuration. Les options malformées **échouent en mode ouvert** — le motif est toujours analysé, sans restriction, et un avertissement est journalisé — ainsi une erreur de configuration ne peut jamais désactiver ou restreindre silencieusement une détection.

> **Remarque :** Les chemins de sonde courants comme `/wp-login.php`, `/.env`, `/phpmyadmin` sont désormais gérés automatiquement par la fonctionnalité [404 Probe Tracking](#404-probe-tracking). Vous n'avez pas besoin de motifs personnalisés pour ceux-ci.

Le niveau de menace pour chaque motif est déterminé automatiquement en faisant correspondre les mots-clés du label avec la configuration `threat_levels` :```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'],
],

---

## Passage en production

Le package est passif par conception - il ne bloque, ne rejette et ne modifie jamais une requête, et le middleware de détection enveloppe tout son corps dans un `try/catch`, de sorte qu'un échec de détection ne peut jamais casser votre application. Il est livré avec des valeurs par défaut sensées et ne nécessite aucun service externe pour fonctionner. Avant de passer en production, cette courte checklist vaut le coup d'œil :

1. **Protégez le tableau de bord et l'API.** Les deux sont par défaut sur `guard = none` pour une première exécution sans configuration, et journalisent un avertissement quotidien tant qu'ils ne sont pas protégés. Avant la production, définissez un guard - `THREAT_DETECTION_DASHBOARD_GUARD` et `THREAT_DETECTION_API_GUARD` (`auth`, `role`, ou `ip`). Une valeur non reconnue ou un guard `role` sur un modèle utilisateur sans `hasRole()` **échoue désormais en mode fermé** (403), donc une faute de frappe n'exposera pas silencieusement les données. La désactivation d'une détection est contrôlée séparément par `THREAT_DETECTION_API_WRITE_GUARD`, qui vaut `role` par défaut. Voir [Authentification du tableau de bord et de l'API](#dashboard-and-api-authentication).
2. **Exécutez les migrations** (`vendor:publish --tag=threat-detection-migrations && migrate`). Une nouvelle publication est sans danger - les migrations déjà publiées sont ignorées.
3. **Choisissez un mode de détection.** `balanced` (par défaut) convient à la plupart des applications ; utilisez `relaxed` pour les sites riches en contenu, `strict` pour les surfaces à haute sécurité. Ajustez avec `content_paths`, `safe_fields` et `min_confidence` - voir [Réduction des faux positifs](#reducing-false-positives).
4. **Passez en revue les PII régionales / motifs personnalisés.** Les valeurs par défaut sont centrées sur l'Inde (Aadhaar, PAN, IFSC) et les motifs numériques larges (par ex. compte bancaire) peuvent correspondre à de longs identifiants numériques en dehors des routes d'authentification. Remplacez ou ajustez `custom_patterns` pour votre région et votre application, et ajoutez les routes à contenu lourd à `auth_paths` / `content_paths`.
5. **Activez la rétention** si vous prévoyez du volume : `THREAT_DETECTION_RETENTION=true` (purge automatique via le scheduler). Nécessite que le scheduler de Laravel (`schedule:run`) soit piloté par cron.
6. **Extras optionnels, tous désactivés par défaut :** alertes Slack (`THREAT_DETECTION_NOTIFICATIONS`), enrichissement géographique (`php artisan threat-detection:enrich` - la seule fonctionnalité qui effectue un appel sortant, vers le service gratuit ip-api.com), et écritures en file d'attente (`THREAT_DETECTION_QUEUE` - à activer uniquement si vous exécutez déjà un worker de file d'attente ; sinon les écritures sont synchrones et ne nécessitent pas Redis).

Aucun Redis, aucun worker de file d'attente et aucun appel réseau sortant ne sont requis pour la détection et la journalisation de base.

---

## Réduction des faux positifs

Le package fournit plusieurs outils pour réduire les faux positifs. Utilisez celui qui correspond à votre situation :

### Champs sûrs et chemins sûrs

Excluez un champ de l'analyse entièrement, soit par son nom partout (`safe_fields`), soit par chemin en notation pointée pour du JSON imbriqué (`safe_paths`). L'approche la plus simple, et la plus radicale - le champ est ignoré, donc aucune détection ne s'exécute dessus.

Détails complets et exemples : [Champs sûrs](#safe-fields-false-positive-reduction).

### Suppression par chemin de contenu

Si vous avez des éditeurs CMS, des formulaires d'articles de blog ou des sections de commentaires où les utilisateurs soumettent du contenu riche, ces chemins déclenchent souvent des faux positifs (par ex., un article de blog contenant des exemples de code `<script>`). Ajoutez ces chemins pour supprimer les alertes de niveau faible/moyen :```php
// config/threat-detection.php
'content_paths' => [
    'admin/posts/*',
    'admin/pages/*',
    'blog/*/edit',
    'comments',
],

### Attribution de score de confiance

Chaque menace reçoit un score de confiance (0-100) basé sur :
- Le nombre de correspondances de motifs dans la même requête
- La gravité du motif correspondant
- L'endroit où le motif a été trouvé (chaîne de requête > en-têtes > corps)
- Si le user-agent correspond à un outil d'attaque connu
- Le mode de détection actuel

Les menaces en dessous du seuil de confiance pour votre mode de détection ne sont pas journalisées (voir [Modes de détection](#detection-modes)).

---

## Types d'attaques détectées

| Catégorie | Exemples |
|----------|---------|
| **Injection SQL** | UNION, booléenne, temporelle, encodage CHAR, DDL (DROP/ALTER/CREATE), DML (INSERT/UPDATE/DELETE), opérations sur fichiers (INTO OUTFILE, LOAD_FILE), énumération ORDER BY, chaînes hexadécimales, UNHEX |
| **Injection NoSQL** | Opérateurs MongoDB $ne, $gt, $regex, $where |
| **XSS** | Balises script, gestionnaires d'événements SVG (`<svg onload=`), gestionnaires d'événements HTML (`<body onload=`, `<img onerror=`), expressions CSS, URI JavaScript, manipulation du DOM |
| **Exécution de code** | Fonctions shell RCE, désérialisation PHP, désérialisation Java (base64 + octets magiques hex), injection de template (Blade, JSP, ASP, Jinja2, Velocity), eval(), décodage base64, PHP assert(), create_function(), preg_replace /e |
| **SSTI** | Sondes mathématiques (`{{7*7}}`), import/config Jinja2, templates Velocity, Expression Language |
| **Injection de commande** | Linux (fonctions shell, chaînes de commandes, curl, wget, nc), Windows (cmd.exe, PowerShell, wscript, cscript, net user) |
| **Accès aux fichiers** | Traversée de répertoire, protocoles LFI/RFI, sondes de fichiers sensibles (.env, .git, composer.json) |
| **SSRF** | Localhost (127.0.0.1, 0.0.0.0, ::1), métadonnées AWS/GCP, IP privées, localhost encodé en hex/décimal, DNS rebinding (xip.io, nip.io, sslip.io) |
| **Injection LDAP** | Manipulation de filtre LDAP, injection OR |
| **Injection XPath** | Sélecteurs d'attributs, fonctions XPath (contains, substring) |
| **Injection CRLF / d'en-tête** | CRLF encodé URL (`%0d%0a`), injection LF, injection d'octet nul |
| **Attaques de protocole** | Contrebande de requêtes HTTP (CL+TE), injection SSI |
| **Exploits CVE** | Shellshock (CVE-2014-6271), Spring4Shell (CVE-2022-22965), PHPUnit RCE (CVE-2017-9841), Drupalgeddon, Log4Shell |
| **Suivi de sondes** | WordPress (`/wp-admin`, `/wp-login.php`), fichiers de configuration (`/.env`, `/.git`), outils de base de données (`/phpmyadmin`), sondes technologiques (`.asp`, `.jsp`), Spring actuator, Swagger/API docs - 50+ chemins |
| **Scanners** | SQLMap, Nikto, Nmap, Burp Suite, FeroxBuster, FFUF, XSStrike, Dalfox, Netsparker, Qualys, Nuclei, et 20+ autres (53 au total) |
| **Scrapers IA** | GPTBot, ClaudeBot, ChatGPT, ByteSpider, Cohere, Common Crawl |
| **Navigateurs sans interface** | HeadlessChrome, PhantomJS, Selenium, Puppeteer, Playwright |
| **Bots** | Scripts Python, clients HTTP Go, cURL, wget, AhrefsBot, SEMRushBot, user agents vides |
| **Authentification** | Détection de force brute, fuites de jetons, exposition de mots de passe, exposition d'ID de session |
| **DDoS** | Détection de requêtes excessives basée sur le débit |
| **Évasion** | Insertion de commentaires SQL, double encodage URL, encodage d'entités HTML, échappements Unicode, IIS Unicode, échappements hex |
| **Autre** | Introspection GraphQL, pollution de prototype, redirection ouverte, XXE, web shells, minage de cryptomonnaie, détection de PII |

---

## Exécution de la suite de tests```bash
composer test