Poi aggiungi il middleware al tuo gruppo `web` (una riga in `bootstrap/app.php` su Laravel 11+, oppure `app/Http/Kernel.php` su Laravel 10) — snippet completo in [Guida rapida](#quick-start) di seguito. Tutto qui; il rilevamento è attivo.```bash
php artisan threat-detection:doctor   # confirms it is actually recording

### 2. Pubblica le migrazioni ed eseguile

> **Questo passaggio è obbligatorio.** Senza di esso, il pacchetto rileverà le minacce ma non potrà memorizzarle nel database. Se salti questo passaggio, la tabella `threat_logs` non esisterà e tutte le rilevazioni andranno perse silenziosamente (vedrai solo errori in `storage/logs/laravel.log`).```bash
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate

Cerca `create_threat_logs_table`, `add_confidence_to_threat_logs_table`, e `create_threat_exclusion_rules_table` -  tutte dovrebbero mostrare `Ran`.

### 3. Registra il middleware

Il middleware è ciò che scansiona le richieste. Devi aggiungerlo al tuo gruppo middleware `web`.

**Se usi Laravel 11 o 12** -  apri `bootstrap/app.php`:```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \JayAnta\ThreatDetection\Http\Middleware\ThreatDetectionMiddleware::class,
    ]);
})

### 4. (Opzionale) Pubblica il file di configurazione```bash
php artisan vendor:publish --tag=threat-detection-config

### Passo 2: Apri un URL di test nel tuo browser

Aggiungi un parametro di query dannoso a **qualsiasi route esistente** nella tua app (la tua homepage, una pagina prodotto, ecc.). Per esempio:

**SQL Injection:**```
http://localhost:8000/?q=' UNION SELECT * FROM users--

**Directory Traversal:**```
http://localhost:8000/?file=../../etc/passwd

**Shellshock (CVE-2014-6271):**```
http://localhost:8000/?cmd=() { :;}; /bin/bash

**DROP TABLE (SQL DDL):**```
http://localhost:8000/?q=DROP TABLE users

Dovresti vedere una tabella con `Total Threats`, conteggi di gravità e IP principali.

**Opzione B -  Tinker:**```bash
php artisan tinker

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

### Cose da sapere durante i test

| Comportamento | Spiegazione |
|----------|-------------|
| La stessa minaccia viene registrata solo una volta ogni 5 minuti | Deduplicazione: lo stesso IP + lo stesso tipo di minaccia viene memorizzato nella cache per 5 minuti. Usa **tipi di attacco diversi** per ogni test, oppure attendi tra un test e l'altro. |
| Le richieste `curl` attivano un rilevamento aggiuntivo | Usare `curl` registra anche un rilevamento user-agent "cURL Command" (severità bassa). È previsto -  il pacchetto rileva gli strumenti automatizzati. |
| Il pacchetto non blocca mai le richieste | La tua app continua a funzionare normalmente. Il rilevamento è passivo. |
| Nessuna configurazione Slack necessaria | Le notifiche sono disattivate per impostazione predefinita. |
| Nessuna connessione internet necessaria | Il rilevamento principale è locale al 100%. Solo il comando opzionale `threat-detection:enrich` chiama un'API esterna per i dati geo. |

### Risoluzione dei problemi

**Inizia da qui: un solo comando risponde alla maggior parte delle domande:**```bash
php artisan threat-detection:doctor

Cosa copre: rilevamento abilitato per questo ambiente; ogni colonna di cui lo scrittore ha bisogno (una mancante scarta **ogni** minaccia); colonne dashboard/API; la tabella delle regole di esclusione; se il middleware è effettivamente collegato a una rotta o a un gruppo; configurazione pubblicata che precede questa versione; pattern personalizzati che oscurano quelli integrati; un driver di cache che non può effettuare il conteggio DDoS; e una dashboard o API lasciata aperta senza autenticazione.

