SuperDiagnosticTool

# SuperDiagnosticTool

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

<p align="center">
  <strong>Strumento di diagnostica e correzione per Windows basato sull'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 raccoglie telemetria hardware in tempo reale, la invia all'API Google Gemini per l'analisi e genera script PowerShell di correzione per risolvere i problemi rilevati. Include molteplici livelli di validazione che uno script generato deve superare prima che all'utente venga chiesto di eseguirlo.

---

## Screenshot

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

*Interfaccia principale con la selezione della modalità di scansione e l'inserimento della descrizione del problema*

---

## Caratteristiche principali

### Supporto hardware universale
- **Scalabilità dinamica:** Si adatta automaticamente a qualsiasi configurazione CPU (da 1 a 128+ core)
- **Logica indipendente dall'hardware:** Funziona su sistemi legacy (Intel Pentium) fino a workstation di fascia alta (AMD Threadripper, Intel Xeon)
- **Fallback sicuri:** Gestione sicura delle query hardware non supportate (frequenza CPU, batteria, memoria swap)
- **Ottimizzato per specifiche ridotte:** Esecuzione leggera per evitare pressione sulle risorse di hardware limitato

### Analisi IA intelligente
- **Integrazione con Google Gemini:** Analisi e diagnostica di sistema basate sull'IA tramite l'API Gemini
- **Raccomandazioni contestuali:** Correla i problemi segnalati dall'utente con la telemetria di sistema raccolta
- **Audit di sicurezza:** Scansiona processi sospetti, perdite di risorse e potenziali indicatori di malware
- **Verifica post-correzione:** Genera report di completamento che distinguono le correzioni automatizzate dagli elementi che richiedono intervento manuale

### Architettura di sicurezza multilivello

Gli script generati da Gemini passano attraverso quattro controlli sequenziali prima che all'utente venga chiesto di approvarne l'esecuzione:

#### Pipeline di validazione
- **Corrispondenza con la knowledge base:** Confronta le soluzioni dell'IA con un insieme di pattern di correzione testati e verificati
- **Simulazione dry-run:** Anteprima di tutte le modifiche previste (servizi, file, registro) prima che avvenga qualsiasi modifica
- **Validazione dello script (`ScriptValidator`):** Controllo a tre livelli — blacklist (blocco totale sui pattern distruttivi), rilevamento di pattern sospetti (consapevole di alias e offuscamento) e punteggio di rischio su scala 0-100
- **Intercettazione dei percorsi critici (`CriticalPathInterceptor`):** Barriera zero-trust che blocca qualsiasi script che tocchi chiavi di registro HKLM/HKCU o percorsi System32 finché l'utente non conferma esplicitamente

#### Limiti di sicurezza
- **Punti di ripristino del sistema:** Creati automaticamente prima di qualsiasi modifica
- **Snapshot pre/post esecuzione:** Cattura completa dello stato del sistema per rilevare e registrare ogni modifica effettuata
- **Generazione del rollback:** Genera automaticamente uno script di rollback selettivo in caso di esecuzione fallita
- **Registrazione dell'esecuzione:** Ogni azione registrata con timestamp in `%TEMP%\superdiagnostic_execution_*.log`

#### Esecuzione PowerShell
- **Verifica dei privilegi di amministratore:** Gli script verificano l'elevazione prima di procedere
- **Sanitizzazione delle variabili:** L'escaping basato su regex preserva le variabili `$env:` senza errori di sintassi
- **Controlli di sicurezza dei servizi:** Verifica l'esistenza del servizio prima di qualsiasi operazione Start/Stop/Set
- **Esecuzione monitorata:** Gli script vengono eseguiti tramite `subprocess.run` con un timeout massimo di 5 minuti, cattura completa di stdout/stderr e pulizia automatica dei file temporanei. Si tratta di esecuzione diretta a livello di host, non di isolamento tramite VM o container. I livelli di validazione sopra descritti costituiscono il confine di sicurezza primario.
- **Gestione degli errori:** Il wrapper PowerShell include blocchi try/catch/finally con segnalazione degli errori riga per riga

### Scansione completa del sistema
- **Metriche di prestazione:** Utilizzo CPU (complessivo + per core), ripartizione della memoria, principali consumatori di risorse
- **Intelligence di rete:** Interfacce attive, configurazione DNS, intensità del segnale Wi-Fi, test di connettività
- **Integrità della sicurezza:** Stato dell'antivirus, profili del firewall, cronologia di Windows Update
- **Salute dell'hardware:** Stato SMART dei dischi, informazioni sulla GPU, stato della batteria (portatili)
- **Servizi di sistema:** Applicazioni di avvio, servizi non riusciti, log eventi critici
- **Audit dei processi:** Identifica i processi con utilizzo di risorse o percorsi di file insoliti

