OpenOcta安全机制详解：Sandbox沙箱、Validator命令校验与人工审批队列三层防护如何设计

【免费下载链接】openoctaOpenOcta is an open-source AIOps Agent installed on Windows & macOS.项目地址: https://gitcode.com/gh_mirrors/op/openocta

OpenOcta 是一款运行在 Windows 与 macOS 上的开源 AIOps Agent，让 AI 智能体自主执行命令、读写文件、调用 API。能力越强，"越界"风险越大：一句"帮我清理磁盘"可能误删重要数据，一次"帮我测试 API"可能访问不该访问的网络地址。为此，OpenOcta 的安全机制设计了Sandbox 沙箱、Validator 命令校验、人工审批队列三层防护，目标是"让 Agent 既能干活，又不会越界"。本文带你弄懂这三层防护的设计思路与开启方法。

控制台左侧的「安全策略」入口集中管理三层防护的开关与规则，保存后会写入openocta.json配置文件的security字段（Windows 默认位于%APPDATA%\openocta\openocta.json）。

为什么 AIOps Agent 需要三层防护？🛡️

AIOps Agent 的日常是真实的系统操作：清理磁盘、查询日志、重启服务、执行脚本。没有约束时，一次指令误解就可能变成生产事故。

如上图，你可以用自然语言指挥 OpenOcta 的数字员工干活，但"随口一句"背后是真实的系统命令。OpenOcta 的答案是纵深防御：三层防护各司其职，哪怕某一层被绕过，后面还有两层兜底：

第一层：Sandbox 沙箱——先圈定活动范围

沙箱是最外层的"爆炸半径"边界，无论命令怎么执行，都只能碰到沙箱允许的东西：

• 允许路径（allowedPaths）：文件系统只允许读写声明过的路径前缀，白名单外一律拒绝；
• 网络白名单（networkAllow）：只允许访问声明过的地址/域名，默认仅放行localhost与127.0.0.1；
• 资源限制（resourceLimit）：CPU、内存、磁盘都有上限，不填时保存会自动写入安全默认值——CPU 60%、内存 1GiB、磁盘 1GiB。

未配置允许路径时，系统默认只放行<ProjectRoot>/workspace与<ProjectRoot>/shared两个目录。拦截效果非常直接：

❌ 访问 /etc/passwd 被拒绝（不在允许路径内） ❌ 请求 https://unknown-api.com 被拒绝（不在网络白名单）

你只需把业务真正需要的路径和域名补进两个列表即可。沙箱的配置结构定义在 src/pkg/config/schema.go（SandboxConfig结构体）。

第二层：Validator 命令校验——高危命令直接"熔断"

第二层针对命令文本本身，对 Agent 想执行的每条命令做确定性检查。核心校验逻辑在 ValidateCommandWithConfig，按顺序过五道关：

1. 长度检查：超过上限（默认 4096 字符）直接拒绝；
2. 控制字符检查：发现隐藏控制字符直接拒绝；
3. 禁止命令（banCommands）：如dd、mkfs、sudo直接拒绝；
4. 禁止参数（banArguments）：如--no-preserve-root、/dev/直接拒绝；
5. 关键词熔断（banFragments）：命令中只要包含rm -rf这类片段，立即拒绝。

校验结果不止"放行/拒绝"二选一。OpenOcta 把命令规则统一成deny → ask → allow的决策引擎（见 EvaluateCommandAccess）：命中禁止规则直接拒绝；命中"需审批"规则进入第三层审批队列；命中允许规则直接放行。还有一个值得一提的细节：复合命令（用&&、||、;串联）会逐段评估、最严格的结果生效——无法靠"拼一条组合命令"绕过校验。

第三层：人工审批队列——敏感操作留人把关

前两层是"机器判断"，第三层是"人来拍板"，也就是 human-in-the-loop：敏感工具调用（如 Bash）进入审批队列，人工批准后才执行。

核心数据结构是 ApprovalQueue，每条审批请求走pending → approved / denied的生命周期。三个关键设计点值得细看：

1️⃣ allow / ask / deny 三张命令清单

把命令分成三类（每行一个，支持 glob 模式）：

• 自动允许：ls、pwd、echo等只读命令，免审批；
• 需要审批：rm、mv、cp等会改动文件系统的命令，进队列等待；
• 始终禁止：sudo、dd、mkfs等高危命令，批了也不执行。

2️⃣「批准」与「全部放行」的区别

控制台上每条审批请求对应三种操作：

• 批准：仅本次请求可执行，下次相同命令仍需审批；
• 全部放行（加入白名单）：本次执行，并把当前会话加入白名单——TTL 有效期内（默认 1 小时）相同命令自动通过；
• 拒绝：不执行，可填写原因留档。

白名单是"会话 + TTL"的过期机制，实现见 AddSessionToWhitelist：过期后会话自动回到"逐次审批"状态，避免长期绕过审批。

3️⃣ Agent 等人批准，而不是死等

命令需要审批时，Request 会生成一条 pending 记录并落盘，运行时会阻塞等待人工结果；等待有超时保护（默认timeoutSeconds: 300），超时后请求标记为 expired，不会永远悬挂。审批记录持久化在~/.openocta/agents/approvals/approvals.json（Windows 为%APPDATA%\openocta\agents\approvals\approvals.json），采用"写临时文件再原子改名"的方式防止记录损坏。网关侧提供 list / approve / whitelist / deny 四个接口，实现在 approvals.go。

如何快速开启：控制台三步配置 🔧

OpenOcta 的安全配置非常友好，不需要手写 JSON：

1. 打开设置：控制台 →Agent→安全策略，页面即 Sandbox / Validator / Approval Queue 三个折叠框，与上文三层一一对应；
2. 打开开关：开启沙箱与审批队列，按需填写允许路径、网络白名单和三类命令清单；
3. 保存生效：保存后配置写入openocta.json的security字段，下次对话即按新规则生效。

前端实现可参考 ui/src/ui/views/sandbox.ts 与 ui/src/ui/app-security.ts。想快速跑通一套典型配置，官方提供了复制即用的示例：docs/security-quickstart.md。

最佳实践速查 ✅

• 沙箱宁严勿松：只开放业务真正需要的目录，优先使用绝对路径，定期审计并收紧白名单；
• Validator 收住高危项：把dd、mkfs、shutdown放进禁止命令，把rm -rf、sudo rm这类组合放进关键词熔断；
• 审批超时别设太长：避免请求长期悬挂，只读命令尽量放进 allow 清单免审；
• 白名单 TTL 从短开始：「全部放行」图方便，但 TTL 用默认 1 小时即可，防止长期绕过审批。

完整的配置字段表、运行时集成细节与 Hook 扩展点，见官方技术文档 docs/security.md。

【免费下载链接】openoctaOpenOcta is an open-source AIOps Agent installed on Windows & macOS.项目地址: https://gitcode.com/gh_mirrors/op/openocta