---

## 🖥️ Интерфейс управления UI

BlockGuard включает **WPF-приложение** для управления защищёнными файлами и папками через визуальный интерфейс — не нужно вручную редактировать `appsettings.json`.

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12349/51a9b7894117382666d869cee59860a33698f666133bd23c6b6cd48b225d942c.png" alt="BlockGuard UI" width="640" />
</p>

### Возможности

- **Панель управления** — Обзор статуса защиты (всего файлов, папок, состояние шифрования)
- **Защищённые файлы** — Добавление/удаление файлов и папок для защиты от доступа ИИ с помощью диалогов выбора файлов
- **Журнал действий** — Журнал всех изменений конфигурации в реальном времени
- **Настройки** — Просмотр пути к файлу конфигурации и информации об агенте
- **Статус агента** — Индикатор в реальном времени, показывающий, запущена ли служба агента BlockGuard

### Как запустить интерфейс```powershell
# From the project root
dotnet run --project src/BlockGuard.UI

---

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

### 1. Клонирование репозитория```powershell
git clone [email protected]:m2l33k/BlockGuard.git
cd BlockGuard

### 3. Соберите решение```powershell
dotnet build BlockGuard.sln --configuration Release

### 4. Настройка защищенных путей и правил

Измените `src/BlockGuard.Agent/appsettings.json`, чтобы определить **какие файлы защищать** и **какие процессы авторизованы**:```json
{
  "BlockGuard": {
    "ProtectedPaths": [
      "C:\\Secrets\\ai-model-keys",
      "C:\\Secrets\\api-credentials.json"
    ],
    "AuthorizedProcesses": [
      {
        "RuleName": "AI-Model-Inference-Engine",
        "ExecutablePath": "C:\\Program Files\\MyAI\\inference.exe",
        "MinimumIntegrityLevel": "Medium",
        "RequireSignature": false
      }
    ]
  }
}

---

## ⚙️ Конфигурация

Вся конфигурация находится в `src/BlockGuard.Agent/appsettings.json` в разделе `"BlockGuard"`.

### Защищённые пути

Массив файлов или каталогов для защиты. Каталоги защищают все файлы рекурсивно.```json
"ProtectedPaths": [
  "C:\\Secrets\\ai-model-keys",
  "C:\\Secrets\\api-credentials.json",
  "D:\\Confidential\\reports"
]

**Пример: правило на основе подписей (для любого подписанного инструмента управления)**```json
{
  "RuleName": "Signed-Management-Tool",
  "ExecutablePath": null,
  "ExpectedFileHash": null,
  "ExpectedSignerSubject": "CN=Contoso Security",
  "MinimumIntegrityLevel": "High",
  "RequireSignature": true
}

### Другие параметры

| Параметр | По умолчанию | Описание |
|---|---|---|
| `IdentityCacheTtlSeconds` | `30` | Сколько секунд кэшируется подтверждённая идентификация процесса |
| `HandleTimeoutSeconds` | `60` | Максимальная длительность (сек) временного разрешения ACL |
| `AuditLogPath` | `C:\ProgramData\BlockGuard\Logs\audit.json` | Путь к файлу журнала аудита в формате JSON |
| `EnableDpapiEncryption` | `true` | Шифровать защищённые файлы в покое с помощью DPAPI |
| `DpapiScope` | `LocalMachine` | Область DPAPI: `LocalMachine` или `CurrentUser` |

---

## 🏃 Запуск агента

### Вариант A: Режим разработки (Консоль)

Лучше всего подходит для тестирования и отладки. Запускайте из **повышенной (от имени администратора) PowerShell**:```powershell
dotnet run --project src/BlockGuard.Agent --configuration Release

Нажмите `Ctrl+C` для остановки.

### Вариант B: Install as a Windows Service (Production)```powershell
# 1. Publish a self-contained build
dotnet publish src/BlockGuard.Agent -c Release -r win-x64 --self-contained -o C:\BlockGuard

# 2. Create the Windows Service
sc.exe create BlockGuard binPath= "C:\BlockGuard\BlockGuard.Agent.exe" start= auto obj= "NT AUTHORITY\SYSTEM" DisplayName= "BlockGuard Security Agent"

# 3. Set the service description
sc.exe description BlockGuard "Process-based file access security agent (DLP)"

# 4. Start the service
sc.exe start BlockGuard

---

## ✅ Проверка работоспособности

### Тест 1: Проверка сборки```powershell
# From the project root directory
dotnet build BlockGuard.sln

# Expected: Build succeeded with 0 Error(s)

