Hebron Log Analyzer

Análisis local de logs para Desarrolladores, Analistas TI y Analistas de Ciberseguridad.

Analiza únicamente archivos de log que te pertenezcan o que estés autorizado a revisar.

🌐 English version: README.en.md

---

Estado del proyecto

0.1.0 — MVP inicial. El pipeline central (parsing, análisis, heurísticas, generación de reportes) está completo, probado y es utilizable en el día a día. La superficie de la CLI y el esquema de reportes aún pueden evolucionar antes de una versión 1.0. Consulta docs/roadmap.md para conocer lo que viene a continuación.

El problema que resuelve

Revisar logs durante un incidente, un ticket de soporte o una revisión rutinaria de seguridad suele significar buscar a mano con grep en texto plano, o bien enviar datos sensibles a una plataforma SaaS de terceros. Hebron Log Analyzer es una CLI local y pequeña que se ubica en un punto intermedio: interpreta formatos de log comunes, agrupa eventos repetidos, extrae y clasifica direcciones IP, resalta un pequeño conjunto de hallazgos heurísticos transparentes, y genera un reporte — todo sin conexión a internet, sin base de datos y sin necesidad de una cuenta.

Funcionalidades

• Parsing multi-formato con detección automática: JSON Lines, syslog, logs de acceso combinados de Apache/Nginx, y un parser de texto genérico como respaldo.
• Agrupación de firmas de eventos: mensajes equivalentes ("Failed login for user X from Y") se agrupan aunque las partes variables difieran, para que el ruido repetido no oculte la señal.
• Análisis de direcciones IP: extracción, clasificación basada en RFC (pública/privada/ loopback/link-local/multicast/reservada), y estadísticas por dirección — sin GeoIP, sin consultas externas.
• Anonimización determinista (--anonymize): reemplaza las direcciones IP reales por alias estables (IP-001, IP-002, ...) de forma consistente en todos los reportes.
• Hallazgos heurísticos transparentes: seis reglas defensivas (fallos de autenticación repetidos, picos de HTTP 5xx, 404 repetidos desde una misma IP, sondeo de rutas sensibles, repetición de errores críticos, repetición de accesos denegados) — siempre presentados como pistas a validar, nunca como incidentes confirmados.
• Cuatro reporters independientes: un resumen de consola con Rich, un reporte HTML autocontenido, un esquema JSON estable, y un conjunto de archivos CSV enfocados.
• Procesamiento en streaming, línea por línea — los archivos nunca se cargan completos en memoria, y los archivos .gz se leen directamente sin descomprimirlos a disco.
• 100% local. Sin llamadas de red, sin telemetría, sin cuentas.

Antes y después

Antes: un archivo de texto con cientos o miles de líneas, donde localizar los eventos importantes significa hacer grep a mano y perder el contexto general.

Después de hla analyze: un resumen ejecutivo, los eventos repetidos agrupados en una sola firma, las direcciones IP más activas clasificadas, y un puñado de hallazgos heurísticos — señalados como pistas a validar, nunca como veredictos — todo en segundos y sin salir de tu equipo.

Ejemplo de salida (español, idioma predeterminado)

$ hla analyze examples/logs/application.log

╭────────────────── Hebron Log Analyzer — Resumen ejecutivo ──────────────────╮
│ Archivos procesados: 1                                                      │
│ Bytes procesados: 2,893                                                     │
│ Líneas totales: 35                                                         │
│ Tiempo de procesamiento: 0.02s                                             │
╰──────────────────────────────────────────────────────────────────────────╯
     Calidad del procesamiento
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Métrica                ┃ Valor ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Líneas interpretadas    │    35 │
│ Líneas no interpretadas │     0 │
│ Tasa de éxito           │ 100.0%│
└─────────────────────────┴───────┘
...
Los hallazgos heurísticos no son prueba de actividad maliciosa y deben validarse en contexto.

Usa --language en en cualquier momento para obtener la misma salida en inglés.

Formatos soportados

ID de formato	Descripción
json	JSON Lines (un objeto JSON por línea)
syslog	Syslog estilo BSD (RFC 3164), con o sin <PRI>
web	Logs de acceso de Apache/Nginx en formato "combined"
generic	Respaldo best-effort para texto no estructurado

La detección de formato es automática por defecto (--format auto) y puede forzarse por ejecución. Consulta docs/supported-formats.md para conocer el mapeo de campos y las limitaciones.

Instalación

Requiere Python 3.11 o superior.

python -m venv .venv

Actívalo:

# Windows
.venv\Scripts\activate

# Linux/macOS
source .venv/bin/activate

Instala el proyecto en modo editable con las dependencias de desarrollo:

