PII-Shield 🛡️

Sidecar di sanificazione log zero-code per Kubernetes. Previene le fughe di dati (GDPR/SOC2) oscurando i PII dai log prima che lascino il pod.

PII-Shield funziona in-process — CLI, sidecar o WASM. Non esiste un'API hosted né un server a cui i tuoi dati vengano inviati.

"Non lasciare che i PII avvelenino i tuoi modelli di IA." PII-Shield garantisce che i dati sensibili non raggiungano mai il tuo dataset di addestramento, evitandoti il riaddestramento forzato dei modelli imposto dal GDPR.

[!WARNING] Stai eseguendo l'upgrade alla v2.0.0? Abbiamo spostato la distribuzione per gli utenti finali su installazioni basate su Helm e Native Sidecar Distroless. Kustomize non è più un percorso di installazione supportato per gli utenti in produzione, sebbene il repository dell'operator mantenga ancora lo scaffolding Kustomize per lo sviluppo locale e la generazione di manifest. L'accesso a /bin/sh all'interno del sidecar PII-Shield non è più supportato. Leggi la Guida alla Migrazione.

Due Modelli di Distribuzione

PII-Shield offre due modi distinti per integrarsi nel tuo stack:

1. Kubernetes Operator (Zero-code): Il nostro modello di distribuzione di punta. Un K8s Operator completamente automatizzato che inietta un Sidecar Distroless altamente sicuro nei tuoi pod per intercettare e sanificare i log al volo.
2. WASM In-Process (Per integrazioni core): Per prestazioni estreme, il motore core può essere incorporato direttamente tramite WASM, fornendo una latenza <1ms senza hop di rete.

Stato del Progetto e Roadmap

PII-Shield è uno strumento di sicurezza open-source attivamente sviluppato in una fase di hardening produttivo. La linea di release v2.x fornisce artefatti CLI, container, Helm/operator e SDK WASM utilizzabili. I percorsi di redazione core sono pronti per distribuzioni controllate, mentre alcune modalità di distribuzione Kubernetes e le garanzie sulla supply chain sono ancora in fase di stabilizzazione.

Vedi KNOWN_LIMITATIONS.md per i confini attuali dell'hardening produttivo.

Perché PII-Shield?

Gli sviluppatori spesso dimenticano di mascherare i dati sensibili. I filtri regex tradizionali in Fluentd/Logstash sono lenti, difficili da mantenere e consumano CPU costosa sugli aggregatori di log.

PII-Shield si posiziona proprio accanto al container della tua applicazione:

• Motore Core in Hardening Produttivo: Ottimizzato per sidecar Kubernetes con basse allocazioni di memoria sui percorsi critici e matching regex deterministico.
• Analisi dell'Entropia Context-Aware: Rileva segreti ad alta entropia anche senza chiavi (es. Error: ... 44saCk9...) analizzando le parole chiave di contesto.
• Regole Regex Personalizzate: Redazione deterministica per dati strutturati (UUID, ID) che sovrascrive i controlli di entropia per pattern noti.
• Copertura Regression & Fuzz: Testato contro casi di stress inclusi rifiuti binari, annidamento JSON e log multilingua.
• Hashing Deterministico: Sostituisce i segreti con hash univoci (es. [HIDDEN:a1b2c]), consentendo al QA di correlare gli errori senza vedere i dati grezzi.
• Drop-in: Nessuna modifica al codice richiesta. Funziona con qualsiasi linguaggio (Node, Python, Java, Go).
• Supporto Whitelist: Consenti esplicitamente pattern sicuri (es. hash git, ID di sistema) usando PII_SAFE_REGEX_LIST per prevenire falsi positivi.

Gestisci PII-Shield su decine di cluster?

Stiamo costruendo un Control Plane hosted con gestione centralizzata delle regole, alerting Slack e analisi della redazione.

Integrazioni

La build WASM in-process di PII-Shield è inclusa in GuardSpine Code, una GitHub Action open-source di AI code-governance, che fornisce il binario e lo accredita nel suo NOTICE.

Considerazioni sulle Prestazioni

Sebbene PII-Shield sia altamente ottimizzato, l'ispezione approfondita di log complessi richiede un'attenta attenzione alla configurazione.

• Log di Testo: Estremamente veloci (>100k righe/s).
• Log JSON: Parsing a zero allocazioni (nessun overhead di encoding/json). Lo scanner analizza manualmente le strutture JSON per garantire un throughput elevato (~7MB/s) senza picchi di memoria.
• Raccomandazione: L'uso è sicuro per throughput elevati. Utilizziamo salvaguardie di ricorsione per prevenire overflow dello stack su JSON profondamente annidati.

Installazione

Helm Chart (Kubernetes Operator)

Il modo ufficiale e raccomandato per distribuire PII-Shield in Kubernetes è tramite il nostro Operator completamente automatizzato:

helm repo add pii-shield https://pii-shield.github.io/pii-shield/
helm repo update
helm install pii-shield-operator pii-shield/pii-shield-operator -n operator-system --create-namespace

Questo distribuisce il PII-Shield Operator che inietta automaticamente sidecar distroless altamente sicuri nei tuoi Pod senza richiedere modifiche al codice o ai Dockerfile.

Docker

Ottieni l'ultima immagine leggera da Docker Hub o GHCR:

docker pull thelisdeep/pii-shield:2.2.3
# OPPURE dal GitHub Container Registry (Enterprise):
docker pull ghcr.io/pii-shield/pii-shield:2.2.3

Build dal Sorgente

Puoi compilare il binario direttamente dal codice sorgente:

go build -o pii-shield ./cmd/cleaner/main.go

Configurazione

Vedi CONFIGURATION.md per l'elenco completo delle variabili d'ambiente, inclusi:

• PII_SALT: Salt HMAC personalizzato (Richiesto per la produzione).
• PII_ADAPTIVE_THRESHOLD: Abilita baseline di entropia dinamiche.
• PII_DISABLE_BIGRAM_CHECK: Ottimizza per log non inglesi.
• PII_CUSTOM_REGEX_LIST: Regole regex personalizzate per la redazione deterministica.
• PII_SAFE_REGEX_LIST: Regole regex whitelist da ignorare (i match vengono restituiti così come sono).

Tabella di Sensibilità dell'Entropia (Soglia Predefinita: 3.6)

Avvio Rapido

1. Test Locale (CLI) Puoi convogliare qualsiasi output di log attraverso PII-Shield per vederlo in azione immediatamente:

# Emula un log con una password sensibile
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:2.2.3

# Output: Error: User password=[HIDDEN:8f3a11] failed login

2. Kubernetes (Iniezione Sidecar Automatizzata) Con il PII-Shield Operator installato, proteggere un'applicazione è semplice come creare una PiiPolicy ed etichettare i tuoi Pod.

Crea una Policy:

apiVersion: core.pii-shield.io/v1alpha1
kind: PiiPolicy
metadata:
  name: strict-policy
  namespace: default
spec:
  injectionMode: "file"

Etichetta il tuo Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: secure-app
spec:
  template:
    metadata:
      labels:
        pii-shield.io/inject: "true"
      annotations:
        pii-shield.io/policy: "strict-policy"
# ...

L'Operator inietterà automaticamente pii-shield-agent usando il pattern Native Sidecar (K8s 1.28+) e maschera in modo sicuro tutti i log!

📋 Gratuito: Checklist di Audit PII nei Log Kubernetes in 25 punti — dove i PII fuoriescono dai pod, quali percorsi di log bypassano i tuoi filtri e come verificare che la redazione funzioni davvero. Ottieni la checklist →

📦 GDPR Compliance Pack — disponibile ora (accesso anticipato): 40+ regole di redazione testate, documentazione pronta per il DPO, modelli di audit-trail. $149 → · HIPAA/PCI in lista d'attesa →

💬 Usi PII-Shield? Raccontaci della tua distribuzione → — 2 minuti, e contribuisce a definire cosa verrà sviluppato dopo.

Verifica

Questo progetto è verificato con una suite di test in crescita progettata per aumentare la fiducia prima dell'hardening produttivo:

1. Unit Test: Coprono casi limite, supporto multilingua e integrità JSON con copertura >85%.
2. Fuzzing: Il fuzzing nativo Go garantisce sicurezza contro crash con input binari casuali e non validi.
3. Smoke Testing: ./scripts/test-smoke.sh esercita carichi di lavoro misti e riporta l'accuratezza del rilevamento.
4. Test End-to-End (E2E): La suite operator/tests/run_e2e.sh esegue la validazione full-stack usando Minikube e Helm. Compila immagini locali, fornisce l'Operator senza cert-manager, distribuisce Job target e verifica l'effettiva redazione dei log intercettando gli output del sidecar.

Benchmark delle Prestazioni

Per confrontare il throughput CLI end-to-end tra il branch corrente e un ref di base:

./benchmark/run_benchmarks.sh

Per impostazione predefinita, il benchmark confronta HEAD con origin/main, aggiorna origin/main, genera un corpus di log misto, alterna l'ordine di esecuzione vecchio/nuovo e riporta mediana, p95, min/max e MiB/s:

BASE_REF=origin/main RUNS=9 LINES=500000 ./benchmark/run_benchmarks.sh

Questo misura il percorso CLI completo da stdin a stdout. Per microbenchmark solo scanner, esegui:

go test -bench=. -benchmem ./pkg/scanner

Test di Integrazione dell'Operator

L'operator mantiene gli unit test rapidi separati dai test di integrazione dell'API Kubernetes. I test regolari dell'operator non avviano un server API locale:

cd operator
go test ./...

Per eseguire la suite di integrazione del controller basata su envtest:

./scripts/test-operator-integration.sh

Questi test avviano un server API Kubernetes locale ed etcd tramite envtest, quindi richiedono il permesso di associarsi a 127.0.0.1. In sandbox ristrette, eseguili in una shell locale, in un ambiente Docker o in un runner CI che consenta il bind su localhost.

Supporto

PII-Shield è un'infrastruttura open-source per log che preservano la privacy. Se questo progetto è utile a te o alla tua organizzazione, puoi supportarne lo sviluppo tramite GitHub Sponsors.

Verifica delle Release

Le linee guida per la verifica del checksum delle release e del digest delle immagini sono documentate in docs/release-verification.md. Le release supportate da firma e provenienza sono tracciate come parte della roadmap di hardening della supply chain.

Licenza

Distribuito sotto la Licenza Apache 2.0. Vedi LICENSE per maggiori informazioni.