cloakllm/CloakLLM-PY
GitHub: cloakllm/CloakLLM-PY
介于应用与 LLM 提供商之间的 Python PII 隐藏中间件，自动识别并替换敏感信息，保护数据不被发送到云端模型，同时提供符合 EU AI Act 要求的防篡改审计日志。
Stars: 0 | Forks: 0
# 🛡️ CloakLLM
**隐藏你的提示词。证明你的合规性。**
你发送给 LLM 提供商的每一个提示词都是以明文形式可见的 —— 姓名、电子邮件、SSN、API 密钥、医疗记录。CloakLLM 会拦截、隐藏（Cloak）并审计每一次调用。
```
┌──────────────┐ ┌─────────────────────┐ ┌──────────────┐
│ Your App │───▶│ CLOAKLLM │───▶│ Claude/GPT │
│ │ │ │ │ /Gemini │
│ "Email │ │ "Email [PERSON_0] │ │ │
│ john@..." │ │ [EMAIL_0]..." │ │ Never sees │
│ │◀───│ │◀───│ real data │
└──────────────┘ └─────────────────────┘ └──────────────┘
│
┌─────────────┐
│ Hash-Chain │
│ Audit Log │
│ (EU AI Act) │
└─────────────┘
> **Also available for JavaScript/TypeScript:** `npm install cloakllm` — zero dependencies, OpenAI SDK integration. See [CloakLLM JS](https://github.com/cloakllm/CloakLLM-JS). | [Project Hub](https://github.com/cloakllm/CloakLLM)
```
## ⏰ 为什么是现在？
**欧盟 AI 法案 (EU AI Act) 将于 2026 年 8 月 2 日开始执行。** 第 12 条要求具备监管机构可以数学验证的防篡改审计日志。违规后果：高达 **全球年收入的 7%**。
你当前的日志记录 (`logger.info()`) 无法通过审计。CloakLLM 提供：
- 🔒 **PII 检测** — 通过 NER + 正则表达式检测姓名、电子邮件、SSN、API 密钥、IP、信用卡、IBAN
- 🎭 **保留上下文的隐藏** — `John Smith` → `[PERSON_0]`（LLM 仍能理解该提示词）
- ⛓️ **防篡改审计链** — 每个事件都通过哈希链接。任何篡改都会破坏链条。
- ⚡ **一行中间件** — OpenAI SDK 和 LiteLLM（100+ 提供商）的即插即用保护
## 🚀 快速开始
### 安装
```
pip install cloakllm # standalone usage
pip install cloakllm[litellm] # with LiteLLM integration
python -m spacy download en_core_web_sm
```
### 选项 A：使用 OpenAI SDK（一行代码）
```
from cloakllm import enable_openai
from openai import OpenAI
client = OpenAI()
enable_openai(client) # Done. All calls are now cloaked.
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Email john@acme.com about Project X"}]
)
# Provider 从未看到 "john@acme.com" — 只有 "[EMAIL_0]"
# Response 在您看到之前自动解密
```
### 选项 B：使用 LiteLLM（一行代码）
```
import cloakllm
cloakllm.enable() # Done. All LiteLLM calls are now cloaked.
import litellm
response = litellm.completion(
model="anthropic/claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "Email john@acme.com about Project X"}]
)
# Provider 从未看到 "john@acme.com" — 只有 "[EMAIL_0]"
# Response 在您看到之前自动解密
```
### 选项 C：独立使用
```
from cloakllm import Shield
shield = Shield()
# Cloak
cloaked, token_map = shield.sanitize(
"Send report to john@acme.com, SSN 123-45-6789"
)
# cloaked: "发送报告到 [EMAIL_0], SSN [SSN_0]"
# ... 向任意 LLM 发送 cloaked prompt ...
# Uncloak response
clean = shield.desanitize(llm_response, token_map)
```
### 脱敏模式（不可逆）
```
from cloakllm import Shield, ShieldConfig
shield = Shield(ShieldConfig(mode="redact"))
redacted, _ = shield.sanitize("Email john@acme.com about Sarah Johnson")
# redacted: "向 [PERSON_REDACTED] 发送关于 [EMAIL_REDACTED] 的邮件"
# 未存储 token map — 无法逆向
```
### 实体详情（合规元数据）
```
from cloakllm import Shield
shield = Shield()
sanitized, token_map = shield.sanitize("Email john@acme.com, SSN 123-45-6789")
# Per-entity metadata (无原始文本 — PII-safe)
token_map.entity_details
# [
# {"category": "EMAIL", "start": 6, "end": 19, "length": 13, "confidence": 0.95, "source": "regex", "token": "[EMAIL_0]"},
# {"category": "SSN", "start": 25, "end": 36, "length": 11, "confidence": 0.95, "source": "regex", "token": "[SSN_0]"}
# ]
# 用于仪表板的完整报告
token_map.to_report()
# {"entity_count": 2, "categories": {...}, "tokens": [...], "mode": "tokenize", "entity_details": [...]}
```
### 选项 D：CLI
```
# 扫描文本中的敏感数据
python -m cloakllm scan "Email john@acme.com, SSN 123-45-6789"
# 验证 audit chain 完整性
python -m cloakllm verify ./cloakllm_audit/
# 查看 audit 统计信息
python -m cloakllm stats ./cloakllm_audit/
```
## ⛓️ 防篡改审计链
每个隐藏事件都记录在哈希链式的仅追加日志中：
```
{
"seq": 42,
"event_id": "a1b2c3d4-...",
"timestamp": "2026-02-27T14:30:00+00:00",
"event_type": "sanitize",
"model": "claude-sonnet-4-20250514",
"entity_count": 3,
"categories": {"PERSON": 1, "EMAIL": 1, "SSN": 1},
"tokens_used": ["[PERSON_0]", "[EMAIL_0]", "[SSN_0]"],
"prompt_hash": "sha256:9f86d0...",
"sanitized_hash": "sha256:a3f2b1...",
"entity_details": [
{"category": "PERSON", "start": 0, "end": 10, "length": 10, "confidence": 0.85, "source": "spacy", "token": "[PERSON_0]"},
{"category": "EMAIL", "start": 12, "end": 25, "length": 13, "confidence": 0.95, "source": "regex", "token": "[EMAIL_0]"},
{"category": "SSN", "start": 27, "end": 38, "length": 11, "confidence": 0.95, "source": "regex", "token": "[SSN_0]"}
],
"latency_ms": 4.2,
"prev_hash": "sha256:7c4d2e...",
"entry_hash": "sha256:b5e8f3..."
}
```
**链条验证：**
```
python -m cloakllm verify ./cloakllm_audit/
# ✅ Audit chain 完整性已验证 — 未检测到篡改。
```
如果任何人修改了单个条目，后续的每个哈希都会失效：
```
Entry #40 ✅ → #41 ✅ → #42 ❌ TAMPERED → #43 ❌ BROKEN → ...
```
这正是欧盟 AI 法案第 12 条所要求的。
## ⚙️ 配置
```
from cloakllm import Shield, ShieldConfig
shield = Shield(config=ShieldConfig(
# Detection
spacy_model="en_core_web_lg", # Larger model = better accuracy
detect_emails=True,
detect_phones=True,
detect_api_keys=True,
custom_patterns=[ # Your own regex patterns
("PROJECT_CODE", r"PRJ-\d{4}-\w+"),
("INTERNAL_ID", r"EMP-\d{6}"),
],
# Audit
log_dir="./compliance_audit",
log_original_values=False, # Never log original PII
# Middleware
skip_models=["ollama/", "local/"], # Don't cloak local model calls
))
```
**LLM 检测（可选）** — 使用本地 Ollama 实例来捕获语义 PII（地址、医疗信息等）：
```
shield = Shield(config=ShieldConfig(
llm_detection=True, # Enable LLM-based detection
llm_model="llama3.2", # Ollama model to use
llm_ollama_url="http://localhost:11434", # Ollama endpoint
llm_timeout=10.0, # Timeout in seconds
llm_confidence=0.85, # Confidence score for LLM detections
))
```
环境变量：
```
CLOAKLLM_LOG_DIR=./audit
CLOAKLLM_SPACY_MODEL=en_core_web_sm
CLOAKLLM_OTEL_ENABLED=true
CLOAKLLM_LLM_DETECTION=true
CLOAKLLM_LLM_MODEL=llama3.2
CLOAKLLM_OLLAMA_URL=http://localhost:11434
```
## 🔍 检测内容
| 类别 | 示例 | 方法 |
|----------|----------|--------|
| `PERSON` | John Smith, Sarah Johnson | spaCy NER |
| `ORG` | Acme Corp, Google | spaCy NER |
| `GPE` | New York, Israel | spaCy NER |
| `EMAIL` | john@acme.com | Regex |
| `PHONE` | +1-555-0142, 050-123-4567 | Regex |
| `SSN` | 123-45-6789 | Regex |
| `CREDIT_CARD` | 4111111111111111 | Regex |
| `IP_ADDRESS` | 192.168.1.100 | Regex |
| `API_KEY` | sk-abc123..., AKIA... | Regex |
| `IBAN` | DE89370400440532013000 | Regex |
| `JWT` | eyJhbGciOi... | Regex |
| Custom | 你的模式 | Regex |
| `ADDRESS` | 742 Evergreen Terrace | LLM (Local) |
| `DATE_OF_BIRTH` | 1990-01-15 | LLM (Local) |
| `MEDICAL` | diabetes mellitus | LLM (Local) |
| `FINANCIAL` | account 4521-XXX | LLM (Local) |
| `NATIONAL_ID` | TZ 12345678 | LLM (Local) |
| `BIOMETRIC` | fingerprint hash | LLM (Local) |
| `USERNAME` | @johndoe42 | LLM (Local) |
| `PASSWORD` | P@ssw0rd123 | LLM (Local) |
| `VEHICLE` | plate ABC-1234 | LLM (Local) |
## 🗺️ 路线图
- [x] PII 检测 (NER + regex)
- [x] 确定性分词
- [x] 哈希链审计日志
- [x] LiteLLM 中间件集成
- [x] OpenAI SDK 中间件集成
- [x] CLI 工具
- [x] 脱敏 / 清洗模式
- [x] 字段级 PII 元数据 (entity_details)
- [ ] OpenTelemetry span 发射（带自动脱敏）
- [ ] RFC 3161 可信时间戳
- [ ] 已签名的审计快照
- [ ] MCP 安全网关（工具验证，权限执行）
- [x] 本地 LLM 检测（可选，通过 Ollama）
- [ ] 基于敏感性的路由（PII → 本地模型，通用 → 云端）
- [ ] 管理仪表板
- [ ] 欧盟 AI 法案合规报告生成器
## 📜 许可证
MIT
## 🤝 贡献
欢迎提交 PR。最高影响力的领域：
1. **非英语 NER** — 希伯来语、阿拉伯语、中文 PII 检测
2. **去分词准确性** — 处理 LLM 的复述
3. **OpenTelemetry 集成** — GenAI 语义约定
4. **MCP 安全** — 工具验证中间件
**为欧盟 AI 法案截止日期而构建。在审计人员到来之前发布。**
标签：AI风险缓解, Claude, CVE检测, DLP, EU AI Act, GDPR, Gemini, GPT, JSONLines, LLM 安全, LLM评估, NER, Ollama, PII 脱敏, Python SDK, spaCy, 中间件, 哈希链, 审计日志, 对抗攻击, 提示词工程, 敏感信息检测, 数据掩码, 数据防泄露, 漏洞管理, 策略决策点, 网络安全, 身份信息保护, 逆向工具, 隐私保护, 零信任