PII-Shield 🛡️

Sidecar de sanitização de logs sem código para Kubernetes. Evita vazamentos de dados (GDPR/SOC2) mascarando PII dos logs antes de saírem do pod.

O PII-Shield executa in-process — CLI, sidecar ou WASM. Não há API hospedada nem servidor para onde seus dados sejam enviados.

"Não deixe que PII envenene seus modelos de IA." O PII-Shield garante que dados sensíveis nunca cheguem ao seu conjunto de treinamento, poupando você do retreinamento de modelos forçado pelo GDPR.

[!WARNING] Atualizando para a v2.0.0? Movemos a distribuição para usuários finais para instalações baseadas em Helm e Native Sidecars Distroless. O Kustomize não é mais um caminho de instalação suportado para usuários de produção, embora o repositório do operador ainda mantenha o scaffolding Kustomize para desenvolvimento local e geração de manifestos. O acesso a /bin/sh dentro do sidecar do PII-Shield não é mais suportado. Leia o Guia de Migração.

Dois Modelos de Implantação

O PII-Shield oferece duas formas distintas de integração à sua stack:

1. Operador Kubernetes (Zero-code): Nosso modelo de implantação principal. Um Operador K8s totalmente automatizado que injeta um Sidecar Distroless altamente seguro em seus pods para interceptar e sanitizar logs em tempo real.
2. WASM In-Process (Para integrações principais): Para desempenho extremo, o mecanismo principal pode ser embutido diretamente via WASM, proporcionando latência <1ms sem saltos de rede.

Status do Projeto e Roadmap

O PII-Shield é uma ferramenta de segurança open-source em desenvolvimento ativo, em fase de endurecimento para produção. A linha de versões v2.x disponibiliza artefatos utilizáveis de CLI, contêiner, Helm/operador e SDK WASM. Os caminhos principais de redação estão prontos para implantações controladas, enquanto alguns modos de implantação Kubernetes e garantias de cadeia de suprimentos ainda estão sendo estabilizados.

Consulte KNOWN_LIMITATIONS.md para os limites atuais de endurecimento para produção.

Por que PII-Shield?

Desenvolvedores frequentemente esquecem de mascarar dados sensíveis. Filtros regex tradicionais em Fluentd/Logstash são lentos, difíceis de manter e consomem CPU cara nos agregadores de logs.

O PII-Shield fica bem ao lado do contêiner da sua aplicação:

• Mecanismo principal endurecido para produção: Otimizado para sidecars Kubernetes com baixas alocações de memória em caminhos críticos e correspondência regex determinística.
• Análise de Entropia Sensível ao Contexto: Detecta segredos de alta entropia mesmo sem chaves (ex.: Error: ... 44saCk9...) analisando palavras-chave de contexto.
• Regras Regex Personalizadas: Redação determinística para dados estruturados (UUIDs, IDs) que substitui verificações de entropia para padrões conhecidos.
• Cobertura de Regressão e Fuzzing: Testado contra casos de estresse incluindo lixo binário, aninhamento JSON e logs multilíngues.
• Hash Determinístico: Substitui segredos por hashes únicos (ex.: [HIDDEN:a1b2c]), permitindo que QA correlacione erros sem ver os dados brutos.
• Plug-and-play: Nenhuma alteração de código necessária. Funciona com qualquer linguagem (Node, Python, Java, Go).
• Suporte a Whitelist: Permite explicitamente padrões seguros (ex.: hashes git, IDs de sistema) usando PII_SAFE_REGEX_LIST para evitar falsos positivos.

Gerenciando o PII-Shield em dezenas de clusters?

Estamos construindo um Control Plane hospedado com gerenciamento centralizado de regras, alertas via Slack e análises de redação.

Integrações

A build WASM in-process do PII-Shield é distribuída dentro do GuardSpine Code, uma GitHub Action open-source de governança de código para IA, que inclui o binário e o credita em seu NOTICE.

Considerações de Desempenho

Embora o PII-Shield seja altamente otimizado, a inspeção profunda de logs complexos exige atenção cuidadosa à configuração.

• Logs de Texto: Extremamente rápidos (>100k linhas/s).
• Logs JSON: Parsing com zero alocações (sem overhead de encoding/json). O scanner analisa manualmente estruturas JSON para garantir alta taxa de transferência (~7MB/s) sem picos de memória.
• Recomendação: O uso é seguro para alta taxa de transferência. Usamos proteções de recursão para evitar estouros de pilha em JSON profundamente aninhado.

Instalação

Helm Chart (Operador Kubernetes)

A forma oficial e recomendada de implantar o PII-Shield no Kubernetes é através do nosso 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

