aezizhu/scrimward

## 问题所在 Scrimward 源于一个简单的认识。在尝试使用 Anthropic 最新的模型 —— **Fable** 和 **Mythos** 时，我们阅读了数据保留条款，这也成为了触发整个项目的契机：在 Claude 的 消费者计划中，你的提示词和编程会话在收到回复后，会在 Anthropic 的服务器上保留 **30 天** （[Anthropic 的消费者条款](https://www.anthropic.com/news/updates-to-our-consumer-terms)）。 对于一个 API key、客户的电子邮件，或者一张内部仪表板的截图来说，在别人的机器上存放三十天 实在是太久了。这是无法接受的 —— 所以我们开发了 `scrimward`。 当你使用 AI 编程代理时，**所有内容都会流向云端**：你输入的提示词、它读取的文件、 它运行的每个命令的输出，以及你粘贴的截图。这就是它的工作方式 —— 而且大多数时候这没问题。但有时，这些数据流中会夹杂着你宁愿不让第三方 看到的内容：API key、客户电子邮件、内部主机名、截图上的名字、日志中的 token。 你不应该在“*使用代理*”和“*保持私密*”之间左右为难。 ## 核心理念 `scrimward` 在你自己的机器上放置了一个微型的**脱敏代理**，位于你的 AI 编程工具和 云端之间。任何信息在通过掩码器之前都不会到达提供商： ``` You ─ prompt / paste / file / image ─▶ your AI coding tool (Claude Code · Codex · Aider · …) │ 's base-URL → 127.0.0.1 ▼ ┌───────────────────────────────┐ │ scrimward proxy │ ← only ever on your machine │ • detect secrets & PII │ │ • mask text → «EMAIL_1» │ │ • refuse images it can't yet │ │ redact (Vision fill: soon) │ │ • FAIL-CLOSED on any doubt │ └───────────────┬─────────────────┘ │ redacted request ▼ provider API (cloud) │ streamed reply ┌───────────────▼─────────────────┐ │ local vault un-masks tokens │ ← real values restored │ «EMAIL_1» → you@example.com │ for your eyes only └───────────────┬─────────────────┘ ▼ Your terminal ``` 最巧妙之处在于**可逆性**：在传输前，机密信息会被替换为一个稳定的 token（`«EMAIL_1»`），然后通过一个**仅限本地的保险库**在流式回复中将其还原 —— 因此模型的回答依然 保持实用且易读，而真实数据从未离开过你的笔记本电脑。 ## 为什么是代理 —— 而不是“仅仅是一个插件”？ 这是该项目最实在的核心。我们根据当前的 Claude Code 文档对其进行了验证 （[`docs/VERIFICATION.md`](docs/VERIFICATION.md)）： - Hook **无法重写你的提示词** —— 它只能*拦截*或*追加*。因此它无法静默地进行掩盖。 - **没有任何 Hook 能看到发往外部的图片。** 粘贴/附加的图片会绕过所有的扩展点。 - **MCP server 从结构上就看不到你的对话** —— 它只能看到它所提供的工具。 因此，`scrimward` 被打包为一个**可安装的组件包**（一个针对特定工具的启动器 + 一个控制平面），它会启动代理，如果路由未激活，则会**失败并阻断**。 ## 功能 - 🔒 **本地优先。** 代理仅在 `127.0.0.1` 上运行。你的真实数据永远不会离开本机。 - 🔁 **可逆。** 输出稳定的 token，通过本地保险库在回复中还原真实数据（可通过模式切换为单向）。 - 🧠 **智能检测器（约 40 种内置检测器）。** 云服务 + SaaS 的 key/token（AWS、GCP、Azure、GitHub，包括细粒度 PAT、GitLab、Stripe、Slack、Twilio、SendGrid、npm/PyPI/HuggingFace、DigitalOcean、Shopify、Linear、Notion 等）、私钥、JWT、OAuth token、数据库/连接字符串 —— 以及 PII（电子邮件、电话、经 Luhn 算法校验的信用卡、mod-97 IBAN、美国 SSN、IP、MAC）。具备抗 Unicode 绕过能力（NFKC + 去除零宽字符）。此外还支持你自定义的规则。 - 🖼️ **图片失败即阻断。** 粘贴的图片（及其他二进制附件 —— PDF、音频）目前尚无法脱敏，因此代理会*拒绝*它们，而不是导致泄露。路线图中包括：设备端 **Apple Vision** 脱敏（OCR -> 检测 -> **纯不透明色块填充**，然后进行二次验证）—— 绝不使用模糊/像素化，因为那仍然是可逆的。 - 🗣️ **指定隐藏内容。** 通过 slash 命令以自然语言添加规则 —— `/redact add …`。 - 🚧 **设计上失败即阻断。** 如果代理未在路径中，该工具将拒绝执行而不是造成泄露。 ## 状态 | 功能 | 状态 | |---|---| | 可行性与威胁模型验证 | ✅ 已完成 — [`docs/VERIFICATION.md`](docs/VERIFICATION.md) | | 架构与规范 | ✅ 已完成 | | 脱敏引擎（文本、可逆保险库） | ✅ 已完成 — 10/10 测试通过 | | 本地代理（流式传输、失败即阻断） | ✅ 已完成 — 10/10 测试通过 | | 适配器：Anthropic、OpenAI-Chat、OpenAI-Responses | ✅ 已完成 | | **Claude Code 插件**（slash 命令 + 失败即阻断的防护 Hook） | ✅ 已完成 | | 启动器：`wrap claude` + `wrap codex` | ✅ 已完成（Codex：API-key 模式） | | 图片 / 二进制附件 —— 失败即阻断的拒绝机制 | ✅ 已完成 | | 图片脱敏（Apple Vision：OCR -> 不透明填充 -> 重新验证） | 🔵 计划中 | | Gemini / Copilot 适配器 + 启动器 | 🔵 计划中 | ### 支持的 studio Scrimward 的形态是面向**提供商**，而不是面向**厂商**的：它可以保护任何你能够将其指向本地代理的工具。 下面这份诚实的矩阵是该项目的信誉核心 —— 完整的各工具设置详情请参见 [`docs/SUPPORTED-TOOLS.md`](docs/SUPPORTED-TOOLS.md)。 | 工具 | 状态 | 方式 | |---|---|---| | **Claude Code** (Anthropic) | ✅ 完全支持 | `ANTHROPIC_BASE_URL` + 项目 `.claude/settings.local.json`；支持订阅（OAuth）模式 | | **Aider** (CLI) | ✅ 完全支持 | 通过 LiteLLM 设置 `OPENAI_API_BASE` + `ANTHROPIC_BASE_URL` —— 本地、自带 key（BYO key）、100% 可拦截 | | **Cline** (VS Code) | ✅ 完全支持 | 将“OpenAI Compatible” / “Anthropic” 提供商的 Base URL 设置为代理（默认的“Cline”账户提供商*不可拦截*） | | **Codex CLI** (OpenAI) | ⚠️ 部分支持 | `OPENAI_BASE_URL` 或 `~/.codex/config.toml`（全局，而非项目级）；API-key 模式纯净，ChatGPT 登录模式需自定义 `model_provider`。支持 Responses API | | **Gemini CLI** (Google) | ⚠️ 部分支持 | `GOOGLE_GEMINI_BASE_URL`（API-key）或 `CODE_ASSIST_ENDPOINT`（默认的“使用 Google 登录”OAuth 会忽略 base-URL 变量）；存在两种请求封装格式 | | **GitHub Copilot** | ⚠️ 部分支持 | CLI 的 `COPILOT_PROVIDER_BASE_URL` / VS Code 自定义端点。自带 key（BYOK）模式纯净；付费订阅路径需要发现 OS-keychain token 并进行 token 交换；IDE 聊天路径最薄弱 | | **Cursor** | ⛔ 无法保护 | 提示词是在 Cursor 的云端组装的，且自带 key（BYOK）的 base-URL 覆盖是在服务端拨号的 —— 本地代理永远无法优先看到内容 | | **Windsurf** (Codeium / Devin Desktop) | ⛔ 无法保护 | 一切都通过 Codeium 的后端路由；没有可供代理驻留的 base-URL hook | 对于 ⛔ 级别，Scrimward **无法**保护你，我们对此直言不讳：该工具在任何提供商调用之前，就会将你的内容发送到其**自身的厂商后端**，因此数据保留点在于工具本身 —— 本地代理对此无能为力。我们绝不佯装不知。 ### 跨工具的工作原理 一个共享的核心，在所有地方重用：一个单一的**本地失败即阻断代理**加上一个可逆的**会话保险库**。针对每个受支持的工具，Scrimward 会添加 (a) 一个轻量级**启动器**，用于将该工具的 base-URL 环境变量/配置指向 `127.0.0.1` 并原封不动地转发其认证标头，以及 (b) 一个针对特定**提供商**的请求体**适配器**，它知道在每种请求/响应结构中文本存在的位置 —— Anthropic Messages、 OpenAI Chat Completions、OpenAI Responses（绝不触碰 reasoning 的 `encrypted_content`）以及 Google Gemini（包括 Cloud Code Assist）—— 从而对外发请求进行脱敏，并对流式回复进行还原。 ## 安装与使用 —— 作为 Claude Code 插件 Scrimward 作为 Claude Code 插件安装，它会**管理代理并失败即阻断** —— 它会阻止工具的使用，直到你的流量真正通过本地脱敏器路由，从而确保你不会发生意外泄露。 ``` # 1. 一次性操作：获取代码 + 其 Python deps（Python 3.12+） git clone https://github.com/aezizhu/scrimward && cd scrimward python3 -m pip install --user fastapi httpx uvicorn click # 2. 在 Claude Code 内部：添加 marketplace + 安装插件 /plugin marketplace add ~/scrimward # path to the clone /plugin install scrimward@scrimward-marketplace # 3. 将其开启，然后重启 Claude Code /scrimward:setup ``` 重启后，你就处于保护之下了。实用命令： | 命令 | 作用 | |---|---| | `/scrimward:setup` | 启动代理 + 路由该项目；随后重启你的工具 | | `/scrimward:status` | 代理是否已启动以及该项目是否已路由？ | | `/scrimward:add ` | 添加你自己的需要始终掩盖的内容（名称、代号、主机） | | `/scrimward:list` | 列出你的自定义规则 | **它是如何保持诚实的：** 一个 `SessionStart` hook 启动代理并报告状态；一个 `PreToolUse` hook **在会话未通过代理路由时拒绝工具使用**（失败即阻断） —— 并会显示明确的消息，提示你运行 `/scrimward:setup` 并重启。内置的检测器（API key、电子邮件、信用卡、 JWT 等）始终处于开启状态；`/scrimward:add` 允许你在此基础上叠加自定义规则。 ## 威胁模型 **防范对象：** 在正常使用受支持的 AI 编程工具（提示词、工具输出、粘贴的图像）期间，意外将机密/PII 传输给模型提供商。 **不防范：** 被入侵的本地机器、模型执行任务所必需的机密（如果你掩盖了它，模型就无法使用它），或非推理的遥测通道 —— 这些通道将由设置单独禁用（`DISABLE_TELEMETRY`、`DISABLE_ERROR_REPORTING` 等）。 这是防止泄露的护栏，而不是防范你机器上蓄意攻击者的绝对保证。 ## 环境要求 - **代理和文本脱敏是跨平台的** —— 无论你的工具在哪里运行，它们都能运行。Cline (VS Code)、Codex、Aider、Gemini CLI、Copilot 和 Claude Code 都是跨平台的。 - 至少有一种你可以将其指向本地代理的**受支持的工具**（参见上面的表格）。 - **图像脱敏（计划中）将需要 macOS（Apple Silicon）**，该功能将使用原生的 Apple Vision 框架在设备端运行。在此之前，图像在任何操作系统上都会触发失败即阻断机制，而其他所有功能在任何地方都能正常工作。 ## 文档 - [`docs/SUPPORTED-TOOLS.md`](docs/SUPPORTED-TOOLS.md) —— 全部八种工具（已引用）的详细设置、状态和注意事项。 - [`docs/integrations/`](docs/integrations/) —— 可直接用于集成的各工具规范（Codex、Gemini、Copilot、Cursor、Windsurf）。 - [`docs/VERIFICATION.md`](docs/VERIFICATION.md) —— 每个受支持工具中实际可行的操作（已引用）。 - [`docs/LEARNINGS-headroom.md`](docs/LEARNINGS-headroom.md) —— 从最接近的现有技术中学到的模式与反模式。 - `docs/ARCHITECTURE.md` —— 组件、数据流和设计决策 *（将随首个代码发布一同推出）*。 ## 贡献 项目仍处于早期阶段 —— 非常欢迎提交 issue 和参与设计讨论。如果你正在研究该代理，请记住一条 至关重要的规则：**永远不要让它失败时放行（fail open）。** 一个会静默泄露的脱敏比没有脱敏器更糟糕。 ## 许可证 [MIT](LICENSE) © Aezi Zhu

标签：AI代码工具, Fail-closed, 数据脱敏, 本地代理, 网络安全, 运行时操纵, 逆向工具, 隐私保护