pii-shield/pii-shieldSidecar K8s zero-codice per la sanitizzazione dei log. Rileva i segreti tramite Entropy Analysis, preserva l'integrità del JSON e oscura i PII in modo deterministico. 🛡️
# PII-Shield 🛡️
**Sidecar di sanitizzazione dei log senza codice per Kubernetes.**
Previene le fughe di dati (GDPR/SOC2) oscurando le PII dai log *prima* che lascino il pod.
PII-Shield viene eseguito in-process — CLI, sidecar o WASM. Non esiste alcuna API ospitata né alcun server a cui vengono inviati i tuoi dati.
> **Stesso nome, progetti diversi.** Questo non è il proxy per la privacy PII Shield del blog della developer community di Microsoft (maggio 2026, [vikasgautam18/pii-shield](https://github.com/vikasgautam18/pii-shield)), non è i prodotti di prompt-redaction piishield.ai o piishield.com, e non è il pacchetto [`pii-shield`](https://pypi.org/project/pii-shield/) su PyPI di Intellirim. I nostri pacchetti sono `pii-shield-wasi` su PyPI e `@aragossa/pii-shield-wasi` su npm; nel testo chiamiamo questo progetto il sidecar PII-Shield.
[](https://github.com/pii-shield/pii-shield/releases/tag/v2.2.7)   [](https://artifacthub.io/packages/search?repo=pii-shield)<br>
[](https://www.bestpractices.dev/projects/12945)   [](https://pii-shield.com/go/sponsors?utm_source=github&utm_medium=readme-badge&utm_campaign=sponsors)
"Non lasciare che le PII avvelenino i tuoi modelli di AI." PII-Shield garantisce che i dati sensibili non raggiungano mai il tuo dataset di addestramento, risparmiandoti il riaddestramento forzato dei modelli a causa del GDPR.
> [!WARNING]
> **Passaggio 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 di produzione, sebbene il repository dell'operator mantenga ancora lo scaffolding Kustomize per lo sviluppo locale e la generazione dei manifest. L'accesso a `/bin/sh` all'interno del sidecar PII-Shield non è più supportato. Leggi la Guida alla Migrazione.
## Due Modelli di Deployment
PII-Shield offre due modi distinti per integrarsi nel tuo stack:
1. **Kubernetes Operator (Zero-code)**: Il nostro modello di deployment di punta. Un Operator K8s 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, offrendo una latenza `<1ms` senza hop di rete.
## Stato del Progetto e Roadmap
PII-Shield è uno strumento di sicurezza open-source in fase di sviluppo attivo, in una fase di hardening per la produzione. La linea di rilascio v2.x distribuisce artefatti utilizzabili di CLI, container, Helm/operator e WASM SDK. I percorsi core di redaction sono pronti per deployment controllati, mentre alcune modalità di deployment Kubernetes e garanzie sulla supply-chain sono ancora in fase di stabilizzazione.
| Componente | Stato |
| --- | --- |
| Scanner core | Rilasciato / deployment controllati |
| CLI sidecar | Rilasciato / deployment controllati |
| Kubernetes operator | Fase di stabilizzazione |
| WASM SDK | Beta rilasciata |
| Integrazione gateway Proxy-Wasm | R&D pianificata |
| UI Control Plane | R&D pianificata |
| Intercettazione eBPF | R&D sperimentale |
Consulta [KNOWN_LIMITATIONS.md](https://github.com/pii-shield/pii-shield/blob/main/KNOWN_LIMITATIONS.md) per i limiti attuali dell'hardening per la produzione.
## 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 trova proprio accanto al tuo container applicativo:**
- **Motore Core in hardening per la produzione:** Ottimizzato per i 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:** Redaction deterministica per dati strutturati (UUID, ID) che sovrascrive i controlli di entropia per pattern noti.
- **Firme di Segreti Integrate:** Credenziali con prefisso dell'emittente — chiavi API AWS e Google, token GitHub, Slack e Stripe, JWT, credenziali `Bearer` e blocchi di chiavi private PEM — vengono oscurate in base al loro formato, così una chiave valida viene catturata anche quando il suo corpo è a bassa entropia o la soglia è stata alzata.
- **Numeri di Telefono per Forma:** I numeri internazionali con un `+`, le forme nordamericane `(555) 234-5678` e le cifre sotto una chiave dal nome telefonico (`phone`, `mobile`, `wa_id`, ...) vengono nascosti anche se le sole cifre non raggiungono mai la soglia di segreto.
- **Numeri d'Identità per Chiave:** Le cifre sotto una chiave che nomina un documento d'identità (`idNumber`, `national_id`, `ssn`, `passport_number`, `tax_id`, ...) vengono nascoste; un id di record come `user_id` o `order_id` no.
- **Copertura Regressione e Fuzz:** Testato contro casi di stress inclusi garbage binario, 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 ospitato con gestione centralizzata delle regole, alerting su Slack e analisi delle redaction.
[](https://tally.so/r/PdY7Ze)
## Integrazioni
La build WASM in-process di PII-Shield è inclusa in [GuardSpine Code](https://github.com/DNYoussef/guardspine-code-action), 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 una particolare attenzione alla configurazione.
- **Log di Testo:** Estremamente veloce (>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 protezioni di ricorsione per prevenire stack overflow 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:
```bash
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'Operator PII-Shield che inietta automaticamente sidecar distroless altamente sicuri nei tuoi Pod senza richiedere alcuna modifica al codice o al Dockerfile.
### Docker
Ottieni l'immagine leggera più recente da Docker Hub o GHCR:
```bash
docker pull thelisdeep/pii-shield:2.2.7
# OR from GitHub Container Registry (Enterprise):
docker pull ghcr.io/pii-shield/pii-shield:2.2.7
```
### Compilazione dal Sorgente
Puoi compilare il binario direttamente dal codice sorgente:
```bash
go build -o pii-shield ./cmd/cleaner
```
### Libreria Go
Lo scanner può essere eseguito all'interno di un programma Go, ad esempio in un `slog.Handler` che oscura ogni record prima che venga scritto. Richiede solo la libreria standard:
```bash
go get github.com/pii-shield/pii-shield/v2/pkg/scanner
```
```go
import "github.com/pii-shield/pii-shield/v2/pkg/scanner"
clean := scanner.ScanAndRedact(line) // one line
cleanText := scanner.ScanAndRedactText(text) // several lines, line endings kept
```
Il pacchetto legge le stesse variabili d'ambiente `PII_*` della CLI quando viene caricato. Le release precedenti alla v2.2.8 dichiarano il percorso del modulo senza `/v2`, quindi `go get` le rifiuta.
## Configurazione
Consulta [CONFIGURATION.md](https://github.com/pii-shield/pii-shield/blob/main/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 in inglese.
- `PII_CUSTOM_REGEX_LIST`: Regole regex personalizzate per la redaction deterministica.
- `PII_SAFE_REGEX_LIST`: Regole regex in whitelist da ignorare (le corrispondenze vengono restituite così come sono).
### Tabella di Sensibilità all'Entropia (Soglia Predefinita: 3.6)
| Entropia | Tipo di Dato | Esempio |
|---------|-----------|---------|
| **0.0 - 3.0** | Parole comuni, ripetizioni | `password`, `admin`, `111111` |
| **3.0 - 3.6** | CamelCase, hash parziali | `ProgramCampaignInstanceJob`, `8f3a11b2c` |
| **3.6 - 4.5** | Percorsi, UUID, Password Deboli | `/opt/application/runtime`, `P@ssw0rd2026!` |
| **4.5 - 5.0** | Token Medi | `E8s9d_2kL1` |
| **5.0+** | Chiavi ad Alta Entropia | (SHA-256, API Keys) |
## Avvio Rapido
1. Test in Locale (CLI)
Puoi convogliare qualsiasi output di log attraverso PII-Shield per vederlo in azione immediatamente:
```bash
# 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.7
# Output: Error: User password=[HIDDEN:8f3a11] failed login
```
2. Kubernetes (Iniezione Automatica del Sidecar)
Con l'Operator PII-Shield installato, proteggere un'applicazione è semplice come creare una `PiiPolicy` ed etichettare i tuoi Pod.
**Crea una Policy:**
```yaml
apiVersion: core.pii-shield.io/v1alpha1
kind: PiiPolicy
metadata:
name: strict-policy
namespace: default
spec:
injectionMode: "file"
```
**Etichetta il tuo Deployment:**
```yaml
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 il `pii-shield-agent` usando 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** — da dove le PII fuoriescono dai pod, quali percorsi di log aggirano i tuoi filtri e come verificare che la redaction funzioni davvero. [Ottieni la checklist →](https://pii-shield.com/#checklist)
📦 **GDPR Compliance Pack — disponibile ora (accesso anticipato)**: oltre 40 regole di redaction testate, documenti pronti per il DPO, template di audit-trail. [$149 →](https://pii-shield.com/gdpr-pack?utm_source=github-readme&utm_medium=readme&utm_campaign=gdpr-pack) · HIPAA/PCI [in lista d'attesa →](https://pii-shield.com/#waitlist)
💬 **Usi PII-Shield?** [Raccontaci del tuo deployment →](https://tally.so/r/Gx4WoZ) — 2 minuti, e determina cosa verrà costruito in seguito.
## Verifica
Questo progetto è verificato con una suite di test in crescita pensata per aumentare la fiducia prima dell'hardening per la produzione:
1. **Unit Test**: Coprono casi limite, supporto multilingua e integrità JSON con copertura >85%.
2. **Fuzzing**: Il fuzzing nativo di Go garantisce la sicurezza contro crash su input binari non validi e casuali.
3. **Smoke Testing**: `./scripts/test-smoke.sh` esegue un corpus congelato di 1000 righe a carico misto end-to-end attraverso il container e riporta l'accuratezza di rilevamento. Un segreto viene considerato catturato solo quando il suo valore è assente dall'output e un marcatore di redaction ne ha preso il posto; una riga sicura deve tornare invariata. L'esecuzione fallisce su qualsiasi falso positivo o falso negativo, e anche quando il container esce con codice diverso da zero o restituisce un numero di righe diverso da quello ricevuto. I segreti senza chiave nel testo in prosa sono tracciati separatamente come lacune note, perché rilevarli si basa unicamente sull'entropia: il corpus congelato non ne consente nessuno, un corpus casuale fresco (`--fuzz`) ne consente due.
4. **Test End-to-End (E2E)**: La suite `operator/tests/run_e2e.sh` esegue una validazione full-stack usando Minikube e Helm. Compila immagini locali, predispone l'Operator senza cert-manager, distribuisce Job target e verifica l'effettiva redaction dei log intercettando gli output del sidecar.
### Verificare il proprio deployment
La suite sopra dimostra lo scanner; non dimostra la tua installazione. Prima di fidarti di un flusso oscurato, inserisci valori che controlli e cercali dal lato del collector:
1. Registra una riga con un numero di carta sintetico, un'email inventata e un numero di conto di test da un pod che controlli, poi esegui `grep -c` per ciascun valore dove arrivano i log. Il conteggio deve essere 0.
2. Esegui qualche migliaio di righe con la forma della produzione attraverso la CLI con un `PII_SALT` fisso e leggi il diff, cercando valori sopravvissuti e valori che sarebbero dovuti rimanere intatti.
3. Ripeti con `PII_ENTITY_TYPE_LABELS=true` per vedere quale rilevatore è scattato: una carta segnalata come `entropy` anziché `card` è comunque nascosta, ma il percorso Luhn non l'ha vista.
4. Con `PII_METRICS_ENABLED=true`, osserva `piishield_redaction_events_total` per `type`; un calo dopo un deploy significa che un formato è cambiato da qualche parte a monte.
5. Dopo ogni regola che protegge un valore dalla redaction, esegui di nuovo il controllo dei valori inseriti.
Ciò che lo scanner non può catturare per design, come un nome in testo libero, è elencato in [KNOWN_LIMITATIONS.md](https://github.com/pii-shield/pii-shield/blob/main/KNOWN_LIMITATIONS.md). La procedura completa con un log di pagamenti prima e dopo è nella [guida ai log bancari](https://pii-shield.com/guide-banking-logs-gdpr#verify).
### Benchmark delle Prestazioni
Per confrontare il throughput end-to-end della CLI tra il branch corrente e un ref di baseline:
```bash
./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:
```bash
BASE_REF=origin/main RUNS=9 LINES=500000 ./benchmark/run_benchmarks.sh
```
Questo misura l'intero percorso CLI da stdin a stdout. Per microbenchmark solo dello scanner, esegui:
```bash
go test -bench=. -benchmem ./pkg/scanner
```
### Test di Integrazione dell'Operator
L'operator mantiene i test unitari veloci separati dai test di integrazione con l'API Kubernetes. I test regolari dell'operator non avviano un server API locale:
```bash
cd operator
go test ./...
```
Per eseguire la suite di integrazione del controller basata su envtest:
```bash
./scripts/test-operator-integration.sh
```
Lo script chiama `make -C operator test-integration`, che scarica i binari envtest per la versione di Kubernetes in `operator/go.mod` al primo utilizzo. La CI esegue lo stesso target a ogni push. 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 è infrastruttura open-source per log che preservano la privacy. Se questo progetto è utile a te o alla tua organizzazione, puoi sostenerne lo sviluppo tramite [GitHub Sponsors](https://pii-shield.com/go/sponsors?utm_source=github&utm_medium=readme-support&utm_campaign=sponsors).
## Verifica delle Release
Le indicazioni per la verifica dei checksum delle release e dei digest delle immagini sono documentate in [docs/release-verification.md](https://github.com/pii-shield/pii-shield/blob/main/docs/release-verification.md). Le release con firma e provenienza sono tracciate come parte della roadmap di hardening della supply-chain.
## Licenza
Distribuito sotto la Licenza Apache 2.0. Consulta `LICENSE` per maggiori informazioni.