SuperDiagnosticTool

# SuperDiagnosticTool

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/11160/8b0da1a673733dc9731164bd4d4a3ecc6a137e583d070725852e8173311ef7fc.png" alt="Значок SuperDiagnosticTool" width="200"/>
</p>

<p align="center">
  <strong>Инструмент диагностики и устранения неполадок Windows на базе ИИ</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 собирает телеметрию оборудования в реальном времени, отправляет её в Google Gemini API для анализа и генерирует скрипты исправления на PowerShell для устранения обнаруженных проблем. Инструмент включает несколько уровней проверки, которые сгенерированный скрипт должен пройти, прежде чем пользователю будет предложено его выполнить.

---

## Скриншоты

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/11160/eb10d4e2a86193e87d0face0e034418d7a5977df9057fb6fed97b0ea705e4442.png" alt="Главный интерфейс" width="800"/>
</p>

*Главный интерфейс с выбором режима сканирования и полем ввода описания проблемы*

---

## Ключевые возможности

### Универсальная поддержка оборудования
- **Динамическое масштабирование:** автоматически адаптируется к любой конфигурации CPU (1–128+ ядер)
- **Независимость от оборудования:** работает как на устаревших системах (Intel Pentium), так и на высокопроизводительных рабочих станциях (AMD Threadripper, Intel Xeon)
- **Корректная обработка отказов:** безопасная обработка неподдерживаемых запросов к оборудованию (частота CPU, батарея, файл подкачки)
- **Оптимизация для слабых систем:** лёгкое выполнение, чтобы избежать нагрузки на ресурсы ограниченного оборудования

### Интеллектуальный анализ с помощью ИИ
- **Интеграция с Google Gemini:** анализ и диагностика системы на базе ИИ через Gemini API
- **Рекомендации с учётом контекста:** сопоставление проблем, о которых сообщил пользователь, с собранной телеметрией системы
- **Аудит безопасности:** поиск подозрительных процессов, утечек ресурсов и потенциальных признаков вредоносного ПО
- **Проверка после исправления:** формирование отчётов о завершении с разделением автоматических исправлений и пунктов, требующих ручного вмешательства

### Многоуровневая архитектура безопасности

Скрипты, сгенерированные Gemini, проходят четыре последовательные проверки, прежде чем пользователю будет предложено одобрить их выполнение:

#### Конвейер проверки
- **Сопоставление с базой знаний:** сверка решений ИИ с набором проверенных, заведомо безопасных шаблонов исправления
- **Симуляция пробного запуска:** предварительный просмотр всех предполагаемых изменений (службы, файлы, реестр) до внесения каких-либо модификаций
- **Валидация скрипта (`ScriptValidator`):** трёхуровневая проверка — чёрный список (жёсткая блокировка деструктивных шаблонов), обнаружение подозрительных шаблонов (с учётом псевдонимов и обфускации) и оценка риска по шкале от 0 до 100
- **Перехват критических путей (`CriticalPathInterceptor`):** шлюз с нулевым доверием, который останавливает любой скрипт, затрагивающий ключи реестра HKLM/HKCU или пути System32, до явного подтверждения пользователем

#### Ограничения безопасности
- **Точки восстановления системы:** создаются автоматически перед любыми изменениями
- **Снимки состояния до и после выполнения:** полный захват состояния системы для обнаружения и журналирования каждого внесённого изменения
- **Генерация отката:** автоматическое создание выборочного скрипта отката в случае сбоя выполнения
- **Журналирование выполнения:** каждое действие записывается с отметками времени в `%TEMP%\superdiagnostic_execution_*.log`

#### Выполнение PowerShell
- **Проверка прав администратора:** Скрипты проверяют наличие повышения прав перед продолжением
- **Санитизация переменных:** Экранирование на основе регулярных выражений сохраняет переменные `$env:` без синтаксических ошибок
- **Проверки безопасности служб:** Проверяет существование службы перед любой операцией Start/Stop/Set
- **Контролируемое выполнение:** Скрипты запускаются через `subprocess.run` с жёстким тайм-аутом в 5 минут, полным захватом stdout/stderr и автоматической очисткой временных файлов. Это прямое выполнение на уровне хоста, а не изоляция в виртуальной машине или контейнере. Описанные выше уровни валидации являются основной границей безопасности.
- **Обработка ошибок:** Обёртка PowerShell включает блоки try/catch/finally с построчной отчётностью об ошибках

### Комплексное сканирование системы
- **Метрики производительности:** Использование ЦП (общее + по ядрам), разбивка памяти, главные потребители ресурсов
- **Сетевая аналитика:** Активные интерфейсы, конфигурация DNS, сила сигнала Wi-Fi, тесты подключения
- **Целостность безопасности:** Статус антивируса, профили брандмауэра, история Windows Update
- **Состояние оборудования:** Статус SMART дисков, информация о GPU, состояние батареи (ноутбуки)
- **Системные службы:** Приложения автозагрузки, сбойные службы, критичные журналы событий
- **Аудит процессов:** Выявляет процессы с необычным использованием ресурсов или расположением файлов

