SuperDiagnosticTool

# SuperDiagnosticTool

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

<p align="center">
  <strong>Outil de diagnostic et de remédiation Windows propulsé par l'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 collecte des données de télémétrie matérielle en temps réel, les envoie à l'API Google Gemini pour analyse et génère des scripts de remédiation PowerShell afin de résoudre les problèmes détectés. Il intègre plusieurs couches de validation qu'un script généré doit franchir avant que l'utilisateur ne soit invité à l'exécuter.

---

## Captures d'écran

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

*Interface principale affichant la sélection du mode d'analyse et la saisie de la description du problème*

---

## Fonctionnalités clés

### Prise en charge universelle du matériel
- **Mise à l'échelle dynamique :** s'adapte automatiquement à toute configuration de CPU (1 à 128+ cœurs)
- **Logique indépendante du matériel :** fonctionne sur les systèmes anciens (Intel Pentium) comme sur les stations de travail haut de gamme (AMD Threadripper, Intel Xeon)
- **Replis gracieux :** gestion sécurisée des requêtes matérielles non prises en charge (fréquence du CPU, batterie, mémoire d'échange)
- **Optimisé pour les configurations modestes :** exécution légère pour éviter toute pression sur les ressources des matériels limités

### Analyse intelligente par IA
- **Intégration Google Gemini :** analyse et diagnostic du système assistés par IA via l'API Gemini
- **Recommandations contextuelles :** met en corrélation les problèmes signalés par l'utilisateur avec la télémétrie système collectée
- **Audit de sécurité :** recherche les processus suspects, les fuites de ressources et les indicateurs potentiels de logiciels malveillants
- **Vérification post-correction :** génère des rapports d'achèvement distinguant les corrections automatisées des éléments nécessitant une intervention manuelle

### Architecture de sécurité multicouche

Les scripts générés par Gemini passent par quatre contrôles séquentiels avant que l'utilisateur ne soit invité à approuver leur exécution :

#### Pipeline de validation
- **Correspondance avec la base de connaissances :** recoupe les solutions de l'IA avec un ensemble de modèles de remédiation testés et éprouvés
- **Simulation à blanc :** prévisualise toutes les modifications prévues (services, fichiers, registre) avant toute modification effective
- **Validation de script (`ScriptValidator`) :** contrôle à trois niveaux — liste noire (blocage strict des modèles destructeurs), détection de motifs suspects (tenant compte des alias et de l'obfuscation) et notation du risque sur une échelle de 0 à 100
- **Interception des chemins critiques (`CriticalPathInterceptor`) :** barrière de confiance zéro qui interrompt tout script touchant aux clés de registre HKLM/HKCU ou aux chemins System32 jusqu'à confirmation explicite de l'utilisateur

#### Limites de sécurité
- **Points de restauration système :** créés automatiquement avant toute modification
- **Instantanés pré/post-exécution :** capture complète de l'état du système pour détecter et journaliser chaque modification effectuée
- **Génération de restauration :** génère automatiquement un script de restauration sélectif en cas d'échec de l'exécution
- **Journalisation de l'exécution :** chaque action est journalisée avec horodatage dans `%TEMP%\superdiagnostic_execution_*.log`

#### Exécution PowerShell
- **Vérification des privilèges administrateur :** Les scripts vérifient l'élévation avant de poursuivre
- **Assainissement des variables :** L'échappement basé sur les expressions régulières préserve les variables `$env:` sans erreurs de syntaxe
- **Contrôles de sécurité des services :** Vérifie l'existence du service avant toute opération Start/Stop/Set
- **Exécution surveillée :** Les scripts s'exécutent via `subprocess.run` avec un délai d'expiration strict de 5 minutes, une capture complète de stdout/stderr et un nettoyage automatique des fichiers temporaires. Il s'agit d'une exécution directe au niveau de l'hôte, et non d'une isolation par VM ou conteneur. Les couches de validation ci-dessus constituent la principale frontière de sécurité.
- **Gestion des erreurs :** Le wrapper PowerShell inclut des blocs try/catch/finally avec un rapport d'erreur ligne par ligne

### Analyse complète du système
- **Métriques de performance :** Utilisation du CPU (globale + par cœur), répartition de la mémoire, principaux consommateurs de ressources
- **Intelligence réseau :** Interfaces actives, configuration DNS, force du signal Wi-Fi, tests de connectivité
- **Intégrité de la sécurité :** État de l'antivirus, profils du pare-feu, historique de Windows Update
- **Santé du matériel :** État SMART des disques, informations GPU, état de la batterie (ordinateurs portables)
- **Services système :** Applications de démarrage, services en échec, journaux d'événements critiques
- **Audit des processus :** Identifie les processus présentant une utilisation des ressources ou des emplacements de fichiers inhabituels

### Rapports centrés sur l'humain
- **Rapports HTML professionnels :** Rapports de diagnostic réactifs au thème sombre avec métriques visuelles
- **Langage d'achèvement au passé :** Les rapports utilisent les balises `[FIXED]`, `[CLEANED]`, `[DISABLED]` pour refléter les actions accomplies
- **Section d'attention manuelle :** Sépare clairement les corrections automatisées des éléments nécessitant l'intervention de l'utilisateur
- **Archives horodatées :** Tous les rapports sont enregistrés dans `AI_Reports/` pour un suivi historique

---

## Démarrage rapide

### Téléchargement

**[Télécharger SuperDiagnosticTool.exe](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases/latest)** — Exécutable autonome (Python non requis)

> L'exécutable n'est pas signé. Windows SmartScreen affichera un avertissement au premier lancement. Consultez [TRUST_GUIDE.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/TRUST_GUIDE.md) pour savoir comment procéder. Si vous préférez vérifier avant d'exécuter, compilez plutôt depuis les sources.

### Prérequis

- Windows 10 ou Windows 11
- Privilèges administrateur (requis pour la télémétrie système et la remédiation)
- Clé API Google Gemini ([Obtenir une clé gratuite](https://aistudio.google.com/app/apikey))

### Premier lancement

1. Téléchargez et exécutez `SuperDiagnosticTool.exe`
2. Saisissez votre clé API Google Gemini lorsque demandé
3. Décrivez votre problème système
4. Sélectionnez le mode d'analyse (Rapide / Approfondi / Complet)
5. Examinez l'analyse de l'IA et le script de remédiation généré
6. Approuvez l'exécution ou consultez le rapport HTML détaillé

---

## Installation (pour les développeurs)

### Prérequis
- Python 3.8 ou supérieur
- Gestionnaire de paquets pip

### Installer les dépendances

Créez un environnement virtuel afin que les dépendances de l'outil restent isolées des
autres projets Python :

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

Activez-le dans l'invite de commandes Windows, puis installez les dépendances listées par le dépôt :

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

Dans PowerShell, activez l'environnement avec :

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

Si PowerShell bloque le script d'activation, ouvrez PowerShell en tant qu'utilisateur et
exécutez une fois `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, puis réessayez la
commande d'activation.

### Exécution depuis les sources

```bash
python super_diagnose_v2.py
```

Pour confirmer que l'arborescence source et les dépendances sont prêtes avant de lancer une analyse, exécutez :

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

La commande doit se terminer sans erreur. L'outil nécessite toujours Windows et
des privilèges d'administrateur lors de son exécution, car plusieurs diagnostics utilisent
PowerShell et des informations système protégées.

---

## Utilisation

### Configuration de la clé API

**Option A : Saisie interactive (recommandée pour une première utilisation)**
- L'outil demande une clé API lors de la première exécution
- La clé est stockée de manière sécurisée via Windows DPAPI (`keyring`) lorsqu'il est disponible

**Option B : Variable d'environnement**
Invite de commandes :
```bat
set GEMINI_API_KEY=your_api_key_here
```

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

**Option C : Fichier de clé manuel**
Créez `gemini.key` dans le répertoire de l'outil :
```
your_api_key_here
```

### Modes de scan

| Mode | Analyse | Cas d'utilisation |
|------|-------|----------|
| **Quick Scan** | CPU, RAM, Informations de base | Vérification rapide des performances |
| **Deep Scan** | Système, Réseau, Sécurité, Journaux, Bluetooth, Processus | Dépannage complet |
| **Complete Scan** | Tout ce qui précède + Santé du disque, GPU, Applications de démarrage | Audit complet du système |

### Exemple de flux de travail

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

## Détails techniques

### Architecture du code
- Conception modulaire — chaque catégorie de diagnostic est une fonction isolée
- Gestion complète des erreurs avec des blocs try/except partout
- Requêtes indépendantes du matériel avec des solutions de repli gracieuses pour les fonctionnalités non prises en charge
- Docstrings Python standard sur toutes les classes et méthodes publiques

### Génération de scripts PowerShell
- Vérification des privilèges d'administrateur avant exécution
- Échappement des variables basé sur les expressions régulières pour éviter les erreurs de syntaxe
- Variables d'environnement (`$env:TEMP`, `$env:PATH`) préservées correctement
- Gestion sécurisée des services avec vérifications d'existence avant chaque opération

### Intégration de Gemini AI
- Invites structurées avec sections délimitées (`[ANALYSIS_START]`, `[FIX_START]`) pour une analyse fiable de la sortie
- Analyse contextuelle utilisant l'instantané de télémétrie système collecté
- Convention de rapport au passé pour les actions de remédiation terminées

---

## Sécurité et confidentialité

### Ce qui reste sur votre machine
- Toutes les analyses et scans système s'exécutent localement.
- Aucune télémétrie n'est stockée sur des serveurs externes par cet outil.

### Ce qui est envoyé à l'extérieur
- Pour générer des recommandations IA, un instantané de télémétrie (charge CPU, mémoire, noms de processus, entrées du journal d'événements, état du réseau) est transmis à l'**API Gemini de Google**.
- Votre clé API est incluse dans chaque requête envoyée à Google.
- Consultez la [politique de confidentialité de Google](https://policies.google.com/privacy) pour savoir comment ces données sont traitées de leur côté.

### Autres propriétés de sécurité
- **Stockage de la clé API :** Stockée via Windows DPAPI (`keyring`) lorsqu'elle est disponible. Jamais commitée dans le contrôle de version.
- **Transparence administrateur :** Chaque script de remédiation est affiché dans son intégralité et nécessite l'approbation explicite de l'utilisateur avant exécution.
- **Non destructif par défaut :** Les modifications du registre et des fichiers nécessitent de passer par `CriticalPathInterceptor` et une confirmation explicite de l'utilisateur.
- **Open Source :** Code source complet disponible pour un examen indépendant sous GPL v3.0.

Voir [SECURITY.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/SECURITY.md) pour une documentation de sécurité supplémentaire.

---

## Dépannage

### Erreur « API Key Invalid »
- Vérifiez que la clé est correcte et active sur [Google AI Studio](https://aistudio.google.com/app/apikey)
- Vérifiez la présence d'espaces ou de caractères de nouvelle ligne cachés dans la clé
- Assurez-vous que la clé a accès à l'API Gemini activé

### « Not Running as Administrator »
- Faites un clic droit sur l'exécutable et sélectionnez « Run as Administrator »
- Ou autorisez l'invite UAC lorsque l'outil demande une élévation

### Erreur « Module Not Found » (version Python)
```bash
pip install --upgrade psutil google-generativeai rich
```

### Le script PowerShell échoue
- Vérifiez que Windows PowerShell 5.1 ou une version ultérieure est installé
- Le script généré est enregistré dans `AI_Reports/remediation.ps1` — examinez-le manuellement pour détecter les erreurs

---

## Compilation depuis les sources

### Compilations automatisées (recommandé)

Le projet utilise GitHub Actions pour compiler les exécutables Windows lors du push d'un tag de version :

1. Poussez vos modifications vers la branche principale
2. Créez et poussez un tag de version :
   ```bash
   git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2
   ```
3. GitHub Actions compile le `.exe` et crée automatiquement une release
4. Téléchargez depuis la [page Releases](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases)

Consultez [`.github/workflows/release.yml`](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/.github/workflows/release.yml) pour la configuration du workflow de release.

### Compilation manuelle (pour les tests)

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

Cela crée `dist/SuperDiagnosticTool.exe` avec l'icône et les dépendances intégrées.

### Structure des fichiers

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

## Avertissement

Cet outil génère et exécute des scripts PowerShell qui modifient les services système, les configurations et les valeurs du registre. Avant d'approuver un script de remédiation :

- **Lisez le script dans son intégralité** — il est affiché avant que l'exécution ne soit autorisée
- **Sauvegardez les données critiques** avant d'exécuter une remédiation automatisée
- **Testez sur un système non critique** si la portée des modifications n'est pas claire

L'auteur n'est pas responsable des dommages système, des pertes de données ou des conséquences imprévues résultant de l'utilisation de cet outil.

---

## Contribution

Les contributions sont les bienvenues. Pour contribuer :

1. Forkez le dépôt
2. Créez une branche de fonctionnalité (`git checkout -b feature/improvement`)
3. Validez vos modifications (`git commit -m 'Add improvement'`)
4. Poussez vers la branche (`git push origin feature/improvement`)
5. Ouvrez une Pull Request

---

## Licence

Ce projet est sous licence **GNU General Public License v3.0** — consultez le fichier [LICENSE](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/LICENSE) pour plus de détails.

Copyright (C) 2026 GUETTAF HOUSSEM EDDINE

---

## Auteur

**Guettaf Houssem Eddine**
Étudiant en génie électrotechnique
Université Akli Mohand Oulhadj, Bouira, Algérie
Email : [email protected]
GitHub : [@Guettaf-hossam](https://github.com/Guettaf-hossam)

---

## Remerciements

- **Google Gemini AI** pour les capacités d'analyse système
- **psutil** pour la télémétrie système multiplateforme
- **Rich** pour le rendu de l'interface terminal

---

<p align="center">
  <strong>Version 1.0</strong> | Dernière mise à jour : août 2026
</p>

<p align="center">
  Université Akli Mohand Oulhadj, Bouira, Algérie
</p>