---

## 🖥️ Interfaccia di Gestione UI

BlockGuard include un'**applicazione desktop WPF** per gestire file e cartelle protetti attraverso un'interfaccia visiva — nessuna necessità di modificare `appsettings.json` manualmente.

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

### Caratteristiche

- **Dashboard** — Panoramica dello stato di protezione (file totali, cartelle, stato di crittografia)
- **File Protetti** — Aggiungi/rimuovi file e cartelle da proteggere dall'accesso AI tramite finestre di dialogo del browser file
- **Registro Attività** — Registro in tempo reale di tutte le modifiche alla configurazione
- **Impostazioni** — Visualizza il percorso del file di configurazione e le informazioni sull'agente
- **Stato Agente** — Indicatore live che mostra se il servizio agente BlockGuard è in esecuzione

### Come Avviare l'UI```powershell
# From the project root
dotnet run --project src/BlockGuard.UI

---

## 🚀 Avvio Rapido

### 1. Clona il Repository```powershell
git clone [email protected]:m2l33k/BlockGuard.git
cd BlockGuard

### 3. Costruisci la Soluzione```powershell
dotnet build BlockGuard.sln --configuration Release

### 4. Configura i percorsi protetti e le regole

Modifica `src/BlockGuard.Agent/appsettings.json` per definire **quali file proteggere** e **quali processi sono autorizzati**:```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
      }
    ]
  }
}

## ⚙️ Configurazione

Tutta la configurazione risiede in `src/BlockGuard.Agent/appsettings.json` nella sezione `"BlockGuard"`.

### Percorsi protetti

Un array di file o directory da proteggere. Le directory proteggono tutti i file in modo ricorsivo.```json
"ProtectedPaths": [
  "C:\\Secrets\\ai-model-keys",
  "C:\\Secrets\\api-credentials.json",
  "D:\\Confidential\\reports"
]

**Esempio: Regola basata su firma (per qualsiasi strumento di gestione firmato)**```json
{
  "RuleName": "Signed-Management-Tool",
  "ExecutablePath": null,
  "ExpectedFileHash": null,
  "ExpectedSignerSubject": "CN=Contoso Security",
  "MinimumIntegrityLevel": "High",
  "RequireSignature": true
}

### Altre Opzioni

| Opzione | Predefinito | Descrizione |
|---|---|---|
| `IdentityCacheTtlSeconds` | `30` | Per quanto tempo (in secondi) un'identità di processo convalidata rimane nella cache |
| `HandleTimeoutSeconds` | `60` | Durata massima (in secondi) di una concessione ACL temporanea |
| `AuditLogPath` | `C:\ProgramData\BlockGuard\Logs\audit.json` | Percorso del file di log di controllo JSON |
| `EnableDpapiEncryption` | `true` | Cripta i file protetti a riposo con DPAPI |
| `DpapiScope` | `LocalMachine` | Ambito DPAPI: `LocalMachine` o `CurrentUser` |

---

## 🏃 Esecuzione dell'Agente

### Opzione A: Modalità di sviluppo (Console)

Ideale per test e debug. Esegui da una **PowerShell con privilegi elevati (Amministratore)**:```powershell
dotnet run --project src/BlockGuard.Agent --configuration Release

Premere `Ctrl+C` per fermare.

### Opzione B: Installare come servizio Windows (Produzione)```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

---

## ✅ Verifica del funzionamento

Segui questi passaggi per confermare che BlockGuard stia proteggendo correttamente i file.

### Test 1: Verifica della build```powershell
# From the project root directory
dotnet build BlockGuard.sln

# Expected: Build succeeded with 0 Error(s)

**✅ Risultato atteso:**
- Messaggio `BlockGuard Security Agent Starting`
- Nessun errore `CRITICAL` o `FATAL`
- `ETW file trace session started successfully`
- `BlockGuard is now actively protecting X path(s)`

**❌ Se vedi `ETW session — insufficient privileges`:**
- Non stai eseguendo come Amministratore. Fai clic destro su PowerShell → "Esegui come amministratore"

### Test 3: Verifica del blocco ACL

Dopo l'avvio dell'agente, verifica che i file protetti siano bloccati:```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

### Test 5: Ispezione del Log di Audit

Dopo che l'agente ha eseguito per un po', controlla il log di audit:```powershell
# View the last 10 audit entries
Get-Content "C:\ProgramData\BlockGuard\Logs\audit.json" | Select-Object -Last 10

### Test 6: Verifica della cattura di eventi ETW

Apri un secondo terminale e prova ad accedere a un file protetto mentre l'agente è in esecuzione:```powershell
# 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"

### Test 7: Verificare l'Accesso Non Autorizzato Bloccato (Modello AI)

