PII-Shield 🛡️

Sidecar de saneamiento de registros sin código para Kubernetes. Evita fugas de datos (GDPR/SOC2) redactando la PII de los registros antes de que salgan del pod.

PII-Shield se ejecuta en proceso — CLI, sidecar o WASM. No hay una API alojada ni un servidor al que se envíen tus datos.

"No permitas que la PII envenene tus modelos de IA." PII-Shield garantiza que los datos sensibles nunca lleguen a tu conjunto de datos de entrenamiento, evitándote el reentrenamiento forzado de modelos por GDPR.

[!WARNING] ¿Actualizando a v2.0.0? Hemos trasladado la distribución para usuarios finales a instalaciones basadas en Helm y sidecars nativos Distroless. Kustomize ya no es una ruta de instalación compatible para usuarios de producción, aunque el repositorio del operador conserva el andamiaje de Kustomize para el desarrollo local y la generación de manifiestos. El acceso a /bin/sh dentro del sidecar de PII-Shield ya no es compatible. Lee la Guía de migración.

Dos Modelos de Implementación

PII-Shield ofrece dos formas distintas de integrarse en tu stack:

1. Operador de Kubernetes (Zero-code): Nuestro modelo de implementación insignia. Un operador de K8s totalmente automatizado que inyecta un sidecar Distroless de alta seguridad en tus pods para interceptar y sanear los registros sobre la marcha.
2. WASM en proceso (Para integraciones principales): Para un rendimiento extremo, el motor central se puede incrustar directamente vía WASM, proporcionando una latencia <1ms sin saltos de red.

Estado del Proyecto y Hoja de Ruta

PII-Shield es una herramienta de seguridad de código abierto en desarrollo activo, en fase de endurecimiento para producción. La línea de lanzamientos v2.x distribuye artefactos utilizables de CLI, contenedor, Helm/operador y SDK WASM. Las rutas principales de redacción están listas para implementaciones controladas, mientras que algunos modos de implementación en Kubernetes y las garantías de la cadena de suministro aún se están estabilizando.

Consulta KNOWN_LIMITATIONS.md para conocer los límites actuales del endurecimiento para producción.

¿Por qué PII-Shield?

Los desarrolladores suelen olvidar enmascarar los datos sensibles. Los filtros regex tradicionales en Fluentd/Logstash son lentos, difíciles de mantener y consumen una CPU costosa en los agregadores de registros.

PII-Shield se sitúa justo al lado del contenedor de tu aplicación:

• Motor central endurecido para producción: Optimizado para sidecars de Kubernetes con bajas asignaciones de memoria en rutas críticas y coincidencia regex determinista.
• Análisis de entropía consciente del contexto: Detecta secretos de alta entropía incluso sin claves (p. ej. Error: ... 44saCk9...) analizando palabras clave del contexto.
• Reglas regex personalizadas: Redacción determinista para datos estructurados (UUIDs, IDs) que anula las comprobaciones de entropía para patrones conocidos.
• Cobertura de regresión y fuzzing: Probado contra casos de estrés, incluidos datos binarios basura, anidamiento JSON y registros multilingües.
• Hash determinista: Reemplaza los secretos con hashes únicos (p. ej., [HIDDEN:a1b2c]), lo que permite a QA correlacionar errores sin ver los datos en bruto.
• Integración directa: No requiere cambios de código. Funciona con cualquier lenguaje (Node, Python, Java, Go).
• Compatibilidad con lista blanca: Permite explícitamente patrones seguros (p. ej., hashes de git, IDs de sistema) usando PII_SAFE_REGEX_LIST para evitar falsos positivos.

¿Gestionas PII-Shield en docenas de clústeres?

Estamos construyendo un plano de control alojado con gestión centralizada de reglas, alertas de Slack y análisis de redacción.

Integraciones

La compilación WASM en proceso de PII-Shield se distribuye dentro de GuardSpine Code, una GitHub Action de código abierto para la gobernanza de código mediante IA, que empaqueta el binario y le da crédito en su NOTICE.

Consideraciones de Rendimiento

Aunque PII-Shield está altamente optimizado, la inspección profunda de registros complejos requiere una atención cuidadosa a la configuración.

• Registros de texto: Extremadamente rápidos (>100k líneas/s).
• Registros JSON: Análisis sin asignaciones de memoria (sin la sobrecarga de encoding/json). El escáner analiza manualmente las estructuras JSON para garantizar un alto rendimiento (~7MB/s) sin picos de memoria.
• Recomendación: Su uso es seguro para alto rendimiento. Usamos salvaguardas de recursión para prevenir desbordamientos de pila en JSON profundamente anidados.

Instalación

Chart de Helm (Operador de Kubernetes)

La forma oficial y recomendada de implementar PII-Shield en Kubernetes es mediante nuestro operador totalmente automatizado:

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

