返回更新列表
新发布Sep 10, 2026

pii-shield v2.2.3

零代码的K8s边车容器,用于日志净化。通过熵分析检测机密,保持JSON完整性,并确定性编辑PII。🛡️

分享

PII-Shield 🛡️

面向 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 边车。

Release License Docker Pulls Artifact Hub
OpenSSF Best Practices Go Report Card Test Coverage Sponsor

“不要让 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 部署模式和供应链保证仍在稳定中。

组件状态
核心扫描器已发布 / 受控部署
CLI 边车已发布 / 受控部署
Kubernetes operator稳定化阶段
WASM SDK已发布 beta
Proxy-Wasm 网关集成计划中的研发
规则服务器(中央规则、面板)首个版本,自托管镜像
eBPF 审计代理(观察 stdout/stderr,从不脱敏)实验性,见 docs/ebpf-audit.md

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

为什么选择 PII-Shield?

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

PII-Shield 就部署在你的应用容器旁边:

  • 面向生产环境强化的核心引擎: 针对 Kubernetes sidecar 优化,热路径内存分配低,正则匹配具有确定性。
  • 上下文感知的熵分析: 即使没有密钥,也能通过分析上下文关键词检测出高熵机密(例如 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?

规则服务器将规则集集中在一处管理:安全团队在浏览器中编辑规则集,在真实扫描器上查看草稿对粘贴的日志行会产生什么效果,发布一个版本,然后每个在 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 版本发布之后:

  • 文本日志(应用和 syslog 风格的行,平均 122 字节):约 92 000 行/秒,10.7 MiB/s。
  • JSON 日志(带嵌套对象的结构化行,平均 161 字节):约 90 000 行/秒,13.8 MiB/s。JSON 行经过引号感知的分词器处理,而非 encoding/json,热路径每行约进行七次内存分配。
  • nginx 访问日志(平均 312 字节,每行都有一个 User-Agent):约 53 000 行/秒,15.7 MiB/s。这种形态是扫描器所见到的最慢的一种,因此当你的日志看起来像这样时,请按此来规划容量。

清洗器是单线程的,因此 CPU 限制就是吞吐量的上限(容量规划表见 docs/sidecar-failure-modes.md)。服务器核心通常比 M1 慢;请使用 ./benchmark/run_benchmarks.sh 测量你自己的日志(参见下文“性能基准测试”)。深度嵌套的 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)的 sidecar 注入到你的 Pod 中,无需任何代码或 Dockerfile 更改。

Docker

从 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 库

扫描器可以在 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_* 指标),因此你可以在开启脱敏前观察真实流量。

熵敏感度表(默认阈值: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 密钥)

快速开始

  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:3.0.0

# Output: Error: User password=[HIDDEN:8f3a11] failed login
  1. Kubernetes(自动 Sidecar 注入) 安装 PII-Shield Operator 后,保护应用只需创建一个 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。


分类