**"Ho testato ma `threat-detection:stats` mostra zero minacce" / "Le minacce non vengono salvate nel database"**

Se il doctor ha dato esito positivo, l'installazione è corretta e il problema è la richiesta di test stessa. Tre cose che non può verificare per te:

| Controllo | Come verificarlo |
|-------|---------------|
| IP non in whitelist | Se hai aggiunto `THREAT_DETECTION_WHITELISTED_IPS` al `.env`, rimuovilo durante il test |
| Hai usato una rotta esistente | L'URL di test deve corrispondere a una rotta reale (es. `/`). Un 404 significa che il middleware non è mai stato eseguito |
| Cache di deduplicazione | Stesso IP + stesso tipo di attacco viene memorizzato in cache per 5 minuti -  prova un tipo di attacco diverso |

> Eseguire `php artisan migrate` da solo non è mai sufficiente: i file di migrazione si trovano
> all'interno del pacchetto e devono essere pubblicati nella cartella `database/migrations/`
> prima. Il doctor stampa il comando esatto quando questo è il problema.

**"L'API restituisce 401 Unauthorized"**

Vedi [Autenticazione API](#api-authentication) qui sotto.

**"La dashboard mostra 404"**

La dashboard è disabilitata per impostazione predefinita. Aggiungi `THREAT_DETECTION_DASHBOARD=true` al `.env` e cancella la cache delle rotte:```bash
php artisan route:clear

### Modalità di rilevamento

| Modalità | Soglia di confidenza | Comportamento |
|------|---------------------|----------|
| `strict` | 0 (registra tutto) | Tutti i pattern attivi, soglie minime. Cattura tutto ma potrebbe segnalare traffico legittimo. |
| `balanced` | 10 | Predefinita. Punteggio di confidenza attivo, soglie standard. Adatta alla maggior parte delle app. |
| `relaxed` | 40 | Solo i pattern ad alta gravità attivano. Ideale per siti con molti contenuti e frequenti falsi positivi. |

### Ambienti abilitati

Per impostazione predefinita, il rilevamento viene eseguito in `production`, `staging` e `local`. Per modificare, pubblica la configurazione e modifica:```php
'enabled_environments' => ['production', 'staging', 'local'],

### Riferimento Configurazione

Pubblica il file di configurazione per vedere tutte le opzioni disponibili:```bash
php artisan vendor:publish --tag=threat-detection-config

Lasciare vuoto (predefinito) per analizzare tutte le rotte (soggetto a `skip_paths`). Quando entrambi sono configurati, `only_paths` viene controllato per primo, quindi `skip_paths` si applica all'interno del set corrispondente.

### Supporto alle code

Per impostazione predefinita, la registrazione delle minacce avviene in modo sincrono nel ciclo di richiesta. Per le applicazioni ad alto traffico, puoi scaricare le scritture del database e le notifiche Slack su una coda:```env
THREAT_DETECTION_QUEUE=true
THREAT_DETECTION_QUEUE_CONNECTION=redis
THREAT_DETECTION_QUEUE_NAME=threat-logs

Richiede che lo scheduler di Laravel sia in esecuzione (`php artisan schedule:run`). Viene eseguito ogni giorno alle 02:00 tramite `threat-detection:purge`.

### Evento ThreatDetected

Ogni minaccia confermata emette un evento `ThreatDetected` a cui puoi metterti in ascolto:```php
// app/Providers/EventServiceProvider.php
use JayAnta\ThreatDetection\Events\ThreatDetected;

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

L'evento trasporta `$ipAddress`, `$requestCount`, `$threshold` e `$windowSeconds`. Viene
limitato a una volta per IP per finestra di deduplicazione (stessa limitazione della riga di log), quindi un flood non può
sovrastare i tuoi listener. Usalo per gli avvisi o per alimentare un archivio di ban esterno; per *rifiutare*
i client oltre soglia, usa `ThreatDetection::isDdosThresholdExceeded($ip)` dal tuo
middleware — vedi [Agire sui dati](#acting-on-the-data-operator-side-blocking).

---

## Notifiche Slack

Le notifiche Slack sono disabilitate per impostazione predefinita. Per abilitarle:```env
THREAT_DETECTION_NOTIFICATIONS=true
THREAT_DETECTION_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
THREAT_DETECTION_SLACK_CHANNEL=#threat-alerts

---

## Dashboard

Il pacchetto include una dashboard integrata in modalità scura (Alpine.js + Tailwind CDN -  non è richiesto alcun passaggio di build).```
+-------------------------------------------------------------------------+
|  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                                         |
+-------------------------------------------------------------------------+

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

### Accesso durante lo sviluppo locale

Il dashboard utilizza il middleware `['web', 'auth']` per impostazione predefinita, quindi gli utenti devono aver effettuato l'accesso. Se la tua app non ha ancora un'autenticazione, limitane l'accesso alla tua macchina locale:```env
THREAT_DETECTION_DASHBOARD_GUARD=ip
THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1

**Opzione 2 -  Modificare direttamente il middleware:**```php
// config/threat-detection.php
'api' => [
    'enabled' => true,
    'prefix' => 'api/threat-detection',
    'middleware' => ['api', 'auth'],  // or 'auth:your-guard'
],

> Ripristina l'autenticazione prima di distribuire in produzione.

### Riferimento Endpoint

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/threat-detection/threats` | Elenca le minacce (impaginate, filtrabili) |
| GET | `/api/threat-detection/threats/{id}` | Dettagli di una singola minaccia |
| POST | `/api/threat-detection/threats/{id}/false-positive` | Contrassegna la minaccia come falso positivo |
| GET | `/api/threat-detection/stats` | Statistiche generali |
| GET | `/api/threat-detection/summary` | Ripartizione dettagliata per tipo, livello, IP |
| GET | `/api/threat-detection/live-count` | Minacce nell'ultima ora |
| GET | `/api/threat-detection/by-country` | Raggruppate per paese |
| GET | `/api/threat-detection/by-cloud-provider` | Raggruppate per provider cloud |
| GET | `/api/threat-detection/top-ips` | IP principali responsabili |
| GET | `/api/threat-detection/timeline` | Cronologia delle minacce (per grafici) |
| GET | `/api/threat-detection/ip-stats?ip=x.x.x.x` | Statistiche per un IP specifico |
| GET | `/api/threat-detection/correlation` | Analisi di correlazione |
| GET | `/api/threat-detection/export` | Esporta in CSV |
| GET | `/api/threat-detection/exclusion-rules` | Elenca le regole di esclusione |
| DELETE | `/api/threat-detection/exclusion-rules/{id}` | Elimina una regola di esclusione |

### Parametri di Query per `/threats`

| Parameter | Description |
|-----------|-------------|
| `keyword` | Cerca in IP, URL, tipo |
| `ip` | Filtra per indirizzo IP |
| `level` | Filtra per livello di minaccia (`high`, `medium`, `low`) |
| `type` | Filtra per tipo di minaccia |
| `country` | Filtra per codice paese |
| `is_foreign` | Filtra IP esteri (`true`/`false`) |
| `cloud_provider` | Filtra per provider cloud |
| `is_false_positive` | Filtra per stato di falso positivo (`true`/`false`) |
| `date_from` / `date_to` | Filtro intervallo di date |
| `per_page` | Elementi per pagina (default: 20, max: 100) |

### Esempio di Risposta 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));
}, []);

