SuperDiagnosticTool

# SuperDiagnosticTool

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/11160/8b0da1a673733dc9731164bd4d4a3ecc6a137e583d070725852e8173311ef7fc.png" alt="Icono de SuperDiagnosticTool" width="200"/>
</p>

<p align="center">
  <strong>Herramienta de diagnóstico y remediación de Windows impulsada por IA</strong>
</p>

<p align="center">
  <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases"><img src="https://img.shields.io/github/v/release/Guettaf-hossam/SuperDiagnosticTool?style=flat-square" alt="Release"></a>
  <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-GPL%20v3.0-blue.svg?style=flat-square" alt="License"></a>
  <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/stargazers"><img src="https://img.shields.io/github/stars/Guettaf-hossam/SuperDiagnosticTool?style=flat-square" alt="Stars"></a>
</p>

SuperDiagnosticTool recopila telemetría de hardware en tiempo real, la envía a la API de Google Gemini para su análisis y genera scripts de remediación en PowerShell para abordar los problemas detectados. Incluye múltiples capas de validación que un script generado debe superar antes de que se solicite al usuario que lo ejecute.

---

## Capturas de pantalla

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/11160/eb10d4e2a86193e87d0face0e034418d7a5977df9057fb6fed97b0ea705e4442.png" alt="Interfaz principal" width="800"/>
</p>

*Interfaz principal mostrando la selección del modo de escaneo y la entrada de descripción del problema*

---

## Características principales

### Compatibilidad universal con hardware
- **Escalado dinámico:** Se adapta automáticamente a cualquier configuración de CPU (1-128+ núcleos)
- **Lógica independiente del hardware:** Funciona en sistemas heredados (Intel Pentium) hasta estaciones de trabajo de gama alta (AMD Threadripper, Intel Xeon)
- **Degradación controlada:** Manejo seguro de consultas de hardware no compatibles (frecuencia de CPU, batería, memoria de intercambio)
- **Optimizado para equipos de bajas prestaciones:** Ejecución ligera para evitar presión sobre los recursos en hardware limitado

### Análisis inteligente con IA
- **Integración con Google Gemini:** Análisis y diagnóstico del sistema impulsados por IA mediante la API de Gemini
- **Recomendaciones contextuales:** Correlaciona los problemas reportados por el usuario con la telemetría del sistema recopilada
- **Auditoría de seguridad:** Busca procesos sospechosos, fugas de recursos e indicadores potenciales de malware
- **Verificación posterior a la corrección:** Genera informes de finalización que distinguen las correcciones automatizadas de los elementos que requieren atención manual

### Arquitectura de seguridad multicapa

Los scripts generados por Gemini pasan por cuatro comprobaciones secuenciales antes de que se solicite al usuario aprobar su ejecución:

#### Canal de validación
- **Coincidencia con la base de conocimientos:** Contrasta las soluciones de la IA con un conjunto de patrones de remediación probados y verificados
- **Simulación en seco:** Previsualiza todos los cambios previstos (servicios, archivos, registro) antes de que se produzca cualquier modificación
- **Validación de scripts (`ScriptValidator`):** Comprobación en tres niveles — lista negra (bloqueo estricto de patrones destructivos), detección de patrones sospechosos (con reconocimiento de alias y ofuscación) y puntuación de riesgo en una escala de 0 a 100
- **Intercepción de rutas críticas (`CriticalPathInterceptor`):** Puerta de confianza cero que detiene cualquier script que toque claves de registro HKLM/HKCU o rutas de System32 hasta que el usuario lo confirme explícitamente

#### Límites de seguridad
- **Puntos de restauración del sistema:** Se crean automáticamente antes de cualquier modificación
- **Instantáneas previas y posteriores a la ejecución:** Captura completa del estado del sistema para detectar y registrar cada cambio realizado
- **Generación de reversión:** Genera automáticamente un script de reversión selectivo si la ejecución falla
- **Registro de ejecución:** Cada acción se registra con marcas de tiempo en `%TEMP%\superdiagnostic_execution_*.log`

