面向 Kubernetes 的零代码日志脱敏边车。 在日志离开 Pod 之前 对 PII 进行脱敏,从而防止数据泄露(GDPR/SOC2)。
PII-Shield 以进程内方式运行——CLI、边车或 WASM。没有托管 API,也没有会将你的数据发送到的服务器。
同名,不同项目。 这不是 Microsoft 开发者社区博客中的 PII Shield 隐私代理(2026 年 5 月,vikasgautam18/pii-shield),也不是 piishield.ai 或 piishield.com 的提示词脱敏产品,也不是 Intellirim 在 PyPI 上的
pii-shield包。我们的包是 PyPI 上的pii-shield-wasi和 npm 上的@aragossa/pii-shield-wasi;在正文中,我们将此项目称为 PII-Shield 边车。
“不要让 PII 毒害你的 AI 模型。”PII-Shield 确保敏感数据永远不会进入你的训练数据集,从而避免因 GDPR 而被迫重新训练模型。
[!WARNING] 要升级到 v2.0.0 吗? 我们已将最终用户分发迁移到基于 Helm 的安装和 Distroless 原生边车。Kustomize 不再是生产用户受支持的发布安装路径,不过 operator 仓库仍保留 Kustomize 脚手架,用于本地开发和清单生成。PII-Shield 边车内不再支持
/bin/sh访问。请阅读迁移指南。
PII-Shield 提供两种不同的方式集成到你的技术栈中:
<1ms 延迟且无网络跳转。PII-Shield 是一个积极开发的开源安全工具,正处于生产加固阶段。v2.x 发布线提供可用的 CLI、容器、Helm/operator 和 WASM SDK 制品。核心脱敏路径已可用于受控部署,而部分 Kubernetes 部署模式和供应链保证仍在稳定中。
| 组件 | 状态 |
|---|---|
| 核心扫描器 | 已发布 / 受控部署 |
| CLI 边车 | 已发布 / 受控部署 |
| Kubernetes operator | 稳定化阶段 |
| WASM SDK | 已发布 beta |
| Proxy-Wasm 网关集成 | 计划中的研发 |
| 规则服务器(中央规则、面板) | 首个版本,自托管镜像 |
| eBPF 审计代理(观察 stdout/stderr,从不脱敏) | 实验性,见 docs/ebpf-audit.md |
有关当前生产加固的边界,请参阅 KNOWN_LIMITATIONS.md。
开发者常常忘记对敏感数据进行掩码。Fluentd/Logstash 中的传统正则过滤器速度慢、难以维护,并且会在日志聚合器上消耗昂贵的 CPU。
PII-Shield 就部署在你的应用容器旁边:
Error: ... 44saCk9...)。Bearer 凭据以及 PEM 私钥块——会按其格式被脱敏,因此即使密钥主体熵值低或阈值已被调高,有效密钥也能被捕获。+ 的国际号码、北美 (555) 234-5678 格式,以及位于以电话命名的键(phone、mobile、wa_id 等)下的数字都会被隐藏,尽管纯数字本身永远不会被判定为机密。idNumber、national_id、ssn、passport_number、tax_id 等)下的数字会被隐藏;而 user_id 或 order_id 这类记录 ID 则不会。[HIDDEN:a1b2c]),使 QA 能够关联错误而无需看到原始数据。PII_SAFE_REGEX_LIST 显式允许安全模式(例如 git 哈希、系统 ID),以防止误报。规则服务器将规则集集中在一处管理:安全团队在浏览器中编辑规则集,在真实扫描器上查看草稿对粘贴的日志行会产生什么效果,发布一个版本,然后每个在 PiiPolicy 中指定该规则集的集群都会用只读令牌拉取它,无需重启 Pod。除非集群开启统计通道,否则不会向它发送任何关于集群的信息,而统计通道只发送计数器。它以镜像 ghcr.io/pii-shield/pii-shield-rules 的形式发布,供你在自己的边界内部署,参见 docs/rules-server.md。发布内容可以用只有发布者持有的密钥进行签名,每次变更都会记入活动日志,可选的统计通道会按集群显示正在运行的规则版本以及隐藏了多少个值,且仅以计数器形式呈现。它运行在 SQLite 上,或为多实例运行在 Postgres 上;deploy/rules-server 可在一台机器上以 HTTPS 和持续备份的方式运行它。
PII-Shield 的进程内 WASM 构建随 GuardSpine Code 一同发布,这是一个开源的 AI 代码治理 GitHub Action,它内置了该二进制文件并在其 NOTICE 中予以致谢。
于 2026-10-25 测量,使用 CLI 读取 stdin 并写入文件,单个 Apple M1 核心(GOMAXPROCS=1),Go 1.27.3,200 000 行语料库,5 次运行的中位数,main 分支在 2.2.8 版本发布之后:
encoding/json,热路径每行约进行七次内存分配。清洗器是单线程的,因此 CPU 限制就是吞吐量的上限(容量规划表见 docs/sidecar-failure-modes.md)。服务器核心通常比 M1 慢;请使用 ./benchmark/run_benchmarks.sh 测量你自己的日志(参见下文“性能基准测试”)。深度嵌套的 JSON 受递归限制约束,因此恶意行无法耗尽栈。
在 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)的 sidecar 注入到你的 Pod 中,无需任何代码或 Dockerfile 更改。
从 Docker Hub 或 GHCR 获取最新的轻量级镜像:
docker pull thelisdeep/pii-shield:3.0.0
# OR from GitHub Container Registry (Enterprise):
docker pull ghcr.io/pii-shield/pii-shield:3.0.0
你可以直接从源代码构建二进制文件:
go build -o pii-shield ./cmd/cleaner
扫描器可以在 Go 程序内部运行,例如在一个 slog.Handler 中,在每条记录被写入之前对其进行脱敏。它只需要标准库:
go get github.com/pii-shield/pii-shield/v3/pkg/scanner
import "github.com/pii-shield/pii-shield/v3/pkg/scanner"
clean := scanner.ScanAndRedact(line) // one line
cleanText := scanner.ScanAndRedactText(text) // several lines, line endings kept
该包在加载时读取与 CLI 相同的 PII_* 环境变量。从 v3.0.0 起,模块路径以 /v3 结尾。v2.2.8 至 v2.3.1 版本为 github.com/pii-shield/pii-shield/v2;v2.2.8 之前的版本声明的路径不带主版本号,因此 go get 会拒绝它们。
完整的环境变量列表请参见 CONFIGURATION.md,其中包括:
PII_SALT:自定义 HMAC 盐(生产环境必需)。PII_ADAPTIVE_THRESHOLD:启用动态熵基线。PII_DISABLE_BIGRAM_CHECK:针对非英文日志进行优化。PII_CUSTOM_REGEX_LIST:用于确定性脱敏的自定义正则规则。PII_SAFE_REGEX_LIST:要忽略的白名单正则规则(匹配项按原样返回)。PII_MODE=audit:试运行。日志行原样通过,并统计本应被脱敏的内容(piishield_audit_* 指标),因此你可以在开启脱敏前观察真实流量。| 熵值 | 数据类型 | 示例 |
|---|---|---|
| 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 密钥) |
# Emulate a log with a sensitive password
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:3.0.0
# Output: Error: User password=[HIDDEN:8f3a11] failed login
PiiPolicy 并为 Pod 添加标签即可。创建策略:
apiVersion: core.pii-shield.io/v1alpha1
kind: PiiPolicy
metadata:
name: strict-policy
namespace: default
spec:
injectionMode: "file"
为你的部署添加标签:
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 会使用 Native Sidecar 模式(K8s 1.28+)自动注入 pii-shield-agent,并安全地遮蔽所有日志!
不确定规则会隐藏哪些内容?先在策略中添加 auditMode: true:sidecar 会保持每一行原样不变,只统计它本应脱敏的内容(piishield_audit_* 指标以及其日志中的每小时摘要)。在真实流量上运行一段时间,然后移除该字段并重启工作负载。在管道模式下,sidecar 仍位于流的路径中;请参阅 KNOWN_LIMITATIONS.md。