pii-shield/pii-shield
GitHub: pii-shield/pii-shield
面向 Kubernetes 的零代码日志脱敏 Sidecar，通过熵分析和确定性哈希在日志离开 Pod 前自动清除 PII 和密钥，助力企业实现 GDPR/SOC2 合规。
Stars: 144 | Forks: 8
# PII-Shield 🛡️
**面向 Kubernetes 的零代码日志净化 Sidecar。**
通过在日志 *离开* Pod 之前对其进行 PII（个人身份信息）脱敏，防止数据泄露（GDPR/SOC2）。
[](https://artifacthub.io/packages/search?repo=pii-shield)
“不要让 PII 毒害你的 AI 模型。”PII-Shield 确保敏感数据永远不会进入你的训练数据集，让你免受因 GDPR 违规而被迫重新训练模型的困扰。
## 两种部署模式
PII-Shield 提供了两种截然不同的方式来集成到你的技术栈中：
1. **Kubernetes Operator（零代码）**：我们的旗舰级部署模型。一个全自动的 K8s Operator，它会将一个高安全性的 Distroless Sidecar 注入到你的 Pod 中，以实时拦截并净化日志。
2. **进程内 WASM（用于核心集成）**：针对极致性能场景，核心引擎可以通过 WASM 直接嵌入，提供 `<1ms` 的延迟且无需网络跳转。
## 为什么选择 PII-Shield？
开发者经常忘记掩盖敏感数据。Fluentd/Logstash 中传统的正则表达式过滤器不仅速度慢、难以维护，还会消耗日志聚合器上昂贵的 CPU 资源。
**PII-Shield 就紧贴在你的应用容器旁：**
- **生产就绪：** 为 Kubernetes Sidecar 进行了优化，具有**超低内存分配**（热路径上零 GC 开销）和确定性的 O(1) 正则表达式匹配。
- **上下文感知的熵分析：** 即使没有匹配键，也能通过分析上下文关键词检测出高熵的机密信息（例如 `Error: ... 44saCk9...`）。
- **自定义正则表达式规则：** 对结构化数据（UUID、ID）进行确定性脱敏，该规则会覆盖熵检查，确保已知模式实现 100% 合规。
- **100% 准确率：** 已通过“野生”压力测试验证，包括处理二进制乱码、JSON 深度嵌套和多语言日志。
- **确定性哈希：** 用唯一的哈希值替换机密信息（例如 `[HIDDEN:a1b2c]`），允许 QA 团队在无需查看原始数据的情况下进行错误关联分析。
- **开箱即用：** 无需更改任何代码。支持任何语言（Node、Python、Java、Go）。
- **白名单支持：** 使用 `PII_SAFE_REGEX_LIST` 显式允许安全模式（例如 git hashes、系统 ID），以防止误报。
## 需要跨数十个集群管理 PII-Shield？
我们正在构建一个托管的控制平面，提供集中式规则管理、Slack 告警和脱敏分析功能。
[](https://tally.so/r/PdY7Ze)
## 受到信赖
**GuardSpine**（AI 治理核心）集成了 PII-Shield 的**进程内 WASM**，在其 Node.js 和 Python 代理内部直接净化敏感的证据追踪记录。
## 性能考量
虽然 PII-Shield 已经过高度优化，但对复杂日志的深度检查仍需注意配置。
- **文本日志：** 极快（>100k 行/秒）。
- **JSON 日志：** 零分配解析（没有 `encoding/json` 开销）。扫描器手动解析 JSON 结构以确保高吞吐量（约 7MB/s），且不会出现内存激增。
- **建议：** 在高吞吐量场景下使用是安全的。我们使用了递归保护机制来防止在深度嵌套的 JSON 中出现堆栈溢出。
## 安装说明
### Helm Chart (Kubernetes Operator)
在 Kubernetes 中部署 PII-Shield 官方且推荐的方式是通过我们全自动的 Operator：
```
helm repo add pii-shield https://aragossa.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:v2.0.0
# 或者从 GitHub Container Registry (Enterprise) 获取：
docker pull ghcr.io/pii-shield/pii-shield:v2.0.0
```
### 从源码构建
你可以直接从源代码构建二进制文件：
```
go build -o pii-shield ./cmd/cleaner/main.go
```
## 配置
有关环境变量的完整列表，请参阅 [CONFIGURATION.md](CONFIGURATION.md)，包括：
- `PII_SALT`：自定义 HMAC salt（生产环境中为必填项）。
- `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** | 中等强度 Token | `E8s9d_2kL1` |
| **5.0+** | 高熵密钥 | （SHA-256，API Keys） |
## 快速入门
1. 本地测试 (CLI)
你可以将任何日志输出通过管道传递给 PII-Shield，立即查看其运行效果：
```
# 模拟包含敏感密码的日志
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:v2.0.0
# 输出: Error: User password=[HIDDEN:8f3a11] failed login
```
2. Kubernetes（自动注入 Sidecar）
安装 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 将使用原生 Sidecar 模式（K8s 1.28+）自动注入 `pii-shield-agent` 并安全地掩盖所有日志！
## 验证
该项目已通过全面的测试套件进行验证，确保了 v2.0.0 版本的生产就绪状态：
1. **单元测试**：涵盖边缘情况、多语言支持和 JSON 完整性，代码覆盖率 >85%。
2. **模糊测试**：原生 Go 模糊测试确保了对无效和随机二进制输入的崩溃安全性。
3. **冒烟测试**：`./run_smoke.sh` 验证了在混合工作负载下 100% 的检测准确率。
4. **端到端 (E2E) 测试**：`operator/tests/run_e2e.sh` 套件使用 Minikube 和 Helm 执行全栈验证。它构建本地镜像，在没有 cert-manager 的情况下配置 Operator，部署目标 Job，并通过拦截 Sidecar 输出来验证实际的日志脱敏效果。
## 许可证
在 Apache 2.0 许可证下分发。有关更多信息，请参见 `LICENSE`。
标签：AI数据安全, DevSecOps, Distroless, DLP, EVTX分析, Fluentd替代, GDPR, Go语言, IPv6支持, JSON处理, Operator, PII检测, Sidecar, SOC2, WASM, WebAssembly, Web截图, 上游代理, 个人信息保护, 人工智能安全, 合规性, 子域名变形, 子域名突变, 容器安全, 敏感数据过滤, 数据泄露, 数据遮盖, 日志安全, 日志审计, 日志脱敏, 熵分析, 秘密检测, 程序破解, 网络安全, 请求拦截, 隐私保护, 零代码