**✅ Ожидаемый вывод:**
- Сообщение `BlockGuard Security Agent Starting`
- Отсутствие ошибок `CRITICAL` или `FATAL`
- `ETW file trace session started successfully`
- `BlockGuard is now actively protecting X path(s)`

**❌ Если вы видите `ETW session — insufficient privileges`:**
- Вы НЕ запущены от имени администратора. Щелкните правой кнопкой мыши PowerShell → "Run as Administrator"

### Тест 3: Проверка блокировки ACL

После запуска агента проверьте, что защищенные файлы заблокированы:```powershell
# Create a test protected file
New-Item -Path "C:\Secrets" -ItemType Directory -Force
Set-Content -Path "C:\Secrets\api-credentials.json" -Value '{"api_key": "secret123"}'

# Start the agent (it will lock down the file)
dotnet run --project src/BlockGuard.Agent

# In ANOTHER non-admin terminal, try to read the file:
Get-Content "C:\Secrets\api-credentials.json"
# Expected: Access Denied error

### Тест 5: Проверка журнала аудита

После того как агент проработает некоторое время, проверьте журнал аудита:```powershell
# View the last 10 audit entries
Get-Content "C:\ProgramData\BlockGuard\Logs\audit.json" | Select-Object -Last 10

### Тест 6: Проверка захвата событий ETW

Откройте второй терминал и попробуйте получить доступ к защищенному файлу, пока агент работает:

# Terminal 1: Agent is running with console output
dotnet run --project src/BlockGuard.Agent

# Terminal 2: Try reading a protected file with notepad
notepad.exe "C:\Secrets\api-credentials.json"
```
В терминале 1 вы должны увидеть запись в журнале, подобную:```
[03:20:15 WRN] [AUDIT] DENIED access to 'C:\Secrets\api-credentials.json' by PID 9876 (C:\Windows\System32\notepad.exe). Reason: No authorization rule matched
```
### Тест 7: Проверка блокировки несанкционированного доступа (ИИ-модель)

Когда процесс (например, неавторизованная ИИ-модель) пытается прочитать защищенную папку или файл, агент немедленно блокирует доступ. ИИ получает строгую ошибку **Access Denied**, а попытка регистрируется в журнале:

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12349/d2a2e20c0fc60e8b3a5f614b0a53c6c7275b634e93b1ce0b9fe4440c38215fac.png" alt="Несанкционированный доступ запрещен" width="600" />
</p>

### Тест 8: Проверка шифрования DPAPI```powershell
# Check that the .enc file was created
Test-Path "C:\Secrets\api-credentials.json.enc"
# Expected: True

# Check that the original plaintext file was securely deleted
Test-Path "C:\Secrets\api-credentials.json"
# Expected: False (if EnableDpapiEncryption is true)
```
### Тест 9: Обнаружение взлома

Пока агент работает, вручную добавьте неавторизованную запись ACL:```powershell
# In an elevated terminal, add a rogue permission
icacls "C:\Secrets\api-credentials.json.enc" /grant Users:R

# Wait up to 60 seconds...
# The agent should detect the tampering and log:
# [CRT] ACL TAMPERING DETECTED on 'C:\Secrets\api-credentials.json.enc'! Re-applying lockdown.
```
### Тест 10: Проверка каталога логов```powershell
# Check both log locations
Get-ChildItem "C:\ProgramData\BlockGuard\Logs\"

