BossConsole 安全体系终极指南:逐工具开关、RBAC 角色权限与签名插件如何协同守护 AI 代理
BossConsole 安全体系终极指南:逐工具开关、RBAC 角色权限与签名插件如何协同守护 AI 代理
BossConsole 是一款开源、跨平台的 AI 代理操作台(JVM 原生实现,非 Electron),用于运行 Claude Code、Codex、Gemini、OpenCode 等编码智能体,并内置真实浏览器、终端、编辑器、密钥管理与 200+ MCP 工具。它的整个安全体系由三道防线构成:逐工具开关(决定智能体"能碰什么")、RBAC 角色权限(决定"谁能碰")、签名插件(决定"插件从哪来、有没有被篡改")。本文带你快速看懂这三道防线各自如何工作、又如何在一次工具调用中协同生效,以及密钥引用如何避免凭据泄漏到智能体对话里。
一、第一道防线:逐工具开关(Per-Tool Kill-Switch)
这是最简单、也最"硬"的一道防线:它决定每个 AI 代理能用哪些 MCP 工具。
- 在哪操作:打开 Toolbox → MCP 标签页,即可浏览全部工具并逐一开关。详见 docs/mcp-agentless-operators.md。
- 开关即摘除:被关闭的工具会从代理的可用工具集中移除,同时拦截其调用——不是"点了才报错",而是代理根本看不见它。
- 持久化 + 故障闭合(fail-closed):关闭列表保存在
~/.boss/mcp-disabled-tools.json。若文件损坏,系统不会"什么都不禁",而是全部工具扣留并在日志与状态栏明确告警;损坏的原文会被备份为.corrupt文件。 - 管理员也绕不过:权限检查对 admin 用户会短路放行,但逐工具开关在调用时刻强制执行,因此它对任何人都生效——这是唯一对所有角色都成立的边界。
⚠️ 官方基础设施插件审计(docs/INFRASTRUCTURE_GUARDRAILS.md)特别点名:如果代理连上了 Kubernetes 集群,应优先关闭
k8s_exec和k8s_apply两个工具,它们能在集群内执行任意命令,等于绕过密钥保护。
这些开关属于"访问控制"而非沙箱:插件运行在宿主进程内,关闭工具不会取消已被授权的工作。
二、第二道防线:RBAC 角色权限
第二道防线回答"这个人能用什么"。BossConsole 基于 Supabase 原生 Custom Claims + Auth Hooks 实现了完整的 RBAC(docs/RBAC_GUIDE.md):
- 角色树继承:角色构成层级结构,父角色自动继承子角色的有效权限。例如
admin继承一切,boss_plugin_admin是最小权限的插件作者角色,user是基线角色。 - JWT 携带权限:登录(魔法链接或 Passkey)时,
custom_access_token_hook把用户的有效权限集注入 JWT 的user_permissions声明,客户端据此做界面显示;但真正的强制执行在服务端。 - 数据库 RLS 兜底:所有表的行级安全策略通过
authorize(权限名)函数校验 JWT 中已验证的权限,客户端"藏起来的按钮"骗不过服务端。 - 委托管理有边界:非管理员只能分配严格低于自己的角色,且只能授予自己持有的权限——被委托的角色管理员永远无法"造出"一个比自己更大的角色。
- 插件按权限门控:插件在
plugin.json中声明requiredPermissions,宿主只向持有全部所需权限的用户展示并注册该插件。
核心设计原则:客户端权限判断只用于界面展示,服务端校验才是安全保证。
三、第三道防线:签名插件(Signed Store Plugins)
前两关管"人"和"工具",第三关管代码本身。
- 插件商店的每个版本都会附带
<jar>.sig签名侧车文件,对锚点pluginId|version|sha256用 RSASSA-PKCS1-v1_5 + SHA-256 签名;加载插件时,PluginSignatureVerifier.kt 用内置固定的发布者公钥逐一验签。 - 验签发生在加载入口:所有安装路径最终都汇入
DynamicPluginLoader.loadPlugin,被篡改的商店行或存储对象无法把"另一个 JAR"偷偷送上你的机器。 - 签名证明的是来源,不是安全:有效签名说明"这个插件确实由该发布者、该版本发布",不保证它没有 bug。签名数据库层设计见 20260716200000_plugin_version_signatures.sql。
顺带一提,代理通过 MCP 操作的正是这台内置真实浏览器,其性能表现可见 benchmark.md 中的 Speedometer 3.1 对比数据。
四、三道防线如何协同:一次工具调用的完整旅程
| 关卡 | 检查什么 | 由谁执行 | 对 admin 是否生效 |
|---|---|---|---|
| 签名插件 | 插件来源与内容完整性 | 插件加载器(PluginSignatureVerifier.kt) | ✅ 生效 |
| 逐工具开关 | 该工具是否被手动关闭 | 调用时刻强制 | ✅ 生效 |
| RBAC 权限 | 调用者是否持有工具声明的权限 | McpToolRegistryCore.permitted() + 服务端 RLS |
❌ 管理员短路放行 |
| 审批策略 | ALLOW / ASK / DENY 三态裁决 | McpPolicy.kt | ✅ 生效 |
协同逻辑一句话概括:签名保证"代码是谁的",开关保证"这扇门开着吗",RBAC 保证"你有钥匙吗",审批策略决定"要不要再问你一次"。其中开关与审批对管理员同样有效,RBAC 则是"非管理员角色才真正有意义的边界"——这也正是官方文档反复强调"桌面单机场景请优先用 Toolbox 开关、而不是只依赖 RBAC"的原因。
五、隐藏彩蛋:密钥引用(Secret References)
BossConsole 还有第四重细节:智能体可以让工具使用已存凭据,但凭据本身永不进入对话记录。代理只写引用 {{secret:<uuid>}},宿主在操作者批准后于治理边界处解析真实值(docs/MCP_SECRET_REFERENCES.md)。对话记录、审批弹窗、操作台账、宿主日志中只会出现引用,绝不出现明文凭据——这是一个"不泄露"保证:密钥不进代理上下文,降低被提示词注入带走的概率。
六、快速上手清单
- 登录后先开 Toolbox → MCP,把当前任务不需要的工具全部关闭(尤其是
k8s_exec、k8s_apply一类"真触达"工具); - 多用户团队按 RBAC 指南配置角色树,给插件作者发
boss_plugin_admin这类最小权限角色; - 从商店安装插件时留意签名校验结果;发布方签名数据库迁移见 supabase/migrations/;
- 需要凭据的场景改用密钥引用,而不是把密钥贴在提示词里;
- 定期用
boss doctor检查开关持久化与策略健康状态(docs/CLI.md)。
七、延伸阅读
- 安全与工具边界总述:README.md
- 基础设施插件权限审计:docs/INFRASTRUCTURE_GUARDRAILS.md
- RBAC 完整参考:docs/RBAC_GUIDE.md
- 密钥引用契约:docs/MCP_SECRET_REFERENCES.md
- 角色层级迁移:20260625000000_role_hierarchy_and_granular_rbac.sql
🛡️ 三道防线各司其职:开关管工具、RBAC 管人、签名管代码。理解它们的边界与协同方式,你就能为 AI 代理搭出一套"默认最小权限"的操作环境。
