winlog-hunter 0.2.0__tar.gz

winlog_hunter-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan Valenzuela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

winlog_hunter-0.2.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: winlog-hunter
+Version: 0.2.0
+Summary: Detección de amenazas en logs de Windows (Security, System, Sysmon, PowerShell) mapeada a MITRE ATT&CK
+Author: Bryan Valenzuela
+License: MIT
+Project-URL: Homepage, https://github.com/BV-cs0/winlog-hunter
+Project-URL: Source, https://github.com/BV-cs0/winlog-hunter
+Project-URL: Issues, https://github.com/BV-cs0/winlog-hunter/issues
+Keywords: blue-team,soc,dfir,windows,sysmon,mitre-attack,threat-hunting
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Logging
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Natural Language :: Spanish
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: evtx
+Requires-Dist: python-evtx>=0.7; extra == "evtx"
+Dynamic: license-file
+
+# 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.
+
+![Informe de winlog-hunter con logs de ataques reales](docs/informe.png)
+
+## Instalación
+
+Necesitas Python 3.9 o superior y git.
+
+```bash
+git clone https://github.com/BV-cs0/winlog-hunter.git
+cd winlog-hunter
+python -m pip install .
+```
+
+## Uso
+
+**1. Abre PowerShell como administrador** y entra en la carpeta del proyecto:
+
+```powershell
+cd winlog-hunter
+```
+
+**2. Genera el informe** con los logs de las últimas 24 horas de tu equipo:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\analisis-diario.ps1
+```
+
+**3. Abre el informe.** Se guarda en `Documentos\winlog-hunter` con la fecha en el nombre:
+
+```powershell
+start $HOME\Documents\winlog-hunter
+```
+
+> Para analizar más tiempo añade `-Horas 72`. Sin administrador también funciona, pero se omite el log Security.
+
+## Detecciones
+
+| ID | Detección | Eventos | MITRE ATT&CK |
+|---|---|---|---|
+| WLH-001 | Fuerza bruta (muchos fallos, misma cuenta y origen) | 4625 | T1110.001 |
+| WLH-002 | Password spraying (un origen, muchas cuentas) | 4625 | T1110.003 |
+| WLH-003 | Inicio de sesión correcto justo después de una fuerza bruta | 4625 → 4624 | T1110, T1078 |
+| WLH-004 | Movimiento lateral (misma cuenta en varios equipos) | 4624 tipo 3/10 | T1021 |
+| WLH-005 | Registro de eventos borrado | 1102, 104 | T1685.005 |
+| WLH-006 | Servicio nuevo; alta si es PsExec o ejecuta algo sospechoso | 7045 | T1543.003, T1569.002 |
+| WLH-007 | Tarea programada; alta si lanza PowerShell, scripts o rutas raras | 4698 | T1053.005 |
+| WLH-008 | Cuenta de usuario creada | 4720 | T1136 |
+| WLH-009 | Alta en grupo privilegiado (por SID, vale en cualquier idioma) | 4728, 4732, 4756 | T1098 |
+| WLH-010 | PowerShell sospechoso; decodifica `-EncodedCommand` | Sysmon 1, 4688 | T1059.001 |
+| WLH-011 | LOLBins: certutil, mshta, rundll32, regsvr32, bitsadmin, wmic | Sysmon 1, 4688 | T1218, T1105, T1197, T1047 |
+| WLH-012 | Office (Word, Excel, Outlook...) lanzando una shell | Sysmon 1, 4688 | T1566.001, T1204.002 |
+| WLH-013 | Acceso a la memoria de LSASS (Mimikatz, procdump...) | Sysmon 10 | T1003.001 |
+| WLH-014 | Comandos de volcado: comsvcs MiniDump, ntdsutil, reg save SAM | Sysmon 1, 4688 | T1003.001-.003 |
+| WLH-015 | DCSync: replicación de AD pedida por un usuario | 4662 | T1003.006 |
+| WLH-016 | Kerberoasting: tickets de servicio RC4 | 4769 | T1558.003 |
+| WLH-017 | Ejecución remota por SMB: PsExec, svcctl, atsvc, copia a ADMIN$ | 5145 | T1021.002, T1569.002 |
+| WLH-018 | Shell lanzada por WMI o WinRM (wmiexec, Invoke-Command) | Sysmon 1, 4688 | T1047, T1021.006 |
+| WLH-019 | Persistencia en el registro: Run, Winlogon, IFEO, COM, LSA, SAM | Sysmon 13 | T1547, T1546 |
+| WLH-020 | Persistencia con suscripciones WMI | Sysmon 19-21 | T1546.003 |
+| WLH-021 | Script de PowerShell malicioso: volcado de LSASS, AMSI, inyección | 4104 | T1059.001, T1003.001 |
+
+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](https://github.com/sbousseaden/EVTX-ATTACK-SAMPLES): 278 ficheros `.evtx` grabados en laboratorio mientras se ejecutaban ataques reales, organizados por táctica.
+
+| Táctica | Ficheros | Detectados |
+|---|---|---|
+| Credential Access | 39 | 14 |
+| Lateral Movement | 47 | 13 |
+| Persistence | 22 | 12 |
+| Execution | 34 | 7 |
+| Herramientas de pruebas automatizadas | 8 | 5 |
+| Privilege Escalation | 66 | 3 |
+| Defense Evasion | 36 | 2 |
+| Discovery | 11 | 1 |
+| Command and Control | 6 | 0 |
+| Otros | 9 | 1 |
+| **Total** | **278** | **58** |
+
+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.
+
+## Activar Sysmon (recomendado)
+
+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:
+
+```powershell
+# 1. Descargar Sysmon y una configuración probada (la de SwiftOnSecurity)
+Invoke-WebRequest https://download.sysinternals.com/files/Sysmon.zip -OutFile $env:TEMP\Sysmon.zip
+Expand-Archive $env:TEMP\Sysmon.zip $env:TEMP\Sysmon -Force
+Invoke-WebRequest https://raw.githubusercontent.com/SwiftOnSecurity/sysmon-config/master/sysmonconfig-export.xml -OutFile $env:TEMP\sysmon.xml
+
+# 2. Instalarlo
+& $env:TEMP\Sysmon\Sysmon64.exe -accepteula -i $env:TEMP\sysmon.xml
+```
+
+Para la regla WLH-021, activa también el registro de bloques de script de PowerShell:
+
+```powershell
+New-Item -Path HKLM:\SOFTWARE\Policies\Microsoft\Windows\PowerShell\ScriptBlockLogging -Force |
+    New-ItemProperty -Name EnableScriptBlockLogging -Value 1 -PropertyType DWord -Force
+```
+
+El análisis diario 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:
+
+```powershell
+# 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 ".[evtx]"`.
+
+## Análisis automático diario del propio equipo (Windows)
+
+Para que el informe se genere solo cada día, en PowerShell **como administrador**:
+
+```powershell
+# Programarlo cada día a las 09:00
+powershell -ExecutionPolicy Bypass -File .\scripts\instalar-tarea.ps1
+
+# A otra hora
+powershell -ExecutionPolicy Bypass -File .\scripts\instalar-tarea.ps1 -Hora 21:30
+
+# Lanzarlo ahora sin esperar
+Start-ScheduledTask -TaskName 'winlog-hunter diario'
+
+# Quitarlo
+powershell -ExecutionPolicy Bypass -File .\scripts\instalar-tarea.ps1 -Desinstalar
+```
+
+- Si hay algún hallazgo **crítico**, aparece un aviso en pantalla con el resumen y la ruta del informe.
+- 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.
+- Si mueves la carpeta del proyecto, vuelve a ejecutar el instalador.
+
+## Reglas Sigma
+
+La carpeta [`sigma/`](sigma/) tiene las 21 detecciones en formato Sigma, validadas con `sigma check`. Se convierten a la consulta de tu SIEM (Splunk, Elastic, Microsoft Sentinel, QRadar...):
+
+```bash
+python -m pip install sigma-cli
+sigma plugin install splunk
+sigma convert -t splunk -p windows-audit -p splunk_windows 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.
+
+## Estructura
+
+```text
+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
+  cli.py       comando winlog-hunter
+scripts/
+  analisis-diario.ps1   exporta los logs del equipo, genera el informe y avisa
+  instalar-tarea.ps1    programa el análisis diario
+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.