---

## Agire sui Dati (Blocco Lato Operatore)

Il pacchetto non blocca mai una richiesta — questa è la sua identità, non un comportamento predefinito. Gli export di cui sopra
alimentano i layer di enforcement che già esegui (fail2ban, nginx, un WAF perimetrale). Ma alcune distribuzioni
non hanno alcun layer di questo tipo da alimentare — hosting condiviso, PaaS, container dietro un load balancer che
non controlli. Per queste, il pacchetto espone le sue *decisioni* come helper, e scrivi tu il
middleware di enforcement. Stessa architettura degli export: **noi forniamo l'intelligence, tu la decisione di rifiuto.**```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);
    }
}

Gli helper:

| Helper | Restituisce | Basato su |
|---|---|---|
| `ThreatDetection::isBlocklisted($ip)` | `bool` | config `blocklisted_ips` (CIDR tramite `IpUtils`; la whitelist ha la precedenza) |
| `ThreatDetection::isWhitelisted($ip)` | `bool` | config `whitelisted_ips` |
| `ThreatDetection::ddosRequestCount($ip)` | `int` | il contatore di flood che il middleware di rilevamento mantiene |
| `ThreatDetection::isDdosThresholdExceeded($ip)` | `bool` | quel contatore rispetto a `ddos.threshold` |

