Esas solicitudes ya están llegando a tu aplicación Laravel. Tu registro de acceso muestra la URL
y el código de estado, y nada más — ni el payload decodificado, ni a cuál de tus
rutas se dirigió, ni si la misma IP ha intentado otras cuarenta cosas en esta hora.

Este paquete responde a esas preguntas. Introdúcelo en cualquier aplicación Laravel 10–13 y comenzará
a escanear cada solicitud HTTP contra más de 150 patrones de ataque, puntuando cada coincidencia por
confianza y escribiéndola en tu base de datos — con un panel integrado, alertas de Slack,
enriquecimiento geográfico y exportaciones para fail2ban/listas de bloqueo. Ninguna solicitud se bloquea jamás. Piensa en
una cámara de seguridad, no en un candado: te muestra exactamente quién está sondeando tus rutas, con qué
frecuencia y con qué técnicas.

> Extraído de una aplicación en producción y probado en tráfico real. 335 pruebas, sin dependencias
> de ejecución más allá del propio Laravel, y sin necesidad de conexión a internet para la detección.
>
> ¿Actualizando? Consulta [UPGRADING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/UPGRADING.md). ¿Contribuyendo? Consulta [CONTRIBUTING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/CONTRIBUTING.md).

## Empieza en menos de un minuto```bash
composer require jayanta/laravel-threat-detection
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate

---

## Dónde encaja: IDS vs WAF vs edge

Este paquete es un **IDS pasivo a nivel de aplicación** — observa y registra, no
bloquea. Está pensado para situarse *junto a* un WAF o un servicio edge, no para
sustituirlo. Cada capa ve algo que las demás no pueden ver:

| | **Este paquete** (IDS de app) | **WAF** (mod_security, Cloudflare WAF) | **Edge / CDN** (Cloudflare) |
|---|:---:|:---:|:---:|
| Bloquea peticiones maliciosas | ❌ solo registra | ✅ | ✅ |
| Contexto completo de la app (ruta exacta, payload decodificado, usuario autenticado) | ✅ | ⚠️ parcial | ❌ |
| Panel integrado + registro de amenazas en tu BD | ✅ | ⚠️ varía | ⚠️ solo edge |
| Detecciones específicas de la app (p. ej. PII de Aadhaar / PAN / IFSC) | ✅ patrones personalizados | ❌ | ❌ |
| Funciona sin conexión / sin servicio externo | ✅ | ⚠️ depende | ❌ |
| Detiene el tráfico antes de que llegue a tu app | ❌ | ✅ edge | ✅ |
| Configuración | un `composer require` | media–alta | baja–media |
| Coste | gratis, MIT | varía | nivel gratuito + de pago |

**La versión corta:** un edge/WAF es tu cerradura en la puerta; esto es la cámara de
seguridad *del interior*, con el contexto de la app para decirte exactamente qué se está
intentando en cada ruta, por quién y con qué frecuencia. Úsalo para alimentar decisiones
reales — baneos de fail2ban, límites de tasa, bloqueo geográfico — con datos que tu capa
edge nunca ve.

### Lo que deliberadamente NO es

