winlog-hunter

Analizador de logs de Windows para blue team. Lee eventos de Security, System, Sysmon y PowerShell, detecta actividad sospechosa con 21 reglas y genera un informe con cada hallazgo mapeado a MITRE ATT&CK. Las reglas también están en formato Sigma para usarlas en cualquier SIEM.

Instalación

Necesitas Python 3.9 o superior.

python -m pip install winlog-hunter

No tiene dependencias obligatorias. En Linux o macOS, para leer ficheros .evtx instala también el extra: python3 -m pip install "winlog-hunter[evtx]" (en Windows no hace falta: usa wevtutil, que viene con el sistema).

Para actualizar a la última versión: python -m pip install --upgrade winlog-hunter. Para comprobar que funciona: winlog-hunter --version.

¿Windows dice que no reconoce winlog-hunter? Algunas instalaciones de Python no ponen su carpeta Scripts en el PATH. Usa python -m winlog_hunter (con guion bajo), por ejemplo python -m winlog_hunter equipo: funciona igual y, de paso, añade esa carpeta al PATH de tu usuario. Desde la siguiente consola que abras, winlog-hunter funcionará directamente.

Uso

1. Abre PowerShell como administrador (sin administrador funciona, pero se omite el log Security).

2. Analiza tu equipo:

winlog-hunter equipo

Exporta los logs de las últimas 24 horas, los analiza y abre el informe en el navegador. Se guarda en Documentos\winlog-hunter con la fecha en el nombre.

Para analizar más tiempo: winlog-hunter equipo --horas 72. Todas las opciones: winlog-hunter equipo --help.

La primera vez, prepara el equipo para que Windows guarde todos los eventos que usan las reglas.

Comandos

winlog-hunter -h                # lista de comandos y ejemplos
winlog-hunter <comando> -h      # todas las opciones de un comando, p. ej. winlog-hunter equipo -h

Detecciones

Para reducir falsos positivos, la severidad depende del contexto: un servicio o una tarea normales salen como baja, y uno que ejecuta powershell -enc sale como alta. Los ataques en ráfaga (500 intentos de contraseña) se agrupan en un único hallazgo.

Resultados con ataques reales

winlog-hunter se ha probado con EVTX-ATTACK-SAMPLES: 278 ficheros .evtx grabados en laboratorio mientras se ejecutaban ataques reales, organizados por táctica.

No se cuentan los ficheros en los que solo salta registro borrado, porque el autor vació los logs antes de grabar cada ataque.

Los puntos débiles son claros: la escalada de privilegios (bypass de UAC, tokens, servicios vulnerables) y la evasión de defensas. Casi todos esos ataques necesitan reglas de Sysmon 7 (carga de DLL), 8 (hilos remotos) y 11 (ficheros creados), que aún no están implementadas.

Preparar el equipo (recomendado)

Windows no guarda por defecto muchos de los eventos que usan las reglas. Dos comandos, en PowerShell como administrador, lo dejan listo:

winlog-hunter auditoria --activar
winlog-hunter sysmon --instalar

Auditoría de Windows

winlog-hunter auditoria --activar activa:

• La auditoría de creación de procesos (4688) con la línea de comandos, de tareas programadas (4698), de cuentas (4720), de grupos (4728, 4732) y de inicios de sesión correctos y fallidos (4624, 4625).
• El Script Block Logging de PowerShell (4104), que necesita la regla WLH-021.
• Un tamaño mayor para los registros Security (128 MB), PowerShell (64 MB) y Sysmon (128 MB), para que quepan 24 horas de eventos.

Antes de cambiar nada guarda la configuración original, y winlog-hunter auditoria --restaurar la deja como estaba. winlog-hunter auditoria --estado muestra qué está activado. Usa los GUID de las subcategorías de auditoría, así que funciona con Windows en cualquier idioma.

Sysmon

Sin Sysmon, Windows no registra los procesos que se ejecutan, los accesos a LSASS ni los cambios en el registro, así que 9 de las 21 reglas no tienen datos. Sysmon es gratuito y de Microsoft. En PowerShell como administrador:

winlog-hunter sysmon --instalar

Descarga Sysmon de la web oficial de Microsoft, comprueba que está firmado por Microsoft y lo instala con una configuración pensada para winlog-hunter. Esa configuración registra los procesos, los accesos a LSASS, los cambios en claves de persistencia y WMI, y filtra el ruido para que el log ocupe poco. Al instalarlo se acepta la licencia de Sysinternals.

