PII-Shield 🛡️

面向 Kubernetes 的零代码日志脱敏边车。 在日志离开 Pod 之前从日志中脱敏 PII，从而防止数据泄露（GDPR/SOC2）。

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

同名，不同项目。 这不是 Microsoft 开发者社区博客（2026 年 5 月，vikasgautam18/pii-shield）中的 PII Shield 隐私代理，不是 piishield.ai 或 piishield.com 的提示词脱敏产品，也不是 Intellirim 在 PyPI 上的 pii-shield 包。我们的包是 PyPI 上的 pii-shield-wasi 和 npm 上的 @aragossa/pii-shield-wasi；在文字表述中，我们将本项目称为 PII-Shield 边车。

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	已发布 beta
Proxy-Wasm 网关集成	计划中的研发
控制平面 UI	计划中的研发
eBPF 拦截	实验性研发

当前生产加固的边界见 KNOWN_LIMITATIONS.md。

为什么选择 PII-Shield？

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

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

生产加固的核心引擎： 针对 Kubernetes 边车优化，热路径内存分配低，正则匹配具有确定性。
上下文感知的熵分析： 即使没有键，也能通过分析上下文关键词检测出高熵密钥（例如 Error: ... 44saCk9...）。
自定义正则规则： 对结构化数据（UUID、ID）进行确定性脱敏，对已知模式覆盖熵检查。
内置密钥签名： 带发行方前缀的凭据——AWS 和 Google API 密钥、GitHub、Slack 和 Stripe 令牌、JWT、Bearer 凭据和 PEM 私钥块——会按其格式被脱敏，因此即使密钥正文熵值低或阈值被调高，有效密钥也能被捕获。
按形态识别电话号码： 带 + 的国际号码、北美 (555) 234-5678 形式，以及位于以电话命名的键（phone、mobile、wa_id、...）下的数字，即使单独的数字永远不会被评为密钥，也会被隐藏。
按键识别身份号码： 位于命名身份证明文件的键（idNumber、national_id、ssn、passport_number、tax_id、...）下的数字会被隐藏；而诸如 user_id 或 order_id 之类的记录 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 高度优化，但对复杂日志的深度检查需要仔细关注配置。

文本日志： 极快（>100k 行/秒）。
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.7
# OR from GitHub Container Registry (Enterprise):
docker pull ghcr.io/pii-shield/pii-shield:2.2.7

从源码构建

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

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

Go 库

扫描器可以在 Go 程序内运行，例如在 slog.Handler 中，在每条记录写入前对其进行脱敏。它只需要标准库：

go get github.com/pii-shield/pii-shield/v2/pkg/scanner

import "github.com/pii-shield/pii-shield/v2/pkg/scanner"

clean := scanner.ScanAndRedact(line)         // one line
cleanText := scanner.ScanAndRedactText(text) // several lines, line endings kept

该包在加载时读取与 CLI 相同的 PII_* 环境变量。v2.2.8 之前的版本声明的模块路径不带 /v2，因此 go get 会拒绝它们。

配置

完整的环境变量列表见 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 Keys)

快速开始

本地测试（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.7

# Output: 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 将一份冻结的 1000 行混合工作负载语料端到端地通过容器运行，并报告检测准确率。只有当密钥的值在输出中不存在且由脱敏标记取代时，该密钥才算被捕获；安全行必须原样返回。任何误报或漏报都会导致运行失败，容器以非零退出或返回的行数与输入不同时也会失败。散文中的无键密钥被单独跟踪为已知缺口，因为检测它们仅依赖熵：冻结语料允许零个，全新随机语料（--fuzz）允许两个。
端到端（E2E）测试：operator/tests/run_e2e.sh 套件使用 Minikube 和 Helm 执行全栈验证。它构建本地镜像，在没有 cert-manager 的情况下配置 Operator，部署目标 Job，并通过拦截边车输出来验证实际的日志脱敏。

检查你自己的部署

上述套件证明的是扫描器；它并不证明你的安装。在信任一条已脱敏的流之前，植入你控制的值，并在收集器侧查找它们：

从你控制的 Pod 记录一行包含合成卡号、虚构邮箱和测试账号的日志，然后在日志落地的位置对每个值执行 grep -c。计数必须为 0。
使用固定的 PII_SALT 将几千行生产形态的日志通过 CLI 运行，并阅读差异，查找幸存下来的值以及本应保持原样的值。
使用 PII_ENTITY_TYPE_LABELS=true 重复，以查看哪个检测器被触发：被报告为 entropy 而非 card 的卡号仍被隐藏，但 Luhn 路径没有看到它。
启用 PII_METRICS_ENABLED=true 后，按 type 观察 piishield_redaction_events_total；部署后的下降意味着上游某处的格式发生了变化。
在每条保护某个值免于脱敏的规则之后，再次运行植入值检查。

pii-shield v2.2.0