# Expected files:
# audit.json              (structured JSON audit log)
# blockguard-20260305.log (daily rolling application log)
```
### Быстрый контрольный список проверки

| # | Тест | Как проверить | Ожидаемый результат |
|---|---|---|---|
| 1 | Сборка | `dotnet build BlockGuard.sln` | 0 ошибок |
| 2 | Запуск агента | `dotnet run --project src/BlockGuard.Agent` (от имени администратора) | Баннер запуска, нет CRITICAL ошибок |
| 3 | Блокировка ACL | `icacls <protected-file>` | Только SYSTEM + Administrators |
| 4 | Блокировка неавторизованного доступа | Чтение защищённого файла из терминала без прав администратора | Доступ запрещён |
| 5 | Захват ETW | Чтение защищённого файла во время работы агента | Запись DENIED в консоли |
| 6 | Журнал аудита | `Get-Content C:\ProgramData\BlockGuard\Logs\audit.json` | Записи JSON с вердиктом |
| 7 | Шифрование DPAPI | `Test-Path <file>.enc` | Существует файл `.enc` |
| 8 | Обнаружение взлома | `icacls <file> /grant Users:R`, затем подождать 60 сек | Зарегистрировано автоматическое восстановление |

---

## 📁 Структура проекта```
BlockGuard/
├── BlockGuard.sln                        # Solution file
├── README.md                             # This file
├── architecture_overview.md              # Detailed architecture documentation
├── assets/
│   ├── Untitled.jpg                      # Project logo (Trusty mascot)
│   └── blockguard_ui_mockup_*.png        # UI mockup screenshot
│
├── src/
│   ├── BlockGuard.Core/                  # Shared models, interfaces, configuration
│   │   ├── Configuration/
│   │   │   └── BlockGuardOptions.cs      # Strongly-typed config (paths, rules, timeouts)
│   │   ├── Interfaces/
│   │   │   ├── IAclEnforcer.cs           # ACL management contract
│   │   │   ├── IAuditLogger.cs           # Audit logging contract
│   │   │   ├── IDpapiWrapper.cs          # DPAPI encryption contract
│   │   │   ├── IFileAccessMonitor.cs     # ETW monitoring contract
│   │   │   ├── IPolicyEvaluator.cs       # Policy evaluation contract
│   │   │   └── IProcessIdentityValidator.cs  # Process identity contract
│   │   └── Models/
│   │       ├── AccessDecision.cs         # Verdict + reason + matched rule
│   │       ├── FileAccessEvent.cs        # ETW event: file, PID, operation
│   │       └── ProcessIdentity.cs        # Hash, signature, SID, integrity
│   │
│   ├── BlockGuard.Monitoring/            # Layer 1: Monitoring & Interception
│   │   ├── EtwFileTraceSession.cs        # Real-time kernel file ETW consumer
│   │   └── AclEnforcer.cs                # NTFS ACL lockdown + temp grants
│   │
│   ├── BlockGuard.Policy/                # Layer 2: Policy & Identity Engine
│   │   ├── ProcessIdentityValidator.cs   # 6-layer P/Invoke validation
│   │   ├── PolicyEvaluator.cs            # AND-logic rule matching
│   │   └── IdentityCache.cs             # Thread-safe LRU cache (TTL)
│   │
│   ├── BlockGuard.Protection/            # Layer 3: Decryption & Handle Manager
│   │   ├── DpapiWrapper.cs               # DPAPI encrypt/decrypt + secure delete
│   │   └── AuditLogger.cs                # Structured JSON audit logging
│   │
│   ├── BlockGuard.Agent/                 # Windows Service entry point
│   │   ├── Program.cs                    # DI container, Serilog, hosting
│   │   ├── BlockGuardService.cs          # Main orchestrator (5-phase startup)
│   │   └── appsettings.json              # Configuration file
│   │
│   └── BlockGuard.UI/                    # WPF Desktop Management Interface
│       ├── App.xaml / App.xaml.cs         # Application resources & dark theme
│       ├── MainWindow.xaml / .cs          # Main window with sidebar navigation
│       ├── ViewModels/
│       │   └── MainViewModel.cs          # MVVM ViewModel (commands, config I/O)
│       └── Services/
│           └── ConfigurationService.cs   # Reads/writes appsettings.json
```
---

## 🔬 Как это работает

### Последовательность запуска (5 фаз)```
Phase 1: ACL Lockdown
  └─ Strip all permissions from protected files
  └─ Grant access only to SYSTEM + Administrators
  └─ Disable ACL inheritance

Phase 2: DPAPI Encryption (optional)
  └─ Encrypt each protected file at rest
  └─ Securely delete plaintext (overwrite with random data)
  └─ Store ciphertext as .enc files

Phase 3: Event Subscription
  └─ Register handler for file access events

Phase 4: ETW Monitoring
  └─ Start kernel-level file trace session
  └─ Filter events by protected paths
  └─ Emit FileAccessEvent for each match

Phase 5: Integrity Check Loop
  └─ Every 60 seconds, verify ACLs are intact
  └─ Auto-remediate if tampering detected
```
### Поток запросов доступа```
┌─────────────┐     ┌───────────────┐     ┌──────────────────┐
│ Process      │     │ ETW Kernel    │     │ Policy           │
│ reads file   │────▶│ File Provider │────▶│ Evaluator        │
└─────────────┘     └───────────────┘     └──────────────────┘
                                                   │
                                          ┌────────┴────────┐
                                          ▼                 ▼
                                    ┌──────────┐     ┌──────────┐
                                    │ ALLOW    │     │ DENY     │
                                    │          │     │          │
                                    │ Grant    │     │ ACL is   │
                                    │ temp ACL │     │ already  │
                                    │ (60s)    │     │ blocking │
                                    └──────────┘     └──────────┘
                                          │                 │
                                          ▼                 ▼
                                    ┌────────────────────────────┐
                                    │     Audit Logger (JSON)    │
                                    └────────────────────────────┘