Quando un processo (come un modello AI non autorizzato) tenta di leggere una cartella o un file protetto, l'agente nega immediatamente l'accesso. L'AI riceverà un errore rigoroso di **Accesso Negato** e il tentativo viene registrato:

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12349/d2a2e20c0fc60e8b3a5f614b0a53c6c7275b634e93b1ce0b9fe4440c38215fac.png" alt="Accesso Non Autorizzato Negato" width="600" />
</p>

### Test 8: Verificare la Crittografia 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)

### Test 10: Verifica Directory dei Log```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)

---

## 🔬 Come Funziona

### Sequenza di Avvio (5 Fasi)```
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

### Convalida del Processo (6 Controlli)

Quando un processo accede a un file protetto, BlockGuard lo convalida tramite:

1. **Percorso Eseguibile** — Risolve e canonicalizza il percorso completo (previene il path traversal)
2. **Hash SHA-256** — Calcola l'hash del binario su disco (rileva la sostituzione del file)
3. **Firma Authenticode** — Convalida la catena della firma digitale (rileva binari non firmati/alterati)
4. **SID del Proprietario del Processo** — Interroga il token per identificare l'account in esecuzione
5. **Livello di Integrità** — Legge l'etichetta obbligatoria (Non attendibile/Basso/Medio/Alto/Sistema)
6. **ID del Processo Padre** — Traccia la catena di creazione del processo (rileva l'iniezione)

Tutti i controlli sono **fail-closed**: se un qualsiasi passo di convalida fallisce, l'accesso è **NEGATO**.

---

## 🛠️ Risoluzione dei problemi

### "Sessione ETW — privilegi insufficienti"

**Causa:** L'agente non è in esecuzione con privilegi di Amministratore/SYSTEM.

**Rimedio:**```powershell
# Right-click PowerShell → "Run as Administrator"
dotnet run --project src/BlockGuard.Agent

### Errori di compilazione dopo la clonazione

**Soluzione:** Ripristina i pacchetti NuGet:```powershell
dotnet restore BlockGuard.sln
dotnet build BlockGuard.sln

---

## 🔒 Considerazioni sulla Sicurezza

### Cosa Questo Agente Può Fare
- ✅ Impedisce ai processi non autorizzati di **leggere** file protetti tramite l'applicazione delle ACL
- ✅ Rileva e **controlla** tutti i tentativi di accesso ai file in tempo reale tramite ETW
- ✅ Crittografa i file **a riposo** utilizzando DPAPI
- ✅ Rileva e **corregge automaticamente** la manomissione delle ACL

### Cosa Questo Agente Non Può Fare
- ❌ **Bloccare le letture dei file in volo** — Questo è un agente in modalità utente; il blocco in volo reale richiede un driver minifilter del kernel
- ❌ **Fermare attacchi a livello kernel** — Un driver kernel dannoso può bypassare le ACL NTFS
- ❌ **Impedire agli Amministratori di sovrascrivere** — Gli account amministratore possono rimuovere le ACL (mitigato dal rilevamento di manomissioni)

### Raccomandazioni per la Produzione

1. **Esegui come `NT AUTHORITY\SYSTEM`** — Usa un servizio Windows, non un'app console
2. **Firma il binario dell'agente** con un certificato Authenticode per prevenire l'auto-manomissione
3. **Abilita BitLocker** sul volume per la crittografia completa del disco (complementa DPAPI)
4. **Inoltra i log di audit a un SIEM** per il monitoraggio centralizzato
5. **Abilita Secure Boot + Applicazione della firma dei driver** per prevenire bypass a livello kernel

---

## 🤝 Contribuire

1. Fai il fork del repository
2. Crea un branch di feature: `git checkout -b feature/my-feature`
3. Esegui il commit delle modifiche: `git commit -m "Add my feature"`
4. Carica sul branch: `git push origin feature/my-feature`
5. Apri una Pull Request

### Stile del Codice
- Segui le convenzioni di denominazione C# (PascalCase per i membri pubblici)
- Aggiungi commenti di documentazione XML a tutte le API pubbliche
- Ogni convalida deve **fallire in chiusura** (negare in caso di errore)
- Smaltisci esplicitamente tutti gli handle nativi nei blocchi `finally`
- Azzera i buffer di memoria sensibili dopo l'uso

---

## 📄 Licenza

Questo progetto è concesso in licenza secondo i termini della MIT License. Vedi [LICENSE](https://github.com/m2l33k/blockguard/blob/main/LICENSE) per i dettagli.

---

<p align="center">
  <b>Realizzato con principi di sicurezza al primo posto per la protezione dei file Windows.</b>
  <br/>
  <sub>BlockGuard — perché i tuoi dati meritano una guardia, non solo un lucchetto.</sub>
</p>