obsify

obsify

让 AI 助手处理敏感文件，同时确保其原始值永远不会进入模型的上下文。

obsify 是一个本地、确定性的 MCP 服务。前沿 模型基于结构进行推理——模式、合成副本、脱敏反馈；而本地确定性代码处理 实质内容，并且只返回经过脱敏的汇总结果。运行时不调用大模型，也不访问网络：检测 采用正则表达式、校验和、字典，以及 Presidio 的 本地 NER。

它支持澳大利亚实体（ABN / ACN / TFN，通过校验和验证），提供凭据/机密检测（云密钥、API 令牌、私钥、数据库连接字符串），以及由标签驱动的路由层，将“助手何时应避开原始数据”变成确定且强制执行的决策，而非主观判断。

如实说明适用范围：run_on_real 会在尽力而为的本地沙箱中执行模型编写的代码，并尽力而为地脱敏其输出。这不是牢不可破的隔离环境。在将其用于任何你无法承受泄露风险的内容之前，请阅读 SECURITY.md。返回汇总结果。

为什么选择 obsify

将机密文档提供给托管式大模型，意味着实质内容会离开你的安全边界。通常的选择是“不要使用大模型”或“信任服务提供商”。obsify 走第三条路——计算移至数据：让代码访问数据，而不是让数据进入模型。

• 模型看到的是电子表格的模式，而非其中的行。
• 模型基于一个合成副本（伪造值、真实结构）进行开发。
• 模型的分析代码在本地运行；返回的只有经过脱敏的汇总输出。

保留前沿模型的推理能力，只移除它查看原始值的途径。

工具

工具	功能	返回内容
scan_pii(path)	扫描文件/文件夹中的个人身份信息	类型、位置、计数——绝不返回值
make_synthetic_twin(path, out)	创建忠实仿真的 Excel 工作簿	模式摘要；仿真副本写入 out（值经过伪造并已验证不会泄露）
run_on_real(code, data_path)	计算移至数据：针对真实文件在本地运行代码（绑定到 DATA_PATH）	仅返回经过个人身份信息脱敏且大小受限的 stdout/stderr——请返回汇总结果
redact_text(text)	将字符串中的个人身份信息替换为 <TYPE> 标记	脱敏后的字符串
verify_value_free(text, terms)	采用默认拒绝策略，检查 text 是否泄露 terms（或其变体）	{"value_free": bool}

**支持的文档：**PDF（文本和表格；复杂表格可通过 obsify[tables] 回退处理）、 Excel .xlsx/.xlsm 和 Word .docx（段落和表格）。无法读取或不受支持的文件 会作为明确的备注/盲点呈现，绝不会被静默丢弃。（暂不支持 OCR——扫描件/图像 页面会标记为覆盖率较低，不会进行转录。）

**已知实体脱敏（可选）。**提供本地 .obsify.entities 名称列表以隐藏这些名称； scan_pii / redact_text 会以确定性方式识别这些名称，以及 NER 会遗漏的后缀/缩写变体 （BRIGHTWATER HLDGS P/L 是 Brightwater Holdings Pty Ltd 的变体），并将其标记为 KNOWN_ENTITY。此 列表会保留在本地，绝不会进入模型的上下文。参见 docs/known_entities.md。

演示

使用官方 MCP Inspector，针对合成数据实时试用全部五种工具：

python -m obsify.make_corpus --out ./corpus_demo
npx @modelcontextprotocol/inspector obsify-mcp

对 ./corpus_demo/ledger.xlsx 调用 scan_pii，确认它只返回类型 / 计数 / 位置，绝不返回值。参见 docs/verifying.md。

试用 — 合成语料库

生成一个虚构但逼真的语料库（全部为合成数据；ABN/ACN/TFN 均通过校验和验证），涵盖 所有三种格式，然后让工具处理它：

pip install "obsify[demo]"                 # reportlab, for the sample PDFs
python -m obsify.make_corpus --out ./corpus_demo

它会生成一个包含多个工作表的 Excel 台账（数字误报的重灾区）、一份 PDF 委托函（正文 + 试算平衡表），以及一份 DOCX 审计备忘录（段落 + 供应商表格）。非常适合用来试用 scan_pii / make_synthetic_twin，而无需接触真实数据。

安装并作为 MCP 服务运行

需要 Python 3.11+。obsify 通过 stdio 使用 MCP——客户端会将其作为本地子进程启动，不会托管在远程。只需在任何支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor、VS Code、……）的配置中添加一个代码块即可完成注册。

推荐 — 通过 uvx 零安装使用：

{ "mcpServers": { "obsify": { "command": "uvx", "args": ["--from", "obsify", "obsify-mcp"] } } }