winlog-hunter sysmon --estado        # comprobar que está instalado
winlog-hunter sysmon --actualizar    # aplicar la configuración de una versión nueva de winlog-hunter
winlog-hunter sysmon --desinstalar   # quitarlo

winlog-hunter equipo incluye Sysmon y PowerShell en cuanto existen.

Cómo sacar los logs de un equipo Windows manualmente

Para analizar otro equipo, o un log concreto, expórtalo y pásaselo a winlog-hunter:

# 1. Exportar los logs (Security requiere administrador)
wevtutil epl Security C:\temp\Security.evtx
wevtutil epl System C:\temp\System.evtx

# 2. Analizarlos y guardar el informe
winlog-hunter analyze C:\temp\Security.evtx C:\temp\System.evtx -o informe.html

El formato del informe se elige por la extensión: .html, .md o .json. También acepta .xml de wevtutil qe y JSON de Winlogbeat o de un SIEM. En Linux/macOS, para leer .evtx instala antes python3 -m pip install "winlog-hunter[evtx]".

Análisis automático diario del propio equipo (Windows)

Para que el informe se genere solo cada día, en PowerShell como administrador:

winlog-hunter programar                 # cada día a las 09:00
winlog-hunter programar --hora 21:30    # a otra hora
winlog-hunter programar --ahora         # lanzarlo ya, sin esperar
winlog-hunter programar --estado        # comprobar que existe
winlog-hunter programar --quitar        # eliminarlo

• Si hay algún hallazgo crítico, aparece un aviso en pantalla con el resumen y la ruta del informe. Con --avisar-desde high también avisa de los de severidad alta.
• Los informes se guardan en Documentos\winlog-hunter y los de más de 30 días se borran solos.
• ejecuciones.log, en la misma carpeta, guarda un resumen de cada ejecución.
• Si el equipo está apagado a la hora programada, se ejecuta al encenderlo.
• Al actualizar winlog-hunter con pip, la tarea usa la versión nueva sin volver a programarla.

Reglas Sigma

La carpeta sigma/ del repositorio tiene las 21 detecciones en formato Sigma, validadas con sigma check. Se convierten a la consulta de tu SIEM (Splunk, Elastic, Microsoft Sentinel, QRadar...):

git clone https://github.com/BV-cs0/winlog-hunter.git
python -m pip install sigma-cli
sigma plugin install splunk
sigma convert -t splunk -p windows-audit -p splunk_windows winlog-hunter/sigma/

Seguridad del propio analizador

Los logs pueden contener datos controlados por un atacante (nombres de usuario, líneas de comandos, nombres de tareas), así que la herramienta los trata como entrada hostil:

• HTML. Todo el contenido se escapa y el informe lleva una Content-Security-Policy que bloquea cualquier script.
• Consola. Se eliminan los caracteres de control, para que una secuencia ANSI dentro de un log no pueda manipular la terminal.
• XML. Se rechazan los documentos con DOCTYPE (protección frente a XXE y billion laughs).
• Markdown. Se escapan los caracteres especiales.

Desinstalar

1. Deshaz los cambios en el equipo (PowerShell como administrador):

winlog-hunter desinstalar

Elimina la tarea programada, deja la auditoría de Windows como estaba antes de auditoria --activar, desinstala Sysmon y quita del PATH la carpeta que añadió winlog-hunter. Solo deshace lo que hizo winlog-hunter: si algo no se había activado, lo indica y lo deja como está.

• --conservar-sysmon: no desinstala Sysmon (por ejemplo, si ya lo usabas antes).
• --borrar-informes: borra también los informes de Documentos\winlog-hunter, que por defecto se conservan.

2. Quita el paquete:

python -m pip uninstall winlog-hunter

Estructura

src/winlog_hunter/
  parsers.py   lectura de EVTX / XML / JSON y normalización de eventos
  rules.py     las 21 reglas de detección mapeadas a MITRE ATT&CK
  report.py    informe en consola, HTML, Markdown y JSON
  local.py     análisis del propio equipo, aviso, tarea programada, auditoría, Sysmon y desinstalación
  pathfix.py   deja el comando winlog-hunter en el PATH si pip no lo hizo
  data/sysmon.xml   configuración de Sysmon para las reglas
  cli.py       comando winlog-hunter (analyze, equipo, programar, auditoria, sysmon, desinstalar, rules)
sigma/         las reglas en formato Sigma
docs/          captura del informe
samples/       datos sintéticos que usan los tests
tests/         tests automáticos

Úsalo solo con logs de equipos que tengas autorización para analizar. Licencia MIT.