Cómo Crear Decoders Personalizados en Wazuh: Guía Práctica con Regex

Introducción

Uno de los superpoderes de Wazuh es su capacidad de procesar cualquier tipo de log. Pero para aprovechar esta potencia, necesitas saber crear decoders personalizados. En esta guía vamos a ver cómo hacerlo paso a paso, usando un ejemplo real de logs de un NAS.

Lo más importante: no intentes crear el decoder completo de una vez. Hazlo poco a poco, probando cada cambio con la herramienta de test.

¿Qué es un Decoder y por qué lo necesitas?

Un decoder es un "traductor" que lee un log en texto plano y extrae los campos importantes en variables estructuradas. Sin un decoder, Wazuh solo ve texto sin significado.

NAS: Users: marialopez, Source IP: 192.168.1.100, Computer name: MariaPC...

srcuser: marialopez
srcip: 192.168.1.100
computer_name: MariaPC
action: Write
resource: Certificados/CertificadoDigital.pfx

El ejemplo: Log de acceso a NAS

Vamos a trabajar con este log real de un NAS (Network Attached Storage):

NAS: Users: marialopez, Source IP: 192.168.1.100, Computer name: MariaPC, Connection type: SMB, Accessed resources: shared/Certificados/CertificadoDigital.pfx, Action: Write

Los campos que queremos extraer son:

• Usuario: marialopez
• IP origen: 192.168.1.100
• Nombre equipo: MariaPC
• Tipo conexión: SMB
• Recurso: shared/Certificados/CertificadoDigital.pfx
• Acción: Write

Paso 1: Empezar simple (solo el usuario)

Regla de oro: nunca intentes capturar todo de una vez. Empieza con un solo campo y ve añadiendo.

<decoder name="nas-access">
  <prematch>^NAS: </prematch>
  <regex>^NAS: Users: (\S+)</regex>
  <order>srcuser</order>
</decoder>

Explicación de cada parte:

Probar con el Decoder Test

En Wazuh Dashboard, ve a Tools → Ruleset Test (o usa /var/ossec/bin/wazuh-logtest por terminal) y pega el log. Si funciona, verás:

**Phase 2: Decoding
   name: 'nas-access'
   srcuser: 'marialopez'

✓ ¡Funciona! El usuario se ha extraído correctamente.

Paso 2: Añadir la IP de origen

Ahora expandimos la regex para capturar también la IP:

<decoder name="nas-access">
  <prematch>^NAS: </prematch>
  <regex type="pcre2">^NAS: Users: (\S+), Source IP: (\d+\.\d+\.\d+\.\d+)</regex>
  <order>srcuser,srcip</order>
</decoder>

Novedades:

Paso 3: El decoder completo

Siguiendo el mismo proceso, añadimos el resto de campos:

<decoder name="nas-access">
  <prematch>^NAS: </prematch>
  <regex type="pcre2">^NAS: Users: (\S+), Source IP: (\d+\.\d+\.\d+\.\d+), Computer name: (\S+), Connection type: (\S+), Accessed resources: (.+), Action: (\w+)$</regex>
  <order>srcuser,srcip,computer_name,conn_type,resource,action</order>
</decoder>

Guía Rápida de Regex para Wazuh

Estas son las expresiones regulares más útiles para crear decoders:

¿Por qué usar PCRE2?

Wazuh soporta dos tipos de regex:

• Regex nativa de Wazuh: Más simple pero limitada
• PCRE2 (type="pcre2"): Estándar de la industria, más potente

Recomendación: usa siempre type="pcre2" para decoders complejos. La sintaxis es la misma que usarías en Python, JavaScript o cualquier otro lenguaje.

¿Para qué sirve extraer estos campos?

Una vez que el decoder extrae los campos, puedes crear reglas específicas:

<!-- Alerta: Alguien modifica un certificado -->
<rule id="100001" level="12">
  <decoded_as>nas-access</decoded_as>
  <field name="action">Write</field>
  <field name="resource">Certificado</field>
  <description>Modificación de certificado en NAS por $(srcuser) desde $(srcip)</description>
</rule>

<!-- Alerta: Acceso desde IP externa -->
<rule id="100002" level="10">
  <decoded_as>nas-access</decoded_as>
  <field name="srcip">^(?!192\.168\.)</field>
  <description>Acceso a NAS desde IP externa: $(srcip)</description>
</rule>

<!-- Alerta: Usuario desconocido -->
<rule id="100003" level="8">
  <decoded_as>nas-access</decoded_as>
  <field name="srcuser">^(?!admin|marialopez|juangarcia)</field>
  <description>Acceso a NAS con usuario no autorizado: $(srcuser)</description>
</rule>

Sin el decoder, nada de esto sería posible. Solo tendrías el texto plano sin poder filtrar por usuario, IP o acción.

Metodología: Construir decoders poco a poco

No saltes pasos. Si intentas escribir la regex completa de una vez, cuando falle no sabrás qué parte está mal.

Dónde guardar el decoder

Los decoders personalizados se guardan en:

/var/ossec/etc/decoders/local_decoder.xml

Después de modificar el archivo, reinicia el manager:

systemctl restart wazuh-manager

Resumen

• Decoder = traductor de logs a campos estructurados
• Sin decoder, no puedes crear reglas específicas
• Usa type="pcre2" para regex estándar
• Construye poco a poco y prueba cada paso
• Regex esenciales: \S+ (no espacios), \d+ (dígitos), .+ (todo), ( ) (captura)

Próximos pasos

Una vez que domines los decoders, el siguiente paso es crear reglas personalizadas que usen los campos extraídos para generar alertas. En el Curso de Wazuh cubrimos todo el flujo completo: decoders → reglas → alertas → notificaciones.