Note:

- **La denylist è statica e gestita dall'operatore.** Il pacchetto non vi aggiunge mai
  nulla: esegue la stessa decisione che prenderebbe una jail di fail2ban ("Ho letto la dashboard; questo /24
  è ostile"), solo in-app.
- Il contatore DDoS conta solo le richieste che hanno raggiunto il rilevamento (`skip_paths`, IP in
  whitelist ed environment disabilitati non vengono mai contati), e resta a 0 sui driver di cache dove
  il rilevamento DDoS è disabilitato (`file`, `database`, `null`).
- Quando un client supera la soglia, viene anche inviato un evento [`DdosThresholdExceeded`](#ddosthresholdexceeded-event)
  — utile per generare alert o alimentare una lista di ban esterna. Non chiamare `abort()`
  dal listener, però: i listener vengono eseguiti all'interno del `try/catch` fail-open
  del middleware di rilevamento, quindi il rifiuto spetta al tuo middleware come sopra.

---

## Tracciamento Probe 404

Il pacchetto rileva i probe di ricognizione -  bot che colpiscono percorsi vulnerabili noti come `/wp-admin`, `/.env` o `/phpmyadmin` sul tuo sito non-WordPress e non-phpMyAdmin. Questi non contengono payload maliziosi; il percorso stesso è il segnale.

Vengono registrati con un tag di tipo `[probe]`, separati dal rilevamento basato sul payload. Se una richiesta di probe contiene anche un payload malizioso, entrambi vengono registrati indipendentemente.

Abilitato di default con 50+ percorsi di probe. Personalizza 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...
    ],
],

I campi elencati qui vengono rimossi dai parametri di query e dal corpo della richiesta - sia form-encoded che JSON (`application/json`) - prima che venga eseguito il rilevamento. Gli altri campi sulla stessa richiesta vengono comunque scansionati completamente.

### Safe Paths (path-aware, per API JSON nidificate)

`safe_fields` corrisponde a un nome di chiave **ovunque** appaia. Per le API JSON nidificate questo è spesso troppo ampio: potresti voler esentare il valore di un campo specifico senza esentare quella chiave ovunque. Usa `safe_paths`, che corrisponde per **percorso** in notazione a punti e supporta i caratteri jolly `fnmatch`:```php
// config/threat-detection.php
'safe_paths' => ['search.query', 'filters.*.value'],

Validatori disponibili:

| Validator  | Checksum | Uso tipico |
|------------|----------|-------------|
| `verhoeff` | Verhoeff | Numeri Aadhaar |
| `luhn`     | Luhn     | Numeri di carte di credito/debito |

Con la mappatura inclusa, timestamp, ID ordine e codici a barre che hanno per caso 12 cifre non vengono più registrati come PII — mentre i numeri Aadhaar genuini lo sono ancora. Se più valori corrispondono e solo uno supera il checksum, il rilevamento scatta comunque: un numero reale in mezzo al rumore è comunque una fuga di dati.

Abbina un validatore al tuo pattern personale per il rilevamento delle carte basato su checksum:```php
'custom_patterns'    => ['/\b(?:\d[ -]?){13,19}\b/' => 'Card Number Detected'],
'pattern_validators' => ['Card Number Detected' => 'luhn'],