uvx 会从 PyPI 获取 obsify，并按需运行——无需永久安装。首次运行时，obsify 会下载 spaCy NER 模型（en_core_web_lg，约 560 MB）并缓存；此过程会获取公开模型，不会发送用户数据（设置 OBSIFY_AUTO_DOWNLOAD=0 可禁止自动下载，之后需自行安装模型）。后续运行会立即启动，且完全离线。

或者安装它（pip / pipx）：

pipx install obsify        # isolated, on PATH  (or: pip install obsify)

然后将客户端指向已安装的命令：

{ "mcpServers": { "obsify": { "command": "obsify-mcp" } } }

重启客户端后，工具就会显示出来。可选扩展：obsify[tables]（通过 camelot + Ghostscript 为复杂表格 PDF 提供备用处理方案）、obsify[compute]（pandas，方便在 run_on_real 代码中使用）。

PATH 注意事项（“服务无法连接”的头号原因）： command 必须能在客户端所看到的 PATH 中解析。图形界面客户端可能无法使用你虚拟环境的 PATH。解决方法：使用 uvx/pipx （可全局解析），或提供绝对路径——"/path/to/.venv/bin/obsify-mcp"（macOS/Linux） 或 "C:\\path\\to\\.venv\\Scripts\\obsify-mcp.exe"（Windows）。

从此仓库运行（尚未发布到 PyPI 时）：

pip install "git+https://github.com/Formative-Sum41/obsify.git"   # gets `obsify-mcp` + `obsify`

路由层 — 确定性决策，而非主观判断

“帮帮我，但别读取机密文件”这件事的难点在于决定何时保护。 obsify 将这个决定从模型中移出，交由环境处理：

1. .obsify.json — 用于对路径分类（public / confidential / restricted）的标签清单。
2. obsify.guard（以 python -m obsify.guard 运行）— 一个 PreToolUse 防护机制，会阻止直接读取已标记的文件 （退出码为 2），并引导助手改用 scan_pii / make_synthetic_twin / run_on_real。
3. 一项约定（写在 CLAUDE.md 中），让助手在触发防护机制之前优先使用 obsify。

使用一条命令完成设置：

obsify init [--dir PATH] [--with-claude-md]

obsify init 的设计理念是非破坏性——它只负责一个文件，并为其余文件提供可粘贴的片段：

• .obsify.json — 由 obsify 管理；init 会写入此文件（除非使用 --force，否则绝不覆盖）。
• .claude/settings.json — 由你管理：init 会打印 PreToolUse 钩子代码块供你粘贴， 但绝不会修改此文件（它会运行代码，因此是否注册由你决定）。
• CLAUDE.md — 由你管理：此约定为可选启用。默认只打印；--with-claude-md 会追加一个带标记、可幂等执行的代码块，绝不会覆盖你的内容。

完整约定：docs/obsify_routing.md。

检测如何保持精准

• 经校验和验证的标识符。 ABN/ACN/TFN 候选项由正则表达式提取，并通过其官方校验和确认，因此不会把随机数字报告为标识符。
• 需要上下文的 ID。 只有附近出现标签词（“TFN”“ABN”“BSB”等）时，才会将单独的数字识别为 ABN/ACN/TFN——这能消除数字分类账中顺序日志 ID 造成的大量误报。
• 抑制无字母内容／带数字的 NER。 纯数字、金额、日期和字母数字代码不会被标记为姓名／组织；真实姓名、电子邮件和地址（都含有字母）不受影响。通过验证的无字母 PII 仍可豁免：校验和 ID（ABN/ACN/TFN/Medicare）、Luhn 卡号、有效 IP、BSB 附近的账号，以及电话号码（依据上下文或电话号码格式）——而小数点仍表示金额，而非电话号码。
• 凭据，而不只是 PII。 云密钥（AWS/GitHub/Google/Slack/Stripe）、JWT、私钥块和数据库连接字符串会由锚定模式标记为 CREDENTIAL——依据供应商前缀（AKIA…、ghp_…）或由关键词限定的 secret = <value>，绝不使用熵启发式规则（这种规则会在十六进制／base64 分类账列中造成大量误报）。整个 BEGIN…END 私钥块都会被屏蔽，而不仅仅是头部，因此不会遗留密钥内容。

实测准确率

obsify 提供带评分的评估工具集（eval/ — 已标注的合成语料库 + 答案键 + 针对发布版检测器的评分器，另有独立第三方交叉检查）。合成语料库的主要结果：预期检测项目的召回率为 100%，数字误报压力测试表中误报为 0（含分组数字防护），并能正确抑制缺少上下文的 ID。与 Microsoft presidio-research 的独立交叉检查结果：EMAIL/IBAN 为 100%，PERSON 为 94%。

