CodeWhale插件贡献MCP：最严格审查下的安全边界

CodeWhale插件贡献MCP最严格审查下的安全边界【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhaleCodeWhale是一个用 Rust 构建的开源终端编码智能体coding agent。它支持通过MCPModel Context Protocol服务器扩展工具能力而插件Plugin还能贡献自己的 MCP 服务器——这正是新手最该关注的地方第三方插件里的工具会以你的身份运行。CodeWhale 为此设计了最严格审查的安全边界未知字段拒绝、凭据脱敏、网络白名单、信任与启用分离让插件 MCP 在可控权限下安全运行。本文带你完整看懂这套机制。上图就是 CodeWhale 的终端界面顶部状态栏中的mcp 0表示当前已加载的 MCP 服务器数量——插件贡献的服务器启用后也会显示在这里。什么是 MCP为什么插件要贡献它MCPModel Context Protocol是一种让 AI 智能体调用外部工具的开放协议。通俗地说MCP 服务器 一个工具包进程向 AI 提供工具、资源和提示模板本地 MCP 服务器以stdio 子进程形式运行远程服务器则通过HTTP 端点连接CodeWhale 通过统一的 MCP 管理器加载它们发现的工具以mcp_服务器名_工具名形式暴露给模型插件贡献 MCP 的价值在于一个审查过的插件包可以同时携带 Skills、命令、Agent 配置和 MCP 服务器复用同一套 MCP 管理器、工具审批、超时与网络策略而不是再造一条旁路。插件的服务器会以plugin-server命名空间标识避免与用户自己的服务器冲突详见 docs/MCP.md。智能体获得 MCP 工具后能力可以大幅扩展——但扩展能力越强安全边界就越重要。最严格审查插件 MCP 的五道防线CodeWhale 的插件包边界刻意比用户手写的mcp.json更严格原则是失败即关闭fail closed任何拿不准的声明都直接拒绝而不是静默放行。1️⃣ 清单校验未知字段直接报错插件清单plugin.json或plugin.toml采用封闭根设计未知字段、未知顶层表、未知的 MCP 字段 → 直接解析失败按字节偏移量报错含糊的本地/远程传输混合声明 → 拒绝组件路径必须是相对路径、无符号链接、无目录穿越..这意味着插件作者无法藏任何悄悄生效的隐藏配置。2️⃣ 凭据脱敏只允许引用环境变量名这是审查中最严格的一环本地 stdio 服务器的env必须是精确的${SOURCE_ENV}来源引用审查时只显示变量名永不读取或打印变量值远程服务器的字面量请求头如写死的Authorization: Bearer xxx直接拒绝认证必须走env_headers或bearer_token_env_var命令行参数中出现已知凭据标志或 token 字面量 → 拒绝带密钥的 URL、用户信息、query、fragment → 拒绝插件子进程只继承脱敏后的基础环境 审查过的映射不会顺带继承宿主的凭据变量。3️⃣ 网络隔离白名单精确匹配 代理旁路远程 MCP 端点必须使用HTTPS仅允许显式的本机回环 HTTPcapabilities.network_hosts声明的主机集合必须与端点归一化后的主机集完全一致——多一个少一个都不行重定向被限制在已审查的源内已审查的插件远程传输完全绕过环境中的HTTP_PROXY/HTTPS_PROXY配置因为代理凭据和代理侧流量不在审查授权范围内插件贡献的MCP OAuth 自 v0.9.1 起被整体禁用声明 OAuth 字段的清单会直接校验失败4️⃣ 信任先于启用两个 SHA-256 回执CodeWhale 把信任和启用拆成了两步这是理解整套机制的关键/plugin validate example # 只读校验不执行任何东西 /plugin show example # 查看组件清单、权限、端点、哈希 /plugin enable example # 首次启用会打开审查视图 /plugin trust example 内容哈希.能力哈希 # 按提示粘贴完整回执 /plugin enable example # 再次执行才真正激活trust命令使用的确认令牌由完整的内容哈希 能力哈希两个 SHA-256 组成不是显示用的前缀。信任阶段只把审查过的树复制到内容寻址的运行时快照并记录回执不激活任何东西。信任回执持久化在~/.codewhale/plugins/state.json保留最近 32 次审查作为审计轨迹。5️⃣ 漂移即失效改一个字节就要重新审查源文件或暂存树内容发生任何编辑 → 哈希不再匹配 → 回执确定性地失效已启用的插件变为不激活必须重新审查禁用、撤销或跨进程的状态变更会移除目录项、取消进行中的 MCP 操作、终止插件 stdio 子进程每次工具调用前都会重新校验权威状态连接前、每次惰性拉起 stdio 子进程后、传输构建后、每次工具/资源/提示操作前插件 MCP 与用户 mcp.json边界对比维度用户手写的 mcp.json插件贡献的 MCP未知字段容忍度高直接解析失败字面量请求头 / 密钥 URL允许拒绝环境变量可继承较宽环境仅脱敏基础环境 审查过的精确引用HTTP 代理显式支持完全旁路OAuth支持禁用信任模型配置即信任内容哈希 能力哈希双回执内容变更重载生效回执失效强制重新审查完整生命周期契约见 docs/PLUGIN_BUNDLES.md安装流程/plugin install/update/uninstall见 docs/PLUGINS.md——安装只负责把文件放到磁盘新安装的插件一律禁用且未信任。运行时还有兜底工具审批照常生效插件审查不等于操作系统沙箱。本地 stdio 服务器本质上是带着你宿主文件系统与网络权限的子进程审查视图会明确打印这条宿主权限警告。在此基础上MCP 工具仍然流经与内置工具相同的审批框架详见 docs/MCP.md 的 Safety Notes只读型 MCP 助手资源/提示列表与读取在策略允许时无需确认有副作用的 MCP 工具一律需要审批Full Access 模式也不能绕过硬性策略拦截宪章、仓库指令、权限规则、沙箱策略的优先级始终高于插件指令MCP 连接层的核心实现位于 crates/mcp/src/lib.rs 与 crates/mcp/src/stdio_client.rs插件发现与信任/启用逻辑在 crates/tui/src/plugins/discovery.rs 和 crates/tui/src/plugins/activation.rs。需要体验完整功能时可从发行版页面获取带 SHA-256 校验和的平台二进制。新手安全使用清单 ✅只安装你信任的插件MCP 服务器配置等价于在你机器上运行代码先show再trust审查视图会展示命令、参数数量、工作目录、环境变量名和端点——确认每一项都符合预期不要把真实 token 写进清单字面量会被拒绝这是设计意图而非 bug更新后重新审查/plugin update换掉的字节会自动使回执失效这是保护你的机制随时可退/plugin disable保留信任但停止贡献/plugin revoke撤销信任两者都会终止进行中的插件子进程写在最后CodeWhale 插件贡献 MCP 的设计哲学可以概括为一句话发现不执行信任不激活激活不越权。它没有用模糊的推荐即信任换取便利而是用封闭清单、双哈希回执、网络白名单和逐次调用前的权威重查为第三方工具画出了一条清晰、可审计、可撤销的安全边界。延伸阅读MCP 完整指南docs/MCP.md插件包契约与信任/启用生命周期docs/PLUGIN_BUNDLES.md插件安装与更新流程docs/PLUGINS.md沙箱策略docs/SANDBOX.md【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考