```
### Валидация процессов (6 проверок)

Когда процесс обращается к защищенному файлу, BlockGuard проверяет его через:

1. **Путь исполняемого файла** — Разрешает и канонизирует полный путь (предотвращает обход пути)
2. **Хэш SHA-256** — Вычисляет хэш бинарного файла на диске (обнаруживает замену файла)
3. **Подпись Authenticode** — Проверяет цепочку цифровой подписи (обнаруживает неподписанные/измененные бинарные файлы)
4. **SID владельца процесса** — Запрашивает токен для идентификации запущенной учетной записи
5. **Уровень целостности** — Считывает обязательную метку (Untrusted/Low/Medium/High/System)
6. **ID родительского процесса** — Отслеживает цепочку создания процессов (обнаруживает инъекции)

Все проверки **fail-closed**: если любой этап проверки завершается неудачей, доступ **ЗАПРЕЩЕН**.

---

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

### "Сеанс ETW — недостаточно привилегий"

**Причина:** Агент не запущен с привилегиями администратора/SYSTEM.

**Решение:**```powershell
# Right-click PowerShell → "Run as Administrator"
dotnet run --project src/BlockGuard.Agent
```
### "Не удается изменить ACL — у агента недостаточно привилегий"

**Причина:** Агент не может изменить права доступа к файлам без повышенных привилегий.

**Исправление:** То же, что и выше — запустите с правами администратора.

### "Защищенный путь не существует. Пропускаем."

**Причина:** Пути в `appsettings.json` не существуют на вашем компьютере.

**Исправление:** Сначала создайте каталоги и файлы:```powershell
New-Item -Path "C:\Secrets\ai-model-keys" -ItemType Directory -Force
Set-Content -Path "C:\Secrets\api-credentials.json" -Value '{"key":"value"}'
```
### Ошибки сборки после клонирования

**Исправление:** Восстановите пакеты NuGet:```powershell
dotnet restore BlockGuard.sln
dotnet build BlockGuard.sln
```
### "Disposed orphaned ETW session"

**Причина:** Предыдущий экземпляр агента аварийно завершился и оставил зомби-сессию ETW. Она автоматически очищается — это ПРЕДУПРЕЖДЕНИЕ, а не ошибка.

### Агент останавливается сразу после запуска

**Причина:** Вероятно, ошибка конфигурации. Проверьте файл журнала:```powershell
Get-Content "C:\ProgramData\BlockGuard\Logs\blockguard-*.log" | Select-Object -Last 50
```
---

## 🔒 Вопросы безопасности

### Что может этот агент
- ✅ Предотвращает чтение защищенных файлов неавторизованными процессами через применение ACL
- ✅ Обнаруживает и **аудитирует** все попытки доступа к файлам в реальном времени через ETW
- ✅ Шифрует файлы **в покое** с помощью DPAPI
- ✅ Обнаруживает и **автоматически исправляет** подмену ACL

### Что этот агент не может
- ❌ **Блокировать чтение файлов на лету** — Это пользовательский агент; настоящая блокировка на лету требует драйвера режима ядра minifilter
- ❌ **Останавливать атаки на уровне ядра** — Вредоносный драйвер ядра может обойти ACL NTFS
- ❌ **Предотвращать отмену администраторами** — Учетные записи администраторов могут удалить ACL (смягчается обнаружением вмешательства)

### Рекомендации для производства

1. **Запускать от имени `NT AUTHORITY\SYSTEM`** — Используйте службу Windows, а не консольное приложение
2. **Подпишите бинарный файл агента** сертификатом Authenticode для предотвращения самостоятельного вмешательства
3. **Включите BitLocker** на томе для полнодискового шифрования (дополняет DPAPI)
4. **Пересылайте журналы аудита в SIEM** для централизованного мониторинга
5. **Включите Secure Boot + Driver Signature Enforcement** для предотвращения обхода на уровне ядра

---

## 🤝 Вклад в проект

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

### Стиль кода
- Следуйте соглашениям об именовании C# (PascalCase для открытых членов)
- Добавьте комментарии XML-документации ко всем открытым API
- Каждая проверка должна **закрываться при ошибке** (отказывать при ошибке)
- Явно освобождайте все нативные дескрипторы в блоках `finally`
- Обнуляйте буферы конфиденциальной памяти после использования

---

## 📄 Лицензия

Этот проект лицензирован под лицензией MIT. Подробнее см. [LICENSE](https://github.com/m2l33k/blockguard/blob/HEAD/LICENSE).

---

<p align="center">
  <b>Создано по принципам безопасности в первую очередь для защиты файлов Windows.</b>
  <br/>
  <sub>BlockGuard — потому что ваши данные заслуживают охраны, а не просто замка.</sub>
</p>