Sentinel Security Platform (pySentinel-SOC5)

Sistema IDS/IPS de última generación (SOC Nivel 5) integrado con IA para detección y respuesta automática ante amenazas de seguridad.

🌐 Visión General del Sistema (SOC5)

Centro de Comando IA	Mapa Global de Amenazas	Control Móvil

🚀 Características Principales

• Integración multi-herramienta: Suricata, Zeek, Wazuh, Wireshark, Velociraptor
• IA con NVIDIA NIM: Análisis contextual usando Mistral Large 3
• Respuesta automática: Bloqueo de IPs, generación de reglas, aislamiento de hosts
• Dashboard en tiempo real: Interfaz web moderna con actualizaciones via WebSocket
• Almacenamiento dual: PostgreSQL (estructurado) + MongoDB (logs completos)

🛠️ Instalación

Prerequisitos

• Python 3.10+
• Node.js 18+
• Docker y Docker Compose (opcional)
• PostgreSQL 16+
• MongoDB 7+

Opción 1: Con Docker (Recomendado)

# 1. Clonar configuración de entorno
cp .env.example .env

# 2. Editar .env con tu NVIDIA API key
nano .env

# 3. Levantar servicios
docker-compose up -d

Opción 2: Manual

# 1. Instalar dependencias Python
cd python-sentinel
pip install -r requirements.txt

# 2. Configurar variables de entorno
cp .env.example .env
# Editar .env con tus configuraciones

# 3. Iniciar bases de datos (si no están ya corriendo)
# PostgreSQL y MongoDB deben estar corriendo

# 4. Iniciar backend
cd backend
python backend_server.py

# 5. Iniciar conectores (en terminales separadas)
cd ../connectors
python suricata_connector.py
python zeek_connector.py

# 6. Iniciar dashboard (en otra terminal)
cd ../../web_dashboard
npm install
npm run dev

🔑 Configuración

NVIDIA NIM API Key

1. Obtén tu API key de NVIDIA NIM
2. Agrégala a .env:

NVIDIA_API_KEY=nvapi-tu-key-aqui

Rutas de Logs

Configurar las rutas donde están los logs de las herramientas de seguridad:

SURICATA_EVE_JSON=/var/log/suricata/eve.json
ZEEK_LOGS_DIR=/var/log/zeek

Automatización

Configurar qué acciones se ejecutan automáticamente:

AUTO_BLOCK_IPS=true          # Bloquear IPs maliciosas automáticamente
AUTO_GENERATE_RULES=true     # Generar reglas de Suricata automáticamente
AUTO_REMEDIATION=false       # Auto-remediación de vulnerabilidades (PRECAUCIÓN)
ALERT_THRESHOLD_CRITICAL=8   # Umbral para alertas críticas
ALERT_THRESHOLD_HIGH=6       # Umbral para alertas altas

🤖 Inteligencia y Base de Conocimiento (Shodan KB)

Sentinel integra una Base de Conocimiento (KB) avanzada que combina datos rascados de Shodan con búsqueda semántica:

• Búsqueda Semántica (RAG): Utiliza ChromaDB para almacenar embeddings de activos y amenazas, permitiendo consultas en lenguaje natural ("¿Qué servidores web tenemos expuestos?").
• Caché Estructurada: Sincronización diaria con PostgreSQL para mantener un inventario técnico detallado de puertos, servicios y vulnerabilidades (CVEs).
• Enriquecimiento Automático: Los agentes consultan la KB para contextualizar alertas de Wazuh con datos externos de la superficie de ataque.

🏹 Agentes de Seguridad (Crossbow)

El sistema utiliza un equipo de agentes especializados coordinados por un Supervisor (LangGraph):

Agente	Especialidad	Herramientas Clave
SOC Analyst	Triaje y Análisis	shodan_kb, bandit, semgrep, interactive_shell
Network Analyst	Seguridad de Red	nmap, netcat, shodan_kb, exploit_search
Recon Specialist	OSINT e Inteligencia	web_search (ddgs), shodan_api, news_search
DFIR Investigator	Análisis Forense	volatility_mock, file_search, hex_decode
Blue Team	Defensa y Mitigación	mitre_research, firewall_config, rule_optimization

📡 API Endpoints

Mapa SOC por rol (L1/L2/L3/Manager): ver inpdocs/API_ROLE_MAP.md.

Alertas

• POST /api/alerts - Crear nueva alerta
• GET /api/alerts - Listar alertas recientes
• GET /api/alerts/{id} - Obtener alerta específica
• PATCH /api/alerts/{id}/status - Actualizar estado de alerta
• POST /api/alerts/{id}/analyze - Analizar alerta con IA
• PATCH /api/alerts/{id}/assign - Asignar/escalar alerta
• POST /api/alerts/{id}/labels - Etiquetar alerta
• GET /api/alerts/{id}/timeline - Timeline correlacionada
• POST /api/alerts/{id}/respond - Ejecutar respuesta automática

Response

• POST /api/response/execute - Ejecutar acciones de respuesta (SOAR)

Rules

• GET /api/rules/wazuh - Listar reglas Wazuh (filtros)
• GET /api/rules/wazuh/local - Obtener local_rules.xml
• POST /api/rules/wazuh/local - Agregar regla a local_rules.xml
• POST /api/rules/wazuh/validate - Validación básica de XML

Integrations

• GET /api/integrations/health - Estado best-effort de integraciones

+### Velociraptor (DFIR) + +- GET /api/velociraptor/clients - Listar agentes activos +- POST /api/velociraptor/clients/{id}/processes - Recolectar lista de procesos +- POST /api/velociraptor/query - Ejecutar VQL (L3)

• GET /api/stats - Estadísticas del dashboard

Chat IA

• POST /api/chat - Conversar con asistente IA

WebSocket

• WS /ws/alerts - Stream de alertas en tiempo real

🤖 Uso de IA

Análisis de Alertas

# El sistema automáticamente analiza alertas críticas y altas
# También puedes solicitar análisis manual:
curl -X POST http://localhost:8000/api/alerts/alert-123/analyze

Chat con IA

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explica esta alerta",
    "alert_id": "alert-123"
  }'

🔐 Seguridad

• Autenticación JWT para API
• Credenciales en variables de entorno (nunca en código)
• HTTPS recomendado para producción
• Rate limiting configurado
• Validación estricta con Pydantic

📊 Dashboard

Acceder al dashboard en http://localhost:3000

Características:

• Alertas en tiempo real
• Gráficos de tráfico y métricas
• Chat con asistente IA
• Panel de control de acciones
• Tema oscuro tipo terminal

🧪 Testing

# Tests unitarios
pytest tests/ -v

# Tests de integración
pytest tests/integration/ -v

🐛 Troubleshooting

Backend no inicia

• Verificar que PostgreSQL y MongoDB estén corriendo
• Revisar variables de entorno en .env
• Verificar logs: docker logs sentinel-backend

Conectores no reciben datos

• Verificar rutas de logs en .env
• Confirmar que Suricata/Zeek estén generando logs
• Revisar permisos de lectura de archivos de log

📝 Contribuir

1. Fork el proyecto
2. Crear branch (git checkout -b feature/nueva-funcionalidad)
3. Commit cambios (git commit -am 'Agregar funcionalidad')
4. Push al branch (git push origin feature/nueva-funcionalidad)
5. Crear Pull Request

🙏 Agradecimientos

• NVIDIA NIM para análisis de IA
• Suricata, Zeek, Wazuh, Wireshark, Velociraptor por las herramientas de seguridad