#### Ejecución de PowerShell
- **Verificación de privilegios de administrador:** Los scripts comprueban la elevación antes de continuar
- **Saneamiento de variables:** El escape basado en regex preserva las variables `$env:` sin errores de sintaxis
- **Comprobaciones de seguridad de servicios:** Verifica la existencia del servicio antes de cualquier operación Start/Stop/Set
- **Ejecución monitorizada:** Los scripts se ejecutan mediante `subprocess.run` con un tiempo de espera estricto de 5 minutos, captura completa de stdout/stderr y limpieza automática de archivos temporales. Se trata de una ejecución directa a nivel de host, no de aislamiento mediante VM o contenedor. Las capas de validación anteriores constituyen el límite de seguridad principal.
- **Manejo de errores:** El wrapper de PowerShell incluye bloques try/catch/finally con informes de error por línea

### Escaneo integral del sistema
- **Métricas de rendimiento:** Uso de CPU (global + por núcleo), desglose de memoria, principales consumidores de recursos
- **Inteligencia de red:** Interfaces activas, configuración de DNS, intensidad de señal Wi-Fi, pruebas de conectividad
- **Integridad de seguridad:** Estado del antivirus, perfiles de firewall, historial de Windows Update
- **Salud del hardware:** Estado SMART del disco, información de la GPU, estado de la batería (portátiles)
- **Servicios del sistema:** Aplicaciones de inicio, servicios fallidos, registros de eventos críticos
- **Auditoría de procesos:** Identifica procesos con uso de recursos o ubicaciones de archivos inusuales

### Informes centrados en las personas
- **Informes HTML profesionales:** Informes de diagnóstico responsivos con tema oscuro y métricas visuales
- **Lenguaje de finalización en pasado:** Los informes usan etiquetas `[FIXED]`, `[CLEANED]`, `[DISABLED]` para reflejar acciones completadas
- **Sección de atención manual:** Separa claramente las correcciones automatizadas de los elementos que requieren intervención del usuario
- **Archivos con marca de tiempo:** Todos los informes se guardan en `AI_Reports/` para su seguimiento histórico

---

## Inicio rápido

### Descarga

**[Descargar SuperDiagnosticTool.exe](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases/latest)** — Ejecutable autónomo (no requiere Python)

> El ejecutable no está firmado. Windows SmartScreen mostrará una advertencia en la primera ejecución. Consulte [TRUST_GUIDE.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/TRUST_GUIDE.md) para saber cómo proceder. Si prefiere verificar antes de ejecutar, compile desde el código fuente.

### Requisitos