L'alert, l'endpoint, i nomi dei campi e l'IP dell'attaccante sopravvivono tutti - solo il valore viene rimosso. La redazione viene eseguita *dopo* il rilevamento, quindi non viene perso nulla.```php
// config/threat-detection.php
'redact' => [
    'enabled' => env('THREAT_DETECTION_REDACT', true),
    'mask'    => '[REDACTED]',
    'labels'  => ['Aadhaar Number Detected', 'PAN Number Detected', /* ... */],
],

Le stesse opzioni sono disponibili per le rotte API con `THREAT_DETECTION_API_GUARD`.

Quando `guard=none` (predefinito), il pacchetto registra un avviso una volta al giorno per ricordarti di configurare l'autenticazione.

La guardia **fallisce in modalità chiusa**: un valore di guardia non riconosciuto (ad es. un refuso) viene negato con un 403 e un avviso registrato, piuttosto che consentire l'accesso silenziosamente, e `guard=role` nega (con un avviso) quando il modello utente autenticato non ha un metodo `hasRole()`.

### Disattivare una rilevazione richiede più del solo accesso in lettura

Contrassegnare una minaccia come falso positivo ed eliminare una regola di esclusione silenziano entrambi un tipo di rilevazione per tutti, il che è un privilegio diverso dalla lettura del registro. Questi due endpoint vengono controllati da una guardia separata:```env
# Options: none, auth, role, ip. Default: role
THREAT_DETECTION_API_WRITE_GUARD=role

**Esempio - rilevare una sonda per endpoint admin personalizzato:**```php
'/\/my-admin-panel/i' => 'Custom Admin Panel Probe',

- **`level`** imposta direttamente il livello di minaccia invece di derivarlo dalle parole chiave `threat_levels` nell'etichetta.
- **`contexts`** limita la scansione a segmenti specifici della richiesta — ad esempio un pattern di carta che ha senso solo nel body smette di far corrispondere sequenze di cifre negli header.
- **`validator`** indica un controllo post-match inline (vedi [Validatori post-match](#post-match-validators-checksum-aware-false-positive-reduction)); ha precedenza sulla mappa `pattern_validators` dell'etichetta.

Le voci stringa e array si mescolano liberamente nella stessa configurazione. Le opzioni malformate **fail open** — il pattern continua a scansionare, senza restrizioni, e viene registrato un avviso — quindi un errore di configurazione non può mai disabilitare o restringere silenziosamente una rilevazione.

> **Nota:** I percorsi di probe comuni come `/wp-login.php`, `/.env`, `/phpmyadmin` sono ora gestiti automaticamente dalla funzionalità [Tracciamento dei probe 404](#404-probe-tracking). Non sono necessari pattern personalizzati per questi.

Il livello di minaccia per ogni pattern è determinato automaticamente confrontando le parole chiave nell'etichetta con la configurazione `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'],
],

---

## Passare alla Produzione

Il pacchetto è passivo per progettazione -  non blocca, rifiuta o altera mai una richiesta, e il middleware di rilevamento avvolge tutto il corpo in `try/catch`, quindi un errore di rilevamento non può mai rompere la tua applicazione. Viene fornito con impostazioni predefinite sensate e non richiede servizi esterni per funzionare. Prima di andare in produzione, vale la pena dare un'occhiata a questa breve checklist:

