如何看懂 CodeAgent 权限安全体系：5 道闸门、路径白名单与 bwrap 沙箱的设计细节

【免费下载链接】codeAgentCodeAgent is an open-source coding agent that lives in your terminal. It understands your repository, plans multi-step changes, writes and edits files, runs commands and tests, and iterates until the task is done — all with a transparent, extensible tool loop.项目地址https://gitcode.com/gh_mirrors/cod/codeAgent点击查看免费下载CodeAgent 是一个跑在终端里的开源 AI 编程 Agent它读代码、改文件、跑命令、跑测试一直迭代到任务完成。但一个能自己敲命令的助手最让人担心的就是它误删文件、篡改密钥。CodeAgent 的权限安全体系正是为此设计每条命令要依次穿过 5 道闸门底线检查、硬拒绝黑名单、破坏性审批、用户审批、LLM 语义分类文件写入受路径白名单约束Linux 下还能用 bwrap 沙箱把命令关进内核级笼子。下面带你快速看懂这套设计。权限安全总览一道命令要过多少关先给结论CodeAgent 里每一次rm、每一次写文件之前都要先过安检。安检的地基是 agent/permission.py 的模块头注释作者把整个流程画成了小区保安式的关卡图关卡名称行为源码位置闸门 0不可绕过的底线任何模式都拒绝rm -rf /、格式化磁盘、改自身依赖permission.py#L178-L321闸门 1硬拒绝黑名单20 条危险命令正则命中直接拒permission.py#L97-L130闸门 2破坏性命令模式rm/git reset --hard等先弹审批permission.py#L408-L418闸门 3用户审批 缓存会话内问过不重复问总是允许跨会话持久化permission.py#L678-L785闸门 4副 LLM 语义分类可选的慢速深审默认关闭失败放行permission_llm.py主入口是 PermissionChecker.check()按 闸门 0 → 内容级规则 → 危险删除 → 黑名单 → 注入面 → 只读快速通道 → 破坏性审批 → LLM 分类 → 默认放行 的顺序走完。顺序就是安全优先级——黑名单永远排在快速通道之前。闸门 0即使跳过所有审批也绕不过的底线最容易被忽略、却最重要的一关是闸门 0。它包含两条系统级不可逆破坏permission.py#L237-L243mkfs格式化、fork bomb、dd写裸磁盘设备、rm -rf /或rm -rf ~整棵树。其中rm的判定不走正则而是逐 token 比对permission.py#L253-L289因为-fr、--recursive --force、--no-preserve-root这些变体一条正则罩不住。自我保护permission.py#L178-L227AI 不许在 CodeAgent 自己的代码目录里跑uv add/pip install——给自己动手术只会把助手搞瘫痪。即便你在/permission里选了bypassPermissions跳过全部审批模式闸门 0 依然生效。这是整个权限系统里唯一的绝对不可绕过检查。路径白名单写文件只准碰三个地方命令有闸门文件同样有。agent/path_guard.py 是路径安全的核心规则非常直白受保护路径读写全拒path_guard.py#L48-L70~/.ssh、~/.aws、~/.gnupg、~/.config/ghGitHub token、/etc、C:\Windows等 17 条。注意它会同时检查原始写法和软链展开后的真实写法软链指向~/.ssh也逃不掉path_guard.py#L82-L118。写保护路径只读不改CodeAgent 自己的项目代码目录允许读、禁止写防止 AI 篡改自身源码。写白名单path_guard.py#L326-L350默认只允许写 ① 当前工作目录 ②~/.codeAgent③ 你用/add-dir显式追加的目录。白名单外的写入会弹审批选总是允许后父目录持久化到settings.json。还有一个容易忽视的细节——可疑路径形态检测path_guard.py#L214-L271。Windows 下有些改名绕过安检的花招8.3 短名GIT~1和GIT是同一个文件、长路径前缀\\?\、文件名尾点.git.实际就是.git、NTFS 数据流冒号、DOS 设备名settings.json.CON……这些写法能让同一个文件呈现出对不上的字符串全部直接拒绝且全平台都查NTFS 磁盘可以挂在任何系统上。顺序铁律保护表排白名单前面——就算你把整个家目录加进白名单~/.ssh照样写不了。bwrap 沙箱把命令关进内核级小房间闸门和白名单是软件层的检查agent/sandbox_runner.py 提供的是 OS 层的硬隔离。用/sandbox on开启后Linux 下命令会被包装成bwrap --die-with-parent --new-session --unshare-pid --unshare-ipc \ --ro-bind /usr /usr --ro-bind /etc /etc ... \ --dev /dev --proc /proc --tmpfs /tmp \ --bind 工作目录 工作目录 -- bash -c 你的命令包装逻辑在 _bwrap_wrap()几个设计点很讲究系统目录只读挂载sandbox_runner.py#L264-L271/usr、/etc等只给看不给改/dev改用沙箱自带的--dev临时盘否则/dev/null这种 curl/git 惯用写法会直接撞 EROFS 报错。独立 PID 命名空间不隔离进程的话沙箱里的命令能看见宿主机全部进程一条kill -9就能干掉 Agent 自己。/tmp用内存盘不挂宿主机的/tmp里面可能有敏感东西改用沙箱内部 tmpfs。可写目录白名单复用沙箱里能写的只有工作目录 ~/.codeAgent 配置中的sandbox_writable_roots和路径白名单同源。macOS 走系统自带的 Seatbeltsandbox-exec 每次现写的.sb规则文件7 天自动清理sandbox_runner.py#L393-L468Windows 走 Job Object 进程笼子win_job_object.py。沙箱不可用时自动降级为普通执行并记警告fail-open不会把任务卡死。审批体验少打扰、有记忆、后台分身自动拒权限系统的另一半是怎么问才不烦人三个机制值得学只读快速通道readonly_commands.py#L30-L57ls、cat、git status、grep这类只看不动手的命令零打扰放行。判定保守优先——find -delete这类带写副作用的形态会被参数黑名单拦下复合命令逐段切分判定ls rm xxx混不过去。注入面检测bash_injection.py#L564$()、反引号、进程替换(...)这些所见非所执行的写法不是直接拒绝而是升级审批——写法本身不一定是攻击但至少该让人看到原文后亲手点批准。语义是宁可多问不漏问。两级审批缓存permission.py#L456-L460本次会话批过的命令不重复问防信任漂移选总是允许的命令存成 JSON 白名单跨会话生效还会派生前缀规则同类npm test命令下次免审。想管理已批准的命令用/approved查看。四种权限模式/permission切换覆盖不同场景模式适用场景default全闸门开启日常默认acceptEditsAI 连续改代码时工作目录内的文件操作自动放行bypassPermissions显式接受全部风险闸门 0 仍生效autoDeny后台子代理专用用户不在场不能弹窗需审批的一律 fail-closed 拒绝另外你可以在settings.json的permissions段写allow/deny/ask内容级规则如Bash(npm test)优先级 deny ask allow连 bypass 模式也不豁免用户的显式 denytool_permissions.py#L39-L44。相关源码速查模块职责agent/permission.py权限主入口5 道闸门 审批缓存 路径检查agent/path_guard.py保护表 / 写保护 / 可疑形态 / 写白名单agent/sandbox_runner.pybwrap / Seatbelt / Job Object 沙箱包装agent/bash_injection.py注入面所见非所执行检测agent/readonly_commands.py只读命令判定表快速通道agent/tool_permissions.pysettings.json 的 allow/deny/ask 规则agent/bash_removal_guard.py危险删除路径与 cdgit 组合防护tools/terminal_tool.py终端命令执行的沙箱接入点小结CodeAgent 的权限安全体系核心思路可以概括为一句话底线不可绕、白名单优先、拿不准就问人。5 道闸门管命令路径白名单管文件bwrap 沙箱在 OS 层兜底审批缓存保证安全不打扰。如果你也在做 Agent 类项目这套顺序即优先级的防线设计非常值得参考——先读 permission.py 的 check() 主流程再顺着它 import 的每个子模块走一遍基本就能读懂全部设计细节。赞分享【免费下载链接】codeAgentCodeAgent is an open-source coding agent that lives in your terminal. It understands your repository, plans multi-step changes, writes and edits files, runs commands and tests, and iterates until the task is done — all with a transparent, extensible tool loop.项目地址https://gitcode.com/gh_mirrors/cod/codeAgent点击查看免费下载相关推荐如何看懂 SJMCL 的账号安全5 道安全闸门一次讲透如何看懂 SJMCL 的账号安全5 道安全闸门一次讲透 SJMCL https://link.gitcode.com/i/6fe1cef3aa2c465836Cyrus 安全实战二工具权限白名单 沙箱文件系统如何防止 Claude Code 越权访问Cyrus 安全实战二工具权限白名单 沙箱文件系统如何防止 Claude Code 越权访问 Cyrus 是一个可部署到任意环境的 Claude如何保障 AI Agent 安全运行Axe 路径沙箱、SSRF 防护与主机白名单机制详解如何保障 AI Agent 安全运行Axe 路径沙箱、SSRF 防护与主机白名单机制详解 让 AI Agent 自动读写文件、执行命令、抓取网页听起来很香上一篇skfolio 特征因子模型完全指南如何用 46 个描述符构建多因子量化组合下一篇横评让 AI 玩转真 iPhone 的 7 美元小黑板跟老牌Siri 开灯玩法比谁才是未来创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考