企业官网建设流程全解析

context-mode 项目边界防护实战：如何堵住路径穿越与符号链接逃逸（Issue 852 完整解析）

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode

context-mode 是一款面向 AI 编码代理的 MCP 上下文优化插件，通过沙箱化工具输出、持久化会话记忆来节省上下文窗口。本文以 Issue 852 为例，带你完整看懂它的项目边界防护是如何堵住路径穿越、绝对路径逃逸与符号链接逃逸这 3 条逃生路线，让 AI 代理的文件处理工具无法绕过宿主沙箱的。

Issue 852 是什么？一次"灯下黑"的沙箱逃逸 🕳️

先还原事故现场，它比想象中更隐蔽：

1. AI 代理想读一个项目外的敏感文件（例如/home/user/some-private-dir/index.ts）；
2. 宿主平台（如 Claude Code）的沙箱正确拒绝了——到这里一切正常；
3. 代理换了个"马甲"，改调 context-mode 的ctx_execute_file工具（在文件上运行代码、只输出摘要）；
4. 旧实现的执行器直接把路径交给resolve(projectRoot, path)——而 Node.js 的规则是：绝对路径参数会直接胜出，项目根形同虚设；
5. 文件被成功读取，逃逸完成。

最致命的是第 5 步的"无人察觉"：宿主弹出 MCP 审批框时，只能看到工具名和参数摘要，无法深入检查参数细节。用户点"同意"的那一刻，根本看不到路径已经溜出了工作区。这就是 Issue 852 的核心：宿主以为自己在执行边界，实际边界早已失守。

相关背景可参考 src/server.ts 中对该问题的设计说明。

三条逃逸路线：攻击者视角的"逃生通道"

context-mode 把逃逸风险归纳为 3 类，修复方案也逐一对应：

1️⃣ 绝对路径逃逸

直接传/etc/passwd这类绝对路径，resolve(projectRoot, abs)会原样返回它，项目根完全不起作用。

2️⃣../路径穿越

传../../../../etc/passwd，一路向上爬出项目目录。

3️⃣ 符号链接逃逸（最阴险）

在项目里放一个看似无害的文件safe.log，它的真实指向（realpath）却是~/.ssh/id_rsa。路径"看起来"在项目内，解引用后却指向项目外——这是纯字符串前缀判断永远防不住的。

修复方案：纯路径数学 + 双重锚定 🛡️

第一层：isPathInsideProject纯路径判定

修复的核心是一个不依赖正则的"纯数学"判定函数 isPathInsideProject：

• 用path.resolve把候选路径解析为绝对路径；
• 用path.relative(root, candidate)做纯字符串运算：结果以..开头（向上逃逸）或仍是绝对路径（Windows 下跨盘符）→ 拒绝；
• 项目根本身、项目内的相对/绝对路径 → 放行；
• 顺带防住了一个经典陷阱：名为myproject-evil/的兄弟目录，不会被"字符串前缀匹配"误判为项目内部。

第二层：符号链接规范化复检

光做词法（lexical）判定还不够。函数会再对路径做realpathSync解引用，要求符号链接解析后的真实位置也必须落在项目内（见 src/security.ts 的 defense-in-depth 注释）。safe.log -> ~/.ssh/id_rsa这类"内穿外"的链接，在这一层被拦下；文件尚不存在时则优雅回退到词法判定，不误伤正常操作。

第三层：服务端边界守卫checkProjectBoundary

守卫被直接植入ctx_execute_file处理器的最前端——先查边界，再查 deny 策略（src/server.ts）：

• 项目根通过统一的 getProjectDir() 解析（其底层逻辑在 src/util/project-dir.ts，会按平台环境级联拒绝"插件安装目录污染"等陷阱）；
• 判定入口是 evaluateProjectContainment，返回inside/allow-rule/outside三种明确结论；
• 命中越界时，工具直接返回清晰报错：File access blocked: "..." resolves outside the project root ... (issue #852)，并顺带告诉用户如何合法放行——报错本身就是文档；
• 设计上还有一处细节：解析失败时"fail-open"（放行），保证守卫故障不会阻塞项目内的正常工作。

另外，ctx_execute_file的 MCP 工具标题被特意写成"Run code over a file (executes code, reads the given path)"（src/server.ts）——既然审批框只渲染标题，那就让标题如实宣告"这会执行代码、会读文件"，把知情权还给审批人。

合法需求怎么办：复用宿主 permissions.allow 逃生舱 🚪

需要读项目外文件是真实场景（比如分析/var/log下的日志）。context-mode 的选择是：不自造开关，直接复用宿主已有的permissions.allow规则。

例如在宿主设置里加一条：

"permissions": { "allow": ["Read(/var/log/**)"] }

这样授权只存在于一个地方（用户本来就要维护的那份配置），宿主和 context-mode 共同遵守，不会出现"context-mode 专属环境变量"这种无人设置、最终腐烂成死代码的开关——测试 tests/security/project-boundary-852.test.ts 甚至断言了这个死代码环境变量必须不存在于源码中。

测试如何把防护钉死 🔒

整套防护由 tests/security/project-boundary-852.test.ts 逐条钉死，覆盖了攻击者能想到的所有姿势：

同时，守卫接线测试 从源码结构层面验证：守卫确实存在于checkProjectBoundary、确实挂在ctx_execute_file处理器里、确实走getProjectDir()——防止未来某次重构把守卫悄悄拆掉而测试照旧全绿。

写在最后

Issue 852 的价值不只是修了一个洞，而是给出了 MCP 工具设计的一条通用准则：宿主沙箱管不住的参数，工具自己必须管。绝对路径、路径穿越、符号链接逃逸这三类向量，加上"审批框不可见参数"这个放大器，构成了 AI 编码代理时代最典型的越权组合。context-mode 用纯路径数学 + realpath 复检 + 宿主配置复用的三层方案，把边界重新锚死在了项目根上——简洁、可测试、且不留维护陷阱。

【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode