PII-Shield 🛡️

面向 Kubernetes 的零代码日志净化边车（Sidecar）。 通过在日志离开 Pod 之前对 PII 进行脱敏，防止数据泄露（GDPR/SOC2）。

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

Docker Pulls

“不要让 PII 污染你的 AI 模型。”PII-Shield 确保敏感数据永远不会到达你的训练数据集，从而避免因 GDPR 要求而被迫重新训练模型。

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

两种部署模型

PII-Shield 提供两种不同的方式集成到你的技术栈中：

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

项目状态与路线图

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

组件	状态
核心扫描器	已发布 / 受控部署
CLI 边车	已发布 / 受控部署
Kubernetes operator	稳定化阶段
WASM SDK	已发布测试版
Proxy-Wasm 网关集成	计划中的研发
控制平面 UI	计划中的研发
eBPF 拦截	实验性研发

有关当前生产加固边界的详细信息，请参阅 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.3
# 或从 GitHub Container Registry（企业版）获取：
docker pull ghcr.io/pii-shield/pii-shield:2.2.3

从源码构建

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

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）

熵值	数据类型	示例
0.0 - 3.0	常见单词、重复内容	`password`、`admin`、`111111`
3.0 - 3.6	驼峰命名、部分哈希	`ProgramCampaignInstanceJob`、`8f3a11b2c`
3.6 - 4.5	路径、UUID、弱密码	`/opt/application/runtime`、`P@ssw0rd2026!`
4.5 - 5.0	中等令牌	`E8s9d_2kL1`
5.0+	高熵密钥	（SHA-256、API 密钥）

快速开始

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

# 模拟包含敏感密码的日志
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:2.2.3

# 输出：Error: User password=[HIDDEN:8f3a11] failed login

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 合规包 —— 现已推出（抢先体验）：40+ 条经过测试的脱敏规则、DPO 就绪文档、审计追踪模板。$149 → · HIPAA/PCI 加入候补名单 →

💬 正在使用 PII-Shield？ 告诉我们你的部署情况 → —— 只需 2 分钟，它将影响后续功能的开发方向。

验证

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

单元测试：覆盖边界情况、多语言支持和 JSON 完整性，覆盖率超过 85%。
模糊测试：原生 Go 模糊测试确保对无效和随机二进制输入具备崩溃安全性。
冒烟测试：./scripts/test-smoke.sh 执行混合工作负载并报告检测准确率。
端到端（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。

pii-shield v2.2.3

分类