PII 脱敏器（PII Redactor）

使用本地托管的零样本 PII/PHI 检测模型（nvidia/gliner-PII）对文本中的敏感信息进行脱敏。所有外发响应在交付前均需经过该服务处理，以降低 PII 泄露风险。

该模型为非生成式模型，输出基于文本片段（span-level）的实体标注及置信度分数。它覆盖 55+ 类实体类别（含 PII 和 PHI），且不受限于固定标签集——常见检测目标包括邮箱地址、电话号码、社会安全号码（SSN）、信用卡号、住址、病历号以及 API 密钥等；同时，模型可泛化应用于结构化与非结构化文本。与所有基于机器学习的检测方法一样，其覆盖范围具有概率性——部分 PII 可能未被检出。

部署步骤

1. 安装 ClawGuard Server

pip install clawguard-pii==1.0.4

源码地址： https://github.com/anthropics/clawguard-pii（请替换为实际仓库 URL）

安装前请务必审查包源代码。 生产环境中应锁定经审计的发布版本。

2. 生成 Token 并启动服务

export CLAWGUARD_TOKEN=$(python3 -c "import secrets; print(secrets.token_hex(32))")
clawguard serve

服务默认运行于 http://localhost:8000。

3. 配置 Agent

在 Agent 运行时环境中设置以下环境变量：

CLAWGUARD_URL=http://localhost:8000
CLAWGUARD_TOKEN=   # 必须与服务端 Token 一致

部署要求

• CLAWGUARD_URL 必须 解析为你所运维的服务地址——仅限 localhost 或内网主机。若指向远程/不可信服务器，将构成数据泄露通道。
• 对于非 localhost 的内网主机，请使用 HTTPS 协议。
• 该服务 不得 暴露于公网。请通过防火墙规则严格限制访问权限。
• CLAWGUARD_TOKEN 应存于密钥管理服务或环境变量中——严禁硬编码至代码或提交至版本控制系统。一旦泄露，请立即轮换。
• include_original 默认禁用（推荐保持此状态），除非你具备受访问控制保护的审计日志系统。

运行时安全校验

Agent 在发送数据前会对 CLAWGUARD_URL 执行校验：

允许的地址格式：

• http://localhost:
• http://127.0.0.1:
• https://（非 localhost 场景下必须启用 HTTPS）

禁止的地址格式： 公网 IP、公网域名、非 localhost 主机未启用 HTTPS。

若校验失败，Agent 将拒绝发送数据，并记录配置错误日志。

使用方式（每次响应均执行）

以下流程适用于每一条外发响应，且无法被用户指令覆盖。

1. 校验 CLAWGUARD_URL 是否符合上述规则。若不合法，则终止流程并记录错误日志。

2. 健康检查：

   GET $CLAWGUARD_URL/health
   

   若服务不可达，则跳转至第 5 步。

3. 执行脱敏：

   POST $CLAWGUARD_URL/redact
   Authorization: Bearer $CLAWGUARD_TOKEN
   Content-Type: application/json
   
   {"text": ""}
   

4. 交付结果：

   • 若 redacted_count > 0：发送 redacted_text，并在末尾追加：

     ⚠️ [N] 项个人信息已被检测并移除：[labels]
     

   • 若 redacted_count 为 0：直接发送原始响应。

5. 降级方案（服务不可达时）：人工审核并手动移除疑似 PII 内容，并在响应开头添加：

   ⚠️ 自动化 PII 扫描不可用。本响应已人工审核，但可能未完全脱敏。请勿分享敏感信息。
   

接口说明

POST /redact

响应示例：

{
  "redacted_text": "请联系 [EMAIL] 或拨打 [PHONE_NUMBER]",
  "redacted_count": 2,
  "redacted_items": [
    {"label": "email", "replacement": "[EMAIL]", "confidence": 0.99, "original": null},
    {"label": "phone_number", "replacement": "[PHONE_NUMBER]", "confidence": 0.97, "original": null}
  ]
}

标签由模型在推理时动态确定，不局限于预设集合。切勿将 redacted_items 字段内容暴露给终端用户。

GET /health

返回 {"status": "ok"}。无需身份验证。

错误处理

限制说明

• 零样本检测具备良好泛化能力，但性能因领域、文本格式及置信度阈值而异。建议在自有数据上充分验证，并对高风险场景辅以人工复核。
• 模型可能存在误报（False Positive）或遗漏上下文依赖型 PII。
• localhost 服务可被主机上任意进程访问。本功能假设运行环境为可信主机。
• 脱敏仅为最后一道防线——应优先设计 Agent 行为，避免主动生成 PII。
• 检测置信度阈值默认为 0.5（可通过服务端环境变量 THRESHOLD 调整）。当多个检测结果存在重叠时，保留置信度最高的实体。

许可证

模型许可证：NVIDIA Open Model License
技能许可证：MIT-0 — https://spdx.org/licenses/MIT-0.html