🧠 Log Sentinel – Mini SIEM en Python

Log Sentinel es un mini-SIEM educativo escrito en Python.
Procesa logs, detecta fuerza bruta, eventos fuera de horario, genera alertas,
mantiene historial histórico, correlaciona eventos y presenta un dashboard de seguridad en consola.

---

📸 Vista previa

---

📂 Arquitectura del Proyecto

Log_Sentinel/
├── README.md
├── main.py                         # Punto de entrada del SIEM
├── rules.json                      # Reglas configurables
├── logs/
│   └── sample.log                  # Log de ejemplo
├── reports/                        # Reportes completos (CSV)
├── alerts/                         # Reportes de alertas (CSV)
├── data/
│   └── alert_history.csv           # Historial persistente de alertas
└── core/
    ├── parser.py                   # Extracción de IP / usuario / timestamp / evento
    ├── analyzer.py                 # Detección (offhours + brute force)
    ├── reporter.py                 # Consola + guardado de reportes
    ├── alert_storage.py            # Persistencia de alertas en historial
    ├── history_reader.py           # Carga + estadísticas del historial
    └── correlator.py               # Correlación local + histórica de eventos

---

⚙️ Instalación y Uso Rápido

git clone https://github.com/gasparswidzinski/Log_Sentinel.git
cd Log_Sentinel
pip install -r requirements.txt
python main.py

💡 Asegurate de tener Python 3.11 y pip instalados.

---

🎯 Flujo Interno – Cómo funciona Log Sentinel

Esta sección explica, paso a paso, qué hace el programa cuando ejecutás:

python main.py

1. Carga las reglas desde rules.json.
2. Lee y parsea el archivo de logs con LogParser.
3. Normaliza todo en un DataFrame de pandas.
4. Detecta:
   • eventos fuera de horario laboral (offhours);
   • posibles ataques de fuerza bruta (bruteforce).
5. Guarda las alertas en un histórico (data/alert_history.csv).
6. Calcula estadísticas históricas sobre todas las corridas.
7. Correlaciona eventos:
   • fallidos → exitosos (correlación local);
   • brute force histórico → login exitoso actual (correlación histórica).
8. Genera reportes en CSV y muestra un dashboard en consola usando Rich.

---

1️⃣ Carga de reglas – rules.json

Archivo de configuración principal:

{
  "working_hours": { "start": 9, "end": 18 },
  "failed_login": {
    "threshold": 3,
    "window_minutes": 10,
    "message": "posible ataque de fuerza bruta"
  },
  "sudo_command": {
    "outside_working_hours": true,
    "message": "uso de comando sudo fuera del horario laboral"
  }
}

🔧 Para qué se usa cada campo:

• working_hours.start / end: horario laboral permitido (en horas).
• failed_login.threshold: cantidad mínima de intentos fallidos para considerar brute force.
• failed_login.window_minutes: ventana de tiempo (en minutos) para contar fallos.
• failed_login.message / sudo_command.message: texto que se usa en la descripción de la regla.

---

2️⃣ Parsing de logs – LogParser (core/parser.py)

La clase LogParser se encarga de tomar una línea de log cruda y devolver un diccionario normalizado con la info clave.

🔍 Datos extraídos:

• IP → usando un regex IPv4 en extract_ip().
• Usuario → extract_user() intenta, en orden, patrones típicos:
  • "invalid user (\w+)"
  • "for (\w+)"
  • "sudo:\s+(\w+)"
  • "\((\w+)\)" (caso CRON)
• Evento (event) → classify_event() mapea:
  • "Failed password" → failed_login
  • "Accepted password" → successful_login
  • "sudo:" → sudo_command
  • "CRON" → cron_job
  • "GET" / "POST" → web_request
  • cualquier otro → other
• Timestamp → extract_timestamp() soporta:
  • formato syslog: Oct 30 10:10:10 ...
  • formato Apache: [30/Oct/2025:13:20:01 +0000]

🧩 Ejemplo de salida de parse_line:

{
  "raw_line": "Oct 30 10:10:10 server1 sshd[1111]: Failed password for root from 45.23.11.90 port 54421 ssh2",
  "ip": "45.23.11.90",
  "user": "root",
  "event": "failed_login",
  "timestamp": datetime(...)
}

---

3️⃣ Lectura y normalización – LogAnalyzer.read_log_file()

Módulo: core/analyzer.py

LogAnalyzer usa el parser para leer el archivo de log completo y armar un DataFrame de pandas con todas las líneas relevantes:

from core.parser import LogParser
from core.analyzer import LogAnalyzer

parser = LogParser()
analyzer = LogAnalyzer(parser, rules=rules)
df = analyzer.read_log_file("logs/sample.log")

El DataFrame resultante tiene, al menos, las columnas:

• timestamp
• ip
• user
• event
• raw_line

Ejemplo conceptual:

timestamp	ip	user	event	raw_line
2025-10-30 10:10:10	45.23.11.90	root	failed_login	...
2025-10-30 10:10:30	45.23.11.90	root	successful_login	...

---

4️⃣ Detección de amenazas – LogAnalyzer

🔹 A) Eventos fuera de horario – detect_offhour(df)

1. Lee working_hours desde rules.json.
2. Filtra filas con timestamp no nulo.
3. Calcula hour = df["timestamp"].dt.hour.
4. Devuelve solo aquellas filas donde la hora está fuera del rango [start, end].

Uso típico:

fuera = analyzer.detect_offhour(df)

🔹 B) Fuerza bruta – detect_bruteforce(df)

1. Filtra event == "failed_login".
2. Lee threshold y window_minutes desde rules.json.
3. Si no hay window_minutes:
   • cuenta intentos fallidos totales por IP.
4. Si hay window_minutes:
   • usa una ventana móvil de tiempo por IP para ver si se superan los N intentos en X minutos.

La función devuelve:

brute_df, threshold, window_minutes = analyzer.detect_bruteforce(df)

---

5️⃣ Historizar alertas – alert_history.csv (core/alert_storage.py)

El módulo alert_storage.py se encarga de persistir las alertas de cada corrida en un archivo histórico CSV.

🔧 Funciones clave:

• ensure_history_dir() → crea data/ si no existe.
• append_alert(offhours_df, bruteforce_df, rules=None):
  • normaliza offhours_df y bruteforce_df a un formato común;
  • agrega:
    • run_timestamp (momento de la corrida);
    • alert_type ("offhours" o "bruteforce");
    • rule (mensaje baseado en rules.json);
  • guarda o appendea en:

data/alert_history.csv

🧾 Formato típico del historial:

run_timestamp	event_timestamp	alert_type	ip	user	rule	raw_line
2025-10-30 10:11:00	2025-10-30 10:10:10	bruteforce	45.23.11.90	root	posible fuerza bruta: ≥3 en 10 minutos	...

---

6️⃣ Historial y estadísticas – history_reader.py

Este módulo permite mirar el historial completo de alertas.

• load_history()

  • carga el CSV data/alert_history.csv;
  • convierte run_timestamp y event_timestamp a datetime.

• history_stats(df) devuelve un diccionario con:

{
  "total": <total_alertas>,
  "by_type": {"offhours": N1, "bruteforce": N2, ...},
  "top_ips": {"45.23.11.90": X, "200.55.22.100": Y, ...},
  "top_users": {"root": A, "admin": B, ...}
}

Estas estadísticas se utilizan para:

• mostrar el total de alertas;
• listar el top de IPs y usuarios;
• armar paneles del dashboard.

---

7️⃣ Correlación de eventos – LogCorrelator (core/correlator.py)

LogCorrelator compara:

• eventos de la corrida actual (events_df);
• historial de alertas (history_df);

para detectar patrones más avanzados.

from core.correlator import LogCorrelator

correlator = LogCorrelator(events_df=df, history_df=history_df)
local_corr = correlator.correlate_local(window_minutes=20, min_fails=1)
historical_corr = correlator.correlate_with_history(history_window_hours=24, min_alerts=1)
correlator.save_correlations(local_corr, historical_corr)