- Windows 10 o Windows 11
- Privilegios de administrador (necesarios para la telemetría del sistema y la remediación)
- Clave de API de Google Gemini ([Obtener clave gratuita](https://aistudio.google.com/app/apikey))

### Primera ejecución

1. Descargue y ejecute `SuperDiagnosticTool.exe`
2. Introduzca su clave de API de Google Gemini cuando se le solicite
3. Describa el problema de su sistema
4. Seleccione el modo de escaneo (Quick / Deep / Complete)
5. Revise el análisis de la IA y el script de remediación generado
6. Apruebe la ejecución o consulte el informe HTML detallado

---

## Instalación (para desarrolladores)

### Requisitos previos
- Python 3.8 o superior
- Gestor de paquetes pip

### Instalar dependencias

Cree un entorno virtual para que las dependencias de la herramienta permanezcan aisladas de
otros proyectos de Python:

```bash
python -m venv .venv
```

Actívelo en el Símbolo del sistema de Windows y, a continuación, instale las dependencias indicadas por el repositorio:

```bat
.venv\Scripts\activate
pip install -r requirements.txt
```

En PowerShell, active el entorno con:

```powershell
.\.venv\Scripts\Activate.ps1
```

Si PowerShell bloquea el script de activación, abre PowerShell como tu usuario y ejecuta `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` una vez, luego intenta el comando de activación de nuevo.

### Ejecutar desde el código fuente

```bash
python super_diagnose_v2.py
```

Para confirmar que el árbol de fuentes y las dependencias están listos antes de iniciar un escaneo, ejecute:

```bash
python -m compileall src super_diagnose_v2.py
```

El comando debería finalizar sin errores. La herramienta sigue requiriendo Windows y
privilegios de administrador cuando se ejecuta, porque varios diagnósticos usan
PowerShell e información protegida del sistema.

---

## Uso

### Configuración de la clave API

**Opción A: Entrada interactiva (recomendada para el primer uso)**
- La herramienta solicita una clave API en la primera ejecución
- La clave se almacena de forma segura mediante Windows DPAPI (`keyring`) cuando está disponible

**Opción B: Variable de entorno**
Símbolo del sistema:
```bat
set GEMINI_API_KEY=your_api_key_here
```

PowerShell:
```powershell
$env:GEMINI_API_KEY = "your_api_key_here"
```

**Opción C: Archivo de clave manual**
Cree `gemini.key` en el directorio de la herramienta:
```
your_api_key_here
```

### Modos de escaneo

| Modo | Escanea | Caso de uso |
|------|-------|----------|
| **Escaneo rápido** | CPU, RAM, información básica | Verificación rápida del rendimiento |
| **Escaneo profundo** | Sistema, red, seguridad, registros, Bluetooth, procesos | Solución de problemas integral |
| **Escaneo completo** | Todo lo anterior + estado del disco, GPU, aplicaciones de inicio | Auditoría completa del sistema |

### Flujo de trabajo de ejemplo

```
1. Run the tool
   > SuperDiagnosticTool.exe

2. Describe your issue
   > High CPU usage and slow performance

3. Select scan mode
   > 3 (Complete System Scan)

4. Wait for AI analysis
   [Scanning system layers...]
   [Processing telemetry...]

5. Review the generated remediation script
   > Execute? (y/n)

6. View the HTML report
   > Open detailed report? (y/n)
```

---

## Detalles técnicos

### Arquitectura del código
- Diseño modular — cada categoría de diagnóstico es una función aislada
- Manejo integral de errores con bloques try/except en todo el código
- Consultas independientes del hardware con alternativas seguras para funciones no compatibles
- Docstrings estándar de Python en todas las clases y métodos públicos

### Generación de scripts de PowerShell
- Verificación de privilegios de administrador antes de la ejecución
- Escape de variables basado en expresiones regulares para evitar errores de sintaxis
- Variables de entorno (`$env:TEMP`, `$env:PATH`) preservadas correctamente
- Gestión segura de servicios con comprobaciones de existencia antes de cada operación

### Integración con Gemini AI
- Prompts estructurados con secciones delimitadas (`[ANALYSIS_START]`, `[FIX_START]`) para un análisis de salida fiable
- Análisis contextual mediante la instantánea de telemetría del sistema recopilada
- Convención de informes en tiempo pasado para las acciones de remediación completadas

---

## Seguridad y privacidad

### Qué permanece en tu máquina
- Todo el escaneo y análisis del sistema se ejecuta localmente.
- Esta herramienta no almacena telemetría en servidores externos.

### Qué se envía al exterior
- Para generar recomendaciones de IA, se transmite una instantánea de telemetría (carga de CPU, memoria, nombres de procesos, entradas del registro de eventos, estado de la red) a la **API de Gemini de Google**.
- Tu clave de API se incluye en cada solicitud a Google.
- Consulta la [política de privacidad de Google](https://policies.google.com/privacy) para saber cómo se tratan estos datos por su parte.

### Otras propiedades de seguridad
- **Almacenamiento de la clave de API:** Se almacena mediante Windows DPAPI (`keyring`) cuando está disponible. Nunca se confirma en el control de versiones.
- **Transparencia de administrador:** Cada script de remediación se muestra en su totalidad y requiere la aprobación explícita del usuario antes de ejecutarse.
- **No destructivo por defecto:** Las modificaciones del registro y de archivos requieren superar `CriticalPathInterceptor` y la confirmación explícita del usuario.
- **Código abierto:** Código fuente completo disponible para revisión independiente bajo GPL v3.0.

Consulta [SECURITY.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/SECURITY.md) para documentación de seguridad adicional.

---

## Solución de problemas

### Error "API Key Invalid"
- Verifica que la clave sea correcta y esté activa en [Google AI Studio](https://aistudio.google.com/app/apikey)
- Comprueba si hay espacios en blanco o caracteres de nueva línea ocultos en la clave
- Asegúrate de que la clave tenga habilitado el acceso a la API de Gemini

### "Not Running as Administrator"
- Haz clic derecho en el ejecutable y selecciona "Run as Administrator"
- O permite el aviso de UAC cuando la herramienta solicite elevación

### Error "Module Not Found" (versión de Python)
```bash
pip install --upgrade psutil google-generativeai rich
```

### El script de PowerShell falla
- Asegúrese de que Windows PowerShell 5.1 o posterior esté instalado
- El script generado se guarda en `AI_Reports/remediation.ps1` — revíselo manualmente en busca de errores

---

## Compilación desde el código fuente

### Compilaciones automatizadas (recomendado)

El proyecto utiliza GitHub Actions para compilar ejecutables de Windows al publicar una etiqueta de versión:

1. Envíe sus cambios a la rama principal
2. Cree y publique una etiqueta de versión:
   ```bash
   git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2
   ```
3. GitHub Actions compila el `.exe` y crea una release automáticamente
4. Descárgalo desde la [página de Releases](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases)

Consulta [`.github/workflows/release.yml`](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/.github/workflows/release.yml) para la configuración del flujo de trabajo de release.

### Compilación manual (para pruebas)

```bash
pip install pyinstaller
pip install -r requirements.txt
python build.py
```

Esto crea `dist/SuperDiagnosticTool.exe` con icono y dependencias incrustados.

### Estructura de archivos

```
SuperDiagnosticTool/
├── super_diagnose_v2.py       # Main entry point and diagnostic logic
├── build.py                   # PyInstaller build script
├── icon.ico                   # Application icon
├── .github/workflows/
│   └── release.yml            # Automated build and release workflow
├── docs/
│   ├── icon.png
│   └── screenshot_main.png
├── src/
│   ├── safety/                # Script validation and monitored execution
│   │   ├── validator.py       # ScriptValidator + CriticalPathInterceptor
│   │   ├── sandbox.py         # SandboxExecutor (monitored subprocess runner)
│   │   ├── dry_run.py         # DryRunSimulator
│   │   ├── restore_point.py   # RestorePointManager
│   │   ├── enhanced_monitoring.py
│   │   └── knowledge_base.py
│   └── security/              # CredentialVault (DPAPI-backed key storage)
├── AI_Reports/                # Generated HTML reports and remediation scripts
├── README.md
├── SECURITY.md
├── TRUST_GUIDE.md
├── LICENSE                    # GPL-3.0
└── .gitignore
```

## Descargo de responsabilidad

Esta herramienta genera y ejecuta scripts de PowerShell que modifican servicios del sistema, configuraciones y valores del registro. Antes de aprobar cualquier script de remediación:

- **Lea el script completo** — se muestra antes de permitir la ejecución
- **Realice una copia de seguridad de los datos críticos** antes de ejecutar la remediación automatizada
- **Pruebe en un sistema no crítico** si el alcance del cambio no está claro

El autor no se hace responsable de daños al sistema, pérdida de datos ni consecuencias no deseadas derivadas del uso de esta herramienta.

---

## Contribuir

Las contribuciones son bienvenidas. Para contribuir:

1. Haga un fork del repositorio
2. Cree una rama de funcionalidad (`git checkout -b feature/improvement`)
3. Confirme sus cambios (`git commit -m 'Add improvement'`)
4. Suba los cambios a la rama (`git push origin feature/improvement`)
5. Abra una Pull Request

---

## Licencia

Este proyecto está licenciado bajo la **GNU General Public License v3.0** — consulte el archivo [LICENSE](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/LICENSE) para más detalles.

Copyright (C) 2026 GUETTAF HOUSSEM EDDINE

---

## Autor

**Guettaf Houssem Eddine**
Estudiante de Ingeniería Electrotécnica
Universidad Akli Mohand Oulhadj, Bouira, Argelia
Correo electrónico: [email protected]
GitHub: [@Guettaf-hossam](https://github.com/Guettaf-hossam)

---

## Agradecimientos

- **Google Gemini AI** por las capacidades de análisis del sistema
- **psutil** por la telemetría del sistema multiplataforma
- **Rich** por la representación de la interfaz de terminal

---

<p align="center">
  <strong>Versión 1.0</strong> | Última actualización: agosto de 2026
</p>

<p align="center">
  Universidad Akli Mohand Oulhadj, Bouira, Argelia
</p>