Esto implementa el operador de PII-Shield, que inyecta automáticamente sidecars distroless de alta seguridad en tus Pods sin requerir ningún cambio de código ni de Dockerfile.

Docker

Obtén la imagen ligera más reciente desde 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

Compilar desde el Código Fuente

Puedes compilar el binario directamente desde el código fuente:

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

Configuración

Consulta CONFIGURATION.md para ver la lista completa de variables de entorno, incluidas:

• PII_SALT: Sal HMAC personalizada (requerida para producción).
• PII_ADAPTIVE_THRESHOLD: Habilita líneas base de entropía dinámicas.
• PII_DISABLE_BIGRAM_CHECK: Optimiza para registros que no están en inglés.
• PII_CUSTOM_REGEX_LIST: Reglas regex personalizadas para redacción determinista.
• PII_SAFE_REGEX_LIST: Reglas regex de lista blanca para ignorar (las coincidencias se devuelven tal cual).

Tabla de Sensibilidad de Entropía (Umbral Predeterminado: 3.6)

Inicio Rápido

1. Prueba Local (CLI) Puedes canalizar cualquier salida de registro a través de PII-Shield para verlo en acción de inmediato:

# 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 (Inyección Automatizada de Sidecars) Con el operador de PII-Shield instalado, proteger una aplicación es tan simple como crear una PiiPolicy y etiquetar tus Pods.

Crea una Política:

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

Etiqueta tu 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"
# ...

El operador inyectará automáticamente el pii-shield-agent usando el patrón de sidecar nativo (K8s 1.28+) y enmascarará de forma segura todos los registros.

📋 Gratis: Lista de verificación de auditoría de PII en registros de Kubernetes en 25 puntos — dónde se filtra la PII desde los pods, qué rutas de registro evaden tus filtros y cómo verificar que la redacción realmente funciona. Obtén la lista de verificación →

📦 Paquetes de cumplimiento (GDPR/HIPAA/PCI) próximamente — obtén acceso anticipado →

💬 ¿Usas PII-Shield? Cuéntanos sobre tu implementación → — 2 minutos, y define lo que se construye a continuación.

Verificación

Este proyecto se verifica con un conjunto de pruebas en crecimiento destinado a aumentar la confianza antes del endurecimiento para producción:

1. Pruebas unitarias: Cubren casos límite, compatibilidad multilingüe e integridad JSON con >85 % de cobertura.
2. Fuzzing: El fuzzing nativo de Go garantiza seguridad frente a caídas ante entradas binarias inválidas y aleatorias.
3. Pruebas de humo: ./scripts/test-smoke.sh ejercita cargas de trabajo mixtas e informa la precisión de detección.
4. Pruebas de extremo a extremo (E2E): El conjunto operator/tests/run_e2e.sh realiza una validación de pila completa con Minikube y Helm. Compila imágenes locales, aprovisiona el operador sin cert-manager, implementa Jobs objetivo y verifica la redacción real de los registros interceptando las salidas de los sidecars.

Puntos de Referencia de Rendimiento

Para comparar el rendimiento de extremo a extremo de la CLI entre la rama actual y una referencia base:

./benchmark/run_benchmarks.sh

De forma predeterminada, el punto de referencia compara HEAD con origin/main, actualiza origin/main, genera un corpus de registros mixto, alterna el orden de ejecución antiguo/nuevo e informa mediana, p95, min/max y MiB/s:

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

Esto mide la ruta completa de stdin a stdout de la CLI. Para microbenchmarks solo del escáner, ejecuta:

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

Pruebas de Integración del Operador

El operador mantiene las pruebas unitarias rápidas separadas de las pruebas de integración de la API de Kubernetes. Las pruebas regulares del operador no inician un servidor de API local:

cd operator
go test ./...

Para ejecutar el conjunto de integración del controlador basado en envtest:

./scripts/test-operator-integration.sh

Estas pruebas inician un servidor de API de Kubernetes local y etcd a través de envtest, por lo que requieren permiso para vincularse a 127.0.0.1. En sandboxes restringidos, ejecútalas en un shell local, un entorno Docker o un runner de CI que permita la vinculación a localhost.

Soporte

PII-Shield es una infraestructura de código abierto para registros que preservan la privacidad. Si este proyecto te resulta útil a ti o a tu organización, puedes apoyar su desarrollo a través de GitHub Sponsors.

Verificación de Lanzamientos

La guía de verificación de checksums de lanzamiento y digests de imagen está documentada en docs/release-verification.md. Los lanzamientos respaldados por firma y procedencia se rastrean como parte de la hoja de ruta de endurecimiento de la cadena de suministro.

Licencia

Distribuido bajo la Licencia Apache 2.0. Consulta LICENSE para más información.