SuperDiagnosticTool

# SuperDiagnosticTool

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

<p align="center">
  <strong>Ferramenta de Diagnóstico e Correção para Windows com 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>

O SuperDiagnosticTool coleta telemetria de hardware em tempo real, envia-a à API Google Gemini para análise e gera scripts de correção em PowerShell para resolver os problemas detectados. Inclui múltiplas camadas de validação que um script gerado deve passar antes de o usuário ser solicitado a executá-lo.

---

## Capturas de Tela

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

*Interface principal mostrando a seleção do modo de verificação e a entrada da descrição do problema*

---

## Principais Recursos

### Suporte Universal a Hardware
- **Escalonamento Dinâmico:** Adapta-se automaticamente a qualquer configuração de CPU (1-128+ núcleos)
- **Lógica Independente de Hardware:** Funciona em sistemas legados (Intel Pentium) até estações de trabalho de alto desempenho (AMD Threadripper, Intel Xeon)
- **Fallbacks Seguros:** Tratamento seguro de consultas a hardware não suportado (frequência da CPU, bateria, memória swap)
- **Otimizado para Especificações Baixas:** Execução leve para evitar pressão sobre os recursos em hardware limitado

### Análise Inteligente com IA
- **Integração com Google Gemini:** Análise e diagnóstico do sistema com IA por meio da API Gemini
- **Recomendações Sensíveis ao Contexto:** Correlaciona os problemas relatados pelo usuário com a telemetria do sistema coletada
- **Auditoria de Segurança:** Verifica processos suspeitos, vazamentos de recursos e possíveis indicadores de malware
- **Verificação Pós-Correção:** Gera relatórios de conclusão que distinguem correções automatizadas de itens que exigem atenção manual

### Arquitetura de Segurança em Múltiplas Camadas

Os scripts gerados pelo Gemini passam por quatro verificações sequenciais antes de o usuário ser solicitado a aprovar a execução:

#### Pipeline de Validação
- **Correspondência com Base de Conhecimento:** Compara as soluções da IA com um conjunto de padrões de correção testados e reconhecidos como confiáveis
- **Simulação Dry-Run:** Pré-visualiza todas as alterações pretendidas (serviços, arquivos, registro) antes que qualquer modificação ocorra
- **Validação de Script (`ScriptValidator`):** Verificação em três níveis — lista de bloqueio (bloqueio rígido de padrões destrutivos), detecção de padrões suspeitos (ciente de aliases e ofuscação) e pontuação de risco em uma escala de 0 a 100
- **Interceptação de Caminhos Críticos (`CriticalPathInterceptor`):** Barreira de confiança zero que interrompe qualquer script que toque em chaves de registro HKLM/HKCU ou caminhos System32 até que o usuário confirme explicitamente

#### Limites de Segurança
- **Pontos de Restauração do Sistema:** Criados automaticamente antes de qualquer modificação
- **Snapshots Pré/Pós-Execução:** Captura completa do estado do sistema para detectar e registrar cada alteração realizada
- **Geração de Rollback:** Gera automaticamente um script de rollback seletivo caso a execução falhe
- **Registro de Execução:** Cada ação é registrada com carimbos de data/hora em `%TEMP%\superdiagnostic_execution_*.log`

#### Execução do PowerShell
- **Verificação de Privilégios de Administrador:** Os scripts verificam a elevação antes de prosseguir
- **Sanitização de Variáveis:** O escape baseado em regex preserva as variáveis `$env:` sem erros de sintaxe
- **Verificações de Segurança de Serviços:** Verifica a existência do serviço antes de qualquer operação Start/Stop/Set
- **Execução Monitorada:** Os scripts são executados via `subprocess.run` com um timeout rígido de 5 minutos, captura completa de stdout/stderr e limpeza automática de arquivos temporários. Esta é uma execução direta ao nível do host, não isolamento por VM ou container. As camadas de validação acima são a principal fronteira de segurança.
- **Tratamento de Erros:** O wrapper do PowerShell inclui blocos try/catch/finally com relatório de erros por linha

### Verificação Abrangente do Sistema
- **Métricas de Desempenho:** Uso de CPU (geral + por núcleo), detalhamento de memória, principais consumidores de recursos
- **Inteligência de Rede:** Interfaces ativas, configuração de DNS, intensidade do sinal Wi-Fi, testes de conectividade
- **Integridade de Segurança:** Estado do antivírus, perfis de firewall, histórico do Windows Update
- **Saúde do Hardware:** Estado SMART do disco, informações da GPU, estado da bateria (portáteis)
- **Serviços do Sistema:** Aplicações de arranque, serviços com falha, registos de eventos críticos
- **Auditoria de Processos:** Identifica processos com uso de recursos ou localizações de ficheiros invulgares

