project-guardian

# 项目守护者 — 面向自主代理的AI守护防火墙 <p align="center"> <img src="scripts/demo/assets/guardian-demo.gif" alt="Guardian mediating an agent's actions: a deterministic traffic light (allow / ask / deny) and a data vault that tokenizes your data so the agent never sees it." width="820"> </p> > **状态：** 正在开发的产品，**v0.1.0 版本已发布**。Rust 工作空间，196 个测试通过。 > 已实现 **第四阶段（强化）**：确定性策略引擎、篡改证据审计日志（可选 **密封密钥签名**）、 advisory Checker、 > MCP 网关 + 标准输入输出传输、守护进程 + 控制套接字、终端审批驾驶舱（TUI）、AgentDojo 评估框架、 > **网络代理与 TLS 拦截**（代理注入凭证、数据泄露检查、默认拒绝出口、驾驶舱 `ask` 路由）、 > **OS 执行沙箱**、**令牌代理**（操作系统密钥链 + 最小权限限制）、**轻量级可验证凭证**、 > **自适应建议 + 安全报告**、**ed25519 签名社区策略包**，以及 **内在关键类别底线**（金钱 / 凭证 / > 数据泄露 / 不可逆转删除永远不能解析为静默 `allow`，即使通过签名包）。快速入门：[`docs/user-guide.md`](docs/user-guide.md)。 > 剩余 1.0 版本：签名/ notarized **打包** 和桌面 GUI — 见 [`ROADMAP.md`](ROADMAP.md)。 > > **评估：** 在 AgentDojo 上使用本地 12B 代理，Guardian 将银行套件的提示注入攻击成功率从 **100% → 0%**（确定性拒绝金钱转移）。 > 我们自己的 **[GuardianBench](evaluation/guardianbench/)** — 为行动防火墙构建的基准 — > 评分为 **0% 误报，0% 误拒，100% 拒绝正确率**，涵盖 8 个领域，以及 **0% PII 数据泄露** > 在其令牌化层（数据代理，ADR-0005）。查看 [`evaluation/`](evaluation/) 以获取完整的、 > 诚实带有缺陷的评分卡（包括行动防火墙范围以下的内容）。 > > **📄 白皮书：** [设计与威胁模型（PDF）](docs/whitepaper.pdf) — 或在 [GitHub 上阅读](docs/whitepaper.md)（附带它工作原理的图表及其对代理的影响）。 > > **许可证：** [Apache-2.0](LICENSE) · **治理：** [CONTRIBUTING](CONTRIBUTING.md) · > [SECURITY](SECURITY.md) · [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) · [ADRs](docs/adr/) > > 本 README 是规范性文档（理念、完整功能集、架构、威胁模型）。关于 **如何** 和 **按什么顺序** 构建，请参见 `ROADMAP.md`；关于已完成的内容，请参见 `docs/changelog.md`。 --- > ## ⚠️ 免责声明 — 自担风险 > > Guardian 是 **早期软件（v0.1.0）**，可以配置为处理 **敏感数据**（凭证、个人数据、财务详情）。 > 它以 **“原样提供，不做任何保证”** 的方式提供，按照 [Apache-2.0](LICENSE) 许可证（参见第 7-8 节）。 > 在法律允许的最大范围内，**作者不承担任何责任**，不论因使用、滥用或无法使用该软件而导致的任何损害、数据损失、安全漏洞、经济损失或其他损害。 > **您自行负责评估其适用性**，评估您配置的策略以及路由通过它的任何数据的安全性。 > 它 **未经认证、审计或生产强化**，不能作为高风险或受监管工作负载的唯一保障措施。 > 有关威胁模型和如何报告漏洞，请参见 [SECURITY.md](SECURITY.md)。 --- ## 1. 什么是 Guardian（一段话） **Guardian** 是一个本地用户空间“防火墙”，位于自主 AI 代理与其可以接触到的事物之间 — 您的文件、您的 shell、网络和您委托给它的在线服务。它 **不信任代理**。代理尝试的每个操作都会作为 **结构化操作** 在代理的工具/MCP 边界处拦截，由 **确定性策略引擎** 评估，并且当需要人类决策时，由单独的“翻译”模型以纯语言解释，然后您批准或拒绝。Guardian 是 **与代理无关的**（它不关心代理是由 Claude、GPT、Llama 还是其他模型驱动的），并且 **与操作系统友好**（它从不安装内核模块或与操作系统争夺控制权）。 ## 快速入门 **最快 — 下载预构建的二进制文件**（无需工具链）从 [最新版本](https://github.com/Vadale/project-guardian/releases/latest)。 它未签名，因此操作系统会提示一次：macOS → 右键 → *打开*；Windows → SmartScreen → *更多信息 → 运行*；Linux → `chmod +x guardian`。然后 `guardian --help`。 （Windows 为实验性/未经测试 — 参见 [`docs/user-guide.md`](docs/user-guide.md)。） **用一条命令设置。** `guardian init` 创建 `~/.guardian/{config.toml,policy.toml}` 以适应您的角色，并打印确切的下一步骤 + MCP 代码段以粘贴： ```sh guardian init # 或：--role personal-assistant guardian-daemon # 终端 1 — 服务 guardian ui # 终端 2 — 审批驾驶舱（TUI） ``` 然后将您的代理的 MCP 客户端指向 Guardian（`guardian init` 打印的代码段适用于任何 MCP 客户端）： ```json { "mcpServers": { "guardian": { "command": "guardian", "args": ["mcp", "--daemon", "/tmp/guardian.sock"] } } } ``` 当操作需要您的批准时，守护进程会 **显示桌面通知**，这样您不必一直监视驾驶舱（在配置中设置 `notifications = false` 以禁用）。 **或从源代码构建** — 需要 [Rust 工具链](https://rustup.rs)： ```sh cargo build --release # 1) 查看流量灯光仲裁端到端（脚本化，无需设置） cargo run -p guardian-cli -- demo # 2) 内部红队记分卡（确定性，无需模型） cargo run -p guardian-cli -- eval # ... 以及 GuardianBench，我们的行动防火墙基准（FN 0% / FP 0% / 拒绝 100%）： GUARDIAN_BIN=target/release/guardian python3 evaluation/guardianbench/guardianbench.py # 3) 真实代理的完整循环 — 三个终端： GUARDIAN_SOCK=/tmp/g.sock cargo run -p guardian-daemon # 服务 GUARDIAN_SOCK=/tmp/g.sock cargo run -p guardian-cli -- ui # 审批驾驶舱（TUI） # 然后将 MCP 客户端（例如 Claude Code）指向： # guardian mcp --daemon /tmp/g.sock ``` 使用 `cargo test --workspace` 运行测试。衡量 Guardian 对代理攻击成功率的影响：[`evaluation/`](evaluation/)。 --- ## 2. 问题 代理从“对话式聊天机器人”发展到“行动式代理” — 它们读写文件、运行 shell 命令、浏览、购物、发送电子邮件，并越来越多地接触敏感帐户（银行、健康记录、公共管理门户）。 这带来了四个具体风险： 1. **敏感数据暴露和破坏性错误。** 直接授予代理访问帐户、电子邮件和私人文档等权限，会让用户面临隐私侵犯、幻觉破坏性操作和外部攻击的风险。 2. **提示注入。** 本时代主要的代理安全威胁：代理 **读取** 的内容（网页、PDF、电子邮件、工具结果）可能包含指令，以劫持代理执行用户从未要求的操作。 3. **点击疲劳/知情同意失败。** 系统级代理会弹出脚本和 API 调用等的审批请求。非技术用户不理解这些请求并盲目批准，从而使安全性失效。 4. **没有人机控制界面和可追溯性。** 现有工具（原始权限提示、Docker）是为程序员构建的。没有直观的“控制室”，也没有一种简单的方法来保留代理实际执行的操作的可篡改记录（与 EU AI 法案第 50 条等透明度义务相关）。 --- ## 3. 设计原则（不可妥协） 这些规则决定了后续的每一个取舍。 1. **安全边界是确定的。LLM 永远不是边界。** 强制执行（允许/询问/拒绝）由一个规则引擎完成，其行为是可预测和可测试的。LLM 仅用于 **翻译和风险评分**，永远不会用于解锁。 2. **拦截结构化操作，而不是代理的原始语言。** 策略引擎和翻译器查看 *实际* 拦截的操作（工具调用及其参数、实际 HTTP 请求、文件操作）— 而不是代理对自己意图的自然语言声明。声明是可操纵的；操作不是。 3. **从构建开始就与代理无关。** 控制在操作边界应用，该边界对于任何模型都是相同的。 4. **用户空间，而不是内核空间。** 没有内核模块，没有需要供应商授予权限的操作系统钩子。（参见第 4 节 — 这是关键决策。） 5. **本地优先/隐私优先。** 策略评估、学习和审计日志位于用户机器上。发送任何内容到云端都是可选的和明确的。 6. **纵深防御。** 工具边界的仲裁是主要控制；操作系统沙箱和网络代理是遏制备份，而不是计划 A。 7. **在关键路径上失败关闭，在便利路径上失败打开。** 货币/凭证/数据泄露路径上的故障会阻塞；低风险路径上的故障会优雅地降级（日志记录，延迟到现有工具默认值）。 8. **默认情况下具有篡改证据。** Guardian 做的所有决定都写入一个追加的、哈希链接的、可签名的审计日志。 --- ## 4. 关键决策：Guardian 在哪里执行 **已解决：Guardian 在代理的操作边界 — 套件/工具调用/MCP 层 — 用户空间中执行。** 它 **不** 在操作系统内核中执行。 ### 为什么不是操作系统内核/操作系统钩子 - 深入的操作系统拦截（Linux LSM/eBPF 超越用户空间，macOS Endpoint Security & Network Extension，Windows minifilter/WFP 内核回调）需要 **供应商授予的权限、代码签名、 notarization 和每个平台的认证**。在 macOS 和 Windows 上，这是一个开源项目和独立维护者的壁垒。 - 内核级错误会使用户的机器崩溃。错误的爆炸半径是整个操作系统。 - 这是错误的高度：在 syscall 级别，您会看到 `write(fd, buf, n)`，而不是 *"代理将 4000 欧元电汇到未知 IBAN"。* 意图在操作边界上是可读的，而不是在内核。 ### 为什么操作/动作边界是正确的阻断点 现代代理套件（Claude Code、Cursor、OpenAI Agents 运行时和任何 MCP 客户端）已经通过 **工具调用接口** 协调代理做的 **所有事情**。代理无法接触世界，除非通过套件公开的工具。 **套件已经是阻断点** — Guardian 的任务是 *成为*、*包装* 或 *插入* 到该仲裁层，而不是与操作系统争夺第二个冗余的阻断点。 这让我们免费获得了： - **结构化操作**（工具名称 + 类型参数）而不是猜测的意图。 - **与代理无关** — 工具边界在任何模型下看起来都相同。 - **无需权限，无需内核，无需 notarization 头痛。** - **跨平台对齐** — 相同的逻辑在 macOS、Windows、Linux 上运行。 ### 诚实的警告（以及我们如何处理它） 套件级拦截仅与其自身的仲裁一样完整。 困难的情况是原始 `Bash`/exec 工具：一旦 `bash` 运行，其子行为（子进程、解释器、原始系统调用、`base64 -d | sh`） **不是** 个别仲裁的。我们通过分层答案处理这个问题： 1. **优先使用结构化工具而不是原始 shell。** 在套件允许的情况下，公开中间仲裁、类型化工具（read_file、write_file、http_request、send_email）而不是原始 shell。结构化工具是完全可仲裁的。 2. **将危险工具包含在沙箱中。** 当原始 `exec`/shell/network *必须* 存在时，在 **现有的 OS 沙箱**（容器、`sandbox-exec`/Seatbelt 配置文件、bubblewrap、Windows AppContainer/Sandbox） 和 **网络代理**（下面）中运行该工具的执行。这是使用现有的用户空间工具进行深度防御 — 而不是自定义内核工作。 3. **无论如何都仲裁网络。** 用户空间 **转发代理** 安装了本地 CA（mitmproxy 样式），捕获 *所有* HTTP(S)，无论它如何创建，都可以在其中进行网络策略、头部信号和内容水印。 因此，分层模型是：**在工具边界进行仲裁（计划 A）→ 将高风险工具包含在沙箱中 + 将所有流量路由到代理（备用）**。 --- ## 5. 架构 ``` ┌──────────────────────────────────────────────────────────┐ │ 代理（任意模型：Claude / GPT / Llama / 本地 / …） │ └──────────────────────────────────────────────────────────┘ │ 结构化操作（工具调用 / MCP / HTTP） ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ Guardian 核心 │ │ │ │ ┌────────────────────┐ ┌──────────────────────┐ ┌────────────────┐ │ │ │ 1. 策略引擎 │ │ 2. 检查器（LLM） │ │ 3. 审计日志 │ │ │ │ 确定性 │──▶│ 翻译器 + 风险评分 — │ │ 追加的、 │ │ │ │ 允许 / 询问 / 拒绝 │ │ 仅限建议 │ │ 哈希链接的、 │ │ │ │ （边界） │ │ │ │ 可签名的 │ │ │ └────────────────────┘ └──────────────────────┘ └────────────────┘ │ │ │ "询问" │ │ ▼ │ │ ┌────────────────────┐ ┌──────────────────────┐ ┌────────────────┐ │ │ │ 4. 审批 UI │ │ 5. 身份和令牌 │ │ 6. 自适应 │ │ │ │ 交通灯 │ │ 代理：范围 OAuth、 │ │ 学习（约束、 │ │ │ │ 仪表板 + 报告 │ │ macaroons、密钥链/ │ │ 本地仅限） │ │ │ │ │ │ 安全 Enclave/TPM │ │ │ │ │ └────────────────────┘ └──────────────────────┘ └────────────────┘ │ └───────────────────────────────────────────────────────────────────────┘ │ 文件系统 │ 网络 │ 凭证 ▼ 结构化 FS 工具 ▼ 前向代理（MITM CA） ▼ 代理注入凭证 + 可选沙箱 + 头部/水印 代理永远 原始执行 + 注入 看不到原始秘密 ``` ### 5.1 拦截适配器（Guardian 如何插入套件） 优先级从高到低： - **（a）MCP 网关 / 代理** — **主要，最通用。** Guardian 作为 MCP 服务器聚合并重新公开用户的真实 MCP 服务器和工具。 套件指向 Guardian；每个 `tools/call` 都通过策略引擎转发。适用于任何 MCP 客户端。 - **（b）原生钩子适配器** — 具有钩子系统的套件（例如 Claude Code 的 `PreToolUse`/`PostToolUse`）。Guardian 注册为钩子处理程序并返回允许/询问/拒绝每个调用。 在可用时提供真正的确定性拒绝。 - **（c）HTTP(S) 前向代理** — 用户空间的 CONNECT 代理，带有本地安装的 CA。拦截 *所有* 出站流量进行网络策略、代理信号和内容水印。这是“系统化”部分，它仍然是纯用户空间（代理 + 受信任的证书）。 - **（d）LLM 网关代理** — **可选。** 代理模型 API 本身以捕获原始请求/响应、从工具结果中抽取注入的指令，并将所有权附加到它们上。有用但不适用于MVP。 ### 5. 2 策略引擎（实际边界） - 声明式规则的确定性评估 → 恰好一个 `允许` / `询问` / `拒绝` 每项操作。 - 结构化字段上的条件（工具名称、参数、目标主机、文件路径、金额、时间、源）使用沙箱、无副作用的表达式求值器（候选：**CEL** 或 **OPA/Rego** 风格的求值器 — 选择可判定和可测试，而不是图灵完备的脚本）。 - **无网络、无LLM、无I/O评估。** 纯粹的（操作、上下文、策略）函数。这是它可审计的原因。 ### 5.3 检查器（翻译器 + 风险评分器）— 仅限建议 - 两个任务：（1）**翻译** 待处理操作为带有真实影响的普通语言（`chmod 777 ./data` → *"允许任何人读取和修改这些文件"*）；（2）发出 **风险评分/理由** 以帮助排序审批队列。 - **它永远不会决定允许/拒绝。** 即使一个完全被破坏的检查器也不能解锁被策略引擎拒绝的操作。 - 它读取 **结构化的截获操作**，而不是代理的原始语言。 - 模型是 **可插拔的**：默认情况下是一个小型本地守护进程（隐私），具有 **可选** 升级到更强大的模型以处理模糊情况。这解决了文档中旧有的“本地学习，无需云端”和“高性能检查器”的矛盾。 ### 5.4 审批 UI / 仪表板 - 跨平台桌面应用程序（候选：**Tauri** — 轻量级、Rust 友好 —优于 Electron）。 - **交通灯** 界面：一个 `询问` 项目队列，带有检查器的普通语言翻译和一键允许/拒绝；一个实时活动视图；一个 **报告** （“安全服务报告”），总结了静默允许的操作、阻止的威胁和规则建议，以批量确认 — 解决点击疲劳的问题。 ### 5.5 审计日志（防篡改） - 只允许追加日志，**哈希链式**（每个条目都提交给前一个条目），可选地使用操作系统密钥链 / 安全围栏 / 可信平台模块中持有的每个安装密钥签名。 - 日志记录：操作、决定、匹配规则、检查者理由、用户响应、时间。 - 这使得“可追溯性”成为现实，而不仅仅是营销口号。 ### 5.6 身份与令牌代理 - 代理**从不直接看到凭证**。它请求代理执行身份验证操作；代理在代理层注入凭证。 - 机制（取代旧的“零知识证明”想法，后者是错误的原语）： - **范围限定 OAuth 2.1 令牌**（如果服务支持它们）。 - **马卡龙（Macaroons）** - 带有减弱**限制**（到期时间、最大金额、允许的端点、源绑定）的 bearer 令牌 - 专为委托的、可以缩小的权限而设计。 - **硬件支持的密钥**（安全围栏 / 可信平台模块）用于签名和秘密存储。 - **W3C 可验证凭证 / 去中心化身份标识**用于去中心化的身份声明。 - **PSD2 / 开放银行 API**作为欧盟银行的正确通道（不是通过模拟头部来抓取银行的屏幕）。 - 设计注意：由于代理持有凭证，**Guardian 本身成为最高价值的目标**。其自身的强化（签名策略、密封密钥、 notarized 构建）是一等要求，而不是事后才考虑。 ### 5.7 自适应学习（故意约束） - 可能会**建议**将重复批准的低风险操作降级为“在此上下文中自动允许”，并可能将异常上下文中看到的操作升级为“询问”。 - **硬性规则：绝不自动降级关键类别** - 资金转移、凭证访问、数据泄露、不可逆删除。这些操作始终需要显式的人类操作。建议会随着时间的推移而失效，并且与学习时的上下文绑定。 - 100% 本地化。没有行为数据离开机器。 ### 5.8 自我保护（代理无法禁用其守护程序） Guardian 只有在被监督的代理无法逃避或关闭它时才有效： - Guardian 是代理的**唯一**工具路径。如果守护程序无法访问，则没有决定，因此也就没有操作 - **关闭失败，而不是打开**。 - 代理进程在**无权限**的情况下运行，无法杀死 Guardian 守护程序、删除/更改代理 CA 或编辑活动策略（单独的权限 + 密封策略）。绕过尝试会被记录为防篡改日志中的空白。 - 监督重启：如果守护程序死亡，集成将拒绝转发工具调用，直到 Guardian 恢复。 ### 5.9 终止开关（惊慌按钮） 一个一次性、始终可用的控制，**立即撤销所有代理权限**：暂停所有适配器，拒绝所有待处理和新的操作，并冻结代理凭证。该功能可从 UI 和 CLI 访问（`guardian panic`），即使 Checker/UI 无响应也设计为可用。 ### 5.10 配置和首次运行 - 单个声明性配置（TOML）选择活动的角色/策略包、Checker 后端和启用的适配器。在加载时验证；无效配置将失败并关闭。 - **安全默认值**：首次运行启动时使用最严格的角色（所有未知操作 → `询问`），出口允许列表为空，学习关闭。用户会故意放宽权限，而不是逆向操作。 ### 5.11 数据、存储、保留和隐私 - 所有状态（审计日志、学习建议、配置）都存储在**本地**操作系统用户数据目录下；秘密存储在操作系统密钥链中，绝不会以纯文本形式存储在磁盘上。 - 审计日志是只允许追加的，并且是哈希链式的；保留时间是用户可配置的，导出是显式的。除非用户选择加入远程 Checker 升级（唯一的网络路径），否则不会传输任何内容，该路径是按操作记录的。 ### 5.12 本地化 Checker 的纯语言解释和所有 UI 文本都是**可本地化**的（面向非技术用户的受众范围是全球的）。决定和日志保持稳定的机器可读格式；只有面向人类的呈现才会被翻译。 --- ## 6. 核心功能（修正后的功能集） | # | 功能 | 功能描述 | 与原始想法相比的修正 | |---|---------|--------------|----------------------------------| | A | **制造者/检查者** | 制造者 = 执行任务的第三方代理；检查者 = 本地模型，将待处理操作翻译成普通语言 + 风险评分。 | 检查者**仅为 advisory**，读取结构化操作，**不读取**代理的原始文本。拒绝决定是由确定性引擎做出的。 | | B | **交通灯权限** | 绿色 = 无声允许；黄色 = 暂停 + 翻译后的批准弹出窗口；红色 = 自动阻止 + 通知。角色（例如“Web Dev”，“税务助理”）预加载规则集。 | 强制执行是确定性的**策略引擎**（基于能力/属性），角色作为预设。交通灯是顶层的 UI。 | | C | **自适应安全** | 本地学习如何降低安全的重复操作，并升级异常操作。 | **绝不**自动降低关键类别；上下文绑定；衰减；仅本地。 | | D | **报告** | 将低风险的自动批准操作批量处理成定期报告；用户确认建议的规则。 | 不变 - 这是良好的设计，直接解决了点击疲劳的问题。 | | E | **出处 / 水印** | AI 生成的电子邮件/评论/表单的选定内容页脚；可选的代理信号 HTTP 头；所有内容都记录下来。 | HTTP 头是一个**礼貌信号，仅用于通知 - 不是安全**（可轻易伪造，可能触发反机器人阻止）。内容标记有助于用户的 AI 法规透明度义务，但**不**使任何人“合规”。视为选择加入，默认关闭头部。 | | F | **身份和令牌** | 代理持有凭证；代理获得范围限定、时间/金额限制的权限。 | **能力令牌 / 马卡龙 / 范围限定 OAuth / 硬件密钥 / 验证凭证** - 而不是零知识证明（对于委托来说，这是一个错误的原语）。 | --- ## 7. 威胁模型 | 攻击者 | 向量 | 主要防御 | |-----------|--------|-----------------| | **幻觉 / 错位代理** | 出于善意但执行破坏性或错误操作 | 确定性策略引擎；`询问`所有不可逆操作；检查者翻译，以便人类捕获 | | **提示注入（#1 威胁）** | 隐藏在网页、PDF、电子邮件或工具结果中的恶意指令会操纵代理 | 策略评估**实际**操作，而不管代理为何想要执行；关键类别始终`询问`/拒绝；可选的 LLM 网关工具结果净化；检查者从不读取攻击者控制的原始文本作为权威 | | **受损 / 恶意的 MCP 服务器或工具** | 工具对操作结果撒谎或窃取数据 | 守护程序看到实际的调用/参数和实际的网络出口（代理）；出口允许列表 | | **通过代理**输出**的敏感数据泄露** | 注入使得代理将其响应/推理中的帐号、操作记录或秘密放入 | 数据要到达攻击者必须经过一个**通道**（消息 / 网络 / 文件）- 这是一个**操作**，守护程序会控制；**令牌代理**（§5.6）将凭证和完整秘密**完全排除**在代理之外（仅注入到授权出口，因此代理无法透露它从未持有的内容）；代理合法处理的残留数据受限于最小权限 + 计划的**输出保护**（检查者侧的 DLP 删减）。操作防火墙**不**设计为检查代理的原始文本 | | **恶意策略包**（供应链） | 社区包允许数据泄露路径 | 签名包、强制审查、声誉、一个“包不能在未经用户明确选择的情况下扩大关键类别权限”的规则，**以及一个内在的运行时底线** - 关键类别操作永远不能仅凭规则或包的解析为无声`允许` | | **攻击守护程序本身**（它持有密钥） | 篡改策略、窃取代理凭证、伪造日志 | 密封密钥（安全围栏/TPM）、签名/锁定策略、哈希链日志、notarized 构建、失败关闭 | | **代理禁用/绕过其守护程序** | 杀死守护程序、删除代理 CA 或路由绕过网关以逃避监管 | 守护程序是代理的**唯一**工具路径（无决策 → 无操作 = **失败关闭**）；代理无权限停止守护程序或更改 CA/策略；监督重启；日志中标记空白。见§5.8 | | **习惯攻击** | 训练自适应层自动允许，然后发动攻击 | 绝不自动降级关键类别；衰减 + 上下文绑定 | | **恶意用户** | 尝试使用代理 + 守护程序进行有害/滥用操作 | 超出“保护用户”的范围，但守护程序的出处/日志记录使滥用可追溯 | > 完整的威胁模型 - 资产、信任边界、攻击树、剩余风险和 OWASP/NIST 映射 - 见 [`docs/threat-model.md`](docs/threat-model.md)。 --- ## 8. 策略模式（具体草图） 声明式、可审查、版本控制。仅为示例 - 最终模式待定。 ```yaml # role: "personal-assistant" version: 1 defaults: decision: ask # 未知操作默认询问 rules: - id: read-project-files when: tool == "read_file" && path.startsWith("~/DOCUDESK/") decision: allow # 绿色：无声 - id: shell-anything when: tool == "exec" decision: ask # 黄色：暂停 + 翻译 sandbox: true # 不管是否批准，都运行在容器中 - id: chmod-world-writable when: tool == "exec" && args.cmd matches "chmod\\s+(777|o\\+w)" decision: ask explain: "使文件对该机器上的任何用户可修改。" - id: outbound-known-hosts when: tool == "http_request" && host in trusted_hosts decision: allow - id: money-movement when: capability == "payment" decision: ask critical: true # 可能**绝不**被学习自动降级 cap: { amount_max: 200, currency: "EUR" } - id: bulk-delete when: tool == "delete" && args.count > 10 decision: ask critical: true - id: data-exfiltration when: tool == "http_request" && method == "POST" && body.contains_secret && host not in trusted_hosts decision: deny # 红色：自动阻止 + 通知 critical: true ``` --- ## 9. 如何实现不可知性（以及我们故意不做的事） **实现方式：** - 在**操作边界**（MCP/工具/HTTP）进行拦截，该边界在任何模型下都是相同的。 - **可插拔的检查者模型**（本地或远程，用户选择）。 - **每个适配器的适配器**，它们都馈送到同一个策略引擎。 **我们故意不做的事情：** - ❌ 安装内核模块或使用需要供应商授权的操作系统钩子。 - ❌ 让任何 LLM 成为允许/拒绝边界。 - ❌ 将可伪造的`User-Agent`头作为安全控制。 - ❌ 使用零知识证明作为委托原语（使用马卡龙/范围令牌/VC）。 - ❌ 通过学习自动降级关键类别操作。 - ❌ 声称 Guardian“使用户依法合规” - 它*帮助*透明度和可追溯性；法律确认是用户的责任。 - ❌ 将行为/学习数据发送到云端（检查者升级是唯一的网络路径，并且是选择加入的）。 **范围外（目前）- 明确推迟，而不是遗忘：** - 多代理/代理到代理的监督（OWASP Agentic 2026 风险类别）- 当前模型保护单个代理；多代理中介是未来工作。 - 深入的操作系统/内核拦截（见§4）- 绝不涉及。 - 任何专有/企业层 - 此仓库是完全开源的。 --- ## 10. 路线图 - 需要构建的所有内容 ### 阶段 0 - 基础（第 1 周） - [ ] 设置 Rust 工作空间（**Rust 已决定 - ADR-0001**；参见 ROADMAP §0）。 - [ ] 仓库脚手架、许可证（**Apache-2.0**，参见 `LICENSE`）、CI、贡献指南。 - [ ] 定义**操作模型**（每个适配器标准化的规范化表示）。 - [ ] 编写正式的**威胁模型**和**策略模式**作为实时规范。 ### 1 阶段 - MVP（可演示的核心，大约第 2-8 周） - [ ] **MCP 网关适配器**（主要）适用于一个 MCP 说话的工具。 - [ ] **确定性策略引擎**，具有声明式模式 + CEL/Rego 风格的评估器 + 完整的测试套件（每个规则的黄金案例）。 - [ ] **检查者**翻译器使用可插拔的模型；仅读取结构化操作。 - [ ] **批准 UI**（Tauri）：交通灯队列 + 普通语言解释 + 允许/拒绝。 - [ ] **防篡改审计日志**（仅追加，哈希链式）。 - [ ] **一个真正的演示场景端到端**（例如代理编辑文件 + 发出 HTTP 请求；守护程序允许绿色，暂停黄色，并阻止红色数据泄露尝试）。 **MVP 完成定义：** 非技术用户可以观看代理工作，获得一个**人类可读**的审批提示，用于一个有风险的操作，看到一个操作被自动阻止，并阅读发生的一切的日志 - **没有 LLM 在拒绝路径中**。 ### 2 阶段 - 隔离和网络（MVP 后） - [ ] **HTTP(S) 前向代理**，带有安装的 CA：网络策略、出口允许列表、可选的代理信号头、可选的内容水印。 - [ ] **操作系统沙箱包装器**用于原始 `exec` 工具（Docker / sandbox-exec / bubblewrap / AppContainer）- 深度防御，仅限现成工具。 - [ ] **原生钩子适配器**（例如 Claude Code `PreToolUse`）。 ### 3 阶段 - 身份、学习、生态系统 - [ ] **身份和令牌代理**：范围限定 OAuth、马卡龙、密钥链/安全围栏/TPM 存储；代理绝不看到原始秘密。 - [ ] **约束自适应学习** + 定期**报告**。 - [ ] **签名社区策略包** + 社区信任/审查管道（这是开源社区引擎）。 - [ ] 可选的 **LLM 网关代理**，带有工具结果净化。 - [ ] 额外的适配器（Cursor、OpenAI 代理运行时、通用 MCP）。 --- ## 11. 建议的技术栈（提案，不锁定） - **核心 / 策略引擎 / 代理：** Rust（安全严谨，跨平台）- Go 是代理/MCP 速度的可接受替代品。 - **策略表达式：** CEL 或 OPA/Rego 风格的评估器（可决定，可测试）。 - **桌面 UI：** Tauri。 - **审计日志：** 仅追加的哈希链式存储（例如 SQLite + 链式哈希，或专门的日志）；每个安装的签名密钥在操作系统密钥链/安全围栏/TPM中。 - **网络代理：** 用户空间 MITM 代理 + 本地受信任的 CA。 - **沙箱后备：** Docker / `sandbox-exec`（macOS）/ bubblewrap（Linux）/ AppContainer 或 Windows 沙箱（Windows）- 全部现成。 --- ## 12. 开放问题（决定前/边建边决） 1. 我们**首先**针对哪个工具启动 MCP 网关？（驱动演示。） 2. 默认本地检查者模型 - 哪个小型模型在质量和占用空间之间取得平衡？ 3. 策略表达式语言 - CEL vs. Rego（DX，沙盒，生态系统）？ 4. 签名策略包如何在社区规模上进行审查而不会出现瓶颈？ 5. 代理安装的 UX - 如何使信任本地 CA 安全且对非技术用户来说不恐怖？ 6. 我们承诺多少 AI 法规透明度故事 vs. 明确声明？（在任何合规声明之前获取法律输入。） --- ## 13. 术语表 - **工具** - 驱动代理并协调其调用的运行时（例如 Claude Code）。守护程序插入此层。 - **制造者** - 执行用户任务的第三方代理。 - **检查者** - 守护程序的本地翻译器/风险评分模型（仅为 advisory）。 - **MCP** - 模型上下文协议；守护程序代理的工具/服务器协议。 - **马卡龙** - 一种 bearer 凭证，可以用上下文限制进行衰减。 - **关键类别** - 资金转移、凭证访问、数据泄露、不可逆删除；绝不通过学习自动降级。