winlog_hunter-0.2.0/README.md

@@ -0,0 +1,187 @@
+# 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.
+
+![Informe de winlog-hunter con logs de ataques reales](docs/informe.png)
+
+## Instalación
+
+Necesitas Python 3.9 o superior y git.
+
+```bash
+git clone https://github.com/BV-cs0/winlog-hunter.git
+cd winlog-hunter
+python -m pip install .
+```
+
+## Uso
+
+**1. Abre PowerShell como administrador** y entra en la carpeta del proyecto:
+
+```powershell
+cd winlog-hunter
+```
+
+**2. Genera el informe** con los logs de las últimas 24 horas de tu equipo:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\analisis-diario.ps1
+```
+
+**3. Abre el informe.** Se guarda en `Documentos\winlog-hunter` con la fecha en el nombre:
+
+```powershell
+start $HOME\Documents\winlog-hunter
+```
+
+> Para analizar más tiempo añade `-Horas 72`. Sin administrador también funciona, pero se omite el log Security.
+
+## Detecciones
+
+| ID | Detección | Eventos | MITRE ATT&CK |
+|---|---|---|---|
+| WLH-001 | Fuerza bruta (muchos fallos, misma cuenta y origen) | 4625 | T1110.001 |
+| WLH-002 | Password spraying (un origen, muchas cuentas) | 4625 | T1110.003 |
+| WLH-003 | Inicio de sesión correcto justo después de una fuerza bruta | 4625 → 4624 | T1110, T1078 |
+| WLH-004 | Movimiento lateral (misma cuenta en varios equipos) | 4624 tipo 3/10 | T1021 |
+| WLH-005 | Registro de eventos borrado | 1102, 104 | T1685.005 |
+| WLH-006 | Servicio nuevo; alta si es PsExec o ejecuta algo sospechoso | 7045 | T1543.003, T1569.002 |
+| WLH-007 | Tarea programada; alta si lanza PowerShell, scripts o rutas raras | 4698 | T1053.005 |
+| WLH-008 | Cuenta de usuario creada | 4720 | T1136 |
+| WLH-009 | Alta en grupo privilegiado (por SID, vale en cualquier idioma) | 4728, 4732, 4756 | T1098 |
+| WLH-010 | PowerShell sospechoso; decodifica `-EncodedCommand` | Sysmon 1, 4688 | T1059.001 |
+| WLH-011 | LOLBins: certutil, mshta, rundll32, regsvr32, bitsadmin, wmic | Sysmon 1, 4688 | T1218, T1105, T1197, T1047 |
+| WLH-012 | Office (Word, Excel, Outlook...) lanzando una shell | Sysmon 1, 4688 | T1566.001, T1204.002 |
+| WLH-013 | Acceso a la memoria de LSASS (Mimikatz, procdump...) | Sysmon 10 | T1003.001 |
+| WLH-014 | Comandos de volcado: comsvcs MiniDump, ntdsutil, reg save SAM | Sysmon 1, 4688 | T1003.001-.003 |
+| WLH-015 | DCSync: replicación de AD pedida por un usuario | 4662 | T1003.006 |
+| WLH-016 | Kerberoasting: tickets de servicio RC4 | 4769 | T1558.003 |
+| WLH-017 | Ejecución remota por SMB: PsExec, svcctl, atsvc, copia a ADMIN$ | 5145 | T1021.002, T1569.002 |
+| WLH-018 | Shell lanzada por WMI o WinRM (wmiexec, Invoke-Command) | Sysmon 1, 4688 | T1047, T1021.006 |
+| WLH-019 | Persistencia en el registro: Run, Winlogon, IFEO, COM, LSA, SAM | Sysmon 13 | T1547, T1546 |
+| WLH-020 | Persistencia con suscripciones WMI | Sysmon 19-21 | T1546.003 |
+| WLH-021 | Script de PowerShell malicioso: volcado de LSASS, AMSI, inyección | 4104 | T1059.001, T1003.001 |
+
+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](https://github.com/sbousseaden/EVTX-ATTACK-SAMPLES): 278 ficheros `.evtx` grabados en laboratorio mientras se ejecutaban ataques reales, organizados por táctica.
+
+| Táctica | Ficheros | Detectados |
+|---|---|---|
+| Credential Access | 39 | 14 |
+| Lateral Movement | 47 | 13 |
+| Persistence | 22 | 12 |
+| Execution | 34 | 7 |
+| Herramientas de pruebas automatizadas | 8 | 5 |
+| Privilege Escalation | 66 | 3 |
+| Defense Evasion | 36 | 2 |
+| Discovery | 11 | 1 |
+| Command and Control | 6 | 0 |
+| Otros | 9 | 1 |
+| **Total** | **278** | **58** |
+
+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.
+
+## Activar Sysmon (recomendado)
+
+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:
+
+```powershell
+# 1. Descargar Sysmon y una configuración probada (la de SwiftOnSecurity)
+Invoke-WebRequest https://download.sysinternals.com/files/Sysmon.zip -OutFile $env:TEMP\Sysmon.zip
+Expand-Archive $env:TEMP\Sysmon.zip $env:TEMP\Sysmon -Force
+Invoke-WebRequest https://raw.githubusercontent.com/SwiftOnSecurity/sysmon-config/master/sysmonconfig-export.xml -OutFile $env:TEMP\sysmon.xml
+
+# 2. Instalarlo
+& $env:TEMP\Sysmon\Sysmon64.exe -accepteula -i $env:TEMP\sysmon.xml
+```
+
+Para la regla WLH-021, activa también el registro de bloques de script de PowerShell:
+
+```powershell
+New-Item -Path HKLM:\SOFTWARE\Policies\Microsoft\Windows\PowerShell\ScriptBlockLogging -Force |
+    New-ItemProperty -Name EnableScriptBlockLogging -Value 1 -PropertyType DWord -Force
+```
+
+El análisis diario 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:
+
+```powershell
+# 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 ".[evtx]"`.
+
+## Análisis automático diario del propio equipo (Windows)
+
+Para que el informe se genere solo cada día, en PowerShell **como administrador**:
+
+```powershell
+# Programarlo cada día a las 09:00
+powershell -ExecutionPolicy Bypass -File .\scripts\instalar-tarea.ps1
+
+# A otra hora
+powershell -ExecutionPolicy Bypass -File .\scripts\instalar-tarea.ps1 -Hora 21:30
+
+# Lanzarlo ahora sin esperar
+Start-ScheduledTask -TaskName 'winlog-hunter diario'
+
+# Quitarlo
+powershell -ExecutionPolicy Bypass -File .\scripts\instalar-tarea.ps1 -Desinstalar
+```
+
+- Si hay algún hallazgo **crítico**, aparece un aviso en pantalla con el resumen y la ruta del informe.
+- 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.
+- Si mueves la carpeta del proyecto, vuelve a ejecutar el instalador.
+
+## Reglas Sigma
+
+La carpeta [`sigma/`](sigma/) tiene las 21 detecciones en formato Sigma, validadas con `sigma check`. Se convierten a la consulta de tu SIEM (Splunk, Elastic, Microsoft Sentinel, QRadar...):
+
+```bash
+python -m pip install sigma-cli
+sigma plugin install splunk
+sigma convert -t splunk -p windows-audit -p splunk_windows 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.
+
+## Estructura
+
+```text
+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
+  cli.py       comando winlog-hunter
+scripts/
+  analisis-diario.ps1   exporta los logs del equipo, genera el informe y avisa
+  instalar-tarea.ps1    programa el análisis diario
+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.