### Relatórios Centrados no Utilizador
- **Relatórios HTML Profissionais:** Relatórios de diagnóstico responsivos com tema escuro e métricas visuais
- **Linguagem de Conclusão no Passado:** Os relatórios usam etiquetas `[FIXED]`, `[CLEANED]`, `[DISABLED]` para refletir ações concluídas
- **Secção de Atenção Manual:** Separa claramente as correções automatizadas dos itens que requerem intervenção do utilizador
- **Arquivos com Data e Hora:** Todos os relatórios são guardados em `AI_Reports/` para rastreio histórico

---

## Início Rápido

### Transferência

**[Transferir SuperDiagnosticTool.exe](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases/latest)** — Executável autónomo (não requer Python)

> O executável não está assinado. O Windows SmartScreen mostrará um aviso na primeira execução. Consulte [TRUST_GUIDE.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/TRUST_GUIDE.md) para saber como proceder. Se preferir verificar antes de executar, compile a partir do código-fonte.

### Requisitos

- Windows 10 ou Windows 11
- Privilégios de administrador (necessários para telemetria e remediação do sistema)
- Chave de API do Google Gemini ([Obter chave gratuita](https://aistudio.google.com/app/apikey))

### Primeira Execução

1. Transfira e execute `SuperDiagnosticTool.exe`
2. Introduza a sua chave de API do Google Gemini quando solicitado
3. Descreva o problema do seu sistema
4. Selecione o modo de verificação (Quick / Deep / Complete)
5. Reveja a análise da IA e o script de remediação gerado
6. Aprove a execução ou visualize o relatório HTML detalhado

---

## Instalação (Para Programadores)

### Pré-requisitos
- Python 3.8 ou superior
- Gestor de pacotes pip

### Instalar Dependências

Crie um ambiente virtual para que as dependências da ferramenta fiquem isoladas de
outros projetos Python:

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

Ative-o no Prompt de Comando do Windows e, em seguida, instale as dependências listadas pelo repositório:

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

No PowerShell, ative o ambiente com:

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

Se o PowerShell bloquear o script de ativação, abra o PowerShell como seu usuário e
execute `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` uma vez, depois tente o
comando de ativação novamente.

### Executar a partir do código-fonte

```bash
python super_diagnose_v2.py
```

Para confirmar que a árvore de código-fonte e as dependências estão prontas antes de iniciar uma varredura, execute:

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

O comando deve terminar sem erros. A ferramenta ainda requer Windows e
privilégios de administrador quando é executada, porque vários diagnósticos usam
PowerShell e informações protegidas do sistema.

---

## Uso

### Configuração da Chave de API

**Opção A: Entrada Interativa (recomendada para o primeiro uso)**
- A ferramenta solicita uma chave de API na primeira execução
- A chave é armazenada com segurança via Windows DPAPI (`keyring`) quando disponível

**Opção B: Variável de Ambiente**
Prompt de Comando:
```bat
set GEMINI_API_KEY=your_api_key_here
```

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

**Opção C: Arquivo de Chave Manual**
Crie `gemini.key` no diretório da ferramenta:
```
your_api_key_here
```

### Modos de Verificação

| Modo | Verifica | Caso de Uso |
|------|-------|----------|
| **Verificação Rápida** | CPU, RAM, Informações Básicas | Verificação rápida de desempenho |
| **Verificação Profunda** | Sistema, Rede, Segurança, Logs, Bluetooth, Processos | Solução de problemas abrangente |
| **Verificação Completa** | Tudo o que foi mencionado acima + Integridade do Disco, GPU, Aplicativos de Inicialização | Auditoria completa do sistema |

### Exemplo de Fluxo de Trabalho

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

---

## Detalhes Técnicos

### Arquitetura do Código
- Design modular — cada categoria de diagnóstico é uma função isolada
- Tratamento abrangente de erros com blocos try/except em todo o código
- Consultas independentes de hardware com fallbacks elegantes para recursos não suportados
- Docstrings Python padrão em todas as classes e métodos públicos

### Geração de Scripts PowerShell
- Verificação de privilégios de administrador antes da execução
- Escape de variáveis baseado em regex para evitar erros de sintaxe
- Variáveis de ambiente (`$env:TEMP`, `$env:PATH`) preservadas corretamente
- Gerenciamento seguro de serviços com verificações de existência antes de cada operação

### Integração com Gemini AI
- Prompts estruturados com seções delimitadas (`[ANALYSIS_START]`, `[FIX_START]`) para análise confiável da saída
- Análise sensível ao contexto usando o snapshot de telemetria do sistema coletado
- Convenção de relatório no tempo passado para ações de remediação concluídas

---

## Segurança e Privacidade

### O que permanece na sua máquina
- Toda a verificação e análise do sistema é executada localmente.
- Nenhuma telemetria é armazenada em servidores externos por esta ferramenta.

### O que é enviado externamente
- Para gerar recomendações de IA, um snapshot de telemetria (carga da CPU, memória, nomes de processos, entradas do log de eventos, estado da rede) é transmitido para a **API Gemini do Google**.
- Sua chave de API é incluída em cada requisição ao Google.
- Consulte a [política de privacidade do Google](https://policies.google.com/privacy) para saber como esses dados são tratados do lado deles.

### Outras propriedades de segurança
- **Armazenamento da Chave de API:** Armazenada via Windows DPAPI (`keyring`) quando disponível. Nunca commitada no controle de versão.
- **Transparência Administrativa:** Cada script de remediação é exibido na íntegra e requer aprovação explícita do usuário antes da execução.
- **Não Destrutivo por Padrão:** Modificações no registro e em arquivos exigem a passagem pelo `CriticalPathInterceptor` e confirmação explícita do usuário.
- **Código Aberto:** Código-fonte completo disponível para revisão independente sob a GPL v3.0.

Consulte [SECURITY.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/SECURITY.md) para documentação adicional de segurança.

---

## Solução de Problemas

### Erro "API Key Invalid"
- Verifique se a chave está correta e ativa no [Google AI Studio](https://aistudio.google.com/app/apikey)
- Verifique se há espaços em branco ou caracteres de nova linha ocultos na chave
- Certifique-se de que a chave tem acesso à API Gemini habilitado

### "Not Running as Administrator"
- Clique com o botão direito no executável e selecione "Executar como administrador"
- Ou permita o prompt do UAC quando a ferramenta solicitar elevação

### Erro "Module Not Found" (versão Python)
```bash
pip install --upgrade psutil google-generativeai rich
```

### O Script PowerShell Falha
- Certifique-se de que o Windows PowerShell 5.1 ou superior está instalado
- O script gerado é salvo em `AI_Reports/remediation.ps1` — revise-o manualmente em busca de erros

---

## Compilando a partir do Código-Fonte

### Compilações Automatizadas (Recomendado)

O projeto usa GitHub Actions para compilar executáveis do Windows ao enviar uma tag de versão:

1. Envie suas alterações para a branch principal
2. Crie e envie uma tag de versão:
   ```bash
   git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2
   ```
3. O GitHub Actions compila o `.exe` e cria uma release automaticamente
4. Baixe na [página de Releases](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases)

Consulte [`.github/workflows/release.yml`](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/.github/workflows/release.yml) para a configuração do fluxo de trabalho de release.

### Compilação Manual (Para Testes)

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

Isso cria `dist/SuperDiagnosticTool.exe` com ícone e dependências incorporados.

### Estrutura de Arquivos

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

## Aviso Legal

Esta ferramenta gera e executa scripts PowerShell que modificam serviços, configurações e valores de registro do sistema. Antes de aprovar qualquer script de remediação:

- **Leia o script completo** — ele é exibido antes que a execução seja permitida
- **Faça backup de dados críticos** antes de executar a remediação automatizada
- **Teste em um sistema não crítico** se o escopo da alteração não estiver claro

O autor não se responsabiliza por danos ao sistema, perda de dados ou consequências não intencionais resultantes do uso desta ferramenta.

---

## Contribuindo

Contribuições são bem-vindas. Para contribuir:

1. Faça um fork do repositório
2. Crie uma branch de funcionalidade (`git checkout -b feature/improvement`)
3. Faça commit das suas alterações (`git commit -m 'Add improvement'`)
4. Envie para a branch (`git push origin feature/improvement`)
5. Abra um Pull Request

---

## Licença

Este projeto está licenciado sob a **GNU General Public License v3.0** — consulte o arquivo [LICENSE](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/LICENSE) para detalhes.

Copyright (C) 2026 GUETTAF HOUSSEM EDDINE

---

## Autor

**Guettaf Houssem Eddine**
Estudante de Engenharia Eletrotécnica
Universidade Akli Mohand Oulhadj, Bouira, Argélia
Email: [email protected]
GitHub: [@Guettaf-hossam](https://github.com/Guettaf-hossam)

---

## Agradecimentos

- **Google Gemini AI** pelas capacidades de análise de sistema
- **psutil** pela telemetria de sistema multiplataforma
- **Rich** pela renderização da interface de terminal

---

<p align="center">
  <strong>Versão 1.0</strong> | Última atualização: Agosto de 2026
</p>

<p align="center">
  Universidade Akli Mohand Oulhadj, Bouira, Argélia
</p>