### Отчётность, ориентированная на человека
- **Профессиональные HTML-отчёты:** Диагностические отчёты с тёмной темой и адаптивным дизайном, с визуальными метриками
- **Формулировки в прошедшем времени:** Отчёты используют теги `[FIXED]`, `[CLEANED]`, `[DISABLED]`, отражающие выполненные действия
- **Раздел ручного вмешательства:** Чётко отделяет автоматические исправления от пунктов, требующих вмешательства пользователя
- **Архивы с отметками времени:** Все отчёты сохраняются в `AI_Reports/` для исторического отслеживания

---

## Быстрый старт

### Загрузка

**[Скачать SuperDiagnosticTool.exe](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases/latest)** — автономный исполняемый файл (Python не требуется)

> Исполняемый файл не подписан. Windows SmartScreen покажет предупреждение при первом запуске. См. [TRUST_GUIDE.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/TRUST_GUIDE.md), чтобы узнать, как продолжить. Если вы предпочитаете проверить перед запуском, соберите из исходного кода.

### Требования

- Windows 10 или Windows 11
- Права администратора (необходимы для системной телеметрии и исправлений)
- Ключ API Google Gemini ([Получить бесплатный ключ](https://aistudio.google.com/app/apikey))

### Первый запуск

1. Скачайте и запустите `SuperDiagnosticTool.exe`
2. Введите ваш ключ API Google Gemini, когда появится запрос
3. Опишите вашу системную проблему
4. Выберите режим сканирования (Quick / Deep / Complete)
5. Просмотрите анализ ИИ и сгенерированный скрипт исправления
6. Одобрите выполнение или просмотрите подробный HTML-отчёт

---

## Установка (для разработчиков)

### Предварительные требования
- Python 3.8 или выше
- Менеджер пакетов pip

### Установка зависимостей

Создайте виртуальное окружение, чтобы зависимости инструмента оставались изолированными от
других проектов Python:

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

Активируйте его в командной строке Windows, затем установите зависимости, перечисленные в
репозитории:

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

В PowerShell активируйте окружение командой:

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

Если PowerShell блокирует скрипт активации, откройте PowerShell от имени вашего пользователя и
один раз выполните `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, затем повторите
команду активации.

### Запуск из исходного кода

```bash
python super_diagnose_v2.py
```

Чтобы убедиться, что дерево исходного кода и зависимости готовы перед началом
сканирования, выполните:

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

Команда должна завершиться без ошибок. Инструмент по-прежнему требует Windows и
прав администратора при запуске, поскольку некоторые диагностики используют
PowerShell и защищённую системную информацию.

---

## Использование

### Настройка API-ключа

**Вариант A: Интерактивный ввод (рекомендуется при первом использовании)**
- При первом запуске инструмент запрашивает API-ключ
- Ключ безопасно сохраняется через Windows DPAPI (`keyring`), если он доступен

**Вариант B: Переменная окружения**
Командная строка:
```bat
set GEMINI_API_KEY=your_api_key_here
```

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

**Вариант C: Ручной файл ключа**
Создайте `gemini.key` в каталоге инструмента:
```
your_api_key_here
```

### Режимы сканирования

| Режим | Что сканируется | Сценарий использования |
|------|-------|----------|
| **Быстрое сканирование** | CPU, RAM, базовая информация | Быстрая проверка производительности |
| **Глубокое сканирование** | Система, сеть, безопасность, журналы, Bluetooth, процессы | Комплексная диагностика |
| **Полное сканирование** | Всё вышеперечисленное + состояние диска, GPU, приложения автозагрузки | Полный аудит системы |

### Пример рабочего процесса

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

## Технические детали

### Архитектура кода
- Модульный дизайн — каждая диагностическая категория представляет собой изолированную функцию
- Комплексная обработка ошибок с блоками try/except повсюду
- Аппаратно-независимые запросы с корректными резервными вариантами для неподдерживаемых функций
- Стандартные строки документации Python для всех публичных классов и методов

### Генерация скриптов PowerShell
- Проверка прав администратора перед выполнением
- Экранирование переменных на основе регулярных выражений для предотвращения синтаксических ошибок
- Переменные среды (`$env:TEMP`, `$env:PATH`) сохраняются корректно
- Безопасное управление службами с проверкой существования перед каждой операцией

### Интеграция с Gemini AI
- Структурированные запросы с разделёнными секциями (`[ANALYSIS_START]`, `[FIX_START]`) для надёжного разбора вывода
- Контекстно-зависимый анализ с использованием собранного снимка телеметрии системы
- Соглашение об отчётах в прошедшем времени для выполненных действий по устранению неполадок

---

## Безопасность и конфиденциальность

### Что остаётся на вашей машине
- Всё сканирование и анализ системы выполняются локально.
- Данные телеметрии не сохраняются на внешних серверах этим инструментом.

### Что передаётся вовне
- Для генерации рекомендаций ИИ снимок телеметрии (нагрузка ЦП, память, имена процессов, записи журнала событий, состояние сети) передаётся в **Gemini API от Google**.
- Ваш API-ключ включается в каждый запрос к Google.
- Ознакомьтесь с [политикой конфиденциальности Google](https://policies.google.com/privacy), чтобы узнать, как эти данные обрабатываются на их стороне.

### Другие свойства безопасности
- **Хранение API-ключа:** Хранится через Windows DPAPI (`keyring`), когда доступно. Никогда не попадает в систему контроля версий.
- **Прозрачность для администратора:** Каждый скрипт устранения неполадок отображается полностью и требует явного одобрения пользователя перед выполнением.
- **Нерарушающий по умолчанию:** Изменения реестра и файлов требуют прохождения `CriticalPathInterceptor` и явного подтверждения пользователя.
- **Открытый исходный код:** Полный исходный код доступен для независимой проверки под лицензией GPL v3.0.

Дополнительную документацию по безопасности см. в [SECURITY.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/SECURITY.md).

---

## Устранение неполадок

### Ошибка «API Key Invalid»
- Убедитесь, что ключ правильный и активный, на [Google AI Studio](https://aistudio.google.com/app/apikey)
- Проверьте наличие скрытых пробелов или символов новой строки в ключе
- Убедитесь, что для ключа включён доступ к Gemini API

### «Not Running as Administrator»
- Щёлкните правой кнопкой мыши по исполняемому файлу и выберите «Запуск от имени администратора»
- Или разрешите запрос UAC, когда инструмент запрашивает повышение прав

### Ошибка «Module Not Found» (версия Python)
```bash
pip install --upgrade psutil google-generativeai rich
```

### Сбой скрипта PowerShell
- Убедитесь, что установлен Windows PowerShell 5.1 или более поздней версии.
- Сгенерированный скрипт сохраняется в `AI_Reports/remediation.ps1` — проверьте его вручную на наличие ошибок.

---

## Сборка из исходного кода

### Автоматизированные сборки (рекомендуется)

Проект использует GitHub Actions для сборки исполняемых файлов Windows при отправке тега версии:

1. Отправьте свои изменения в основную ветку.
2. Создайте и отправьте тег версии:
   ```bash
   git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2
   ```
3. GitHub Actions собирает `.exe` и автоматически создаёт релиз
4. Скачайте со [страницы релизов](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases)

См. [`.github/workflows/release.yml`](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/.github/workflows/release.yml) для конфигурации процесса выпуска.

### Ручная сборка (для тестирования)

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

Это создаёт `dist/SuperDiagnosticTool.exe` со встроенной иконкой и зависимостями.

### Структура файлов

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

---

## Отказ от ответственности

Этот инструмент генерирует и выполняет скрипты PowerShell, которые изменяют системные службы, конфигурации и значения реестра. Перед утверждением любого сценария исправления:

- **Прочитайте скрипт полностью** — он отображается до того, как будет разрешено его выполнение
- **Создайте резервную копию критически важных данных** перед запуском автоматизированного исправления
- **Протестируйте на некритичной системе**, если масштаб изменений неясен

Автор не несёт ответственности за повреждение системы, потерю данных или непредвиденные последствия, возникшие в результате использования этого инструмента.

---

## Участие в разработке

Мы приветствуем вклад в проект. Чтобы внести свой вклад:

1. Сделайте форк репозитория
2. Создайте ветку для новой функции (`git checkout -b feature/improvement`)
3. Зафиксируйте изменения (`git commit -m 'Add improvement'`)
4. Отправьте изменения в ветку (`git push origin feature/improvement`)
5. Откройте Pull Request

---

## Лицензия

Этот проект распространяется под лицензией **GNU General Public License v3.0** — подробности см. в файле [LICENSE](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/LICENSE).

Copyright (C) 2026 GUETTAF HOUSSEM EDDINE

---

## Автор

**Guettaf Houssem Eddine**
Студент по специальности «Электротехника»
Университет Akli Mohand Oulhadj, Буира, Алжир
Email: [email protected]
GitHub: [@Guettaf-hossam](https://github.com/Guettaf-hossam)

---

## Благодарности

- **Google Gemini AI** за возможности анализа системы
- **psutil** за кроссплатформенную телеметрию системы
- **Rich** за отрисовку терминального интерфейса

---

<p align="center">
  <strong>Версия 1.0</strong> | Последнее обновление: август 2026
</p>

<p align="center">
  Университет Akli Mohand Oulhadj, Буира, Алжир
</p>