🛡️ Sentinel Detector — Deep Auditor v1.1.1

Sentinel Detector es un auditor y escáner de seguridad para sistemas Windows diseñado para ejecutarse directamente en tu terminal. Combina análisis heurístico avanzado en tiempo real con Validación por Inteligencia Artificial para identificar, analizar y eliminar programas dañinos (malware), persistencias sospechosas en el registro y archivos maliciosos ocultos, protegiéndote activamente contra falsos positivos.

✨ Características Principales

• 🧠 IA con Redundancia Automática: El motor de IA prueba hasta 5 modelos gratuitos en secuencia con reintento automático en caso de rate limit (429). Configurable vía SENTINEL_AI_MODEL.
• 💬 Sentinel Expert IA (Cybersecurity Chatbot): Un asistente conversacional interactivo integrado en consola. Carga automáticamente los resultados del último escaneo para que puedas preguntar sobre rutas, procesos o archivos específicos detectados en tu PC. Escribe salir o esc para regresar al menú.
• 📄 Auditoría y Desofuscación de Scripts: Permite auditar y desofuscar scripts locales sospechosos (.bat, .ps1, .vbs, .py). La IA analiza el contenido completo, detecta técnicas de evasión o cifrado (como Base64) y revela su verdadera función en español.
• 📈 Reporte de Postura y Puntuación de Salud (Security Score): Evalúa la salud general de tu sistema otorgando una calificación de 0 a 100 basada en las amenazas encontradas. Genera un reporte detallado exportable en Markdown (sentinel_security_report.md) con recomendaciones preventivas personalizadas.
• 💾 Análisis de Memoria en Vivo (Procesos): Escanea procesos activos buscando técnicas comunes de malware, como la Suplantación de Identidad (Masquerading) (ej. svchost.exe corriendo fuera de System32), rutas sospechosas (AppData, Temp), conexiones de red activas hacia IPs externas y comandos cmdline altamente maliciosos.
• 🔑 Auditoría de Persistencia (Registro de Windows): Examina las llaves de arranque automático de Windows (HKCU\Run, HKLM\Run, etc.) buscando scripts maliciosos, accesos directos ocultos o entradas huérfanas en el disco.
• 📂 Escáner de Archivos Engañosos: Inspecciona carpetas críticas de usuario en busca de trampas comunes como doble extensión maliciosa (ej: foto.jpg.exe) y copias temporales sospechosas de bases de datos de credenciales.
• 🎨 Interfaz Terminal Adaptativa: Diseñado con la biblioteca rich. Las tablas se adaptan al ancho de la terminal: layout compacto en pantallas angostas, columnas completas en pantallas anchas.
• ⚡ Menú de Desinfección Activa y Automatizada: Permite terminar procesos maliciosos, limpiar llaves de arranque, eliminar archivos infectados y ejecutar un escaneo completo + filtrado IA + auto-limpieza en un solo paso.

🚀 Instalación y Uso

Opción A: Instalación Global vía pnpm (Recomendado)

Esta es la forma más rápida y limpia. No necesitas clonar el repositorio. Abre una terminal (PowerShell o CMD, preferiblemente como Administrador) y ejecuta:

pnpm add -g @jeremysg31/sentinel-detector --ignore-scripts

[!NOTE] Se recomienda --ignore-scripts para evitar la ejecución de scripts arbitrarios durante la instalación. Las dependencias de Python se instalan automáticamente al ejecutar el comando por primera vez.

Una vez instalado, ejecuta desde cualquier lugar:

sentinel-detector

Opción B: Instalación Global vía npm (Alternativa)

Si usas npm en lugar de pnpm:

npm install -g @jeremysg31/sentinel-detector --ignore-scripts

[!NOTE] npm no tiene la restricción de minimumReleaseAge de pnpm v11, por lo que las nuevas versiones están disponibles inmediatamente.

Una vez instalado, ejecuta desde cualquier lugar:

sentinel-detector

Opción C: Para Desarrolladores (Ejecución Local)

Si has descargado o clonado el repositorio:

Método 1: Enlace global (symlink)

pnpm link --global
sentinel-detector

(Cualquier cambio guardado en el código local se aplica automáticamente al comando global).

Método 2: Ejecución directa en Python

pip install rich psutil requests python-dotenv
python DetectarLacra.py

[!IMPORTANT] Requisito de Administrador: Se recomienda ejecutar la terminal como Administrador. De lo contrario, Windows denegará el acceso a ciertos procesos del sistema y llaves protegidas del Registro.

💣 Desinstalación

Si necesitas eliminar el paquete globalmente, ejecuta:

pnpm uninstall -g @jeremysg31/sentinel-detector

Esto removerá el comando sentinel-detector de tu sistema.

Sentinel Detector no incluye ninguna API Key por defecto. Para usar las funciones de IA (chatbot, auditoría de scripts, filtrado de falsos positivos) necesitas una clave gratuita de OpenRouter:

1. Consigue tu API Key gratis en OpenRouter.ai/keys.
2. En el menú principal, selecciona la opción 6 para configurar tu API Key.
3. O crea un archivo .env en la carpeta del proyecto:

   OPENROUTER_API_KEY=tu_clave_aqui

   (Opcional) Para usar un modelo distinto al predeterminado:

   SENTINEL_AI_MODEL=google/gemma-4-26b-a4b-it:free

[!IMPORTANT] Sin API Key el programa sigue funcionando para escaneos heurísticos; solo las funciones que requieren IA quedarán deshabilitadas.

💬 Uso del Chatbot (Sentinel Expert IA)

| Acción | Comando | |---|---|---| | Salir del chat | Escribe salir, esc, exit o volver | | Cancelar mientras escribes | Presiona Ctrl+C (vuelve al prompt) |