🔸 A) Correlación local – correlate_local(...)

Busca secuencias:

1. Uno o varios failed_login
2. Seguidos de un successful_login
3. Misma (ip, user)
4. Dentro de una ventana de X minutos

Es útil para casos del tipo:

“Hubo varios intentos fallidos y luego un login exitoso para la misma IP/usuario.”

🔸 B) Correlación histórica – correlate_with_history(...)

Cruza:

• alertas históricas de tipo bruteforce
• logins exitosos actuales (successful_login)

Si una IP/usuario tuvo fuerza bruta en las últimas N horas y ahora tiene un login exitoso, se genera una correlación sospechosa.

Las correlaciones se guardan como CSV en:

alerts/correlated_local.csv
alerts/correlated_history.csv

---

8️⃣ Reportes y visualización – LogReporter (core/reporter.py)

LogReporter se encarga de:

• guardar DataFrames en CSV;
• mostrar resultados formateados en consola con Rich.

💾 Reportes generados

Por defecto se crean (o se pueden crear) archivos como:

• reports/full_log_report.csv → todos los eventos parseados
• alerts/offhours_report.csv → eventos fuera de horario
• alerts/bruteforce_report.csv → intentos de fuerza bruta
• alerts/correlated_local.csv → correlaciones locales
• alerts/correlated_history.csv → correlaciones históricas

🎨 Visualización en consola

Funciones como:

• show_offhours(df)
• show_bruteforce(df, threshold, window_minutes)

usan Rich para mostrar:

• tablas con headers;
• colores;
• mensajes claros sobre si se detectaron o no eventos sospechosos.

---

9️⃣ Dashboard final – show_dashboard_summary() (main.py)

En main.py se define una función show_dashboard_summary(...) que muestra un mini dashboard tipo SIEM, con paneles Rich:

• Resumen general:

  • líneas procesadas;
  • total de alertas;
  • correlaciones locales e históricas.

• Alertas por tipo:
  Tabla con cantidad por tipo de alerta.

• Top IPs y Top usuarios:
  Paneles con las IPs y usuarios con más alertas.

• Resumen de correlaciones:
  Cantidad de correlaciones locales e históricas detectadas.

Es el panel central que da una vista rápida del estado de seguridad según los logs analizados.

---

🔁 Diagrama del flujo completo

             ┌───────────────┐
             │   rules.json   │
             └───────┬───────┘
                     ▼
           ┌────────────────────┐
           │     LogParser      │
           │    (parse_line)    │
           └─────────┬──────────┘
                     ▼
       ┌─────────────────────────────┐
       │       DataFrame (df)        │
       └─────────┬──────────┬────────┘
                 │          │
                 ▼          ▼
   ┌──────────────────┐   ┌───────────────────┐
   │ detect_offhour   │   │ detect_bruteforce │
   └─────────┬────────┘   └──────────┬────────┘
             ▼                       ▼
     ┌────────────────┐     ┌────────────────┐
     │  offhours_df    │     │  bruteforce_df │
     └─────────┬────────┘     └──────────┬────┘
               ▼                        ▼
     ┌────────────────────┐    ┌─────────────────────┐
     │   append_alert()    │    │  alert_history.csv  │
     └─────────┬──────────┘    └──────────┬──────────┘
               ▼                        ▼
        ┌──────────────────┐   ┌─────────────────────────┐
        │   history_stats   │   │      LogCorrelator      │
        └─────────┬────────┘   └──────────┬─────────────┘
                  ▼                       ▼
         ┌─────────────────┐      ┌────────────────────────┐
         │ Dashboard (Rich) │      │  save_correlations()   │
         └─────────────────┘      └────────────────────────┘

---

🧪 Logs compatibles

Log Sentinel está pensado para funcionar con:

• Logs de sistema tipo syslog:
  • sshd, sudo, CRON, etc.
• Logs de Apache/Nginx en formato access log.
• Cualquier log de texto que contenga:
  • timestamps reconocibles;
  • mensajes con IPs;
  • información de usuario.

