Caveman.PrivacyGuard 1.2.1

Caveman.PrivacyGuard 🛡️🇪🇺

<img width="638" height="408" alt="Gemini_Generated_Image_tnxoi9tnxoi9tnxo" src="https://github.com/user-attachments/assets/5a8e3193-b7d3-4a41-90e6-e672467ce6cb" />

Enterprise-grade PII & Privacy Analyzer for AI/LLM workflows
Rileva, valuta e maschera automaticamente dati sensibili in 27 paesi UE, con scoring del rischio, conformità GDPR/PCI-DSS/NIST e integrazione seamless con qualsiasi pipeline AI.

✨ Features

📦 Installazione

dotnet add package Caveman.PrivacyGuard

🚀 Quick Start

Modalità Avviso (Default)

var analyzer = new PrivacyAnalyzer { EnableAutoMasking = true };

// 🔹 Default: Inglese
var resEn = analyzer.Analyze("CF: RSSMRA80A01H501U, email: test@x.com");
Console.WriteLine($"[EN] Risk: {resEn.RiskLevel}\n{resEn.WarningMessage}");

// 🔹 Overload: Italiano
var resIt = analyzer.Analyze("CF: RSSMRA80A01H501U, email: test@x.com", "it");
Console.WriteLine($"[IT] Rischio: {resIt.RiskLevel}\n{resIt.WarningMessage}");

// 🔹 Overload: Tedesco
var resDe = analyzer.Analyze("Steuer-ID: 12345678901, IBAN: DE89370400440532013000", "de");
Console.WriteLine($"[DE] Risiko: {resDe.RiskLevel}\n{resDe.WarningMessage}");

Output:

🔒 Score: 26/100
⚠️  Avviso: ⛔ Dati rilevati: Codice Fiscale (IT), Email. Pseudonimizzazione obbligatoria.
✅ Safe for AI: False

var analyzer = new PrivacyAnalyzer { EnableAutoMasking = true };

var text = "Cliente: Mario Rossi, email mario@azienda.it, IBAN: IT60X0542811101000000123456";
var result = analyzer.Analyze(text);

Console.WriteLine($"🛡️  Testo sicuro per LLM:\n{result.MaskedText}");

Output:

🛡️  Testo sicuro per LLM:
Cliente: Mario Rossi, email [EMAIL], IBAN: [IBAN]

🪄 Session Restore — Zero Sensitive Data to the LLM

Il vero punto di forza: i dati sensibili non lasciano mai il client. Il flusso è:

1. Mask — PrivacyAnalyzer rileva e sostituisce con placeholder univoci [PG_1], [PG_2], ecc.
2. Send — Il testo mascherato (privo di dati reali) viene inviato al LLM
3. Restore — La risposta del LLM viene processata da PrivacySession.Restore() che ripristina i valori originali lato client

var session = new PrivacySession();
var analyzer = new PrivacyAnalyzer { EnableAutoMasking = true };

// 1. Analizza e maschera (i dati restano solo nella session)
var result = analyzer.Analyze(
    "Mario Rossi, email mario@azienda.it, IBAN: IT60X0542811101000000123456",
    "en", session);

Console.WriteLine(result.MaskedText);
// Output: Mario Rossi, email [PG_1], IBAN: [PG_2]

// 2. Invia result.MaskedText al LLM...
var aiResponse = "Contatta il cliente via [PG_1] per l'addebito su [PG_2]";

// 3. Ripristina lato client (nessun dato sensibile è mai uscito)
var safeResponse = session.Restore(aiResponse);
Console.WriteLine(safeResponse);
// Output: Contatta il cliente via mario@azienda.it per l'addebito su IT60X0542811101000000123456

API Reference

// Crea una nuova sessione
var session = new PrivacySession();

// Analizza con sessione (placeholder univoci [PG_N])
var result = analyzer.Analyze(input, "en", session);

// Oppure via proprietà CurrentSession
analyzer.CurrentSession = new PrivacySession();
var result = analyzer.Analyze(input);

// Ripristina una risposta AI
string restored = session.Restore(aiResponseText);

// Ispeziona i placeholder generati
foreach (var entry in session.GetAll())
    Console.WriteLine($"{entry.Key} → {entry.Value.OriginalValue} ({entry.Value.Category})");