### Reportistica incentrata sull'utente
- **Report HTML professionali:** Report diagnostici responsive con tema scuro e metriche visive
- **Linguaggio di completamento al passato:** I report utilizzano i tag `[FIXED]`, `[CLEANED]`, `[DISABLED]` per riflettere le azioni completate
- **Sezione Attenzione manuale:** Separa chiaramente le correzioni automatiche dagli elementi che richiedono l'intervento dell'utente
- **Archivi con timestamp:** Tutti i report vengono salvati in `AI_Reports/` per la tracciabilità storica

---

## Avvio rapido

### Download

**[Scarica SuperDiagnosticTool.exe](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases/latest)** — Eseguibile standalone (non richiede Python)

> L'eseguibile non è firmato. Windows SmartScreen mostrerà un avviso al primo avvio. Consulta [TRUST_GUIDE.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/TRUST_GUIDE.md) per sapere come procedere. Se preferisci verificare prima di eseguirlo, compila dai sorgenti.

### Requisiti

- Windows 10 o Windows 11
- Privilegi di amministratore (necessari per la telemetria di sistema e la remediation)
- Chiave API Google Gemini ([Ottieni una chiave gratuita](https://aistudio.google.com/app/apikey))

### Primo avvio

1. Scarica ed esegui `SuperDiagnosticTool.exe`
2. Inserisci la tua chiave API Google Gemini quando richiesto
3. Descrivi il problema del tuo sistema
4. Seleziona la modalità di scansione (Quick / Deep / Complete)
5. Esamina l'analisi dell'AI e lo script di remediation generato
6. Approva l'esecuzione o visualizza il report HTML dettagliato

---

## Installazione (per sviluppatori)

### Prerequisiti
- Python 3.8 o superiore
- Gestore di pacchetti pip

### Installa le dipendenze

Crea un ambiente virtuale in modo che le dipendenze dello strumento rimangano isolate dagli
altri progetti Python:

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

Attivalo in Windows Command Prompt, poi installa le dipendenze elencate dal
repository:

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

In PowerShell, attiva l'ambiente con:

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

Se PowerShell blocca lo script di attivazione, apri PowerShell come tuo utente ed
esegui una volta `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, poi riprova
il comando di attivazione.

### Esecuzione dal codice sorgente

```bash
python super_diagnose_v2.py
```

Per confermare che l'albero dei sorgenti e le dipendenze siano pronti prima di avviare una scansione, eseguire:

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

Il comando dovrebbe terminare senza errori. Lo strumento richiede comunque Windows e
privilegi di amministratore quando viene eseguito, poiché diverse diagnostiche utilizzano
PowerShell e informazioni di sistema protette.

---

## Utilizzo

### Configurazione della chiave API

**Opzione A: Input interattivo (consigliato per il primo utilizzo)**
- Lo strumento richiede una chiave API al primo avvio
- La chiave viene memorizzata in modo sicuro tramite Windows DPAPI (`keyring`) quando disponibile

**Opzione B: Variabile d'ambiente**
Prompt dei comandi:
```bat
set GEMINI_API_KEY=your_api_key_here
```

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

**Opzione C: File di chiave manuale**
Creare `gemini.key` nella directory dello strumento:
```
your_api_key_here
```

### Modalità di scansione

| Modalità | Elementi analizzati | Caso d'uso |
|------|-------|----------|
| **Scansione rapida** | CPU, RAM, informazioni di base | Verifica rapida delle prestazioni |
| **Scansione approfondita** | Sistema, rete, sicurezza, log, Bluetooth, processi | Risoluzione dei problemi completa |
| **Scansione completa** | Tutto quanto sopra + integrità del disco, GPU, app di avvio | Audit completo del sistema |

### Esempio di flusso di lavoro

```
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)
```

## Dettagli tecnici

### Architettura del codice
- Design modulare — ogni categoria diagnostica è una funzione isolata
- Gestione completa degli errori con blocchi try/except in tutto il codice
- Query indipendenti dall'hardware con fallback controllati per le funzionalità non supportate
- Docstring Python standard su tutte le classi e i metodi pubblici

### Generazione degli script PowerShell
- Verifica dei privilegi di amministratore prima dell'esecuzione
- Escaping delle variabili basato su regex per prevenire errori di sintassi
- Variabili d'ambiente (`$env:TEMP`, `$env:PATH`) preservate correttamente
- Gestione sicura dei servizi con controlli di esistenza prima di ogni operazione

### Integrazione con Gemini AI
- Prompt strutturati con sezioni delimitate (`[ANALYSIS_START]`, `[FIX_START]`) per un parsing affidabile dell'output
- Analisi consapevole del contesto tramite lo snapshot di telemetria di sistema raccolto
- Convenzione di rendicontazione al passato per le azioni di remediation completate

---

## Sicurezza e privacy

### Cosa rimane sulla tua macchina
- Tutte le operazioni di scansione e analisi del sistema vengono eseguite localmente.
- Nessuna telemetria viene memorizzata su server esterni da questo strumento.

### Cosa viene inviato all'esterno
- Per generare raccomandazioni AI, uno snapshot di telemetria (carico CPU, memoria, nomi dei processi, voci del registro eventi, stato della rete) viene trasmesso all'**API Gemini di Google**.
- La tua chiave API è inclusa in ogni richiesta a Google.
- Consulta l'[informativa sulla privacy di Google](https://policies.google.com/privacy) per sapere come questi dati vengono gestiti dalla loro parte.

### Altre proprietà di sicurezza
- **Archiviazione della chiave API:** Memorizzata tramite Windows DPAPI (`keyring`) quando disponibile. Mai inserita nel controllo di versione.
- **Trasparenza amministrativa:** Ogni script di remediation viene mostrato per intero e richiede l'approvazione esplicita dell'utente prima dell'esecuzione.
- **Non distruttivo per impostazione predefinita:** Le modifiche al registro e ai file richiedono il superamento di `CriticalPathInterceptor` e la conferma esplicita dell'utente.
- **Open Source:** Codice sorgente completo disponibile per una revisione indipendente con licenza GPL v3.0.

Consulta [SECURITY.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/SECURITY.md) per ulteriore documentazione sulla sicurezza.

---

## Risoluzione dei problemi

### Errore "API Key Invalid"
- Verifica che la chiave sia corretta e attiva su [Google AI Studio](https://aistudio.google.com/app/apikey)
- Controlla la presenza di spazi bianchi o caratteri di nuova riga nascosti nella chiave
- Assicurati che la chiave abbia l'accesso all'API Gemini abilitato

### "Not Running as Administrator"
- Fai clic con il pulsante destro del mouse sull'eseguibile e seleziona "Esegui come amministratore"
- Oppure consenti il prompt UAC quando lo strumento richiede l'elevazione dei privilegi

### Errore "Module Not Found" (versione Python)
```bash
pip install --upgrade psutil google-generativeai rich
```

### Lo script PowerShell non funziona
- Assicurarsi che Windows PowerShell 5.1 o versione successiva sia installato
- Lo script generato viene salvato in `AI_Reports/remediation.ps1` — esaminarlo manualmente per individuare errori

---

## Compilazione dal codice sorgente

### Compilazioni automatizzate (consigliate)

Il progetto utilizza GitHub Actions per compilare gli eseguibili Windows al push di un tag di versione:

1. Eseguire il push delle modifiche al branch principale
2. Creare ed eseguire il push di un tag di versione:
   ```bash
   git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2
   ```
3. GitHub Actions compila il file `.exe` e crea automaticamente una release
4. Scarica dalla [pagina 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) per la configurazione del workflow di release.

### Build manuale (per i test)

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

Questo crea `dist/SuperDiagnosticTool.exe` con icona e dipendenze incorporate.

### Struttura dei file

```
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
```

## Disclaimer

Questo strumento genera ed esegue script PowerShell che modificano servizi di sistema, configurazioni e valori del registro. Prima di approvare qualsiasi script di remediation:

- **Leggi lo script completo** — viene visualizzato prima che l'esecuzione sia consentita
- **Esegui il backup dei dati critici** prima di eseguire la remediation automatizzata
- **Esegui test su un sistema non critico** se l'ambito delle modifiche non è chiaro

L'autore non è responsabile per danni al sistema, perdita di dati o conseguenze indesiderate derivanti dall'uso di questo strumento.

---

## Contributing

I contributi sono benvenuti. Per contribuire:

1. Fai un fork del repository
2. Crea un branch per la funzionalità (`git checkout -b feature/improvement`)
3. Esegui il commit delle modifiche (`git commit -m 'Add improvement'`)
4. Esegui il push sul branch (`git push origin feature/improvement`)
5. Apri una Pull Request

---

## License

Questo progetto è distribuito sotto la licenza **GNU General Public License v3.0** — consulta il file [LICENSE](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/LICENSE) per i dettagli.

Copyright (C) 2026 GUETTAF HOUSSEM EDDINE

---

## Author

**Guettaf Houssem Eddine**
Studente di Ingegneria Elettrotecnica
Università Akli Mohand Oulhadj, Bouira, Algeria
Email: [email protected]
GitHub: [@Guettaf-hossam](https://github.com/Guettaf-hossam)

---

## Acknowledgments

- **Google Gemini AI** per le capacità di analisi del sistema
- **psutil** per la telemetria di sistema multipiattaforma
- **Rich** per il rendering dell'interfaccia terminale

---

<p align="center">
  <strong>Version 1.0</strong> | Last Updated: August 2026
</p>

<p align="center">
  Akli Mohand Oulhadj University, Bouira, Algeria
</p>