Con modificaciones mínimas al parser, se puede extender a otros formatos.

---

🚀 Roadmap (Ideas futuras)

• Reglas ampliadas para distintos tipos de eventos (web, base de datos, etc.).
• Integración con API / webhooks para enviar alertas a otros sistemas.
• Dashboard web con Streamlit u otra herramienta.
• Soporte para múltiples archivos de log en una sola corrida.
• CLI con argumentos para elegir archivo de input, reglas, path de salida, etc.

---

✍️ Autor

Gaspar Swidzinski

Proyecto personal de aprendizaje en:

• 🛡️ Ciberseguridad
• 🐍 Desarrollo en Python
• 📊 Análisis y correlación de logs

---

📄 Licencia

Distribuido bajo la licencia MIT License.
Podés usarlo, modificarlo y compartirlo libremente citando al autor original.

---

🌍 Log Sentinel – Python Mini SIEM (English Version)

Log Sentinel is an educational mini-SIEM written in Python.
It processes logs, detects brute-force attempts and off-hours activity,
keeps a historical alert store, correlates events, and shows a security dashboard in the console.

---

📸 Preview

---

📂 Project Architecture

Log_Sentinel/
├── README.md
├── main.py                         # SIEM entry point
├── rules.json                      # Detection rules
├── logs/
│   └── sample.log                  # Sample log
├── reports/                        # Full reports (CSV)
├── alerts/                         # Alert reports (CSV)
├── data/
│   └── alert_history.csv           # Persistent alert history
└── core/
    ├── parser.py                   # Extract IP / user / timestamp / event
    ├── analyzer.py                 # Detection (offhours + brute force)
    ├── reporter.py                 # Console output + report saving
    ├── alert_storage.py            # Alert history persistence
    ├── history_reader.py           # History loading + statistics
    └── correlator.py               # Local + historical event correlation

---

⚙️ Quick Installation & Usage

git clone https://github.com/gasparswidzinski/Log_Sentinel.git
cd Log_Sentinel
pip install -r requirements.txt
python main.py

💡 Make sure you have Python 3.11 and pip installed.

---

🎯 Internal Flow – How Log Sentinel Works

This section explains, step by step, what the program does when you run:

python main.py

1. Loads rules from rules.json.
2. Reads and parses the log file using LogParser.
3. Normalizes everything into a pandas DataFrame.
4. Detects:
   • off-hours activity (offhours);
   • possible brute-force attacks (bruteforce).
5. Appends alerts to a persistent history (data/alert_history.csv).
6. Computes historical statistics across all runs.
7. Correlates events:
   • failed → successful logins (local correlation);
   • past brute-force → current successful login (historical correlation).
8. Generates CSV reports and shows a Rich-powered console dashboard.

---

1️⃣ Rule Loading – rules.json

Main configuration file:

{
  "working_hours": { "start": 9, "end": 18 },
  "failed_login": {
    "threshold": 3,
    "window_minutes": 10,
    "message": "possible brute force attack"
  },
  "sudo_command": {
    "outside_working_hours": true,
    "message": "sudo command used outside working hours"
  }
}

🔧 What each field is used for:

• working_hours.start / end: allowed working hour range (in hours).
• failed_login.threshold: minimum number of failed attempts to flag brute force.
• failed_login.window_minutes: time window (minutes) to count failures.
• failed_login.message / sudo_command.message: human-readable rule descriptions.

---

2️⃣ Log Parsing – LogParser (core/parser.py)

LogParser takes a raw log line and returns a normalized dictionary with the key information.

🔍 Extracted fields:

• IP → regular IPv4 regex in extract_ip().
• User → extract_user() tries several patterns:
  • "invalid user (\w+)"
  • "for (\w+)"
  • "sudo:\s+(\w+)"
  • "\((\w+)\)" (CRON case)
• Event (event) → classify_event() maps:
  • "Failed password" → failed_login
  • "Accepted password" → successful_login
  • "sudo:" → sudo_command
  • "CRON" → cron_job
  • "GET" / "POST" → web_request
  • anything else → other
