PII-Shield 🛡️

面向 Kubernetes 的零代码日志脱敏边车（Sidecar）。 通过在日志离开 Pod 之前对 PII（个人身份信息）进行脱敏，防止数据泄漏（GDPR/SOC2）。

PII-Shield 以进程内方式运行——支持 CLI、边车或 WASM。没有托管 API，也没有接收你数据的服务器。

"不要让 PII 污染你的 AI 模型。"PII-Shield 确保敏感数据永远不会进入你的训练数据集，让你免于因 GDPR 而被迫重新训练模型。

[!WARNING] 要升级到 v2.0.0 吗？ 我们已将最终用户的分发方式迁移到基于 Helm 的安装和 Distroless 原生边车。Kustomize 不再是面向生产用户的受支持发布安装路径，不过 Operator 仓库仍保留 Kustomize 脚手架，用于本地开发和清单生成。PII-Shield 边车内部不再支持访问 /bin/sh。请阅读迁移指南。

两种部署模型

PII-Shield 提供两种不同的集成方式：

1. Kubernetes Operator（零代码）：我们的旗舰部署模型。一个全自动的 K8s Operator，可将高度安全的 Distroless 边车注入到你的 Pod 中，实时拦截并脱敏日志。
2. 进程内 WASM（用于核心集成）：为了极致性能，核心引擎可通过 WASM 直接嵌入，提供 <1ms 延迟，无网络跳转。

项目状态与路线图

PII-Shield 是一款处于生产加固阶段的、积极开发中的开源安全工具。v2.x 版本线发布了可用的 CLI、容器、Helm/Operator 和 WASM SDK 构件。核心脱敏路径已可用于受控部署，而部分 Kubernetes 部署模式和供应链保障仍在稳定化中。

有关当前生产加固的边界，请参阅 KNOWN_LIMITATIONS.md。

为什么选择 PII-Shield？

开发人员常常忘记对敏感数据进行脱敏。Fluentd/Logstash 中传统的正则过滤器速度慢、难以维护，并且会在日志聚合器上消耗昂贵的 CPU。

PII-Shield 就位于你的应用容器旁边：

• 生产加固的核心引擎： 专为 Kubernetes 边车优化，在热点路径上实现低内存分配和确定性正则匹配。
• 上下文感知的熵分析： 即使没有密钥，也能通过分析上下文关键词检测出高熵机密（例如 Error: ... 44saCk9...）。
• 自定义正则规则： 针对结构化数据（UUID、ID）的确定性脱敏，对已知模式覆盖熵检查。
• 回归与模糊测试覆盖： 已针对二进制垃圾数据、JSON 嵌套和多语言日志等压力场景进行测试。
• 确定性哈希： 将机密替换为唯一哈希（例如 [HIDDEN:a1b2c]），使 QA 无需查看原始数据即可关联错误。
• 即插即用： 无需修改代码。适用于任何语言（Node、Python、Java、Go）。
• 白名单支持： 使用 PII_SAFE_REGEX_LIST 显式放行安全模式（例如 git 哈希、系统 ID），以避免误报。

需要跨数十个集群管理 PII-Shield？

我们正在构建一个托管控制平面，提供集中式规则管理、Slack 告警和脱敏分析。

集成

PII-Shield 的进程内 WASM 构建内置在 GuardSpine Code 中，后者是一个开源的 AI 代码治理 GitHub Action，它将该二进制文件打包，并在其 NOTICE 中注明出处。

性能注意事项

虽然 PII-Shield 已经过高度优化，但对复杂日志的深度检查仍需谨慎对待配置。

• 文本日志： 极快（>10 万行/秒）。
• JSON 日志： 零分配解析（无 encoding/json 开销）。扫描器手动解析 JSON 结构，以确保高吞吐量（约 7MB/s）且无内存尖峰。
• 建议： 可安全用于高吞吐场景。我们使用递归保护机制来防止深度嵌套 JSON 导致栈溢出。

安装

Helm Chart（Kubernetes Operator）

在 Kubernetes 中部署 PII-Shield 的官方推荐方式是通过我们完全自动化的 Operator：

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

这将部署 PII-Shield Operator，它会自动将高度安全、基于 Distroless 的边车注入到你的 Pod 中，无需修改任何代码或 Dockerfile。

Docker

从 Docker Hub 或 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

从源码构建

你可以直接从源码构建二进制文件：

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

配置

有关环境变量的完整列表，请参阅 CONFIGURATION.md，包括：

• PII_SALT：自定义 HMAC 盐值（生产环境必需）。
• PII_ADAPTIVE_THRESHOLD：启用动态熵基线。
• PII_DISABLE_BIGRAM_CHECK：针对非英文日志进行优化。
• PII_CUSTOM_REGEX_LIST：用于确定性脱敏的自定义正则规则。
• PII_SAFE_REGEX_LIST：要忽略的白名单正则规则（匹配项原样返回）。

熵敏感度表（默认阈值：3.6）

快速开始

1. 本地测试（CLI） 你可以将任何日志输出通过管道传给 PII-Shield，立即查看实际效果：

# 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（自动边车注入） 安装 PII-Shield Operator 后，保护应用只需创建一个 PiiPolicy 并为你的 Pod 打上标签即可。

创建策略：

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

为你的 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"
# ...

Operator 将使用原生边车模式（K8s 1.28+）自动注入 pii-shield-agent，并安全地脱敏所有日志！

📋 免费获取：25 项 Kubernetes 日志 PII 审计检查清单——涵盖 PII 从 Pod 中泄漏的位置、哪些日志路径会绕过你的过滤器，以及如何验证脱敏确实生效。获取检查清单 →

📦 合规包（GDPR/HIPAA/PCI）即将推出——抢先获取 →

💬 正在使用 PII-Shield？ 告诉我们你的部署情况 → ——只需 2 分钟，它将决定接下来构建什么。

验证

本项目通过不断扩充的测试套件进行验证，旨在生产加固前提升信心：

1. 单元测试：覆盖边缘情况、多语言支持和 JSON 完整性，覆盖率 >85%。
2. 模糊测试：原生 Go 模糊测试确保针对无效和随机二进制输入的崩溃安全性。
3. 冒烟测试：./scripts/test-smoke.sh 执行混合工作负载并报告检测准确率。
4. 端到端（E2E）测试：operator/tests/run_e2e.sh 套件使用 Minikube 和 Helm 执行全栈验证。它构建本地镜像、在不使用 cert-manager 的情况下部署 Operator、部署目标 Job，并通过拦截边车输出来验证实际的日志脱敏。

性能基准测试

要比较当前分支与基线 ref 之间的端到端 CLI 吞吐量：

./benchmark/run_benchmarks.sh

默认情况下，基准测试会将 HEAD 与 origin/main 进行比较、刷新 origin/main、生成混合日志语料库、交替新旧运行顺序，并报告中位数、p95、最小值/最大值以及 MiB/s：

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

这会测量完整的 stdin 到 stdout CLI 路径。如需仅扫描器的微基准测试，请运行：

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

Operator 集成测试

Operator 将快速的单元测试与 Kubernetes API 集成测试分开。常规的 Operator 测试不会启动本地 API 服务器：

cd operator
go test ./...

要运行基于 envtest 的控制器集成测试套件：

./scripts/test-operator-integration.sh

这些测试通过 envtest 启动本地 Kubernetes API 服务器和 etcd，因此需要具备绑定到 127.0.0.1 的权限。在受限的沙箱环境中，请在允许 localhost 绑定的本地 shell、Docker 环境或 CI 运行器中运行它们。

支持

PII-Shield 是用于隐私保护日志的开源基础设施。如果这个项目对您或您的组织有用，您可以通过 GitHub Sponsors 支持其开发。

发布验证

发布校验和与镜像摘要验证指南记录在 docs/release-verification.md 中。基于签名和来源证明的发布作为供应链加固路线图的一部分进行跟踪。

许可证

基于 Apache 2.0 License 分发。有关更多信息，请参阅 LICENSE。