// Ottieni un singolo mapping
var entry = session.GetEntry("[PG_1]");

// Aggiungi manualmente un placeholder (pubblico)
session.AddOrGet("Email", "manual@test.com");

// Unisci un'altra sessione (ignora duplicati per valore)
session.MergeFrom(anotherSession);

// Resetta la sessione
session.Clear();

// Metodo statico su PrivacyAnalyzer
string restored = PrivacyAnalyzer.RestoreText(aiResponse, session);

// Metodo di istanza (usa CurrentSession)
analyzer.CurrentSession = session;
string restored2 = analyzer.RestoreText(aiResponse);

Nota: Senza sessione (Analyze(input) o Analyze(input, lang)), il masking usa i placeholder testuali [EMAIL], [IBAN], ecc. come in precedenza.

⚙️ Configurazione Avanzata

Whitelist (Esclusioni Sicure)

analyzer.AddToWhitelist(
    "test@company.eu",      // Email di test
    "127.0.0.1",            // IP localhost
    "IT00000000000"         // PIVA dummy
);

// Rimozione e reset
analyzer.RemoveFromWhitelist("test@company.eu");
analyzer.ClearWhitelist();  // rimuove tutte le esclusioni

// Ispezione
var all = analyzer.GetWhitelist();     // IReadOnlySet<string>
if (analyzer.IsWhitelisted("127.0.0.1"))
    Console.WriteLine("IP nella whitelist");

Validatori Personalizzati

// Registra un nuovo validatore per un formato nazionale custom
ValidatorRegistry.Register("MY_CUSTOM_ID", value => 
    value.Length == 10 && value.StartsWith("XYZ") && value.All(char.IsDigit));

// Rimuove un validatore esistente
ValidatorRegistry.Unregister("MY_CUSTOM_ID");

// Resetta tutti i validatori ai built-in (rimuove i custom)
ValidatorRegistry.Reset();

Ispezione e Gestione Regole a Runtime

// Elenca tutte le categorie di regole attualmente caricate
var categories = analyzer.GetLoadedCategories();

// Ispeziona una regola specifica (regex, peso, validatore, ecc.)
var emailRule = analyzer.GetRule("Email");
Console.WriteLine(emailRule.Pattern);   // regex compilata
Console.WriteLine(emailRule.BaseWeight); // peso

// Rimuove tutte le regole di una categoria
analyzer.RemoveRule("Email");

// Pulisce TUTTE le regole (embedded + custom)
analyzer.ClearRules();

Rilascio Risorse

PrivacyAnalyzer implementa IDisposable per rilasciare il ReaderWriterLockSlim. Tutti i metodi pubblici lanciano ObjectDisposedException se chiamati dopo lo smaltimento:

using var analyzer = new PrivacyAnalyzer { EnableAutoMasking = true };
var result = analyzer.Analyze("test@example.com");
// analyzer.Dispose() chiamato automaticamente all'uscita del using

Analisi Asincrona

Per applicazioni UI o web, AnalyzeAsync esegue l'analisi su un thread pool e supporta CancellationToken:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

try
{
    var result = await analyzer.AnalyzeAsync(
        "Email: test@example.com, IBAN: IT60X0542811101000000123456",
        cts.Token);

    Console.WriteLine($"Score: {result.Score}");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Analisi cancellata per timeout.");
}

Overload disponibili: AnalyzeAsync(input), AnalyzeAsync(input, session, ct), AnalyzeAsync(input, language, ct), AnalyzeAsync(input, language, session, ct).

YAML Esterno e Dinamico

// Carica regole da file (si aggiungono a quelle embedded)
analyzer.LoadCustomYaml("path/to/custom-rules.yaml");

// Carica regole da stringa YAML (utile per DB/config remota)
var yaml = @"
version: ""2.0""
countries:
  - code: ""XX""
    rules:
      - category: ""CustomPII""
        pattern: '\bSENSITIVE_\w+\b'
        base_weight: 20
        compliance_tags: [""GDPR Art.4(1)""]";
analyzer.LoadCustomYamlFromString(yaml);

Compliance Tags da YAML

I flag di compliance (compliance_tags nel YAML) vengono automaticamente raccolti e uniti a quelli hardcodati. Puoi aggiungere tag personalizzati per ogni regola:

- category: "MyCustomID"
  pattern: '\bMY_\d{6}\b'
  base_weight: 15
  compliance_tags: ["GDPR Art.4(1)", "Internal Policy #42"]

JSON Config e Hot-Reload

Oltre a YAML, supportiamo configurazione JSON con hot-reload automatico:

// Carica regole da file JSON
analyzer.LoadCustomJson("path/to/custom-rules.json");

// Carica da stringa
var json = @"{
  ""version"": ""2.0"",
  ""countries"": [
    { ""code"": ""XX"", ""rules"": [
      { ""category"": ""CustomPII"", ""pattern"": ""\\bSENSITIVE_\\w+\\b"", ""base_weight"": 20 }
    ]}
  ]
}";
analyzer.LoadCustomJsonFromString(json);

// Hot-reload: osserva il file e ricarica automaticamente
analyzer.WatchConfig("path/to/custom-rules.json");

// Evento notificato dopo ogni ricarica
analyzer.ConfigReloaded += (s, e) => Console.WriteLine("⚡ Config ricaricata!");

// Ferma il watcher
analyzer.StopWatching();

Validazione Regole

Verifica che tutte le regole caricate siano valide (nessuna eccezione in fase di match):

if (analyzer.ValidateRules())
    Console.WriteLine("✅ Tutte le regole sono valide");
else
    Console.WriteLine("❌ Regole invalide trovate");

Integrazione ILogger

Collega un logger per diagnostic durante analisi e configurazione:

analyzer.Logger = myLogger;  // ILogger<PrivacyAnalyzer>
// Eventi loggati: categorie rilevate, score alto, load configurazioni

Session Export e Persistence

Esporta e importa sessioni come JSON per salvare/ripristinare lo stato tra richieste:

var session = new PrivacySession();
session.AddEntry("Email", "test@example.com");

// Esporta
string json = session.ToJson();

// Ricostruisci
var restored = PrivacySession.FromJson(json);

// Importa in sessione esistente
existingSession.ImportFromJson(json);

IReadOnlySession

API read-only sicura per esposizione pubblica:

IReadOnlySession readOnly = session;
int count = readOnly.Count;
var entry = readOnly.GetEntry("[PG_1]");
string text = readOnly.Restore(aiResponse);

🔐 Compliance & GDPR

PrivacyAnalysisResult.ComplianceFlags combina automaticamente:

• YAML — compliance_tags definiti per ogni regola in rules.yaml
• Hardcoded — Mappatura automatica per categorie note (GDPR, PCI-DSS, NIST 800-53)

if (result.ComplianceFlags.Contains("GDPR Art.4(1)"))
{
    // Logica per base giuridica, DPIA, minimizzazione
}
if (result.ComplianceFlags.Contains("PCI-DSS"))
{
    // Crittografia, segmentazione rete, audit
}

Soglie di Rischio:

⚠️ Disclaimer: Questa libreria è uno strumento tecnico di supporto. Non sostituisce una Valutazione d'Impatto sulla Protezione dei Dati (DPIA) né il parere di un DPO. La conformità GDPR richiede valutazioni contestuali, basi giuridiche e processi organizzativi.

🧪 Testing & Performance

// Benchmark rapido
var analyzer = new PrivacyAnalyzer();
var sw = System.Diagnostics.Stopwatch.StartNew();

for (int i = 0; i < 10_000; i++)
{
    analyzer.Analyze("Testo con email test@example.com e IBAN DE89370400440532013000");
}

sw.Stop();
Console.WriteLine($"⚡ 10k analisi in {sw.ElapsedMilliseconds}ms ({10_000.0 / sw.ElapsedMilliseconds:F1} req/sec)");

🤝 Contributing

Fork il repo Crea un branch per la tua feature (git checkout -b feature/nuovo-paese) Aggiungi regole in rules.yaml + validatori in ValidatorRegistry.cs Aggiungi test in tests/ (xUnit) PR con descrizione chiara e esempi 🌍 Per aggiungere un nuovo paese: segui lo schema YAML esistente, implementa il validatore (se necessario) e aggiungi la voce nella tabella del README.

📄 License

Distribuito sotto licenza MIT. Vedi LICENSE per dettagli.

🆘 Support & Roadmap

🛡️ Proteggi i dati, abilita l'AI. Compliance by design.