PII-Shield 🛡️

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

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

"Não deixe a PII envenenar 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 o usuário final para instalações baseadas em Helm e Sidecars Nativos Distroless. O Kustomize não é mais um caminho de instalação de release 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 manifests. 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 maneiras distintas de se integrar à 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 releases v2.x entrega 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 o PII-Shield?

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

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 a 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 no Slack e análise de redação.

Integrações

A versão 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 fornece 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 alto throughput. Usamos salvaguardas de recursão para prevenir estouros de pilha em JSON profundamente aninhado.

Instalação

Helm Chart (Operador Kubernetes)

A maneira oficial e recomendada de implantar o PII-Shield no Kubernetes é por meio 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 alterações de código ou Dockerfile.

Docker

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

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

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 serem ignoradas (correspondências são retornadas como estão).

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

Início Rápido

1. Teste Localmente (CLI) Você pode enviar 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.0

# 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 PII em Logs Kubernetes com 25 pontos — onde a PII vaza dos pods, quais caminhos de log contornam seus filtros e como verificar se a redação realmente funciona. Obtenha o checklist →

📦 Pacotes de Conformidade (GDPR/HIPAA/PCI) em breve — tenha acesso antecipado →

💬 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 de destino e verifica a redação real dos logs interceptando as saídas dos sidecars.

Benchmarks de Desempenho

Para comparar o throughput da CLI ponta a ponta entre a branch atual e um 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 mistos, alterna a ordem de execução antigo/novo e relata mediana, p95, min/max e MiB/s:

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

Isso mede o caminho completo da CLI de stdin a 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 da 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 de controladores baseada em envtest:

./scripts/test-operator-integration.sh

Esses testes iniciam um servidor de API Kubernetes local e etcd por meio do 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 por meio do GitHub Sponsors.

Verificação de Release

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

Licença

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