PII-Shield 🛡️

Sidecar Zero-code per la sanificazione dei log in Kubernetes. Impedisce le fughe di dati (GDPR/SOC2) oscurando le PII dai log prima che lascino il pod.

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

"Non lasciare che le PII avvelenino i tuoi modelli AI." PII-Shield garantisce che i dati sensibili non raggiungano mai il tuo dataset di addestramento, salvandoti dal riaddestramento del modello imposto dal GDPR.

[!WARNING] Aggiornamento alla v2.0.0? Abbiamo spostato la distribuzione per gli utenti finali su installazioni basate su Helm e sidecar nativi Distroless. Kustomize non è più un percorso di installazione supportato per gli utenti in produzione, anche se il repository dell'operatore mantiene 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 operatore K8s completamente automatizzato che inietta un sidecar Distroless altamente sicuro nei tuoi pod per intercettare e sanificare i log al volo.
2. In-Process WASM (Per integrazioni core): Per prestazioni estreme, il motore core può essere incorporato direttamente tramite WASM, garantendo una latenza <1ms senza salti di rete.

Stato del Progetto e Roadmap

PII-Shield è uno strumento di sicurezza open-source in fase attiva di sviluppo e di indurimento per la produzione. La linea di release v2.x distribuisce artefatti utilizzabili per CLI, container, Helm/operator e SDK WASM. I percorsi core di redazione sono pronti per implementazioni controllate, mentre alcune modalità di distribuzione Kubernetes e le garanzie sulla supply chain sono ancora in fase di stabilizzazione.

Consulta KNOWN_LIMITATIONS.md per gli attuali confini dell'indurimento in produzione.

Perché PII-Shield?

Gli sviluppatori spesso dimenticano di mascherare i dati sensibili. I tradizionali filtri regex 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:

• Core Engine indurito per la produzione: Ottimizzato per i sidecar Kubernetes con basse allocazioni di memoria sui percorsi critici e matching regex deterministico.
• Analisi dell'entropia sensibile al contesto: Rileva segreti ad alta entropia anche senza chiavi (es. Error: ... 44saCk9...) analizzando le parole chiave del contesto.
• Regole regex personalizzate: Redazione deterministica per dati strutturati (UUID, ID) che sovrascrive i controlli di entropia per pattern noti.
• Copertura regression e fuzz: Testato contro casi di stress tra cui dati binari spazzatura, 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: Consente esplicitamente pattern sicuri (es. hash git, ID di sistema) utilizzando PII_SAFE_REGEX_LIST per prevenire falsi positivi.

Gestisci PII-Shield su decine di cluster?

Stiamo costruendo un Control Plane ospitato con gestione centralizzata delle regole, avvisi Slack e analisi delle redazioni.

Integrazioni

La build WASM in-process di PII-Shield è inclusa in GuardSpine Code, una GitHub Action open-source per la governance del codice AI, che include 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. Usiamo protezioni contro la ricorsione per prevenire overflow dello stack su JSON profondamente annidati.

Installazione

Helm Chart (Operatore Kubernetes)

Il modo ufficiale e consigliato per distribuire PII-Shield in Kubernetes è tramite il nostro Operatore 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 l'Operatore PII-Shield che inietta automaticamente sidecar distroless altamente sicuri nei tuoi Pod senza richiedere modifiche al codice o al Dockerfile.

Docker

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

docker pull thelisdeep/pii-shield:2.2.0
# OR from GitHub Container Registry (Enterprise):
docker pull ghcr.io/pii-shield/pii-shield:2.2.0

Compilazione dal Sorgente

Puoi compilare il binario direttamente dal codice sorgente:

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

Configurazione

Consulta CONFIGURATION.md per un elenco completo delle variabili d'ambiente, tra cui:

• 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 di whitelist da ignorare (le corrispondenze vengono restituite così come sono).

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

Avvio Rapido

1. Test in locale (CLI) Puoi convogliare qualsiasi output di log tramite PII-Shield per vederlo subito in azione:

# Emulate a log with a sensitive password
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:2.2.0

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

2. Kubernetes (Iniezione Automatica del Sidecar) Con l'Operatore PII-Shield 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'Operatore inietterà automaticamente il pii-shield-agent utilizzando il pattern Native Sidecar (K8s 1.28+) e maschererà in modo sicuro tutti i log!

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

📦 Pacchetti di conformità (GDPR/HIPAA/PCI) in arrivo — ottieni l'accesso anticipato →

💬 Usi PII-Shield? Raccontaci della tua implementazione → — 2 minuti, e contribuisce a determinare ciò che verrà sviluppato dopo.

Verifica

Questo progetto è verificato con una suite di test in continua crescita, pensata per aumentare la fiducia prima dell'indurimento in produzione:

1. Test unitari: Coprono casi limite, supporto multilingua e integrità JSON con una copertura >85%.
2. Fuzzing: Il fuzzing nativo di Go garantisce sicurezza dai crash contro input binari non validi e casuali.
3. Smoke test: ./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 una validazione full-stack utilizzando Minikube e Helm. Compila immagini locali, configura l'Operatore senza cert-manager, implementa i Job target e verifica l'effettiva redazione dei log intercettando gli output del sidecar.

Benchmark delle Prestazioni

Per confrontare il throughput end-to-end della CLI 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 l'intero percorso CLI da stdin a stdout. Per microbenchmark del solo scanner, esegui:

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

Test di Integrazione dell'Operatore

L'operatore mantiene i test unitari rapidi separati dai test di integrazione dell'API Kubernetes. I test regolari dell'operatore 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 sostenere il suo 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 indurimento della supply chain.

Licenza

Distribuito sotto la Licenza Apache 2.0. Consulta LICENSE per ulteriori informazioni.