• Timestamp → extract_timestamp() supports:
  • syslog style: Oct 30 10:10:10 ...
  • Apache style: [30/Oct/2025:13:20:01 +0000]

🧩 Example parse_line output:

{
  "raw_line": "Oct 30 10:10:10 server1 sshd[1111]: Failed password for root from 45.23.11.90 port 54421 ssh2",
  "ip": "45.23.11.90",
  "user": "root",
  "event": "failed_login",
  "timestamp": datetime(...)
}

---

3️⃣ Reading & Normalizing – LogAnalyzer.read_log_file()

Module: core/analyzer.py

LogAnalyzer uses the parser to read the full log file and build a pandas DataFrame with all relevant lines:

from core.parser import LogParser
from core.analyzer import LogAnalyzer

parser = LogParser()
analyzer = LogAnalyzer(parser, rules=rules)
df = analyzer.read_log_file("logs/sample.log")

The resulting DataFrame contains at least:

• timestamp
• ip
• user
• event
• raw_line

Conceptual example:

timestamp	ip	user	event	raw_line
2025-10-30 10:10:10	45.23.11.90	root	failed_login	...
2025-10-30 10:10:30	45.23.11.90	root	successful_login	...

---

4️⃣ Threat Detection – LogAnalyzer

🔹 A) Off-hours events – detect_offhour(df)

1. Reads working_hours from rules.json.
2. Filters rows with a non-null timestamp.
3. Computes hour = df["timestamp"].dt.hour.
4. Returns only rows where the hour is outside [start, end].

Typical usage:

offhours_df = analyzer.detect_offhour(df)

🔹 B) Brute force – detect_bruteforce(df)

1. Filters event == "failed_login".
2. Reads threshold and window_minutes from rules.json.
3. If window_minutes is missing:
   • counts total failed attempts per IP.
4. If window_minutes is set:
   • uses a sliding time window per IP to check if N attempts occur within X minutes.

The function returns:

brute_df, threshold, window_minutes = analyzer.detect_bruteforce(df)

---

5️⃣ Alert History – alert_history.csv (core/alert_storage.py)

alert_storage.py is responsible for persisting alerts from each run into a historical CSV.

🔧 Key functions:

• ensure_history_dir() → creates data/ if it does not exist.
• append_alert(offhours_df, bruteforce_df, rules=None):
  • normalizes offhours_df and bruteforce_df into a common schema;
  • adds:
    • run_timestamp (when the run occurred);
    • alert_type ("offhours" or "bruteforce");
    • rule (message based on rules.json);
  • saves/appends to:

data/alert_history.csv

🧾 Typical history format:

run_timestamp	event_timestamp	alert_type	ip	user	rule	raw_line
2025-10-30 10:11:00	2025-10-30 10:10:10	bruteforce	45.23.11.90	root	possible brute force: ≥3 in 10 minutes	...

---

6️⃣ History & Statistics – history_reader.py

This module lets you inspect the full alert history.

• load_history()

  • loads data/alert_history.csv;
  • converts run_timestamp and event_timestamp to datetime.

• history_stats(df) returns a dictionary like:

{
  "total": <total_alerts>,
  "by_type": {"offhours": N1, "bruteforce": N2, ...},
  "top_ips": {"45.23.11.90": X, "200.55.22.100": Y, ...},
  "top_users": {"root": A, "admin": B, ...}
}

These stats are used to:

• show total alerts;
• list top IPs and users;
• build dashboard panels.

---

7️⃣ Event Correlation – LogCorrelator (core/correlator.py)

LogCorrelator compares:

• current run events (events_df);
• historical alerts (history_df);

to detect more advanced patterns.

from core.correlator import LogCorrelator

correlator = LogCorrelator(events_df=df, history_df=history_df)
local_corr = correlator.correlate_local(window_minutes=20, min_fails=1)
historical_corr = correlator.correlate_with_history(history_window_hours=24, min_alerts=1)
correlator.save_correlations(local_corr, historical_corr)

🔸 A) Local correlation – correlate_local(...)

Looks for sequences:

1. One or more failed_login events
2. Followed by a successful_login
3. Same (ip, user)
4. Within a given time window

Useful for situations like:

“There were several failed attempts and then a successful login for the same IP/user.”

🔸 B) Historical correlation – correlate_with_history(...)

Crosses:

• historical bruteforce alerts
• current successful_login events

If an IP/user had brute-force alerts in the last N hours and now has a successful login, it generates a suspicious correlation.

Correlations are saved as CSV in:

alerts/correlated_local.csv
alerts/correlated_history.csv

---

8️⃣ Reporting & Visualization – LogReporter (core/reporter.py)

LogReporter handles:

• saving DataFrames to CSV;
• showing formatted results in the console using Rich.

💾 Generated reports

By default (or optionally), it creates files such as:

• reports/full_log_report.csv → all parsed events
• alerts/offhours_report.csv → off-hours events
• alerts/bruteforce_report.csv → brute-force attempts
• alerts/correlated_local.csv → local correlations
• alerts/correlated_history.csv → historical correlations

🎨 Console visualization

Functions like:

• show_offhours(df)
• show_bruteforce(df, threshold, window_minutes)

use Rich to display:

• tables with headers;
• colored output;
• clear messages about whether suspicious activity was detected or not.

---

9️⃣ Final Dashboard – show_dashboard_summary() (main.py)

In main.py, the show_dashboard_summary(...) function renders a mini-SIEM dashboard with Rich panels:

• General summary:

  • processed lines;
  • total alerts;
  • local & historical correlations.

• Alerts by type:
  Table with counts per alert type.

• Top IPs & top users:
  Panels with the most active IPs and users.

• Correlation summary:
  Number of local and historical correlations detected.

This is the central panel that gives a quick view of the security posture based on the analyzed logs.

---

🔁 Full Flow Diagram

             ┌───────────────┐
             │   rules.json   │
             └───────┬───────┘
                     ▼
           ┌────────────────────┐
           │     LogParser      │
           │    (parse_line)    │
           └─────────┬──────────┘
                     ▼
       ┌─────────────────────────────┐
       │       DataFrame (df)        │
       └─────────┬──────────┬────────┘
                 │          │
                 ▼          ▼
   ┌──────────────────┐   ┌───────────────────┐
   │ detect_offhour   │   │ detect_bruteforce │
   └─────────┬────────┘   └──────────┬────────┘
             ▼                       ▼
     ┌────────────────┐     ┌────────────────┐
     │  offhours_df    │     │  bruteforce_df │
     └─────────┬────────┘     └──────────┬────┘
               ▼                        ▼
     ┌────────────────────┐    ┌─────────────────────┐
     │   append_alert()    │    │  alert_history.csv  │
     └─────────┬──────────┘    └──────────┬──────────┘
               ▼                        ▼
        ┌──────────────────┐   ┌─────────────────────────┐
        │   history_stats   │   │      LogCorrelator      │
        └─────────┬────────┘   └──────────┬─────────────┘
                  ▼                       ▼
         ┌─────────────────┐      ┌────────────────────────┐
         │ Dashboard (Rich) │      │  save_correlations()   │
         └─────────────────┘      └────────────────────────┘

---

🧪 Supported Logs

Log Sentinel is meant to work with:

• syslog-style system logs:
  • sshd, sudo, CRON, etc.
• Apache/Nginx access logs.
• Any textual log containing:
  • recognizable timestamps;
  • messages with IPs;
  • user information.

With small changes to the parser, it can be extended to additional formats.

---

🚀 Roadmap (Future Ideas)

• Extended rules for different event classes (web, database, etc.).
• Integration with APIs / webhooks to push alerts elsewhere.
• Web dashboard using Streamlit or similar.
• Support for multiple log files in a single run.
• CLI flags for input log path, rules file, output directory, etc.

---

✍️ Author

Gaspar Swidzinski

Personal learning project around:

• 🛡️ Cybersecurity
• 🐍 Python development
• 📊 Log analysis and event correlation

---

📄 License

Distributed under the MIT License.
You are free to use, modify, and share it, with proper attribution to the original author.