ocultar-pii

Ocultar

Ocultar 是一款用于 AI 工作流的开源本地 PII/PHI 脱敏引擎。

它以本地 HTTP sidecar 的形式运行。在文本发送到云端大模型之前将其发送给 Ocultar；Ocultar 会返回相同的文本，并将每一处个人数据替换为确定性、可逆的令牌 （[EMAIL_9c8f7a1b]、[PERSON_3a12b4cd] 等）。原始数据会加密并存储在本地保险库中。持有审计员令牌的调用方可以还原这些数据。

任何 PII 都不会到达上游模型。

---

快速开始 — Docker

export OCU_MASTER_KEY=$(openssl rand -hex 32)
export OCU_SALT=$(openssl rand -hex 16)
export OCU_AUDITOR_TOKEN=$(openssl rand -hex 24)

docker run --rm -p 4141:4141 \
  -e OCU_MASTER_KEY \
  -e OCU_SALT \
  -e OCU_AUDITOR_TOKEN \
  ghcr.io/ocultar-dev/ocultar:latest -serve 4141

快速开始 — 从源代码构建

CGO_ENABLED=1 go build -o ocultar ./services/refinery/cmd/

OCU_MASTER_KEY=$(openssl rand -hex 32) \
OCU_SALT=$(openssl rand -hex 16) \
OCU_AUDITOR_TOKEN=$(openssl rand -hex 24) \
./ocultar -serve 4141

---

API 参考

GET /api/health

返回引擎状态。无需身份验证。

{
  "status": "healthy",
  "version": "1.14",
  "vault": { "status": "online" },
  "slm":   { "status": "online", "circuit": "closed" }
}

---

POST /api/refine

对文本或 JSON 中的 PII 进行脱敏。无需身份验证。

请求正文：原始文本字符串或任意 JSON 值。

响应：

{
  "refined": "{\"message\":\"Hello [PERSON_3a12b4cd], your order [EMAIL_9c8f7a1b] is ready.\"}",
  "report": {
    "hits": 2,
    "types": ["PERSON", "EMAIL"]
  }
}

refined 是一个 JSON 编码的字符串 — 解析一次即可获得脱敏后的负载。

---

POST /api/reveal

将保险库令牌还原为原始数据。

身份验证：必须在 Authorization: Bearer <OCU_AUDITOR_TOKEN> 标头中提供令牌。 如果服务器未设置 OCU_AUDITOR_TOKEN，则返回 403。

请求正文：

{ "tokens": ["[PERSON_3a12b4cd]", "[EMAIL_9c8f7a1b]"] }

响应：

{
  "results": {
    "[PERSON_3a12b4cd]": "Alice Martin",
    "[EMAIL_9c8f7a1b]": "[email protected]"
  }
}

---

GET /api/entities · POST /api/entities · POST /api/entities/seed

管理持久化实体注册表（预先录入规范名称，使所有变体映射到同一个令牌）。需要 Authorization: Bearer <OCU_AUDITOR_TOKEN>。

---

架构

在任何文本离开设备之前，Ocultar 会运行两个检测层级：

层级 1 — 确定性正则表达式 / 启发式（快速，零外传）

子层级	防护机制	检测内容
0	词典	configs/protected_entities.json 中的 VIP 姓名、组织名称
0.5	模式 + 熵	通过香农评分检测高熵字符串（API 密钥、机密）
1	规则引擎	EMAIL、SSN、IBAN、信用卡、50 多种国家身份证件格式
1.1	电话号码防护	libphonenumber 验证
1.2	地址防护	启发式街道地址解析器（EN/FR/ES/DE）
1.5	上下文检测	问候语、签名、疑问句中的姓名

层级 2 — 基于 SLM 的 NER（召回率更高，端点可配置）

将文本发送到本地 AI sidecar 进行命名实体识别。扫描器始终会初始化，但只有在 SLM_SIDECAR_URL 处运行兼容的 sidecar 时才会产生结果。 将其指向 privacy-filter 或 llama.cpp 实例即可启用 NER。

SLM_SIDECAR_URL=http://localhost:8085 ./ocultar -serve 4141

对于 llama.cpp / Qwen 端点，请使用 SLM_ADAPTER=openai-chat；对于 privacy-filter 协议（默认值），则保持未设置。

---

隐私模型

• 零外传设计。 只有经过遮蔽的令牌（[EMAIL_9c8f7a1b]，……）会转发给上游模型。原始文本不会传输。
• 仅限本地保险库。 每个令牌与其原始值之间的映射使用 AES-256-GCM 和 HKDF-SHA256 加密，并存储在本地文件系统中的 DuckDB 保险库（vault.db）内。保险库文件绝不会传输。
• 保留原始提示词。 为支持审计差异视图，refinery 会将每条原始（未遮蔽）提示词记录在本地保险库中。这些数据与令牌映射一并加密存储，不会发送到任何地方。如果不希望保留提示词，请勿配置 OCU_AUDITOR_TOKEN——未配置审计员令牌时，揭示端点会返回 403，且无法访问差异视图。
• 失败关闭设计。 如果 refinery 遇到错误或不可用，网关会返回 5xx 错误并停止运行，不会将原始文本作为后备方案转发。

---

配置

变量	必需	默认值	用途
OCU_MASTER_KEY	是（生产环境）	不安全的开发密钥	用于 HKDF 的 32 字节以上 AES 密钥材料
OCU_SALT	是（生产环境）	内置默认值	每个部署使用的 HKDF 盐值
OCU_AUDITOR_TOKEN	是	—	/api/reveal 和 /api/entities 的 Bearer 令牌
OCU_VAULT_PATH	否	vault.db	DuckDB 保险库文件路径
SLM_SIDECAR_URL	否	http://localhost:8085	Tier 2 NER 侧车端点
SLM_ADAPTER	否	privacy-filter	侧车协议：privacy-filter 或 openai-chat

---

从源代码构建

需要启用 CGO 的 Go 1.24+（DuckDB 和 libphonenumber 需要 C 编译器）。

git clone https://github.com/ocultar-dev/ocultar.git
cd ocultar
make build

运行测试：

CGO_ENABLED=1 go test ./...

---

许可证

Apache 2.0——参见 LICENSE。