pip install -e ".[dev]"

Inicio rápido

hla analyze examples/logs/application.log

Tu primer análisis, paso a paso

1. Instala el proyecto siguiendo la sección de instalación anterior.
2. Ejecuta un análisis simple sobre uno de los logs sintéticos incluidos:

   hla analyze examples/logs/application.log

   Verás en la consola el resumen ejecutivo, la calidad del procesamiento, la distribución de severidades, los eventos más frecuentes, las IPs principales y los hallazgos heurísticos.
3. Genera un reporte HTML para revisarlo con calma en el navegador:

   hla analyze examples/logs/application.log --report html --output-dir reportes

4. Abre reportes/analysis.html en cualquier navegador — es un solo archivo, no necesita conexión a internet ni un servidor.
5. Si vas a compartir el reporte, considera anonimizar las IPs primero:

   hla analyze examples/logs/application.log --anonymize --report html --output-dir reportes

Para un recorrido más detallado con todos los logs de ejemplo del proyecto, consulta docs/guia-de-usuario.md.

Cómo leer el reporte HTML

El reporte HTML está pensado para leerse de arriba hacia abajo:

• ¿Qué hace este analizador? — una explicación en lenguaje simple de lo que la herramienta hizo con tus logs, y de lo que explícitamente no hace.
• Resumen ejecutivo — las cifras clave: archivos procesados, líneas totales, tasa de éxito del análisis, tiempo de procesamiento y cantidad de hallazgos.
• Cómo interpretar este reporte — el significado de cada severidad (INFO, ADVERTENCIA, ERROR, CRÍTICO, DESCONOCIDO) y de los términos "hallazgo heurístico", "evidencia" y "confianza".
• Calidad del procesamiento — cuántas líneas se interpretaron correctamente y con qué parser.
• Distribución por severidad y Línea de tiempo — una vista general de cuándo ocurrieron los eventos y con qué severidad.
• Eventos más frecuentes y Direcciones IP principales — el ruido repetido agrupado, y quién genera más actividad.
• Estadísticas HTTP — si el log contenía tráfico web, un desglose de códigos y métodos.
• Hallazgos heurísticos — la sección más sensible: cada fila incluye una recomendación y una nota de falsos positivos. Léelas siempre antes de sacar conclusiones.
• Archivos procesados, Metodología, Limitaciones y Privacidad — el contexto necesario para interpretar todo lo anterior con criterio.

Hallazgo heurístico vs. ataque confirmado

Un hallazgo heurístico es una observación mecánica: "esta condición específica se cumplió en los datos" (por ejemplo, más de cinco fallos de autenticación desde la misma IP en pocos minutos). Un ataque confirmado es una conclusión humana, tomada después de investigar el contexto real: revisar si esa IP es conocida, si el sistema tiene otras señales, si el patrón tiene una explicación operativa legítima, etc.

Hebron Log Analyzer solo produce lo primero. Nunca produce lo segundo. Por eso cada hallazgo incluye una recomendación ("qué revisar a continuación") y una nota de falsos positivos ("por qué esto podría no ser un problema"), y por eso todo reporte repite:

Los hallazgos heurísticos no son prueba de actividad maliciosa y deben validarse en contexto.

Qué NO hace Hebron Log Analyzer

• No confirma ataques ni incidentes de seguridad.
• No realiza escaneos de red, puertos, ni pruebas de intrusión.
• No hace consultas GeoIP ni resuelve la ubicación física de una IP.
• No se conecta a internet ni a ningún servicio externo en ningún momento.
• No modifica, elimina ni mueve tus archivos de log originales.
• No sustituye una investigación de seguridad ni el criterio de un analista humano.

Ejemplos de uso

Generar todos los formatos de reporte en un directorio:

hla analyze examples/logs/application.log \
  --report console \
  --report html \
  --report json \
  --report csv \
  --output-dir reports

Analizar un directorio de forma recursiva:

hla analyze ./logs --recursive --output-dir reports

Anonimizar direcciones IP en todas las salidas:

hla analyze ./logs --recursive --anonymize --report html

Generar el reporte en inglés en vez de español (el predeterminado):

hla analyze ./logs --language en --report html

Listar los formatos soportados:

hla formats

Mostrar la versión instalada:

hla version

La ayuda siempre está disponible:

hla --help
hla analyze --help

Comandos de la CLI

Comando	Propósito
hla analyze RUTA	Analiza un archivo o directorio y genera los reportes
hla formats	Lista los formatos de log soportados
hla version	Muestra la versión instalada

Opciones principales de analyze: --report (repetible: console, html, json, csv), --output-dir, --recursive, --anonymize, --format (auto, json, syslog, web, generic), --language (es, predeterminado, o en), --max-lines, --encoding, --include, --exclude, --top, --sample-size, --debug.