Isso implanta o Operador PII-Shield que injeta automaticamente sidecars distroless altamente seguros em seus Pods sem exigir qualquer alteração de código ou Dockerfile.

Docker

Obtenha a imagem leve mais recente do Docker Hub ou GHCR:

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

Compilar a partir do Código-Fonte

Você pode compilar o binário diretamente do código-fonte:

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

Configuração

Consulte CONFIGURATION.md para uma lista completa de variáveis de ambiente, incluindo:

• PII_SALT: Salt HMAC personalizado (Obrigatório para produção).
• PII_ADAPTIVE_THRESHOLD: Ativa linhas de base de entropia dinâmicas.
• PII_DISABLE_BIGRAM_CHECK: Otimiza para logs não-ingleses.
• PII_CUSTOM_REGEX_LIST: Regras regex personalizadas para redação determinística.
• PII_SAFE_REGEX_LIST: Regras regex de whitelist a ignorar (correspondências são retornadas como estão).

Tabela de Sensibilidade de Entropia (Limiar Padrão: 3.6)

Início Rápido

1. Teste Localmente (CLI) Você pode canalizar qualquer saída de log pelo PII-Shield para vê-lo em ação imediatamente:

# Simule um log com uma senha sensível
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:2.2.3

# Saída: Error: User password=[HIDDEN:8f3a11] failed login

2. Kubernetes (Injeção Automatizada de Sidecar) Com o Operador PII-Shield instalado, proteger uma aplicação é tão simples quanto criar um PiiPolicy e rotular seus Pods.

Crie uma Política:

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

Rotule seu 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"
# ...

O Operador injetará automaticamente o pii-shield-agent usando o padrão Native Sidecar (K8s 1.28+) e mascarará com segurança todos os logs!

📋 Grátis: Checklist de Auditoria de Vazamento de PII em Logs Kubernetes com 25 pontos — onde o PII vaza dos pods, quais caminhos de log ignoram seus filtros e como verificar se a redação realmente funciona. Obtenha o checklist →

📦 Pacote de Conformidade GDPR — disponível agora (acesso antecipado): Mais de 40 regras de redação testadas, documentação pronta para DPO, modelos de trilha de auditoria. $149 → · HIPAA/PCI na lista de espera →

💬 Usando o PII-Shield? Conte-nos sobre sua implantação → — 2 minutos, e isso molda o que será construído em seguida.

Verificação

Este projeto é verificado com uma suíte de testes crescente destinada a aumentar a confiança antes do endurecimento para produção:

1. Testes Unitários: Cobrem casos extremos, suporte multilíngue e integridade JSON com cobertura >85%.
2. Fuzzing: Fuzzing nativo em Go garante segurança contra falhas com entradas binárias inválidas e aleatórias.
3. Testes de Fumaça: ./scripts/test-smoke.sh exercita cargas de trabalho mistas e relata a precisão da detecção.
4. Testes Ponta a Ponta (E2E): A suíte operator/tests/run_e2e.sh realiza validação full-stack usando Minikube e Helm. Ela compila imagens locais, provisiona o Operador sem cert-manager, implanta Jobs alvo e verifica a redação real de logs interceptando as saídas do sidecar.

Benchmarks de Desempenho

Para comparar a taxa de transferência CLI ponta a ponta entre o branch atual e uma ref de base:

./benchmark/run_benchmarks.sh

Por padrão, o benchmark compara HEAD com origin/main, atualiza origin/main, gera um corpus de logs misto, alterna a ordem de execução antigo/novo e relata mediana, p95, min/máx e MiB/s:

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

Isso mede o caminho CLI completo de stdin para stdout. Para microbenchmarks apenas do scanner, execute:

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

Testes de Integração do Operador

O operador mantém testes unitários rápidos separados dos testes de integração com a API Kubernetes. Os testes regulares do operador não iniciam um servidor de API local:

cd operator
go test ./...

Para executar a suíte de integração do controlador baseada em envtest:

./scripts/test-operator-integration.sh

Esses testes iniciam um servidor de API Kubernetes local e etcd através de envtest, portanto exigem permissão para vincular a 127.0.0.1. Em sandboxes restritos, execute-os em um shell local, ambiente Docker ou runner de CI que permita bind em localhost.

Suporte

O PII-Shield é uma infraestrutura open-source para logs que preservam a privacidade. Se este projeto for útil para você ou sua organização, você pode apoiar seu desenvolvimento através do GitHub Sponsors.

Verificação de Lançamento

As orientações de verificação de checksum de lançamento e digest de imagem estão documentadas em docs/release-verification.md. Lançamentos com assinatura e proveniência são rastreados como parte do roadmap de endurecimento da cadeia de suprimentos.

Licença

Distribuído sob a Licença Apache 2.0. Consulte LICENSE para mais informações.