- **No es un WAF.** Nunca bloquea, filtra ni modifica una petición. Usa Cloudflare,
  mod_security o un WAF real para la aplicación de políticas. (¿No tienes capa edge a la
  que delegar? Los [helpers del lado del operador](#acting-on-the-data-operator-side-blocking)
  exponen las decisiones del paquete para que escribas tu propio middleware de bloqueo de
  cinco líneas — el código de aplicación de políticas sigue siendo tuyo, no del paquete.)
- **No sustituye a la codificación segura.** Las consultas parametrizadas, la validación de
  entrada y el escape de salida son tus defensas reales. Este paquete asume que tu código ya
  es seguro y te da *visibilidad*, no protección.
- **No es un servicio edge.** Si puedes poner Cloudflare delante, hazlo — y luego añade esto
  para el detalle a nivel de aplicación que los servicios edge no pueden ver.

### Entonces, ¿qué haces realmente con él?

La pregunta más común sobre un detector que nunca bloquea. Cuatro respuestas, en
orden creciente de esfuerzo:

| Quieres | Usa | Esfuerzo |
|---|---|---|
| Ver qué te está atacando | El [panel](#dashboard) o `threat-detection:stats` | ninguno, ya está en ejecución |
| Banear a los reincidentes en el firewall | [`threat-detection:export-fail2ban`](#artisan-commands) — canalízalo a un cron | una línea |
| Denegar en el servidor web | [`threat-detection:export-blocklist`](#artisan-commands) → directivas de nginx/apache | una línea |
| Rechazar peticiones en la app | [Helpers del lado del operador](#acting-on-the-data-operator-side-blocking) — `isBlocklisted()`, `isDdosThresholdExceeded()` | ~10 líneas de tu propio middleware |
| Reaccionar en tiempo real | El [evento `ThreatDetected`](#threatdetected-event) — Telegram, SIEM, PagerDuty | un listener |

El paquete aporta la inteligencia; tú aportas el rechazo. Esa división es
deliberada — el código de aplicación de políticas que vive en tu app es código que puedes
leer, probar y desactivar, y significa que un fallo de detección nunca puede tumbar tu sitio.

### Cómo se compara con otros paquetes de seguridad de Laravel

Estos resuelven problemas distintos y se complementan bien — la tabla trata de elegir la
herramienta adecuada, no de ganar.

| Paquete | Qué hace | ¿Bloquea? | Úsalo cuando |
|---|---|:---:|---|
| **este paquete** | Escanea cada petición contra más de 150 patrones, registra con contexto completo de la app | ❌ | Quieres *ver* qué se está intentando contra tu app |
| `spatie/laravel-honeypot` | Campo de formulario oculto que atrapa bots de spam | ✅ solo formulario | Tienes formularios públicos que reciben spam |
| `graham-campbell/security` | Elimina marcado tipo XSS de la entrada | ✅ muta | Quieres saneamiento ingenuo de entrada |
| `spatie/laravel-csp` | Envía cabeceras Content-Security-Policy | ✅ navegador | Quieres restringir lo que carga el navegador |
| `laravel/fortify` + límites de tasa | Limitación de autenticación y bloqueo | ✅ | Necesitas protección contra fuerza bruta en el inicio de sesión |
| Cloudflare / mod_security | WAF edge, bloquea antes de tu app | ✅ | Quieres que el tráfico se detenga antes de llegar |

El resumen honesto: un honeypot atrapa el spam de formularios, un WAF bloquea el tráfico
conocido como malo en el edge y CSP restringe el navegador. **Ninguno de ellos te dice qué
intentó un atacante contra tus rutas específicas, con el payload decodificado y el usuario
autenticado adjunto.** Ese vacío es lo que esto cubre — y es por eso que el paquete
deliberadamente no bloquea: puedes ejecutarlo junto a todo lo anterior
sin que ninguno interfiera con los demás.

---

## Requisitos

- PHP 8.2+ (Laravel 13 requiere PHP 8.3+)
- Laravel 10.x, 11.x, 12.x o 13.x
- Cualquier base de datos compatible con Laravel (MySQL, PostgreSQL, SQLite, SQL Server)
- Cualquier driver de caché — **no se requiere Redis ni worker de colas**. Redis/Memcached
  solo se *recomienda* para habilitar la comprobación opcional de DDoS (que se desactiva
  automáticamente en drivers no atómicos). Las escrituras en cola son opcionales y están
  desactivadas por defecto.

---

## Cómo funciona

1. Un middleware escanea cada petición HTTP entrante
2. La petición se comprueba contra 158 patrones regex que cubren inyección SQL, XSS, RCE, traversal de archivos, SSRF, LDAP, XPath, SSTI y más
3. Si un patrón de amenaza coincide, se escribe un registro en tu tabla de base de datos `threat_logs` con la IP, la URL, el tipo de amenaza, el nivel de severidad y una puntuación de confianza
4. Opcionalmente, se envía una alerta de Slack para amenazas de alta severidad
5. La petición continúa con normalidad — **no se bloquea nada**

No se necesita conexión a internet para la detección.

---

## Inicio rápido

### 1. Instala el paquete```bash
composer require jayanta/laravel-threat-detection

Esto crea dos tablas: `threat_logs` (almacena amenazas detectadas) y `threat_exclusion_rules` (almacena reglas de falsos positivos).

**Verifica que las tablas se hayan creado:**```bash
php artisan migrate:status

> **Cómo comprobar tu versión de Laravel:** Ejecuta `php artisan --version` en tu terminal.

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

El paquete funciona con valores predeterminados sensatos. Publicar la configuración te permite personalizar los patrones de detección, los modos de sensibilidad, las notificaciones de Slack y más. Si omites este paso, todo sigue funcionando.

**Eso es todo.** Tu aplicación ahora está detectando amenazas.

---

## Verifica que funciona

Después de la instalación, activa una amenaza de prueba y confirma que se registró.

### Paso 1: Inicia tu aplicación```bash
php artisan serve

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

**RCE (Ejecución Remota de Código):**```
http://localhost:8000/?cmd=system('ls -la')

**Inyección de comandos en Windows:**```
http://localhost:8000/?cmd=powershell -c whoami

> Usa una ruta que realmente exista en tu aplicación (como `/`). Si la URL devuelve un 404, es posible que el middleware no se haya ejecutado.

### Paso 3: Verifica que las amenazas se hayan registrado

**Opción A - Comando de Artisan (la más rápida):**```bash
php artisan threat-detection:stats

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

### Cosas a tener en cuenta al probar

| Comportamiento | Explicación |
|----------|-------------|
| La misma amenaza solo se registra una vez cada 5 minutos | Deduplicación: la misma IP + el mismo tipo de amenaza se almacena en caché durante 5 minutos. Usa **tipos de ataque diferentes** para cada prueba, o espera entre pruebas. |
| Las solicitudes `curl` activan detección adicional | Usar `curl` también registra una detección de user-agent "cURL Command" (severidad baja). Esto es esperado: el paquete detecta herramientas automatizadas. |
| El paquete nunca bloquea solicitudes | Tu aplicación sigue funcionando con normalidad. La detección es pasiva. |
| No se necesita configuración de Slack | Las notificaciones están desactivadas por defecto. |
| No se necesita conexión a internet | La detección principal es 100 % local. Solo el comando opcional `threat-detection:enrich` llama a una API externa para datos geográficos. |

### Solución de problemas

**Empieza aquí: un solo comando responde la mayoría de esto:**```bash
php artisan threat-detection:doctor

Qué cubre: detección habilitada para este entorno; cada columna que el escritor
necesita (una que falte descarta **todas** las amenazas); columnas del panel/API; la
tabla de reglas de exclusión; si el middleware está realmente conectado a una ruta o
grupo; configuración publicada que es anterior a esta versión; patrones personalizados que
ocultan los integrados; un controlador de caché que no puede realizar el conteo de DDoS; y un panel o
API dejados abiertos sin autenticación.

**"Probé pero `threat-detection:stats` muestra cero amenazas" / "Las amenazas no se almacenan en la base de datos"**

Si el doctor pasó, la instalación está bien y el problema es la solicitud de prueba
en sí. Tres cosas que no puede verificar por ti:

| Comprobación | Cómo verificar |
|-------|---------------|
| La IP no está en la lista blanca | Si agregaste `THREAT_DETECTION_WHITELISTED_IPS` a `.env`, elimínalo durante las pruebas |
| Se usó una ruta existente | La URL de prueba debe coincidir con una ruta real (p. ej., `/`). Un 404 significa que el middleware nunca se ejecutó |
| Caché de deduplicación | Misma IP + mismo tipo de ataque se almacena en caché durante 5 minutos: prueba con un tipo de ataque diferente |

> Ejecutar `php artisan migrate` por sí solo nunca es suficiente: los archivos de migración viven
> dentro del paquete y deben publicarse en `database/migrations/` de tu aplicación
> primero. El doctor imprime el comando exacto cuando este es el problema.

**"La API devuelve 401 Unauthorized"**

Consulta [Autenticación de API](#api-authentication) a continuación.

**"El panel muestra 404"**

El panel está deshabilitado por defecto. Agrega `THREAT_DETECTION_DASHBOARD=true` a `.env` y limpia la caché de rutas:```bash
php artisan route:clear

### Modos de Detección

| Modo | Umbral de Confianza | Comportamiento |
|------|---------------------|----------|
| `strict` | 0 (registra todo) | Todos los patrones activos, umbrales más bajos. Detecta todo, pero puede marcar tráfico legítimo. |
| `balanced` | 10 | Predeterminado. Puntuación de confianza activa, umbrales estándar. Bueno para la mayoría de las aplicaciones. |
| `relaxed` | 40 | Solo se activan los patrones de alta severidad. Ideal para sitios con mucho contenido y falsos positivos frecuentes. |

### Entornos Habilitados

Por defecto, la detección se ejecuta en `production`, `staging` y `local`. Para cambiarlo, publique la configuración y edite:```php
'enabled_environments' => ['production', 'staging', 'local'],

### Referencia de configuración

Publica el archivo de configuración para ver todas las opciones disponibles:```bash
php artisan vendor:publish --tag=threat-detection-config

Déjalo vacío (por defecto) para escanear todas las rutas (sujeto a `skip_paths`). Cuando ambos están configurados, `only_paths` se comprueba primero y luego `skip_paths` se aplica dentro del conjunto coincidente.

### Soporte de colas

Por defecto, el registro de amenazas ocurre de forma síncrona en el ciclo de solicitud. Para aplicaciones de alto tráfico, puedes descargar las escrituras en la base de datos y las notificaciones de Slack a una cola:```env
THREAT_DETECTION_QUEUE=true
THREAT_DETECTION_QUEUE_CONNECTION=redis
THREAT_DETECTION_QUEUE_NAME=threat-logs

Requiere que el programador de Laravel esté en ejecución (`php artisan schedule:run`). Se ejecuta diariamente a las 02:00 mediante `threat-detection:purge`.

### Evento ThreatDetected

Cada amenaza confirmada despacha un evento `ThreatDetected` al que puedes suscribirte:```php
// app/Providers/EventServiceProvider.php
use JayAnta\ThreatDetection\Events\ThreatDetected;

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

El evento lleva `$ipAddress`, `$requestCount`, `$threshold` y `$windowSeconds`. Se
limita a una vez por IP por ventana de deduplicación (el mismo límite que la fila de registro), por lo que una inundación no puede
ahogar tus listeners. Úsalo para alertas o para alimentar un almacén de baneo externo; para *rechazar*
clientes que superen el umbral, usa `ThreatDetection::isDdosThresholdExceeded($ip)` desde tu propio
middleware en su lugar — consulta [Actuando sobre los datos](#acting-on-the-data-operator-side-blocking).

---

## Notificaciones de Slack

Las alertas de Slack están deshabilitadas por defecto. Para habilitarlas:```env
THREAT_DETECTION_NOTIFICATIONS=true
THREAT_DETECTION_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
THREAT_DETECTION_SLACK_CHANNEL=#threat-alerts

---

## Panel de control

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12500/fc7950bd0cc6323bcc2d62b03e31c99edc7450b0ef76f9cbfa5133b527b25269.png" alt="Panel de detección de amenazas: estadísticas, cronología de 7 días, registro de amenazas en vivo, principales IP infractoras y amenazas por país" width="100%">
</p>

El paquete incluye un panel de control integrado con modo oscuro (Alpine.js + Tailwind CDN, sin necesidad de paso de compilación).```
+-------------------------------------------------------------------------+
|  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`

### Acceso durante el desarrollo local

El panel utiliza el middleware `['web', 'auth']` por defecto, por lo que los usuarios deben haber iniciado sesión. Si tu aplicación aún no tiene autenticación, restringe el acceso solo a tu propia máquina:```env
THREAT_DETECTION_DASHBOARD_GUARD=ip
THREAT_DETECTION_DASHBOARD_IPS=127.0.0.1

**Opción 2: Modificar el middleware directamente:**```php
// config/threat-detection.php
'api' => [
    'enabled' => true,
    'prefix' => 'api/threat-detection',
    'middleware' => ['api', 'auth'],  // or 'auth:your-guard'
],

> Restaure la autenticación antes de implementar en producción.

### Referencia de Endpoints

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | `/api/threat-detection/threats` | Listar amenazas (paginadas, filtrables) |
| GET | `/api/threat-detection/threats/{id}` | Detalles de una sola amenaza |
| POST | `/api/threat-detection/threats/{id}/false-positive` | Marcar amenaza como falso positivo |
| GET | `/api/threat-detection/stats` | Estadísticas generales |
| GET | `/api/threat-detection/summary` | Desglose detallado por tipo, nivel, IP |
| GET | `/api/threat-detection/live-count` | Amenazas en la última hora |
| GET | `/api/threat-detection/by-country` | Agrupadas por país |
| GET | `/api/threat-detection/by-cloud-provider` | Agrupadas por proveedor de nube |
| GET | `/api/threat-detection/top-ips` | IPs más infractoras |
| GET | `/api/threat-detection/timeline` | Línea temporal de amenazas (para gráficos) |
| GET | `/api/threat-detection/ip-stats?ip=x.x.x.x` | Estadísticas para una IP específica |
| GET | `/api/threat-detection/correlation` | Análisis de correlación |
| GET | `/api/threat-detection/export` | Exportar a CSV |
| GET | `/api/threat-detection/exclusion-rules` | Listar reglas de exclusión |
| DELETE | `/api/threat-detection/exclusion-rules/{id}` | Eliminar una regla de exclusión |

### Parámetros de Consulta para `/threats`

| Parámetro | Descripción |
|-----------|-------------|
| `keyword` | Buscar en IP, URL, tipo |
| `ip` | Filtrar por dirección IP |
| `level` | Filtrar por nivel de amenaza (`high`, `medium`, `low`) |
| `type` | Filtrar por tipo de amenaza |
| `country` | Filtrar por código de país |
| `is_foreign` | Filtrar IPs extranjeras (`true`/`false`) |
| `cloud_provider` | Filtrar por proveedor de nube |
| `is_false_positive` | Filtrar por estado de falso positivo (`true`/`false`) |
| `date_from` / `date_to` | Filtro de rango de fechas |
| `per_page` | Elementos por página (predeterminado: 20, máximo: 100) |

### Ejemplo de Respuesta de la 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));
}, []);

---

## Actuando sobre los Datos (Bloqueo del Lado del Operador)

El paquete nunca bloquea una solicitud — esa es su identidad, no un valor predeterminado. Las exportaciones anteriores
alimentan las capas de aplicación de políticas que ya ejecutas (fail2ban, nginx, un WAF perimetral). Pero algunos despliegues
no tienen tal capa a la que alimentar — hosting compartido, PaaS, contenedores detrás de un balanceador de carga que
no controlas. Para esos casos, el paquete expone sus *decisiones* como ayudantes, y tú escribes el
middleware de aplicación de políticas tú mismo. Misma arquitectura que las exportaciones: **nosotros suministramos la
inteligencia, tú suministras la denegación.**```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);
    }
}

Los helpers:

| Helper | Devuelve | Respaldado por |
|---|---|---|
| `ThreatDetection::isBlocklisted($ip)` | `bool` | config `blocklisted_ips` (CIDR vía `IpUtils`; la whitelist tiene prioridad) |
| `ThreatDetection::isWhitelisted($ip)` | `bool` | config `whitelisted_ips` |
| `ThreatDetection::ddosRequestCount($ip)` | `int` | el contador de inundación que mantiene el middleware de detección |
| `ThreatDetection::isDdosThresholdExceeded($ip)` | `bool` | ese contador frente a `ddos.threshold` |

Notas:

- **La lista de bloqueo es estática y mantenida por el operador.** Nada en el paquete añade
  elementos a ella — ejecuta la misma decisión que tomaría un jail de fail2ban ("leí el panel; este /24
  es hostil"), solo que dentro de la aplicación.
- El contador DDoS cuenta únicamente las peticiones que llegaron a la detección (`skip_paths`, IPs
  en whitelist y entornos deshabilitados nunca se cuentan), y permanece en 0 en drivers de caché donde
  la detección DDoS está deshabilitada (`file`, `database`, `null`).
- Cuando un cliente supera el umbral, también se despacha un [`DdosThresholdExceeded` event](#ddosthresholdexceeded-event)
  — útil para alertar o alimentar una lista de bloqueo externa. No llames a `abort()`
  desde el listener, sin embargo: los listeners se ejecutan dentro del `try/catch` de fail-open
  del middleware de detección, así que el rechazo pertenece a tu propio middleware como se indicó antes.

---

## Seguimiento de Sondas 404

El paquete detecta sondas de reconocimiento — bots que golpean rutas vulnerables conocidas como `/wp-admin`, `/.env` o `/phpmyadmin` en tu sitio que no es WordPress ni phpMyAdmin. Estas no tienen payload malicioso; la ruta en sí es la señal.

Se registran con una etiqueta de tipo `[probe]`, separada de la detección basada en payload. Si una petición de sonda también contiene un payload malicioso, ambas se registran de forma independiente.

Habilitado por defecto con más de 50 rutas de sonda. Personalízalo en `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...
    ],
],

Los campos que se listan aquí se eliminan de los parámetros de consulta y del cuerpo de la solicitud — tanto codificado como formulario como JSON (`application/json`) — antes de que se ejecute la detección. Otros campos en la misma solicitud aún se escanean por completo.

### Rutas seguras (conscientes de la ruta, para APIs JSON anidadas)

`safe_fields` coincide con un nombre de clave **en cualquier lugar** donde aparezca. Para APIs JSON anidadas, eso suele ser demasiado amplio: es posible que quieras eximir el valor de un campo específico sin eximir esa clave en todas partes. Usa `safe_paths`, que coincide por **ruta** en notación de puntos y admite comodines `fnmatch`:```php
// config/threat-detection.php
'safe_paths' => ['search.query', 'filters.*.value'],

Validadores disponibles:

| Validador  | Checksum | Uso típico |
|------------|----------|-------------|
| `verhoeff` | Verhoeff | Números Aadhaar |
| `luhn`     | Luhn     | Números de tarjetas de crédito/débito |

Con la asignación incluida, las marcas de tiempo, los IDs de pedido y los códigos de barras que casualmente tienen 12 dígitos ya no se registran como PII, mientras que los números Aadhaar genuinos sí lo siguen siendo. Si varios valores coinciden y solo uno pasa el checksum, la detección sigue activándose: un número real entre ruido sigue siendo una fuga.

Combina un validador con tu propio patrón para la detección de tarjetas con verificación de checksum:```php
'custom_patterns'    => ['/\b(?:\d[ -]?){13,19}\b/' => 'Card Number Detected'],
'pattern_validators' => ['Card Number Detected' => 'luhn'],

La alerta, el endpoint, los nombres de los campos y la IP atacante se conservan; solo se elimina el valor. La redacción se ejecuta *después* de la detección, por lo que nada se pierde.```php
// config/threat-detection.php
'redact' => [
    'enabled' => env('THREAT_DETECTION_REDACT', true),
    'mask'    => '[REDACTED]',
    'labels'  => ['Aadhaar Number Detected', 'PAN Number Detected', /* ... */],
],

Las mismas opciones están disponibles para las rutas de API con `THREAT_DETECTION_API_GUARD`.

Cuando `guard=none` (valor predeterminado), el paquete registra una advertencia una vez al día para recordarte que configures la autenticación.

La protección **falla de forma segura**: un valor de guard no reconocido (p. ej., un error tipográfico) se deniega con un 403 y una advertencia registrada en lugar de conceder acceso silenciosamente, y `guard=role` deniega (con una advertencia) cuando el modelo de usuario autenticado no tiene un método `hasRole()`.

### Deshabilitar una detección requiere más que acceso de lectura

Marcar una amenaza como falso positivo y eliminar una regla de exclusión silencian un tipo de detección para todos, lo cual es un privilegio distinto al de leer el registro. Esos dos endpoints se verifican contra una protección separada:```env
# Options: none, auth, role, ip. Default: role
THREAT_DETECTION_API_WRITE_GUARD=role

**Ejemplo: detectar una sonda de endpoint de administración personalizada:**```php
'/\/my-admin-panel/i' => 'Custom Admin Panel Probe',

- **`level`** establece el nivel de amenaza directamente en lugar de derivarlo de las palabras clave de `threat_levels` en la etiqueta.
- **`contexts`** restringe el escaneo a segmentos específicos de la solicitud — p. ej., un patrón de tarjeta que solo tiene sentido en el cuerpo deja de coincidir con secuencias de dígitos en las cabeceras.
- **`validator`** nombra una comprobación posterior a la coincidencia en línea (consulta [Validadores posteriores a la coincidencia](#post-match-validators-checksum-aware-false-positive-reduction)); tiene prioridad sobre el mapa de etiquetas `pattern_validators`.

Las entradas de cadenas y matrices se combinan libremente en la misma configuración. Las opciones malformadas **fallan abiertamente** — el patrón sigue escaneando, sin restricciones, y se registra una advertencia — por lo que un error de configuración nunca puede deshabilitar o estrechar silenciosamente una detección.

> **Nota:** Las rutas de sondeo comunes como `/wp-login.php`, `/.env`, `/phpmyadmin` ahora se gestionan automáticamente mediante la función de [Seguimiento de sondeos 404](#404-probe-tracking). No necesitas patrones personalizados para esas.

El nivel de amenaza para cada patrón se determina automáticamente al comparar palabras clave en la etiqueta con la configuración de `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'],
],

---

## Puesta en Producción

El paquete es pasivo por diseño: nunca bloquea, rechaza ni altera una solicitud, y el middleware de detección envuelve todo su cuerpo en `try/catch`, por lo que un fallo de detección nunca puede romper tu aplicación. Incluye valores predeterminados sensatos y no necesita servicios externos para funcionar. Antes de salir a producción, vale la pena revisar esta breve lista de verificación:

1. **Protege el panel y la API.** Ambos usan `guard = none` por defecto para una primera ejecución sin configuración, y registran una advertencia diaria mientras estén desprotegidos. Antes de producción, establece un guard: `THREAT_DETECTION_DASHBOARD_GUARD` y `THREAT_DETECTION_API_GUARD` (`auth`, `role` o `ip`). Un valor no reconocido o un guard `role` en un modelo de usuario sin `hasRole()` ahora **falla de forma segura** (403), por lo que un error tipográfico no expondrá datos silenciosamente. Deshabilitar una detección se controla por separado con `THREAT_DETECTION_API_WRITE_GUARD`, que por defecto es `role`. Consulta [Autenticación del Panel y la API](#dashboard-and-api-authentication).
2. **Ejecuta las migraciones** (`vendor:publish --tag=threat-detection-migrations && migrate`). Volver a publicar es seguro: las migraciones ya publicadas se omiten.
3. **Elige un modo de detección.** `balanced` (predeterminado) se adapta a la mayoría de las aplicaciones; usa `relaxed` para sitios con mucho contenido, `strict` para superficies de alta seguridad. Ajusta con `content_paths`, `safe_fields` y `min_confidence`: consulta [Reducción de Falsos Positivos](#reducing-false-positives).
4. **Revisa los patrones regionales de PII / personalizados.** Los valores predeterminados están centrados en India (Aadhaar, PAN, IFSC) y los patrones numéricos amplios (por ejemplo, cuentas bancarias) pueden coincidir con IDs numéricos largos fuera de las rutas de autenticación. Reemplaza o recorta `custom_patterns` para tu región y aplicación, y añade rutas con mucho contenido a `auth_paths` / `content_paths`.
5. **Activa la retención** si esperas volumen: `THREAT_DETECTION_RETENTION=true` (purga automática mediante el programador). Requiere que el programador de Laravel (`schedule:run`) esté controlado por cron.
6. **Extras opcionales, todos desactivados por defecto:** alertas de Slack (`THREAT_DETECTION_NOTIFICATIONS`), enriquecimiento geográfico (`php artisan threat-detection:enrich` — la única función que realiza una llamada saliente, al gratuito ip-api.com) y escrituras en cola (`THREAT_DETECTION_QUEUE` — actívalo solo si ya ejecutas un worker de cola; de lo contrario, las escrituras son síncronas y no necesitan Redis).

No se requieren Redis, worker de cola ni llamadas de red salientes para la detección y el registro principales.

---

## Reducción de Falsos Positivos

El paquete proporciona múltiples herramientas para reducir los falsos positivos. Usa la que se adapte a tu situación:

### Campos Seguros y Rutas Seguras

Excluye un campo del escaneo por completo, ya sea por nombre en todas partes (`safe_fields`) o por ruta con notación de puntos para JSON anidado (`safe_paths`). Es el enfoque más simple y el más contundente: el campo se omite, por lo que no se ejecuta ninguna detección sobre él.

Detalles completos y ejemplos: [Campos Seguros](#safe-fields-false-positive-reduction).

### Supresión de Rutas de Contenido

Si tienes editores de CMS, formularios de publicaciones de blog o secciones de comentarios donde los usuarios envían contenido enriquecido, esas rutas suelen provocar falsos positivos (por ejemplo, una publicación de blog que contiene ejemplos de código `<script>`). Añade esas rutas para suprimir alertas de baja/media gravedad:```php
// config/threat-detection.php
'content_paths' => [
    'admin/posts/*',
    'admin/pages/*',
    'blog/*/edit',
    'comments',
],

### Puntuación de Confianza

Cada amenaza recibe una puntuación de confianza (0-100) basada en:
- Número de coincidencias de patrones en la misma solicitud
- Gravedad del patrón coincidente
- Dónde se encontró el patrón (cadena de consulta > cabeceras > cuerpo)
- Si el user-agent coincide con una herramienta de ataque conocida
- Modo de detección actual

Las amenazas por debajo del umbral de confianza para tu modo de detección no se registran (consulta [Modos de Detección](#modos-de-detección)).

---

## Tipos de Ataques Detectados

| Categoría | Ejemplos |
|----------|---------|
| **Inyección SQL** | UNION, booleana, basada en tiempo, codificación CHAR, DDL (DROP/ALTER/CREATE), DML (INSERT/UPDATE/DELETE), operaciones de archivo (INTO OUTFILE, LOAD_FILE), enumeración ORDER BY, cadenas hexadecimales, UNHEX |
| **Inyección NoSQL** | Operadores de MongoDB $ne, $gt, $regex, $where |
| **XSS** | Etiquetas de script, manejadores de eventos SVG (`<svg onload=`), manejadores de eventos HTML (`<body onload=`, `<img onerror=`), expresiones CSS, URIs JavaScript, manipulación del DOM |
| **Ejecución de Código** | Funciones de shell RCE, deserialización PHP, deserialización Java (bytes mágicos base64 + hex), inyección de plantillas (Blade, JSP, ASP, Jinja2, Velocity), eval(), decodificación base64, assert() de PHP, create_function(), preg_replace /e |
| **SSTI** | Sondeos matemáticos (`{{7*7}}`), import/config de Jinja2, plantillas Velocity, Lenguaje de Expresión |
| **Inyección de Comandos** | Linux (funciones de shell, cadenas de comandos, curl, wget, nc), Windows (cmd.exe, PowerShell, wscript, cscript, net user) |
| **Acceso a Archivos** | Traversal de directorios, protocolos LFI/RFI, sondeos de archivos sensibles (.env, .git, composer.json) |
| **SSRF** | Localhost (127.0.0.1, 0.0.0.0, ::1), metadatos AWS/GCP, IPs privadas, localhost codificado en hex/decimal, rebinding DNS (xip.io, nip.io, sslip.io) |
| **Inyección LDAP** | Manipulación de filtros LDAP, inyección OR |
| **Inyección XPath** | Selectores de atributos, funciones XPath (contains, substring) |
| **Inyección CRLF / Cabeceras** | CRLF codificado en URL (`%0d%0a`), inyección LF, inyección de byte nulo |
| **Ataques de Protocolo** | Contrabando de solicitudes HTTP (CL+TE), inyección SSI |
| **Exploits CVE** | Shellshock (CVE-2014-6271), Spring4Shell (CVE-2022-22965), RCE PHPUnit (CVE-2017-9841), Drupalgeddon, Log4Shell |
| **Seguimiento de Sondeos** | WordPress (`/wp-admin`, `/wp-login.php`), archivos de configuración (`/.env`, `/.git`), herramientas de bases de datos (`/phpmyadmin`), sondeos de tecnología (`.asp`, `.jsp`), actuator de Spring, documentación Swagger/API - más de 50 rutas |
| **Escáneres** | SQLMap, Nikto, Nmap, Burp Suite, FeroxBuster, FFUF, XSStrike, Dalfox, Netsparker, Qualys, Nuclei, y más de 20 otros (53 en total) |
| **Raspadores de IA** | GPTBot, ClaudeBot, ChatGPT, ByteSpider, Cohere, Common Crawl |
| **Navegadores Headless** | HeadlessChrome, PhantomJS, Selenium, Puppeteer, Playwright |
| **Bots** | Scripts Python, clientes HTTP Go, cURL, wget, AhrefsBot, SEMRushBot, user agents vacíos |
| **Autenticación** | Detección de fuerza bruta, fugas de tokens, exposición de contraseñas, exposición de ID de sesión |
| **DDoS** | Detección de solicitudes excesivas basadas en tasa |
| **Evasión** | Inserción de comentarios SQL, doble codificación URL, codificación de entidades HTML, escapes Unicode, IIS Unicode, escapes hex |
| **Otros** | Introspección GraphQL, contaminación de prototipos, redirección abierta, XXE, webshells, minería de criptomonedas, detección de PII |

---

## Ejecución del Conjunto de Pruebas```bash
composer test