Los errores se muestran como mensajes breves y accionables, sin stack trace, salvo que se utilice --debug.

Reportes

• Consola — un resumen renderizado con Rich: resumen ejecutivo, calidad del parsing, distribución de severidades, top de eventos, top de IPs, hallazgos heurísticos y advertencias.
• HTML (analysis.html) — un único archivo autocontenido sin recursos externos (sin CDN, sin fuentes remotas, sin llamadas de red), seguro para abrir sin conexión o adjuntar a un ticket.
• JSON (analysis.json) — un esquema estable y versionado (schema_version) pensado para scripting e integraciones. Ver docs/report-schema.md.
• CSV — un archivo enfocado por sección: summary.csv, severity_distribution.csv, event_signatures.csv, ip_statistics.csv, heuristic_findings.csv, http_statistics.csv.

Idioma

Español es el idioma predeterminado para toda la salida dirigida al usuario: ayuda de la CLI, mensajes, reporte de consola, HTML, encabezados CSV, y los títulos/descripciones/recomendaciones de los hallazgos heurísticos. Usa --language en para obtener la misma información en inglés. Los valores técnicos (severidad en el JSON, clasificación de IP, rule_id, métodos y códigos HTTP, nombres de archivo de los reportes) permanecen siempre en su forma técnica original, independientemente del idioma, para no romper la compatibilidad del esquema JSON ni de integraciones existentes. El JSON incluye además un campo "language" indicando qué idioma se usó para generar ese reporte. Ver docs/guia-de-usuario.md para una guía completa en español.

Anonimización

Al pasar --anonymize se aplica seudonimización determinista: cada dirección IP se reemplaza por un alias (IP-001, IP-002, ...) asignado ordenando las direcciones por su timestamp first_seen (con empates resueltos por la propia dirección). Con el mismo conjunto de archivos de entrada, la asignación de alias es reproducible; si cambia el conjunto de logs, sus timestamps o las direcciones IP presentes, los alias también pueden cambiar. Los alias son consistentes dentro de un mismo reporte — la misma dirección siempre se corresponde con el mismo alias en la consola, el HTML, el JSON, el CSV y en todas las muestras de mensajes truncadas — lo cual también significa que los alias permiten correlacionar actividad dentro de ese reporte.

Esto reduce la exposición directa de direcciones IP en un reporte compartido; no es anonimización criptográfica irreversible, ni elimina otros datos sensibles (credenciales, datos personales, identificadores internos) que puedan aparecer en los logs. Revisa siempre un reporte antes de compartirlo. Más detalles en docs/security-and-privacy.md.

Arquitectura (resumen)

Readers (texto/gzip) → Parsers (JSON/syslog/web/genérico) → Motor de análisis
  (firmas de eventos, análisis de IP, estadísticas, timeline, heurísticas) → Reporters
  (consola/HTML/JSON/CSV)

Los parsers implementan una interfaz común BaseLogParser y se seleccionan mediante un registro que puntúa una muestra de líneas por archivo y recurre al parser genérico como respaldo. Consulta docs/architecture.md para el detalle completo, un diagrama de flujo de datos y los puntos de extensión.

Seguridad y privacidad

• Los archivos de log se tratan como entrada no confiable: no se usa eval/exec, no se ejecutan comandos del shell, las secuencias ANSI se neutralizan, la salida HTML se escapa, y las líneas y muestras se truncan y limitan en cantidad.
• Todo se ejecuta localmente. Sin solicitudes de red, sin telemetría, sin cuentas.
• Los archivos de log pueden contener datos personales, credenciales, tokens o identificadores internos. Analiza únicamente archivos de log que te pertenezcan o que estés autorizado a revisar.

Detalles completos en docs/security-and-privacy.md.

Limitaciones

• La detección de formato es por archivo y heurística; un archivo que mezcle varios formatos puede terminar completo bajo el parser genérico.
• Los timestamps de syslog clásico sin año asumen el año actual.
• Los hallazgos heurísticos usan umbrales fijos y documentados, y no sustituyen una investigación completa — requieren validación humana.
• Sin GeoIP, sin escaneo activo, sin integración con SIEM en esta versión (ver el roadmap).

Roadmap

Consulta docs/roadmap.md para conocer el trabajo planificado (configuración externa, plugins, análisis en tiempo real, una interfaz web local, y más).

Cómo contribuir

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para la configuración local, las convenciones, y cómo agregar un parser, una regla heurística o un reporter.

Licencia

MIT

Autor

Hernan Daniel Briceño Hernandez — github.com/Hebrondev