Gestión de Tickets y Plantillas Personalizadas

Suricatavel cuenta con un Subsistema de Tickets que se integra con plataformas externas de seguimiento de problemas y sistemas de mensajería. Esto le permite enviar automáticamente tickets detallados o alertas cuando se activan las políticas de seguridad.

---

Integraciones Compatibles

Suricatavel admite dos canales principales de adaptadores de tickets:

1. Jira

Crea tareas directamente en su instancia de Jira Cloud o Jira Server.

• Propiedades de Conexión: URL de Jira, correo/usuario de autenticación y token de API/contraseña.
• Valores por Defecto: Clave del proyecto por defecto (ej. SEC) y tipo de tarea por defecto (ej. Task, Bug).
• Mapeo de Prioridades: Mapea los números de gravedad de alerta (1 a 3) a IDs de prioridad o etiquetas de Jira.

2. Webhooks Personalizados

Envía cargas útiles POST HTTP a herramientas de mensajería (Slack, Microsoft Teams, Discord) o pasarelas de API.

• Propiedades de Conexión: URL del Webhook de destino y método HTTP.
• Creador de Payload Personalizado: Plantilla JSON personalizada opcional para anular la estructura JSON predeterminada.

---

Configuración de Integraciones

Para configurar un canal de tickets:

1. Vaya a Administración > Configuración > Ticketing en el Panel de Administración.
2. Haga clic en Añadir Integración y seleccione Jira o Webhook.
3. Complete los detalles de conexión y tokens de credenciales.
4. Haga clic en Probar Conexión para verificar la comunicación.
5. Guarde la configuración.

---

Creación de Plantillas de Tickets

Las plantillas definen el diseño del título y el cuerpo de los tickets generados. Se gestionan en el menú Administración > Plantillas y utilizan la sintaxis de plantillas Twig.

Variables Disponibles en la Plantilla

Cuando se activa una política, las siguientes variables de contexto se inyectan en sus plantillas Twig:

Variables Comunes (Todos los disparadores)

• {{ trigger_type }}: Evento disparador (alert_created o ioc_score_updated).
• {{ trigger_label }}: Etiqueta legible del disparador (Alert Created o IOC Score Updated).
• {{ timestamp }}: Marca de tiempo ISO 8601 del evento.
• {{ app_url }}: URL base de su panel Suricatavel.
• {{ app_name }}: Nombre de la aplicación.
• {{ summary }}: Resumen breve del evento.
• {{ policy_name }}: Nombre de la política que se activó.
• {{ policy_id }}: ID de la política que se activó.

Contexto de Alerta (Disponible si alert es verdadero)

• {{ alert }}: Se evalúa como true cuando el origen es una alerta de Suricata.
• {{ source_ip }}: Dirección IP de origen.
• {{ dest_ip }}: Dirección IP de destino.
• {{ severity }}: Gravedad de la alerta (1, 2 o 3).
• {{ signature }}: Mensaje de la firma de la regla de Suricata.
• {{ category }}: Categoría de clasificación de la alerta.
• {{ hostname }}: Nombre del nodo host que registró la alerta.
• {{ source_port }}: Puerto de origen.
• {{ dest_port }}: Puerto de destino.
• {{ protocol }}: Protocolo IP (TCP, UDP, ICMP, etc.).

Contexto de IOC (Disponible si ioc es verdadero)

• {{ ioc }}: Se evalúa como true cuando el origen es un cambio de puntuación de IOC.
• {{ ioc_value }}: Valor del indicador (ej. IP, dominio).
• {{ ioc_type }}: Tipo de indicador (ej. ipv4, domain).
• {{ ioc_score }}: Puntuación de amenaza actualizada (0–100).
• {{ ioc_observations }}: Número de veces observado en eventos de red.

---

Ejemplos de Plantillas Twig

Plantilla de Título del Ticket

[{{ app_name }}] {{ trigger_label }} — {{ summary }}

Plantilla del Cuerpo del Ticket (Markdown)

## Ticket de Seguridad Automatizado

**Activado por política:** {{ policy_name | default('N/A') }}
**Disparador:** {{ trigger_label }}
**Fecha/Hora:** {{ timestamp }}

{% if alert is defined and alert %}
### Detalles de la Alerta
| Campo | Valor |
|---|---|
| Firma | {{ signature }} |
| Gravedad | {{ severity }} |
| IP Origen | {{ source_ip }} |
| IP Destino | {{ dest_ip }} |
| Categoría | {{ category | default('N/A') }} |
| Hostname | {{ hostname | default('N/A') }} |
| Protocolo | {{ protocol | default('N/A') }} |
{% endif %}

{% if ioc is defined and ioc %}
### Detalles del IOC
| Campo | Valor |
|---|---|
| Valor | {{ ioc_value }} |
| Tipo | {{ ioc_type }} |
| Puntuación de Reputación | {{ ioc_score }} |
| Observaciones | {{ ioc_observations }} |
{% endif %}

---
*Este ticket se creó automáticamente mediante [Suricatavel]({{ app_url }}).*

---

Vinculación de Acciones a Políticas

Una vez creadas las integraciones y plantillas, puede automatizar la generación de tickets:

1. Edite o cree una regla de automatización en la sección Administración > Políticas.
2. En la estructura de Acciones, seleccione Notification / Ticket.
3. Seleccione el canal de Integración y la Plantilla a utilizar.
4. Defina campos de anulación opcionales (como etiquetas de Jira, proyectos específicos, asignados o payloads JSON de Webhook).
5. Guarde la política.

---

Gestión de Colas y Reintentos

Para evitar la pérdida de eventos de API, Suricatavel procesa las acciones de tickets de forma asíncrona en segundo plano.

• Limitación de Tasa y Fluctuación (Jitter): Si un proveedor externo devuelve un límite de tasa (HTTP 429), el motor de tickets reprograma automáticamente la tarea. Respeta la cabecera Retry-After del proveedor y aplica un retraso con fluctuación aleatoria para evitar saturar el servidor.
• Fallos y Notificaciones: Si una acción de ticket falla después de agotar los intentos de reintento configurados, se notificará a los administradores a través de los canales de alerta configurados (ej. Correo, Slack, Telegram).