返回更新列表
新发布Aug 18, 2026

pii-shield v2.2.0

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

分享

PII-Shield 🛡️

面向 Kubernetes 的零代码日志脱敏边车。 在 PII 离开 Pod 之前 将其从日志中脱敏，从而防止数据泄露（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 网关集成计划中的研发
控制平面 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 私钥块——会按其格式被脱敏，因此即使密钥主体熵值低或阈值被调高，有效密钥也能被捕获。
  • 回归与模糊测试覆盖： 已针对压力用例进行测试，包括二进制垃圾数据、JSON 嵌套和多语言日志。
  • 确定性哈希： 用唯一哈希替换密钥（例如 [HIDDEN:a1b2c]），让 QA 能够关联错误而无需看到原始数据。
  • 即插即用： 无需修改代码。适用于任何语言（Node、Python、Java、Go）。
  • 白名单支持： 使用 PII_SAFE_REGEX_LIST 显式允许安全模式（例如 git 哈希、系统 ID），以防止误报。

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

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

集成

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.4
# OR from GitHub Container Registry (Enterprise):
docker pull ghcr.io/pii-shield/pii-shield:2.2.4

从源码构建

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

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 密钥)

快速开始

  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.4

# Output: Error: User password=[HIDDEN:8f3a11] failed login
  1. 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 分钟，它将影响接下来的开发方向。

验证

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

  1. 单元测试：覆盖边缘情况、多语言支持和 JSON 完整性，覆盖率 >85%。
  2. 模糊测试：原生 Go 模糊测试确保针对无效和随机二进制输入的崩溃安全性。
  3. 冒烟测试：./scripts/test-smoke.sh 通过容器端到端运行一个固定的 1000 行混合工作负载语料库，并报告检测准确率。只有当密钥的值未出现在输出中且被脱敏标记取代时，该密钥才算被捕获；安全行必须原样返回。任何误报或漏报都会导致运行失败，容器以非零退出或返回的行数与输入不同时也会失败。散文中的无键密钥作为已知缺口单独跟踪，因为检测它们仅依赖熵：固定语料库允许零个，全新随机语料库（--fuzz）允许两个。
  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 runner 中运行它们。

支持

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

发布验证

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

许可证

在 Apache 2.0 许可证下分发。更多信息请参见 LICENSE。

阅读更多

分类

容器安全数据泄露云安全DevSecOps隐私保护秘密检测日志分析