winlog_hunter-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "winlog-hunter"
+version = "0.2.0"
+description = "Detección de amenazas en logs de Windows (Security, System, Sysmon, PowerShell) mapeada a MITRE ATT&CK"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Bryan Valenzuela" }]
+keywords = ["blue-team", "soc", "dfir", "windows", "sysmon", "mitre-attack", "threat-hunting"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Security",
+    "Topic :: System :: Logging",
+    "Environment :: Console",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "Natural Language :: Spanish",
+]
+dependencies = []
+
+[project.optional-dependencies]
+evtx = ["python-evtx>=0.7"]
+
+[project.urls]
+Homepage = "https://github.com/BV-cs0/winlog-hunter"
+Source = "https://github.com/BV-cs0/winlog-hunter"
+Issues = "https://github.com/BV-cs0/winlog-hunter/issues"
+
+[project.scripts]
+winlog-hunter = "winlog_hunter.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

winlog_hunter-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

winlog_hunter-0.2.0/src/winlog_hunter/__init__.py

@@ -0,0 +1,3 @@
+"""winlog-hunter: detección de amenazas en logs de Windows mapeada a MITRE ATT&CK."""
+
+__version__ = "0.2.0"

winlog_hunter-0.2.0/src/winlog_hunter/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

winlog_hunter-0.2.0/src/winlog_hunter/cli.py