📋 Menú Principal

| Opción | Función | |---|---| | 1 | Análisis Inteligente Automatizado (Escaneo + IA + Auto-Limpieza) | | 2 | Análisis Personalizado (Elegir qué escanear + acciones manuales) | | 3 | Sentinel Expert IA (Chatbot de Consultoría) | | 4 | Auditar y Desofuscar un Script Local | | 5 | Generar Reporte de Postura de Seguridad y Puntuación | | 6 | Cambiar / Ingresar API Key de OpenRouter | | 7 | Salir |

🛠️ Tecnologías Utilizadas

• Python 3 — Lógica principal del detector, requests y acceso al sistema.
• Node.js & pnpm — Distribución del CLI y empaquetado global.
• Rich — Formateador visual y animaciones de terminal.
• Psutil & Winreg — Acceso a procesos y registro del sistema operativo.
• OpenRouter API — Motor de IA con fallback automático entre modelos gratuitos.

📝 Changelog

v1.1.1

• 🔥 API Key removida del código — La clave hardcodeada fue eliminada. Ahora solo se carga desde variable de entorno OPENROUTER_API_KEY o archivo .env.
• 🧹 Código público listo — Eliminados datos personales y claves del repositorio.
• 🐛 Fix: Ctrl+C en chatbot — Reemplazado el mecanismo de cancelación por hilos (se trababa) por una captura simple de KeyboardInterrupt.
• 🐛 Fix: accesos frágiles a respuesta IA — Reemplazados accesos directos result['choices'][0]['message']['content'] por .get() seguro en todos los métodos.
• 🐛 Fix: progreso colgado con 0 procesos — scan_processes() ahora retorna early si no hay procesos.
• 🐛 Fix: falso "sistema limpio" sin API Key — run_automated_analysis() ahora distingue si la IA corrió o no antes de mostrar el veredicto.
• 🐛 Fix: except: desnudos — Reemplazados por except Exception:.
• 🐛 Fix: proc.connections() obsoleto — Cambiado a proc.net_connections() (elimina el DeprecationWarning).
• 💄 Interfaz adaptativa al ancho de terminal — Banner, tablas y truncamiento de texto se ajustan al tamaño de la consola.
• 💄 Pantalla limpia en cada opción — clear_screen() (vía cls nativo) antes y después de cada acción, sin residuos del menú.
• 💄 Mensajes de error IA con tips específicos — Cada error (429, 402, 401, 503) muestra su solución correspondiente.
• 🚀 Reintento automático en rate limit — Si todos los modelos dan 429, espera 15s y reintenta.
• 🚀 Modelos actualizados — Lista de modelos gratuitos renovada con opciones actuales de OpenRouter.
• 🚀 Modelo configurable vía env var — SENTINEL_AI_MODEL permite cambiar el modelo por defecto.
• 🧠 Historial del chatbot truncado — conversation_history limitado a 12 mensajes para evitar fugas de tokens/memoria.
• 🧠 Código muerto eliminado — Heurística #4 de scan_filesystem (elif pass), headers sin uso, import socket sobrante.
• 📝 Documentación actualizada — README refleja que no hay API Key por defecto y cómo configurarla.

v1.0.7

• 🐛 Fix: NameError al iniciar — La función ensure_pnpm() usaba console.print() de Rich antes de que Rich fuera importado, causando un crash al arrancar. Ahora usa print() nativo.

v1.0.6

• 🐛 Fix crítico: Ctrl+C durante respuesta de la IA — Antes, al pulsar Ctrl+C mientras la IA respondía, el programa crasheaba con un KeyboardInterrupt dentro de la capa SSL/socket de requests. Ahora la llamada a la API se ejecuta en un hilo secundario (daemon thread), y el hilo principal espera con timeouts cortos (0.15s), lo que permite capturar Ctrl+C de forma instantánea sin importar si la red está bloqueada.
• ✅ Cancelación limpia — Al cancelar, el spinner se detiene inmediatamente, se muestra un mensaje amigable y el historial de conversación se mantiene íntegro.

v1.0.5

• ✅ IA con redundancia automática: Si el modelo principal falla o tiene límite de peticiones, cambia automáticamente a modelos alternativos gratuitos (Llama 3.3 70B, Llama 3.2 3B, Gemma 4 31B, openrouter/free).
• ✅ Chatbot: cancelar respuesta con Ctrl+C — Al pulsar Ctrl+C mientras la IA responde, se cancela la solicitud limpiamente y vuelve al prompt sin perder el historial de la conversación.
• ✅ Chatbot: Ctrl+C en prompt no cierra el programa — Se captura tanto KeyboardInterrupt como EOFError para evitar crashes al pulsar Ctrl+C mientras se escribe.
• ✅ Chatbot: comando esc — Además de salir, ahora se puede escribir esc para volver al menú principal.
• ✅ Chatbot: contexto del escaneo integrado — El chatbot carga automáticamente los resultados del último análisis para dar respuestas más precisas sobre tu PC.
• ✅ Rutas directas en resultados — Los informes y resultados muestran la ruta completa de cada amenaza detectada.

v1.0.4

• ✅ Instalación automática de dependencias Python al ejecutar.
• ✅ Restricción de instalador a pnpm.
• ✅ Mejora del menú: Análisis Automatizado y Personalizado.

🛡️ Descargo de Responsabilidad

Esta herramienta está diseñada para auditorías rápidas de seguridad y asistencia heurística local. No reemplaza a un antivirus comercial completo y en tiempo real. Utilízala bajo tu propia responsabilidad. ¡Mantén tu sistema libre de lacras!

Desarrollado con ❤️ y tecnología avanzada.