该工具集发挥了作用——它发现了实际缺陷，随后这些缺陷都得到了修复： 信用卡和电话号码曾被数字噪声过滤器静默抑制（现已通过校验和验证／电话号码格式豁免），而 Medicare、IP、出生日期、澳大利亚护照和驾照则没有识别器（现已添加，并由校验和或上下文限定）。完整方法、数据和其余已记录的缺口（SWIFT/BIC、非出生日期）：eval/README.md。

测试

pip install -e ".[dev]"
pytest tests/            # or run any file directly: python tests/test_obsify.py

13 个测试套件（88 项测试），在 CI 中通过 Linux + Windows / Python 3.11 + 3.12 运行：

• mcp-protocol — 通过 stdio 启动真实服务并与其进行 MCP 通信（与 Claude 等客户端使用的路径相同）：确认所有五个工具均以有效架构注册，且调用可通过 JSON-RPC 完成往返——包括 scan_pii 端到端仅返回结构信息。
• checksums — 使用外部发布的 ABN/ACN/TFN 示例（有效和损坏的示例）进行锚定验证，以打破生成器与验证器之间的循环依赖。
• obsify / twin / redaction — 隐私不变量：仅输出结构信息、不泄露的孪生数据，以及失败时默认拒绝的自检。
• precision — 误报抑制器可消除数字分类账噪声，同时保留真实姓名。
• credentials — 锚定的机密模式可捕获云密钥／令牌／JWT／私钥块／连接字符串，同时由关键词锚定的通用模式在普通文本中保持精准（不使用熵）。
• routing — 防护机制的阻止／允许分类，以及 obsify init 的非破坏性约定。
• corpus — 端到端测试合成 PDF+Excel+DOCX 语料库：按格式检测、DOCX 段落和表格提取，以及所有格式均仅输出结构信息。
• evaluation — 将带评分的工具集作为回归门槛（召回率、抑制效果、误报压力测试、缺口）。
• robustness — 优雅降级：损坏／超大／空／嵌套／不支持的输入均不会导致崩溃，并始终会以备注形式呈现。
• model / variants — 首次运行时模型自动下载逻辑；verify_value_free 后的变体规范化。

交互式验证（MCP Inspector）和实时客户端的最终检查，请参阅 docs/verifying.md。

相关项目

obsify 是多个致力于“让 AI 安全地处理敏感数据”的 MCP 服务之一——它们大多互为补充，从不同角度解决同一个问题。了解各自适用的场景很有帮助：

工具	方案	最适合
obsify	检测 + 形状隔离：模型只能看到形状、合成孪生数据和脱敏聚合结果——绝不会看到值（无论真实还是伪造）	混乱、非结构化的文档（PDF/Excel/DOCX），无法预先枚举 PII；严格隔离值；强制规定何时进行保护
cloakbox	策略驱动的预净化：将数据库标记化为经过去标识化的副本，供模型自由查询	已知的结构化架构，且希望在保留引用关系的干净副本上进行丰富分析（联接/聚合）
redact-mcp	可逆混淆代理：模型处理一致的伪造数据；代理工具往返转发真实 API 调用	渗透测试工作流和机密信息，模型必须处理逼真的数据，并在之后还原真实数据
cms-ai	企业级脱敏服务：通过 REST/MCP 提供 Presidio + spaCy，支持多语言，可扩展	提供 UI 并支持横向扩展的托管式多语言脱敏 API

obsify 的独特之处：在这些项目中，只有它不会向模型提供原始值，也不会提供可供模型操作的完整镜像——只提供形状 + 脱敏聚合结果——同时还具备经过校验和验证的标识符、凭据检测、确定性的路由防护，以及严格禁止联网 / 调用大模型的保证。它位于隔离程度最高的一端，专为机密金融文档打造。

**坦诚说明取舍：**obsify 优先考虑值的隔离，而非数据的实用性。如果你需要在干净副本上进行保留引用关系的分析（cloakbox）、可逆地往返还原数据（redact-mcp），或使用托管式多语言服务（cms-ai），这些项目会更合适——它们也很适合与 obsify 搭配使用，而非与之竞争。

贡献

欢迎提交 PR——设置说明、合并标准和不可妥协的约束（库中不调用大模型、运行时不联网、不使用真实数据、只处理形状而非实质内容）请参阅 CONTRIBUTING.md。安全问题请参阅 SECURITY.md（请私下报告）。

许可证

MIT — 请参阅 LICENSE。