@@ -0,0 +1,153 @@
+"""Interfaz de línea de comandos."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import timedelta
+from pathlib import Path
+
+from . import __version__
+from .models import SEVERITIES, SEVERITY_ORDER
+from .parsers import load_events
+from .report import RENDERERS, SEVERITY_LABEL, Stats, render_console
+from .rules import RULES, Config, run_rules
+
+FORMATS = ("console", "json", "markdown", "html")
+_EXTENSION_FORMAT = {".json": "json", ".md": "markdown", ".markdown": "markdown", ".html": "html", ".htm": "html"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="winlog-hunter",
+        description="Analiza logs de Windows (Security, System, Sysmon) y detecta actividad "
+        "sospechosa mapeada a MITRE ATT&CK.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    analyze = sub.add_parser("analyze", help="analiza ficheros o carpetas de logs")
+    analyze.add_argument("paths", nargs="+", type=Path, help=".evtx, .xml (wevtutil), .jsonl/.json o carpetas")
+    analyze.add_argument("-f", "--format", choices=FORMATS, help="formato de salida (por defecto, según -o o consola)")
+    analyze.add_argument("-o", "--output", type=Path, help="fichero donde guardar el informe")
+    analyze.add_argument("--min-severity", choices=SEVERITIES, default="low", help="oculta hallazgos por debajo")
+    analyze.add_argument("--rules", help="IDs de reglas separados por comas, p. ej. WLH-001,WLH-003")
+    analyze.add_argument("--fail-on", choices=SEVERITIES, help="sale con código 1 si hay hallazgos de esa severidad o más")
+    analyze.add_argument("--threshold", type=int, default=5, help="fallos para considerar fuerza bruta (5)")
+    analyze.add_argument("--spray-accounts", type=int, default=5, help="cuentas distintas para password spraying (5)")
+    analyze.add_argument("--window", type=float, default=5, help="ventana de correlación en minutos (5)")
+    analyze.add_argument("--lateral-hosts", type=int, default=3, help="equipos distintos para movimiento lateral (3)")
+    analyze.add_argument("--no-color", action="store_true", help="desactiva los colores en consola")
+
+    sub.add_parser("rules", help="lista las reglas de detección")
+    return parser
+
+
+def _enable_ansi() -> bool:
+    if os.name != "nt":
+        return True
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        handle = kernel32.GetStdHandle(-11)
+        mode = ctypes.c_uint32()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        return bool(kernel32.SetConsoleMode(handle, mode.value | 0x0004))
+    except Exception:
+        return False
+
+
+def _list_rules() -> int:
+    for r in RULES:
+        print(f"{r.id}  [{SEVERITY_LABEL[r.severity]}]  {', '.join(r.mitre)}")
+        print(f"         {r.title}: {r.description}")
+    return 0
+
+
+def _analyze(args: argparse.Namespace) -> int:
+    known = {r.id for r in RULES}
+    only = None
+    if args.rules:
+        only = {rid.strip().upper() for rid in args.rules.split(",") if rid.strip()}
+        unknown = only - known
+        if unknown:
+            print(f"error: reglas desconocidas: {', '.join(sorted(unknown))}", file=sys.stderr)
+            return 2
+    for name in ("threshold", "spray_accounts", "lateral_hosts"):
+        if getattr(args, name) < 1:
+            print(f"error: --{name.replace('_', '-')} debe ser al menos 1", file=sys.stderr)
+            return 2
+    if args.window <= 0:
+        print("error: --window debe ser mayor que 0", file=sys.stderr)
+        return 2
+
+    try:
+        loaded = load_events(args.paths)
+    except (FileNotFoundError, PermissionError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    if not loaded.events and loaded.warnings:
+        print("error: no se pudo leer ningún evento:", file=sys.stderr)
+        for warning in loaded.warnings[:10]:
+            print(f"  - {warning}", file=sys.stderr)
+        return 2
+
+    config = Config(
+        window=timedelta(minutes=args.window),
+        brute_force_threshold=args.threshold,
+        spray_min_accounts=args.spray_accounts,
+        lateral_min_hosts=args.lateral_hosts,
+    )
+    all_findings = run_rules(loaded.events, config, only)
+    minimum = SEVERITY_ORDER[args.min_severity]
+    findings = [f for f in all_findings if f.rank >= minimum]
+
+    stats = Stats(
+        events=len(loaded.events),
+        files=loaded.files,
+        first_event=loaded.events[0].timestamp if loaded.events else None,
+        last_event=loaded.events[-1].timestamp if loaded.events else None,
+        warnings=loaded.warnings,
+    )
+
+    fmt = args.format or (_EXTENSION_FORMAT.get(args.output.suffix.lower(), "console") if args.output else "console")
+    if fmt == "console":
+        color = (
+            not args.no_color
+            and args.output is None
+            and "NO_COLOR" not in os.environ
+            and sys.stdout.isatty()
+            and _enable_ansi()
+        )
+        text = render_console(findings, stats, color=color)
+    else:
+        text = RENDERERS[fmt](findings, stats)
+
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(text if text.endswith("\n") else text + "\n", encoding="utf-8")
+        print(f"Informe {fmt} guardado en {args.output} ({len(findings)} hallazgos)", file=sys.stderr)
+    else:
+        print(text)
+
+    # --fail-on es independiente de lo que se muestra: se evalúa sobre todos los hallazgos.
+    if args.fail_on and any(f.rank >= SEVERITY_ORDER[args.fail_on] for f in all_findings):
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="replace")
+    args = build_parser().parse_args(argv)
+    if args.command == "rules":
+        return _list_rules()
+    return _analyze(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())