🔐 Breach Monitor - Sistema de Monitoreo de Filtraciones

📋 Descripción

Breach Monitor v1.0.0 es un sistema empresarial para monitoreo automatizado de filtraciones de datos y credenciales. El sistema consulta múltiples fuentes de inteligencia (HIBP, LeakCheck, Intelligence X, DeHashed) para detectar cuando emails o dominios de tu organización aparecen en brechas de seguridad.

🎯 Características Principales

• ✅ Múltiples Fuentes: Integración con 4+ servicios de breach intelligence
• ✅ Monitoreo Automático: Escaneos programados vía cron configurable
• ✅ Alertas Inteligentes: Notificaciones por email con clasificación de severidad
• ✅ API REST: Endpoints para integración con dashboards y SIEM
• ✅ CLI Completo: Comandos administrativos para gestión
• ✅ Instalación Sencilla: Scripts automatizados para Ubuntu 24.04+

🗂️ Estructura del Proyecto

/opt/breach-monitor/               # Aplicación principal
├── venv/                         # Entorno virtual Python
├── lib/                          # Librerías core
│   ├── config.py                # Gestión de configuración
│   └── database.py              # Modelos SQLAlchemy
├── modules/                      # Módulos de servicio
│   ├── hibp_service.py          # Cliente HIBP API v3
│   ├── breach_sources.py        # LeakCheck, IntelX, DeHashed
│   ├── scanner_service.py       # Orquestador de escaneos
│   └── notification_service.py  # Notificaciones email
└── requirements.txt             # Dependencias Python

/etc/breach-monitor/              # Configuración
└── config.ini                   # Archivo de configuración principal

/var/lib/breach-monitor/          # Datos del sistema
├── scripts/                     # Scripts ejecutables
│   ├── breach_monitor.py       # Monitor principal
│   └── breach_api.py           # Servidor API REST
└── data/                        # Base de datos SQLite

/var/log/breach-monitor/          # Logs del sistema
├── breach-monitor.log           # Log principal
├── scans/                       # Logs de escaneos
├── alerts/                      # Logs de alertas
└── api/                         # Logs de API

🚀 Instalación

Requisitos del Sistema

Componente	Versión Mínima	Recomendado
OS	Ubuntu 22.04+	Ubuntu 24.04 LTS
Python	3.10+	3.12+
RAM	1GB	2GB+
Disco	1GB	5GB+

Instalación Rápida (2 Partes)

# 1. Clonar o descargar el proyecto
git clone https://github.com/tuusuario/breach-monitor.git
cd breach-monitor

# 2. Ejecutar instalador Parte 1 (sistema base)
sudo bash breach_monitor_installer_part1.sh

# 3. Ejecutar instalador Parte 2 (Python y servicios)
sudo bash breach_monitor_installer_part2.sh

Configuración Durante la Instalación

El instalador configurará interactivamente:

1. API Keys de fuentes de datos (HIBP, LeakCheck, etc.)
2. Servidor SMTP para notificaciones
3. Horarios de escaneo (cron)
4. Activos iniciales a monitorear (dominios/emails)

⚙️ Configuración

Archivo Principal: /etc/breach-monitor/config.ini

[database]
type = sqlite
sqlite_path = /var/lib/breach-monitor/data/breach_monitor.db

[sources]
hibp_enabled = true
hibp_api_key = tu-api-key-aqui
hibp_rate_limit_delay = 6.5

[scheduler]
enabled = true
daily_scan_time = 06:00
additional_cron = 0 */6 * * *

[email]
enabled = true
smtp_server = smtp.gmail.com
smtp_port = 587
smtp_username = tu-email@gmail.com
recipients = security@tuempresa.com

[api]
enabled = true
port = 8080
api_key = tu-api-key-secreto

🧰 Comandos de Administración

# Estado del sistema
breach-monitor-admin status
breach-monitor-status          # Atajo

# Control de servicios
breach-monitor-admin start
breach-monitor-admin stop
breach-monitor-admin restart

# Escaneos
breach-monitor-admin scan                    # Escaneo completo
breach-monitor-admin scan-email user@dom.com # Escaneo individual
breach-monitor-admin init-data               # Cargar activos desde config

# Notificaciones
breach-monitor-admin test-email              # Enviar prueba

# Logs y configuración
breach-monitor-admin logs
breach-monitor-admin config

📡 API REST

Endpoints Principales

# Health check
GET /api/v1/health

# Activos
GET  /api/v1/assets
POST /api/v1/assets
DELETE /api/v1/assets/{id}

# Filtraciones
GET /api/v1/breaches
PATCH /api/v1/breaches/{id}/status

# Escaneos
POST /api/v1/scan
POST /api/v1/scan/quick

# Estadísticas
GET /api/v1/stats/dashboard

# Notificaciones
POST /api/v1/notifications/test

Ejemplo de Uso

# Escaneo rápido de un email
curl -X POST http://localhost:8080/api/v1/scan/quick \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tu-api-key" \
  -d '{"email": "test@example.com"}'

Documentación Interactiva

Accede a la documentación Swagger en:

• http://localhost:8080/docs
• http://localhost:8080/redoc

📧 Fuentes de Datos

Fuente	Descripción	Costo
Have I Been Pwned	Principal, más completa	$3.50/mes
LeakCheck	Datos adicionales	Freemium
Intelligence X	Inteligencia avanzada	Freemium
DeHashed	Base de datos extensa	Pago

Obtener API Keys

• HIBP: https://haveibeenpwned.com/API/Key
• LeakCheck: https://leakcheck.io/
• Intelligence X: https://intelx.io/
• DeHashed: https://dehashed.com/

🔒 Seguridad

• Usuario dedicado breach-monitor sin privilegios
• Configuración con permisos restrictivos (640)
• Servicios systemd con hardening
• API protegida con API Key opcional
• Logs con opción de anonimización

🗑️ Desinstalación

sudo bash breach_monitor_uninstaller.sh

El desinstalador ofrece crear un backup antes de eliminar.

📊 Métricas

Métrica	Valor
Líneas de código	~3,500
Versión Python	3.10+
Dependencias	15+ packages
Sistemas probados	Ubuntu 22.04, 24.04

📄 Changelog

v1.0.0 (2025)

• 🎉 Versión inicial
• ✅ Integración HIBP, LeakCheck, IntelX, DeHashed
• ✅ Sistema de notificaciones por email
• ✅ API REST completa
• ✅ Instaladores automatizados
• ✅ Comandos administrativos

👨‍💻 Autor

Juan Pablo Díaz Ezcurdia

• Website: jpdiaz.com
• GitHub: @juanpadiaz

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para detalles.

---

⚠️ Aviso: Este sistema es una herramienta de seguridad defensiva. Úselo responsablemente y solo para monitorear activos de su organización o con autorización explícita.