# Eventos de seguridad

> Busca, filtra y sigue en directo cada petición que el borde ha bloqueado, desafiado o registrado, desde el panel o la API.

Un **evento de seguridad** se registra cuando el borde bloquea, desafía o registra una petición: una regla del WAF, un límite de peticiones, una regla de IP o de país, un escudo o un error de TLS con el origen (`525`/`526`). Los eventos llegan al panel poco después de producirse y se conservan 30 días.

## Campos del evento

| Campo | Significado |
|---|---|
| `ts` | Hora de la petición. |
| `action` | `block`, `challenge`, `log` o `allow`. |
| `host`, `method`, `path`, `status` | La petición y el estado con el que respondió el borde. |
| `ip`, `country_code`, `asn` | La dirección del cliente, su país y su red. |
| `rule_id`, `rule_name`, `attack_type`, `msg` | La regla que coincidió y el motivo. Los límites de peticiones aparecen como `rate_rule:<id>`; los errores de TLS con el origen, como `origin_tls`. |
| `user_agent`, `tls_fingerprint` | El software del cliente. |

## Explora los eventos en el panel

Ve a **Analítica › Tráfico** y baja hasta **Eventos de seguridad**.

- **Intervalo**: últimos 5 minutos, 15 minutos, última hora, últimas 24 horas o últimos 7 días, o un **Intervalo personalizado**.
- **Filtros**: pulsa **Añadir filtro**, o los botones + / − de cualquier valor de la tabla, para incluir o excluir un campo (*es* / *no es*). Los filtros aparecen como etiquetas que puedes alternar o quitar.
- **Búsqueda**: texto libre sobre la ruta, la IP, la regla, el user agent y otros campos.
- **Histograma**: eventos en el tiempo por acción; pulsa una barra para ampliar su intervalo.
- **Desglose**: eventos por acción, reglas principales, límites de peticiones principales y países principales.
- **Filas**: abre una fila para ver todos sus campos, como tabla o en JSON; elige los campos visibles en **Columnas**.
- **En directo**: muestra los eventos nuevos según llegan. Se pausa mientras el puntero está sobre la lista, mientras la recorres o te desplazas por ella, y mientras la pestaña del navegador está oculta.

## Consulta los eventos con la API

| Ruta | Respuesta |
|---|---|
| `GET /v1/orgs/{org}/zones/{zone}/events` | Eventos, los más recientes primero: `items` y `next_cursor` para la página siguiente. |
| `GET /v1/orgs/{org}/zones/{zone}/events/summary` | `total`, `by_action`, `top_rules`, `top_rate_rules`, `top_countries`. |
| `GET /v1/orgs/{org}/zones/{zone}/events/histogram?step=<s>` | Eventos por intervalo y acción; `step` de 1 a 86400 segundos, como mucho 1000 intervalos (sin él, un paso automático de como mucho 60 intervalos). |
| `GET /v1/orgs/{org}/zones/{zone}/events/stream` | Flujo en directo (Server-Sent Events). |

Cualquier rol de la organización puede consultarlos, incluidos los tokens de solo lectura y los limitados a una zona.

### Parámetros

| Parámetro | Significado |
|---|---|
| `since`, `until` | Fechas y horas RFC 3339. Por defecto, las últimas 24 horas; como mucho 31 días. |
| `action`, `rule_id`, `rule_name`, `rate_rule`, `ip`, `country`, `host`, `path`, `status` | Solo los eventos con ese valor. Se pueden repetir (hasta 20 valores cada uno). |
| `not_action`, `not_ip`, … | Los mismos campos con `not_`: excluye los eventos con ese valor. |
| `q` | Búsqueda de texto libre, hasta 200 caracteres. |
| `limit`, `cursor` | Tamaño de página (100 por defecto, como mucho 1000) y el `next_cursor` de la página anterior (solo en `/events`). |

```sh
curl -s "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/events?action=block&country=CN&not_path=/health&limit=50" \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
```

### Flujo en directo

`/events/stream` admite los mismos filtros y envía Server-Sent Events:

| Evento | Datos |
|---|---|
| `ready` | Parámetros del flujo (`poll_ms`, `heartbeat_ms`, `max_age_s`). |
| `event` | Un evento de seguridad, con su `id`. |
| `ping` | Mantenimiento de la conexión cuando lleva un rato sin pasar nada. |
| `bye` | El flujo termina a los 10 minutos; vuelve a conectar con `Last-Event-ID` para seguir donde lo dejaste. |

```sh
curl -sN "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/events/stream?action=block" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" -H "Accept: text/event-stream"
```

Una organización puede tener hasta 10 flujos abiertos a la vez; los demás responden `429` (`too_many_streams`).

## Relacionado

- [WAF](https://developers.openwaf.dev/es/waf/): las reglas que hay detrás de los eventos.
- [Solución de problemas con 525 y 526](https://developers.openwaf.dev/es/ssl/troubleshooting/): eventos de TLS con el origen.