1. **Proteggi la dashboard e l'API.** Entrambe sono impostate di default su `guard = none` per un primo avvio senza configurazione e registrano un avviso giornaliero finché sono non protette. Prima della produzione, imposta una guardia -  `THREAT_DETECTION_DASHBOARD_GUARD` e `THREAT_DETECTION_API_GUARD` (`auth`, `role`, o `ip`). Un valore non riconosciuto o una guardia `role` su un modello utente senza `hasRole()` ora **fallisce in modalità chiusa** (403), quindi un errore di battitura non esporrà silenziosamente i dati. La disattivazione di un rilevamento è limitata separatamente da `THREAT_DETECTION_API_WRITE_GUARD`, che per impostazione predefinita è `role`. Vedi [Autenticazione di Dashboard e API](#dashboard-and-api-authentication).
2. **Esegui le migrazioni** (`vendor:publish --tag=threat-detection-migrations && migrate`). La ripubblicazione è sicura -  le migrazioni già pubblicate vengono saltate.
3. **Scegli una modalità di rilevamento.** `balanced` (predefinita) si adatta alla maggior parte delle app; usa `relaxed` per siti ricchi di contenuti, `strict` per superfici ad alta sicurezza. Ottimizza con `content_paths`, `safe_fields` e `min_confidence` -  vedi [Ridurre i Falsi Positivi](#reducing-false-positives).
4. **Rivedi i pattern PII regionali / personalizzati.** I valori predefiniti sono incentrati sull'India (Aadhaar, PAN, IFSC) e i pattern numerici ampi (es. conto bancario) possono corrispondere a lunghi ID numerici al di fuori delle route di autenticazione. Sostituisci o taglia `custom_patterns` per la tua regione e applicazione, e aggiungi le route ad alto contenuto a `auth_paths` / `content_paths`.
5. **Attiva la conservazione** se prevedi volumi: `THREAT_DETECTION_RETENTION=true` (pulizia automatica tramite lo scheduler). Richiede che lo scheduler di Laravel (`schedule:run`) sia pilotato da cron.
6. **Extra opzionali, tutti disattivati per impostazione predefinita:** avvisi Slack (`THREAT_DETECTION_NOTIFICATIONS`), arricchimento geografico (`php artisan threat-detection:enrich` -  l'unica funzionalità che effettua una chiamata in uscita, al servizio gratuito ip-api.com), e scritture in coda (`THREAT_DETECTION_QUEUE` -  abilita solo se esegui già un worker per le code; altrimenti le scritture sono sincrone e non richiedono Redis).

Per il rilevamento e la registrazione di base non sono richiesti Redis, worker per le code o chiamate di rete in uscita.

---

## Ridurre i Falsi Positivi

Il pacchetto fornisce diversi strumenti per ridurre i falsi positivi. Usa quello che si adatta alla tua situazione:

### Campi Sicuri e Percorsi Sicuri

Escludi un campo dalla scansione completamente, sia per nome ovunque (`safe_fields`) sia tramite percorso in notazione a punti per JSON annidati (`safe_paths`). L'approccio più semplice, e il più drastico -  il campo viene saltato, quindi su di esso non viene eseguito alcun rilevamento.

Dettagli completi ed esempi: [Campi Sicuri](#safe-fields-false-positive-reduction).

### Soppressione dei Percorsi di Contenuto

Se hai editor CMS, moduli di post per blog o sezioni di commenti in cui gli utenti inviano contenuti ricchi, quei percorsi spesso generano falsi positivi (es. un post di blog contenente esempi di codice `<script>`). Aggiungi quei percorsi per sopprimere gli avvisi bassi/medi:```php
// config/threat-detection.php
'content_paths' => [
    'admin/posts/*',
    'admin/pages/*',
    'blog/*/edit',
    'comments',
],

### Punteggio di confidenza

Ogni minaccia riceve un punteggio di confidenza (0-100) basato su:
- Numero di corrispondenze di pattern nella stessa richiesta
- Gravità del pattern corrispondente
- Dove è stato trovato il pattern (query string > headers > body)
- Se lo user-agent corrisponde a uno strumento di attacco noto
- Modalità di rilevamento corrente

Le minacce al di sotto della soglia di confidenza per la tua modalità di rilevamento non vengono registrate (vedi [Modalità di rilevamento](#detection-modes)).

---

## Tipi di attacco rilevati

| Categoria | Esempi |
|----------|---------|
| **SQL Injection** | UNION, booleano, basato sul tempo, codifica CHAR, DDL (DROP/ALTER/CREATE), DML (INSERT/UPDATE/DELETE), operazioni su file (INTO OUTFILE, LOAD_FILE), enumerazione ORDER BY, stringhe esadecimali, UNHEX |
| **NoSQL Injection** | operatori MongoDB $ne, $gt, $regex, $where |
| **XSS** | Tag di script, gestori di eventi SVG (`<svg onload=`), gestori di eventi HTML (`<body onload=`, `<img onerror=`), espressioni CSS, URI JavaScript, manipolazione del DOM |
| **Esecuzione di codice** | funzioni di shell RCE, deserializzazione PHP, deserializzazione Java (byte magici base64 + hex), iniezione di template (Blade, JSP, ASP, Jinja2, Velocity), eval(), decodifica base64, assert() PHP, create_function(), preg_replace /e |
| **SSTI** | Sonde matematiche (`{{7*7}}`), import/config di Jinja2, template Velocity, Expression Language |
| **Iniezione di comandi** | Linux (funzioni di shell, catene di comandi, curl, wget, nc), Windows (cmd.exe, PowerShell, wscript, cscript, net user) |
| **Accesso ai file** | Attraversamento di directory, protocolli LFI/RFI, sonde di file sensibili (.env, .git, composer.json) |
| **SSRF** | Localhost (127.0.0.1, 0.0.0.0, ::1), metadati AWS/GCP, IP privati, localhost codificato in hex/decimale, DNS rebinding (xip.io, nip.io, sslip.io) |
| **Iniezione LDAP** | Manipolazione di filtri LDAP, iniezione OR |
| **Iniezione XPath** | Selettori di attributi, funzioni XPath (contains, substring) |
| **CRLF / Iniezione di header** | CRLF codificato in URL (`%0d%0a`), iniezione LF, iniezione di byte nulli |
| **Attacchi di protocollo** | HTTP request smuggling (CL+TE), iniezione SSI |
| **Exploit CVE** | Shellshock (CVE-2014-6271), Spring4Shell (CVE-2022-22965), PHPUnit RCE (CVE-2017-9841), Drupalgeddon, Log4Shell |
| **Tracciamento dei probe** | WordPress (`/wp-admin`, `/wp-login.php`), file di configurazione (`/.env`, `/.git`), strumenti di database (`/phpmyadmin`), sonde tecnologiche (`.asp`, `.jsp`), Spring actuator, documentazione Swagger/API -  50+ percorsi |
| **Scanner** | SQLMap, Nikto, Nmap, Burp Suite, FeroxBuster, FFUF, XSStrike, Dalfox, Netsparker, Qualys, Nuclei e altri 20+ (53 in totale) |
| **Scraper IA** | GPTBot, ClaudeBot, ChatGPT, ByteSpider, Cohere, Common Crawl |
| **Browser headless** | HeadlessChrome, PhantomJS, Selenium, Puppeteer, Playwright |
| **Bot** | Script Python, client HTTP Go, cURL, wget, AhrefsBot, SEMRushBot, user agent vuoti |
| **Autenticazione** | Rilevamento di brute force, perdite di token, esposizione di password, esposizione di session ID |
| **DDoS** | Rilevamento di richieste eccessive basato sulla frequenza |
| **Evasione** | Inserimento di commenti SQL, doppia codifica URL, codifica entità HTML, escape Unicode, IIS Unicode, escape hex |
| **Altro** | Introspezione GraphQL, prototype pollution, open redirect, XXE, web shell, crypto mining, rilevamento di PII |

---

## Esecuzione della suite di test```bash
composer test