From 524deeaad53397eee7adb59a90e7cff94ed97ebe Mon Sep 17 00:00:00 2001 From: nullptr-error <104547331+nullptr-error@users.noreply.github.com> Date: Mon, 7 Sep 2026 13:03:35 +0800 Subject: [PATCH] feat(sandbox): run sandboxed execs as root by default (#3067) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(sandbox): run sandboxed execs as root by default Every chat session owns its own sandbox, so the in-container account is not a tenant boundary and root is the least surprising default for an agent that installs packages and writes wherever it needs. Host and cross-tenant isolation stay at the container boundary. DefaultSandboxExecUser becomes "root" (remote_client.go) and the sandbox image ends with USER root. The three backends keep naming the account explicitly on every exec so the account a call lands on does not depend on which backend a workspace selected; the adapter default, the file operations and the artifact-directory bootstrap all follow the constant. The template still provisions a uid 1000 "user" account for interop with E2B/Cube tooling that addresses it by name. Root also makes the skill-install flow's account hand-over pointless, so it goes: verification no longer runs after a chown/chmod lock-down and a repair round no longer reopens the tree (normalizeSkillPermissions and reopenSkillDirForRepair are gone), and the prepare and scratch commands stop chowning. The scratch wipe now also clears /tmp, and the cache budget guard sizes only root's caches, since no second account can grow one. Verification is asserted to stay on the ordinary executor (no AsRoot, no AllowSkillsRoot) rather than on which account it ran as. * refactor(skills): install chat-time extras into the skill's own env PYTHONPATH / NODE_PATH pointed at a per-session overlay (/workspace/.skill-packages/) because the skill tree was frozen after install: root-owned, mode 555, and often built by `uv venv` with no pip, so `pip install --target` somewhere else was the only way a chat session could add a package. None of that holds now. The lock-down is gone and execs run as root, so a missing package goes straight into the skill's own environment, and the write is already session-local: a chat sandbox is built from the config's image and its filesystem dies with the session, so nothing reaches the image other sessions start from. The overlay bought nothing over that while splitting one skill's packages across two locations. SessionSkillPackageDir goes, and applySessionPackagePath becomes applySkillNodePath: it appends the skill's own node_modules after whatever the caller supplied, replacing a `+=` that prepended a bare separator once the overlay stopped seeding the variable. No PYTHONPATH is injected at all. Python dependencies are reached through the skill's venv interpreter, which the shell wrapper already puts first on PATH; the overlay-era value named the venv root, which is not an importable path. PYTHONPATH stays on the injected-name blacklist so a stored value cannot shadow the venv. The runtime hints and every prompt that described the overlay now name `/.venv/bin/python -m pip install` and `npm install` in the skill directory. frozenSkillTreeGuidance / isFrozenSkillVenvFailure are renamed for what they detect now that nothing is frozen. * docs(prompts): reserve /workspace/output for finished deliverables /workspace/output is the one directory an artifact collector reads, so everything written there is offered to the user as a deliverable. The prompts described it as the place for "deliverables" or "downloadable artifacts" without saying it is exclusively that, which reads as "the directory you write results to" — and a model doing multi-step work has results at every step. Drafts, intermediate renders and debug dumps land next to the finished file and the user is handed all of them. The four places that describe the workspace now say the same thing: the collector reads only /workspace/output, so finished deliverables go there and everything in progress goes anywhere else under /workspace. The attachment block gains the matching half for the other direction — /workspace/input holds the user's own files and is not ours to write to, which it previously implied by calling the paths "read-only inputs" while the tools that enforce it say so plainly. Only the /workspace/input half is enforced (write_sandbox_file refuses that tree). Whether a file is finished is a judgement no tool can make, so the output half stays guidance and is stated wherever the model is already reading about the workspace rather than in one place it might not see. * fix(skills): restore executable bundles and package recovery * style(sandbox): wrap prompt text for repository lint checks * fix(sandbox): guard recovery paths and document root execution --------- Co-authored-by: hailongzhao Co-authored-by: wizardchen --- .../prompt_templates/agent_system_prompt.yaml | 2 +- docker/Dockerfile.sandbox | 25 ++-- docs/agent-skills.md | 25 ++-- docs/agent-tools-design.md | 4 +- docs/sandbox-cluster.md | 6 +- docs/sandbox-docker-backend.md | 46 ++++--- docs/sandbox-protocol.md | 4 +- internal/agent/prompts.go | 12 +- internal/agent/skills/env_resolver.go | 30 ++--- internal/agent/skills/env_resolver_test.go | 18 ++- internal/agent/skills/manager.go | 7 +- internal/agent/skills/shell_environment.go | 3 +- .../agent/skills/shell_environment_test.go | 7 +- internal/agent/skills/skill.go | 5 +- internal/agent/tools/read_file.go | 7 +- internal/agent/tools/sandbox_write.go | 18 ++- internal/agent/tools/shell_exec.go | 45 +++++-- internal/agent/tools/shell_exec_test.go | 89 ++++++++++++-- .../tools/shell_runtime_integration_test.go | 31 ++++- internal/agent/tools/skill_runtime_guard.go | 95 ++++++++++----- .../agent/tools/skill_runtime_guard_test.go | 112 +++++++++++++++++- .../service/session_attachment_staging.go | 8 +- .../session_attachment_staging_test.go | 4 +- .../service/tenant_skill_install.go | 104 ++++------------ .../service/tenant_skill_install_test.go | 110 +++++++++-------- .../service/tenant_skill_verify.go | 6 +- internal/sandbox/capabilities.go | 7 +- internal/sandbox/cube_remote_client.go | 8 +- internal/sandbox/docker_idle_sweeper.go | 6 +- internal/sandbox/docker_idle_sweeper_test.go | 4 +- internal/sandbox/docker_remote_client.go | 88 +++++++------- internal/sandbox/docker_remote_client_test.go | 21 ++-- internal/sandbox/e2b_remote_client.go | 10 +- .../sandbox/envd_compat_transport_test.go | 4 +- internal/sandbox/remote_client.go | 22 ++-- internal/sandbox/session_manager.go | 13 +- internal/sandbox/session_manager_test.go | 17 ++- internal/sandbox/skill_paths.go | 14 --- internal/sandbox/skill_paths_test.go | 6 +- 39 files changed, 634 insertions(+), 409 deletions(-) diff --git a/config/prompt_templates/agent_system_prompt.yaml b/config/prompt_templates/agent_system_prompt.yaml index 7b02f859..a7ca4859 100644 --- a/config/prompt_templates/agent_system_prompt.yaml +++ b/config/prompt_templates/agent_system_prompt.yaml @@ -427,7 +427,7 @@ templates: - Many skills defer optional packages (python-docx, python-pptx, …) to a first-use script such as `scripts/install_deps.py --word`. That pattern does not work after this install: the skill tree is snapshotted read-only and `uv venv` often has no pip, so a later chat cannot `pip install` into the venv. + Many skills defer optional packages (python-docx, python-pptx, …) to a first-use script such as `scripts/install_deps.py --word`. That pattern is the wrong moment: a chat session runs from the image you are building now, and whatever it installs dies with that session, so the work is repeated by every session and fails wherever the sandbox has no egress. - Install every extra NOW. Read SKILL.md, requirements extras, pyproject optional-dependencies, and any `install_deps.py` / whitelist of locked packages. - Run those installer scripts here with non-interactive flags covering every extra (`--yes`, `--all`, `--word --ppt`, …), or `uv pip install` the packages they name. - Do not leave "pip install when the user asks for Word" for session time. diff --git a/docker/Dockerfile.sandbox b/docker/Dockerfile.sandbox index 7d448ae1..d1712c4a 100644 --- a/docker/Dockerfile.sandbox +++ b/docker/Dockerfile.sandbox @@ -51,29 +51,32 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # Add packages here when installed skills actually need them: -# Create non-root user (UID 1000) for sandbox execution. The account is named -# "user" because that is the account name E2B templates are expected to expose -# and the one WeKnora names when running scripts and file operations against an -# E2B-protocol backend. Docker also selects this account by name. +# Sandbox scripts run as root by default: each chat session owns its own +# sandbox, so the in-container account is not a tenant boundary, and agents are +# expected to install packages and write wherever they need. A non-root +# "user" account (UID 1000) is still created and named for interop — E2B +# templates expose it and some tooling still addresses it by name — and it +# gives something for `sudo` and E2B/Cube requests that target a named account +# to land on. The Docker backend can also address it numerically as 1000:1000. RUN groupadd -g 1000 user && \ useradd -u 1000 -g user -m -s /bin/bash user -# Pre-create the two directories every backend writes to and hand them to the -# sandbox account. Runtime preparation uses this same account and fails if -# the image does not provide a writable workspace; it never escalates to root -# or replaces existing directories to repair ownership. +# Pre-create the two directories every backend writes to. Root can create them +# at exec time too. Ownership stays with the compatibility account so tools +# explicitly selecting user can also write here; default root execs do not +# rely on that ownership. RUN mkdir -p /workspace/input /workspace/output && \ chown -R user:user /workspace WORKDIR /workspace -USER user +USER root # Stage 3: Cube template image # # envd is what Cube talks to for everything — the readiness probe that decides # whether a template build succeeds, plus every later exec and file call. It -# runs as root and drops to the account named in each request, which is why -# this variant does not keep the runtime's USER user. +# runs as root and selects the account named in each request. WeKnora names +# root by default, matching the runtime stage. # # This target is linux/amd64 only: cubesandbox-base publishes no arm64 image, # which matches Cube itself (PVM is x86_64-only). diff --git a/docs/agent-skills.md b/docs/agent-skills.md index 606137b1..88d89956 100644 --- a/docs/agent-skills.md +++ b/docs/agent-skills.md @@ -239,7 +239,7 @@ Skills 功能通过两个工具与 Agent 交互: 自己编写的脚本先用 `write_sandbox_file` 写入 `scripts/analyze.py`,然后以相同 `skill_name` 运行 `python3 scripts/analyze.py`。用 `edit_sandbox_file` 修改,用 `read_file` 查看;这些工具的相对路径也从 `/workspace` 解析。Shell 已启用时通过 `ls`/`find` 浏览目录,不再额外注册 `list_sandbox_files`。 -生成文件放在 `/workspace/output`;原始附件位于 `/workspace/input`,应保留原样。已安装技能目录只读。Node 的 `NODE_PATH` 支持 CommonJS,自建 ESM 脚本仍需在可写项目目录安装依赖,或调用技能目录中的原始脚本。 +生成文件放在 `/workspace/output`;原始附件位于 `/workspace/input`,应保留原样。已安装技能可在本会话沙箱内补装依赖,写入随会话销毁,不会修改其他会话使用的镜像。Node 的 `NODE_PATH` 支持 CommonJS,自建 ESM 脚本仍需在可写项目目录安装依赖,或调用技能目录中的原始脚本。 ### 旧工具迁移 @@ -395,19 +395,18 @@ fullResult := validator.ValidateAll(scriptContent, args, stdin) ### Docker 沙箱 -Docker 模式提供最强的隔离: +Docker 后端为每个会话提供独立容器,当前隔离和资源配置如下(详见 [Docker 后端](./sandbox-docker-backend.md)): -- **非 root 用户**:容器内以普通用户运行 -- **Capability 限制**:移除所有 Linux capabilities -- **只读文件系统**:根文件系统只读 -- **资源限制**:内存 256MB,CPU 限制 -- **网络隔离**:默认无网络访问 -- **临时挂载**:Skill 目录只读挂载 -- **脚本预校验**:执行前进行安全校验 +- **执行账号**:默认 root;宿主机和跨会话隔离依赖容器与挂载配置,容器共享宿主机内核。 +- **Capability 限制**:先移除全部,再补回 CHOWN、DAC_OVERRIDE、FOWNER、FSETID、SETGID、SETUID、KILL;启用 `no-new-privileges`。 +- **文件系统**:容器可写层承载技能和工作区,根文件系统不设为只读;当前不支持挂载技能卷,技能随镜像进入会话。 +- **资源限制**:默认 2 GiB 内存、2 核 CPU、512 个进程,可通过配置调整。 +- **网络**:默认 `bridge`,配置禁止出网时使用 `none`;不支持域名级网络规则。 +- **工具约束**:Shell 命令黑名单和文件路径前缀检查用于限制误操作,不是容器内 root 的安全边界。 #### 沙箱镜像 -系统使用专用的沙箱镜像 `wechatopenai/weknora-sandbox`,预装了 Python 3.11、Node.js 20、常用 CLI 工具和 Python 库,无需在执行时临时安装依赖。 +系统使用专用的沙箱镜像 `wechatopenai/weknora-sandbox`,预装了 Python 3.11、Node.js 20、uv 和常用 CLI 工具;技能依赖在技能安装阶段写入各自环境。 **预拉取镜像**(推荐在首次部署时执行,避免首次执行脚本时等待下载): @@ -421,11 +420,11 @@ sh scripts/build_images.sh -s > 如果未预拉取,创建第一个沙箱时会先拉取镜像,首次执行需要等待下载完成;也可以在设置页的模板步骤提前触发拉取。 -> 用 `main` 而非 `latest`:`latest` 只在发版时移动,目前仍停在 `/workspace` 及其 `input`/`output` 目录交给沙箱账号之前的版本,用它建出来的沙箱写不了自己的产物目录。发版带上该修复后即可换回 `latest`。 +> 示例使用 `main`;生产部署应固定已验证的版本标签,并确认镜像与应用版本兼容。 **镜像内置环境**: -- Python 3.11 + pip(requests、pyyaml、pandas、beautifulsoup4) -- Node.js 20 + npm +- Python 3.11 + pip、uv;第三方 Python 包由技能安装阶段提供 +- Node.js 20 + npm、pnpm - CLI 工具:jq、curl、bash、grep、sed、awk 等 ```bash diff --git a/docs/agent-tools-design.md b/docs/agent-tools-design.md index 8f183b77..bd10bbe8 100644 --- a/docs/agent-tools-design.md +++ b/docs/agent-tools-design.md @@ -82,7 +82,9 @@ WeKnora 的通用沙箱操作需要四个稳定原语:读取、写入、编辑 未指定技能的下一条命令使用系统运行环境。命名了不存在或未接入的技能环境时直接报错,不静默回退到系统解释器。 -技能树保持只读。Python 临时依赖通过不带 `skill_name` 的系统 Python 安装到 `/workspace/.skill-packages/`,再带 `skill_name` 执行。Node 的 `NODE_PATH` 支持 CommonJS;自建 ESM 脚本应在可写项目目录安装依赖,或调用技能目录里的原始脚本,不能假定 NODE_PATH 支持 ESM。 +技能缺包时装进技能自己的环境:安装调用也带 `skill_name`,保持 `work_dir` 为默认的 `/workspace`。Python 用 `uv pip install --python "${WEKNORA_SKILL_DIR:?}/.venv/bin/python" `,无需虚拟环境内已有 pip;Node 用 `npm --prefix "${WEKNORA_SKILL_DIR:?}" install `。`$WEKNORA_SKILL_DIR` 由本次调用注入,指向镜像内技能或宿主机来源技能的实际暂存目录。如果尚无 `.venv`,先用 `python3 -m venv --without-pip "${WEKNORA_SKILL_DIR:?}/.venv"` 创建;自定义镜像没有 uv 时,先用该虚拟环境的 Python 执行 `-m ensurepip --upgrade`,成功后再执行 `-m pip install `。随后仍带同一 `skill_name` 执行原命令。命令中的 `${WEKNORA_SKILL_DIR:?}` 会在变量缺失或为空时终止,避免误用根目录。真正的只读挂载仍需先配置可写的技能环境,root、uv 和 pip 都无法绕过挂载限制。 + +沙箱归本会话独占且以 root 运行,这类写入落在会话自己的容器里、随会话销毁,不会回流到其他会话启动用的镜像;因此不再需要 `/workspace` 下的包 overlay,技能的包也不会被拆到两个位置。Node 的 `NODE_PATH` 支持 CommonJS;自建 ESM 脚本应在可写项目目录安装依赖,或调用技能目录里的原始脚本,不能假定 NODE_PATH 支持 ESM。 文件工具继续保留写入预算、精确编辑校验、读取分页和二进制处理。Shell 输出保留原来的字节限额和截断策略;完整输出不自动保存,需要时显式重定向到工作区日志。产物仍由 `/workspace/output` 收集,以 `sandbox:` 引用。 diff --git a/docs/sandbox-cluster.md b/docs/sandbox-cluster.md index d6b0ab5d..9b81a7d1 100644 --- a/docs/sandbox-cluster.md +++ b/docs/sandbox-cluster.md @@ -21,7 +21,7 @@ - Node.js 20、npm 与 npx; - jq 及基础 Shell 工具; - `/workspace` 工作目录; -- UID 1000 的非 root `user` 账号(E2B 模板约定的账号名,WeKnora 以它执行脚本与文件操作)。 +- UID 1000 的 `user` 账号(E2B 模板约定的账号名,保留供按名字寻址的工具与 `sudo` 使用;WeKnora 执行脚本与文件操作默认用的是 root,见 `DefaultSandboxExecUser`)。 生产环境应使用与 WeKnora 相同的版本标签,不建议长期指向 `latest`。Skills 新增系统依赖时,应先更新标准镜像并重新注册模板,再切换集群的默认模板 ID。 @@ -36,7 +36,7 @@ 区别在于 Cube 变体额外注入了 envd。Cube 直接把 OCI 镜像变成模板,并以 `GET :49983/health` 探活,这个端点只有 envd 提供;不带 envd 的镜像建模板必然以 `connection refused` 失败。E2B 不需要这个变体,因为它的构建流程会自行注入 envd;Docker 后端则完全不需要 envd。详见 [Cube 自带镜像接入](https://cubesandbox.com/zh/guide/tutorials/bring-your-own-image.html)。 -Cube 变体只发布 linux/amd64——envd 的来源镜像 `cubesandbox-base` 没有 arm64,Cube 自身的 PVM 形态也只支持 x86_64。变体内 envd 以 root 运行,脚本仍按请求指定的账号执行,落在同一个 uid 1000 的 `user` 上。 +Cube 变体只发布 linux/amd64——envd 的来源镜像 `cubesandbox-base` 没有 arm64,Cube 自身的 PVM 形态也只支持 x86_64。变体内 envd 以 root 运行,脚本按请求指定的账号执行;WeKnora 默认显式指定 root。 ## CubeSandbox @@ -66,7 +66,7 @@ Cube 变体只发布 linux/amd64——envd 的来源镜像 `cubesandbox-base` 3. 点击“连接并继续”。WeKnora 先验证控制面地址与凭据,通过后才进入模板步骤并列出集群模板。**不会自动创建**。没有 WeKnora 标准模板时在占位卡片上点「创建」,会从 `wechatopenai/weknora-sandbox:main-cube` 发起构建。改 DNS 或需要换镜像时在 weknora 卡片上点「重建」:优先对现有标准模板做 in-place rebuild(模板 ID 不变);只有 redo 被拒绝时才先建新模板、成功后再删旧的。已安装 Skill 的配置(以及同一集群上其它已装 Skill 的配置)不能重建。失败模板同样用「重建」(CubeMaster 拒绝 redo、错误码 130400 时尤其需要)。 4. 模板构建状态会自动刷新。状态变为 `READY` 后才可选择并进入运行配置;界面显示模板名称、状态和版本,配置内部才保存该集群自己的 `template_id`。 -模板镜像必须提供 uid 1000 的 `user` 账号:WeKnora 以该账号执行脚本与文件操作。写权限只保证在 `/workspace/output` 与 `/workspace/input` 下。 +标准模板保留 uid 1000 的 `user` 兼容账号;WeKnora 默认显式以 root 执行脚本与文件操作。模板应提供可写的 `/workspace`,运行前会准备 `input`、`output` 和本次工作目录。技能安装的维护调用只准备其工作目录。自定义只读挂载仍限制 root 的写入。 多实例 WeKnora 必须配置 Redis,以共享 session 到 sandbox 的绑定。只有单实例开发环境才应使用内存绑定。 diff --git a/docs/sandbox-docker-backend.md b/docs/sandbox-docker-backend.md index dc9cb116..051cf04e 100644 --- a/docs/sandbox-docker-backend.md +++ b/docs/sandbox-docker-backend.md @@ -33,7 +33,7 @@ CubeSandbox / E2B 的集群与模板见 [沙箱集群与标准模板](./sandbox- ## 现在的形态 -一个沙箱就是一个容器。标准镜像以 `USER user` 结尾,创建时覆盖为 uid 0,这样入口才能在 `/var/lib` 写下活跃标记;脚本仍以 `user` 执行。PID 1 是 `sleep infinity`,所有工作都通过 exec 进去做。 +一个沙箱就是一个容器。标准镜像以 `USER root` 结尾,创建时仍显式指定 uid 0,这样即便换成以非 root 结尾的自定义镜像,入口也能在 `/var/lib` 写下活跃标记;脚本按每次调用指定的账号执行,默认是 root(见 `DefaultSandboxExecUser`)。一个会话独占一个沙箱,容器内没有第二个账号需要用文件权限隔开,隔离边界在容器本身。PID 1 是 `sleep infinity`,所有工作都通过 exec 进去做。 这层 wrapper 是通过 `Entrypoint` 下发并把 `Cmd` 显式清空的:daemon 会把镜像自带的 ENTRYPOINT 拼到 Cmd 前面,所以只设 Cmd 时,任何声明了 ENTRYPOINT 的镜像(本文件的 @@ -75,32 +75,29 @@ ENTRYPOINT 拼到 Cmd 前面,所以只设 Cmd 时,任何声明了 ENTRYPOINT 执行命令的东西——包括普通技能脚本,不需要 root——都可以起一个后台循环持续 `touch` 标记, 把自己维持成「一直活跃」。当前没有硬寿命上限,需要的话应由部署方在 daemon 侧限制。 -**所有 exec 都以 `user`(uid 1000) 运行,没有例外。** 脚本执行、`shell_exec`、全部文件操作、 -以及 manager 自己的产物目录 bootstrap 都跑在沙箱账号下;`RemoteExecRequest.User` 留空时 -适配器解析成 `DefaultSandboxExecUser` 而不是 root,漏传账号只会失去权限、不会拿到权限。 +**所有 exec 都显式指定账号,默认是 root。** 脚本执行、`shell_exec`、全部文件操作、以及 +manager 自己的产物目录 bootstrap 都跑在 `DefaultSandboxExecUser` 下;`RemoteExecRequest.User` +留空时适配器解析成这个常量而不是镜像声明的账号,因此一次调用落到哪个账号,不取决于空间选了 +哪个后端。 -bootstrap 尤其不能以 root 跑:产物目录位于会话自己可写的 `/workspace` 下,而 `chown`/`chmod` -会跟随符号链接。会话只要把产物目录换成指向 `/etc` 的链接,一次 root bootstrap 就会把 `/etc` -的属主交给沙箱账号,接着改写 `passwd` 即可让该账号在下一次 exec 时变成 uid 0(真机验证过)。 -以沙箱账号执行时这条链直接断在内核:`chown` 对不属于自己的目标一律失败。 +默认 root 的前提是一个会话独占一个沙箱:容器内没有第二个租户的文件需要用 mode bit 隔开,跨 +租户与宿主机的隔离都落在容器边界上。镜像里仍然保留 uid 1000 的 `user` 账号,供 E2B/Cube 侧 +按名字寻址的工具以及 `sudo` 使用。 容器 `CapDrop: ALL` 之后额外补回 CHOWN/DAC_OVERRIDE/FOWNER/FSETID/SETGID/SETUID/KILL, -Docker 默认给的 NET_RAW、MKNOD、SYS_CHROOT 等一律不给。注意这批 capability 是给容器内 -**root** 用的(装包、修属主),而目前没有任何 exec 以 root 运行,因此它们对现有路径是冗余的; -保留是为了自定义镜像里用 `sudo` 装包的场景,收紧它们是可以独立推进的加固项。 +Docker 默认给的 NET_RAW、MKNOD、SYS_CHROOT 等一律不给。exec 以 root 运行之后这批 capability +就是实际在用的(装包、修属主都要);收紧它们需要先确认技能安装路径不依赖,是可以独立推进的 +加固项。 -**文件操作走 exec,不走 archive 接口。** archive 接口(`PUT`/`GET`/`HEAD /archive`)由 daemon -执行,这意味着两件事同时成立:它忽略 exec user 一律以 root 操作,并且会在路径解析时跟随符号 -链接。沙箱账号对 `/workspace` 有写权限,而调用侧的路径守卫都是字符串前缀比较,于是 -`ln -s /root /workspace/output/esc` 之后,`/workspace/output/esc/secret.txt` 既能通过守卫, -又会被 daemon 以 root 读出来(真机验证过,不是推演)。改成以沙箱账号 exec 之后,能不能读写 -由内核判定,符号链接指向哪里都不再重要,也不存在「先校验后使用」之间被换掉链接的窗口。 -`Stat` 用 `find`,它不跟随**最后一段**路径,因此路径本身是链接时会如实报告为 `other` 类型, -要求正规文件的调用方在尝试读取之前就会拒绝。 +**文件操作走 exec,不走 archive 接口。** exec 为文件操作统一提供显式账号、超时控制和活跃标记更新; +archive 接口由 daemon 执行,不遵循这些逐次 exec 设置。默认账号已经是 root,因此这两条路径都不能 +靠容器内的属主和 mode bit 把文件访问限制在 `/workspace`。路径前缀检查也不是符号链接隔离: +`/workspace/output/esc` 指向 `/root` 时,经它访问的文件仍可能由 root exec 读写。 -这个保证到最后一段为止:中间层的链接由内核在路径解析时展开,`/workspace/output/链接/passwd` -仍会 stat 成普通文件(真机验证过)。因此「只读产物目录」是一个约定而非权限边界——绕过它读到的 -东西,沙箱账号本来就能用 `shell_exec` 读到,真正的边界始终是内核的权限检查。 +`Stat` 用 `find`,不跟随**最后一段**链接,会将该链接报告为 `other`;中间层链接仍由路径解析展开, +所以 `/workspace/output/链接/passwd` 可能被报告为普通文件。单独的 Stat 检查也不能防止检查后替换链接。 +产物目录约定不构成文件系统权限边界。宿主机和跨会话隔离依赖容器及挂载配置,真正的只读挂载仍限制 root。 +若后续文件 API 需要严格的路径隔离,应在路径解析和实际访问时实施,不能沿用「exec 的内核账号检查会挡住链接」的前提。 archive 接口里只剩 `HEAD` 还在用,且仅用于读固定路径的活跃标记。 @@ -131,8 +128,9 @@ archive 接口里只剩 `HEAD` 还在用,且仅用于读固定路径的活跃 「允许访问私网地址」开关过一遍 `SafeDialControl`,这样保存校验解析到公网、连接时被 重解析到 169.254.169.254 的情况也拦得住。unix socket 不经过这一层。 -镜像要求:uid 1000 的 `user` 账号、`/workspace/{input,output}` 归该账号所有、 -GNU `find`(`-printf`)与 coreutils `timeout`。`docker/Dockerfile.sandbox` 产出的标准镜像满足这些, +镜像要求:可按名执行的 `root` 账号、可写的 `/workspace`、 +GNU `find`(`-printf`)与 coreutils `timeout`。标准镜像另保留 uid 1000 的 `user` 账号, +并将工作区属主设为该账号以兼容显式选择 `user` 的工具;默认 root 执行不依赖这个属主。`docker/Dockerfile.sandbox` 产出的标准镜像满足这些, Debian 系基础镜像天然带 find 和 timeout。 部署形态: diff --git a/docs/sandbox-protocol.md b/docs/sandbox-protocol.md index 23a79083..9242dde0 100644 --- a/docs/sandbox-protocol.md +++ b/docs/sandbox-protocol.md @@ -60,9 +60,9 @@ - 认证:envd 要求 `Authorization: Basic base64(":")`,SDK 发的是 `X-User-ID` 头。E2B Cloud 对此宽容,其他实现直接返回 `unauthenticated: no user specified`。 - 文件上传:envd 的 `POST /files` 只接受 `multipart/form-data`,SDK 发的是裸 `application/octet-stream`,会得到 500。 -另外健康探针改用 `GET /v2/sandboxes`:旧的 `GET /sandboxes` 已不在客户端其他调用路径上,部分 E2B 兼容实现也只实现了 v2,用旧接口探活会把健康的后端判成不可用。文件操作现在也显式声明执行账号(`user`),与脚本运行账号保持一致,而不是依赖各实现的默认值。 +另外健康探针改用 `GET /v2/sandboxes`:旧的 `GET /sandboxes` 已不在客户端其他调用路径上,部分 E2B 兼容实现也只实现了 v2,用旧接口探活会把健康的后端判成不可用。文件操作显式声明执行账号(默认 `root`,见 `DefaultSandboxExecUser`),与脚本运行账号保持一致,而不是依赖各实现的默认值。 -模板镜像需要提供 `user` 账号(uid 1000),这是 E2B 模板的既定约定;WeKnora 以该账号执行脚本与文件操作。写权限只保证在 `/workspace/output`(产物目录,执行前由 WeKnora 创建并授权)与 `/workspace/input`(附件暂存)下,脚本不应假设 `/workspace` 根目录可写。 +标准模板保留 `user` 账号(uid 1000)供兼容工具显式选用;WeKnora 默认以 `root` 执行脚本与文件操作。模板应提供可写的 `/workspace`,普通调用会准备 `/workspace/output`、`/workspace/input` 和本次工作目录,维护调用只准备其工作目录。工作目录参数的前缀检查不是 root 命令的文件系统隔离边界;自定义只读挂载也不会因为使用 root 而变成可写。 ## 一致性测试 diff --git a/internal/agent/prompts.go b/internal/agent/prompts.go index e94ed8e3..51caba88 100644 --- a/internal/agent/prompts.go +++ b/internal/agent/prompts.go @@ -265,11 +265,19 @@ func formatToolGuidance(names []string) string { b.WriteString("Use read_file for workspace files and listed skill:// resources. In older instructions, translate read_skill(skill_name, file_path) to read_file(path=skill:///) and read_sandbox_file to read_file.\n") } if has("shell_exec") || has("write_sandbox_file") { - b.WriteString("Session workspace: /workspace. Preserve uploaded originals in /workspace/input; create scratch files under /workspace and deliverables under /workspace/output. Commands start from their specified working directory on every call. Files and installed packages persist within the session.\n") + b.WriteString("Session workspace: /workspace. Preserve uploaded originals in /workspace/input. " + + "/workspace/output is the only directory collected for download, " + + "so it takes finished deliverables only; " + + "keep drafts and intermediate files in another directory under /workspace. " + + "Commands start from their specified working directory on every call. " + + "Files and installed packages persist within the session.\n") b.WriteString(sandboxArtifactReferenceGuidance()) } if has("shell_exec") && has("read_file") { - b.WriteString("For listed skills, run bundled scripts and your own scripts with shell_exec(skill_name=..., command=...). This selects an installed skill's runtime or stages host skill resources, and applies scoped credentials; use $WEKNORA_SKILL_DIR for bundled files. The installed tree is read-only.\n") + b.WriteString("For listed skills, run bundled scripts and your own scripts with " + + "shell_exec(skill_name=..., command=...). This selects an installed skill's runtime " + + "or stages host skill resources, and applies scoped credentials; " + + "use $WEKNORA_SKILL_DIR for bundled files.\n") b.WriteString("In older instructions, translate execute_skill_script(skill_name, script_path, ...) to shell_exec(skill_name=..., command=...).\n") } diff --git a/internal/agent/skills/env_resolver.go b/internal/agent/skills/env_resolver.go index 83134c61..249da432 100644 --- a/internal/agent/skills/env_resolver.go +++ b/internal/agent/skills/env_resolver.go @@ -3,9 +3,8 @@ package skills import ( "context" "fmt" + "path" "strings" - - "github.com/Tencent/WeKnora/internal/sandbox" ) // SkillEnvResolver produces the environment one execution gets. It is separate @@ -67,24 +66,25 @@ func ApplyResolvedEnv(env, resolved map[string]string) { } } -// applySessionPackagePath prepends the per-session extra-packages directory -// so a frozen skill venv can still see `pip install --target` extras without -// mutating the snapshot. Missing directories are ignored by the interpreters. -func applySessionPackagePath(env map[string]string, skillName string) { - if env == nil { +// applySkillNodePath puts the skill's own node_modules on NODE_PATH, after +// anything the caller supplied. +// +// Python gets no equivalent on purpose. Its dependencies are reached through +// the skill's own virtualenv interpreter, which the shell wrapper puts first +// on PATH and which already carries its site-packages. A PYTHONPATH entry +// would have to name that site-packages directory by interpreter version to +// be importable at all, and pointing it at the venv root — as an overlay-era +// path did — resolves nothing. +func applySkillNodePath(env map[string]string, skillDir string) { + if env == nil || skillDir == "" { return } - dir := sandbox.SessionSkillPackageDir(skillName) - if dir == "" { - return - } - prependPathEnv(env, pythonPathEnvVar, dir) - prependPathEnv(env, nodePathEnvVar, dir) + appendPathEnv(env, nodePathEnvVar, path.Join(skillDir, "node_modules")) } -func prependPathEnv(env map[string]string, key, dir string) { +func appendPathEnv(env map[string]string, key, dir string) { if existing := strings.TrimSpace(env[key]); existing != "" { - env[key] = dir + ":" + existing + env[key] = existing + ":" + dir return } env[key] = dir diff --git a/internal/agent/skills/env_resolver_test.go b/internal/agent/skills/env_resolver_test.go index e19be416..7817966d 100644 --- a/internal/agent/skills/env_resolver_test.go +++ b/internal/agent/skills/env_resolver_test.go @@ -28,14 +28,20 @@ func TestApplyResolvedEnvAddsNewKeysAndKeepsExistingOnes(t *testing.T) { require.Equal(t, "/workspace/output", env[artifactHistoryEnvVar]) } -func TestApplySessionPackagePathPrependsPythonAndNodePath(t *testing.T) { - env := map[string]string{pythonPathEnvVar: "/already"} +// Python is deliberately absent here: the skill's venv interpreter carries its +// own packages, so an injected PYTHONPATH would only be able to shadow them. +func TestApplySkillNodePathAppendsAfterTheCallersValue(t *testing.T) { + skillDir := sandbox.SkillsImageRoot + "/律师助手" - applySessionPackagePath(env, "律师助手") + env := map[string]string{nodePathEnvVar: "/already"} + applySkillNodePath(env, skillDir) + require.Equal(t, "/already:"+skillDir+"/node_modules", env[nodePathEnvVar]) - dir := sandbox.SessionSkillPackageDir("律师助手") - require.Equal(t, dir+":/already", env[pythonPathEnvVar]) - require.Equal(t, dir, env[nodePathEnvVar]) + empty := map[string]string{} + applySkillNodePath(empty, skillDir) + require.Equal(t, skillDir+"/node_modules", empty[nodePathEnvVar], + "a caller that supplied nothing must not get a leading separator") + require.NotContains(t, empty, pythonPathEnvVar) } // The message is read by the agent and relayed verbatim to a person, so it has diff --git a/internal/agent/skills/manager.go b/internal/agent/skills/manager.go index 88c5419c..c2fd32a7 100644 --- a/internal/agent/skills/manager.go +++ b/internal/agent/skills/manager.go @@ -35,9 +35,10 @@ const artifactHistoryEnvVar = "WEKNORA_SKILL_HISTORY_ROOT" // install-time verification pass exports the same name. const skillDirEnvVar = "WEKNORA_SKILL_DIR" -// pythonPathEnvVar / nodePathEnvVar carry the per-session extra-packages -// overlay (see sandbox.SessionSkillPackageDir). They are injected rather than -// left for the skill to declare so a stored PYTHONPATH cannot displace them. +// nodePathEnvVar carries the skill's own node_modules. pythonPathEnvVar is +// never injected — a skill's Python packages arrive through its venv +// interpreter — but stays on the blacklist below, because a stored PYTHONPATH +// could otherwise shadow exactly those packages. const pythonPathEnvVar = "PYTHONPATH" const nodePathEnvVar = "NODE_PATH" diff --git a/internal/agent/skills/shell_environment.go b/internal/agent/skills/shell_environment.go index de99e62d..69ca9398 100644 --- a/internal/agent/skills/shell_environment.go +++ b/internal/agent/skills/shell_environment.go @@ -32,8 +32,7 @@ func (m *Manager) PrepareShellEnvironment(ctx context.Context, sessionID, skillN for k, v := range env { runtimeEnv[k] = v } - applySessionPackagePath(runtimeEnv, skillName) - runtimeEnv[nodePathEnvVar] += ":" + path.Join(dir, "node_modules") + applySkillNodePath(runtimeEnv, dir) runtimeEnv[skillDirEnvVar] = dir runtimeEnv[artifactOutputEnvVar] = ArtifactOutputDir() runtimeEnv[artifactHistoryEnvVar] = ArtifactOutputDir() diff --git a/internal/agent/skills/shell_environment_test.go b/internal/agent/skills/shell_environment_test.go index 01b8e8a9..64125c84 100644 --- a/internal/agent/skills/shell_environment_test.go +++ b/internal/agent/skills/shell_environment_test.go @@ -2,6 +2,7 @@ package skills import ( "context" + "strings" "testing" "github.com/Tencent/WeKnora/internal/sandbox" @@ -24,8 +25,10 @@ func TestShellEnvironmentSelectsOnlyAllowedInstalledSkills(t *testing.T) { require.Contains(t, wrapped, "/pdf/.venv/bin") require.Contains(t, wrapped, "--noprofile --norc") require.Equal(t, "caller", actual["TOKEN"]) - require.Equal(t, "/workspace/.skill-packages/pdf:/workspace/custom", actual["PYTHONPATH"]) - require.Contains(t, actual["NODE_PATH"], "/pdf/node_modules") + require.Equal(t, "/workspace/custom", actual["PYTHONPATH"], + "the skill's Python packages arrive through its venv interpreter on PATH, "+ + "so nothing here may displace what the caller asked for") + require.Equal(t, "/pdf/node_modules", strings.TrimPrefix(actual["NODE_PATH"], sandbox.SkillsImageRoot)) require.Equal(t, "/workspace/custom", env["PYTHONPATH"], "caller environment must not be mutated") require.Len(t, env, 2) for _, name := range []string{"other", "missing", "../pdf"} { diff --git a/internal/agent/skills/skill.go b/internal/agent/skills/skill.go index 550dd846..5d2a2159 100644 --- a/internal/agent/skills/skill.go +++ b/internal/agent/skills/skill.go @@ -237,8 +237,9 @@ func ParseSkillMetadata(content string) (*SkillMetadata, error) { // IsOnDemandInstallerPath reports whether path is a first-use dependency // installer (scripts/install_deps.py and friends). Skills ship these to defer -// optional packages to chat time, which cannot work once the skill tree is -// snapshotted read-only. The installer agent's prompt ("install these extras +// optional packages to chat time, which is the wrong moment: the work is +// repeated by every session built from the image and fails wherever the +// sandbox has no egress. The installer agent's prompt ("install these extras // now") and the runtime hint ("skip this installer") key off the same list. func IsOnDemandInstallerPath(scriptPath string) bool { base := strings.ToLower(filepath.Base(strings.TrimSpace(scriptPath))) diff --git a/internal/agent/tools/read_file.go b/internal/agent/tools/read_file.go index 22cba0d9..c143c5dc 100644 --- a/internal/agent/tools/read_file.go +++ b/internal/agent/tools/read_file.go @@ -120,7 +120,12 @@ func (t *ReadFileTool) readSkillResource(ctx context.Context, input ReadFileInpu if !installed { dir = "a session directory prepared automatically from this skill package" } - fmt.Fprintf(&b, "Execution: shell_exec(skill_name=%q, command=...). Use $WEKNORA_SKILL_DIR for bundled scripts (resources: %s); cwd defaults to /workspace. Installed image skills are read-only; host skill resources are staged into the session automatically (host virtualenvs and node_modules are not copied). Deliverables belong in /workspace/output.\n\n", name, dir) + fmt.Fprintf(&b, "Execution: shell_exec(skill_name=%q, command=...). "+ + "Use $WEKNORA_SKILL_DIR for bundled scripts (resources: %s); "+ + "cwd defaults to /workspace. "+ + "Host skill resources are staged into the session automatically "+ + "(host virtualenvs and node_modules are not copied). "+ + "Deliverables belong in /workspace/output.\n\n", name, dir) } else { b.WriteString("Execution is unavailable: this agent has no sandbox shell. The skill instructions can be read; configuring a shell-capable sandbox is required to run scripts.\n\n") } diff --git a/internal/agent/tools/sandbox_write.go b/internal/agent/tools/sandbox_write.go index 2c12ad7e..e09d5791 100644 --- a/internal/agent/tools/sandbox_write.go +++ b/internal/agent/tools/sandbox_write.go @@ -7,8 +7,12 @@ // Design notes: // - Session-scoped: the sandbox is resolved from ToolExecContext.SessionID. // - Path guardrail: writes sit under /workspace and never under -// /workspace/input (staged attachments stay read-only). Prefer -// /workspace/output for files the user should download. +// /workspace/input (staged attachments are the user's, not ours). +// /workspace/output is what gets collected for download, so the +// description reserves it for finished deliverables and sends scratch +// work elsewhere under /workspace. Only the /workspace/input half is +// enforced here; the rest is guidance, because "finished" is a judgement +// the tool cannot make. // - Content stays out of ToolResult.Data/Output: the model already has the // bytes it just sent. The result is path + size so the next call can // shell_exec the file. @@ -93,7 +97,9 @@ type SandboxFileSink interface { // writeSandboxFileDescription carries one %s, filled with the size guidance // derived from the round's completion-token budget. const writeSandboxFileDescription = `Create, overwrite, or append a text file under /workspace, excluding /workspace/input. -Use /workspace/output for deliverables. Send both path and content (path first). Use edit_sandbox_file for small changes to an existing file. File content does not pass through shell quoting. +/workspace/output is collected for download, so it holds finished deliverables only; put drafts, scratch and +intermediate files in any other directory under /workspace. Send both path and content (path first). +Use edit_sandbox_file for small changes to an existing file. File content does not pass through shell quoting. Large files: first call uses mode=overwrite (default), subsequent calls use mode=append with only the next chunk. Keep calls in order and inspect the reported running byte count. A refused/truncated call wrote nothing; retry that chunk with complete JSON, never duplicate successful chunks. %s Binary content is not accepted. The result reports the absolute path and total size without echoing content.` @@ -104,9 +110,9 @@ Binary content is not accepted. The result reports the absolute path and total s // depends on the agent's per-round token budget and is stated in the tool // description, which is built per session. type WriteSandboxFileInput struct { - Path string `json:"path" jsonschema:"Absolute or /workspace-relative sandbox path to write. Must sit under /workspace and must not sit under /workspace/input. Prefer /workspace/output for downloadable artifacts."` - Content string `json:"content" jsonschema:"Text to write. In overwrite mode this is the full file; in append mode it is only the next chunk. Keep near the per-call size stated in the tool description so the response is not cut off. Do not send binary bytes."` //nolint:lll // one-line struct tag - Mode string `json:"mode,omitempty" jsonschema:"How to apply content: 'overwrite' (default) replaces the file, 'append' adds to the end of an existing file. Use append to build a large file across several calls."` //nolint:lll // one-line struct tag + Path string `json:"path" jsonschema:"Absolute or /workspace-relative sandbox path to write. Must sit under /workspace and must not sit under /workspace/input. Use /workspace/output for finished deliverables only; intermediate files belong elsewhere under /workspace."` //nolint:lll // JSON schema tags must remain on one line. + Content string `json:"content" jsonschema:"Text to write. In overwrite mode this is the full file; in append mode it is only the next chunk. Keep near the per-call size stated in the tool description so the response is not cut off. Do not send binary bytes."` //nolint:lll // one-line struct tag + Mode string `json:"mode,omitempty" jsonschema:"How to apply content: 'overwrite' (default) replaces the file, 'append' adds to the end of an existing file. Use append to build a large file across several calls."` //nolint:lll // one-line struct tag } // WriteSandboxFileTool writes a text file into the session sandbox. diff --git a/internal/agent/tools/shell_exec.go b/internal/agent/tools/shell_exec.go index 4ec4da30..81634ee1 100644 --- a/internal/agent/tools/shell_exec.go +++ b/internal/agent/tools/shell_exec.go @@ -128,12 +128,24 @@ var shellExecBlacklist = []struct { var shellExecTool = BaseTool{ name: ToolShellExec, - description: `Execute a command in the current session's isolated sandbox as its non-root user. Never runs on the host. + description: `Execute a command in the current session's isolated sandbox as root. +The sandbox belongs to this session alone; nothing here runs on the host. - CWD defaults to /workspace on every call; cd does not persist. work_dir selects another directory under /workspace and missing directories are created as the same user. - Use ls/find to discover files, grep/awk to search, and cat/head/tail/sed to inspect text. Read known paths directly; no mandatory discovery call. - Use write_sandbox_file for scripts or large text; edit_sandbox_file for precise changes. Commands are limited to 8192 bytes. Execution is synchronous (no nohup or trailing &). -- skill_name selects a listed skill for this call. Installed skills use their Python virtualenv and Node modules; host skill resources are automatically staged in the session with the system runtime. Scoped credentials apply to both. Example: skill_name="pdf", command="python3 report.py". Run bundled scripts via "$WEKNORA_SKILL_DIR/scripts/...". Omit skill_name for system commands. -- /workspace/input contains user attachments: preserve originals. /workspace/output holds downloadable deliverables. Installed skills under /opt/weknora/tenant/skills are read-only. Install Python extras WITHOUT skill_name using python3 -m pip install --target /workspace/.skill-packages/ , then run with skill_name. System package installation requires the skill installer; ordinary sessions cannot apt-get or elevate privileges. +- skill_name selects a listed skill for this call. Installed skills use their Python virtualenv and Node modules; + host resources are staged automatically and use the system runtime until a local .venv is created. + Scoped credentials apply to both. Example: skill_name="pdf", command="python3 report.py". + Run bundled scripts via "$WEKNORA_SKILL_DIR/scripts/...". Omit skill_name for system commands. +- /workspace/input contains user attachments: preserve originals. /workspace/output is the only directory collected + for download, so it takes finished deliverables only; keep scratch and intermediate files elsewhere under /workspace. + apt-get is available when the sandbox network policy allows it; permanent dependencies belong in the skill installer. +- Install extras with skill_name set and the default work_dir: + ` + "`" + skillPythonPackageInstallCommand + "`" + ` (no pip needed), or + ` + "`" + skillNodePackageInstallCommand + "`" + `. + If .venv is absent, create it with python3 -m venv --without-pip "${WEKNORA_SKILL_DIR:?}/.venv". + Without uv, run the venv Python with -m ensurepip --upgrade before -m pip install. + Changes live and die with this session. - Non-zero exit_code is a command result: inspect stderr before deciding whether a corrected call is useful. Transport failures/timeouts are tool failures. Changing tools does not change permissions; do not repeat a denied operation through another tool. - stdout/stderr have independent byte limits, preserving head and tail when truncated. Full output is not automatically saved; redirect verbose commands to a workspace log when it must be retained. Binary bytes are suppressed. - Reference collected deliverables as ![description](sandbox:) using the exact filename.`, @@ -162,7 +174,7 @@ type ShellExecInput struct { // uses the caller-scoped SkillEnvResolver, so values // are per-caller (taken from ctx) and never persist. Omitting it leaves // shell_exec's behaviour unchanged. - SkillName string `json:"skill_name,omitempty" jsonschema:"Optional available skill name. Selects its installed runtime or stages its host resources, plus package overlay and scoped credentials. CWD remains /workspace. Omit for system commands."` + SkillName string `json:"skill_name,omitempty" jsonschema:"Optional available skill name. Selects its installed runtime or stages its host resources, plus scoped credentials. CWD remains /workspace. Omit for system commands."` //nolint:lll // JSON schema tags must remain on one line. } // SandboxInstallCommandExecutor is the privileged counterpart of @@ -698,8 +710,8 @@ func shellExecRecoveryHint(exitCode int, command, stderr string) string { if h := shellCommandNotFoundHint(exitCode, command, stderr); h != "" { parts = append(parts, h) } - if isFrozenSkillVenvFailure(stderr) { - parts = append(parts, "Hint: "+frozenSkillTreeGuidance(skillNameFromShellCommand(command))) + if isSkillVenvInstallFailure(stderr) { + parts = append(parts, "Hint: "+skillVenvFailureGuidance(skillNameFromShellCommand(command), stderr)) return strings.Join(parts, "\n") } if h := shellMissingModuleHint(command, stderr); h != "" { @@ -717,18 +729,27 @@ func (t *ShellExecTool) recoveryHint(skillName string, exitCode int, command, st if t.skillEnvironment == nil { return shellExecRecoveryHint(exitCode, command, stderr) } - lower := strings.ToLower(stderr) - if strings.Contains(lower, "permission denied") || strings.Contains(lower, "read-only file system") { - return "Permission denied: commands and file tools share the same user. Use /workspace for scratch files and /workspace/output for deliverables. The installed skill tree is read-only; switching tools, chmod, sudo, or retrying the same write cannot grant access." + if isSkillVenvInstallFailure(stderr) { + if skillName == "" { + skillName = skillNameFromShellCommand(command) + } + return skillVenvFailureGuidance(skillName, stderr) + } + if isPermissionFailure(stderr) || isReadOnlyFilesystemFailure(stderr) { + return "Permission denied: commands and file tools share the same user. " + + "Inspect path permissions and mount restrictions; use a writable workspace location. " + + "Switching tools or retrying the same write does not grant access." } if isMissingInterpreterModule(stderr) { if skillName == "" { return "If this command needs an installed skill's packages, repeat shell_exec with that skill_name to select its runtime. Otherwise install the missing dependency in the writable workspace." } if strings.Contains(stderr, "Cannot find module") || strings.Contains(stderr, "MODULE_NOT_FOUND") { - return "The selected skill runtime could not resolve this Node module. For custom scripts, install dependencies in a writable workspace project. NODE_PATH supports CommonJS; ESM imports resolve relative to the script and need a local dependency tree. Preserve the installed skill directory." + return missingSkillPackageGuidance(skillName) + + " NODE_PATH supports CommonJS; ESM imports resolve relative to the script, " + + "so custom ESM scripts need dependencies in their own workspace project." } - return fmt.Sprintf("The selected skill runtime lacks this module. Install extras with shell_exec WITHOUT skill_name: python3 -m pip install --target %s ; then rerun with skill_name=%q.", sandbox.SessionSkillPackageDir(skillName), skillName) + return "The selected skill runtime lacks this module. " + missingSkillPackageGuidance(skillName) } return shellCommandNotFoundHint(exitCode, command, stderr) } @@ -749,7 +770,7 @@ func shellMissingModuleHint(command, stderr string) string { } func isMissingInterpreterModule(stderr string) bool { - if isFrozenSkillVenvFailure(stderr) { + if isSkillVenvInstallFailure(stderr) { return false } return strings.Contains(stderr, "ModuleNotFoundError") || diff --git a/internal/agent/tools/shell_exec_test.go b/internal/agent/tools/shell_exec_test.go index b1fee614..1a97a95c 100644 --- a/internal/agent/tools/shell_exec_test.go +++ b/internal/agent/tools/shell_exec_test.go @@ -20,16 +20,20 @@ type fakeShellExecutor struct { err error timeout time.Duration calls int + command string + workDir string + env map[string]string } func (f *fakeShellExecutor) ExecShellCommand( _ context.Context, _ string, - _ string, - _ string, + command string, + workDir string, timeout time.Duration, - _ map[string]string, + env map[string]string, ) (*sandbox.ExecuteResult, error) { + f.command, f.workDir, f.env = command, workDir, env f.timeout = timeout f.calls++ if f.err != nil { @@ -220,7 +224,10 @@ func TestShellExecSuppressesBinaryStreams(t *testing.T) { func TestShellExecDescriptionDefinesOneExecutionEntry(t *testing.T) { description := NewShellExecTool(&fakeShellExecutor{}, nil).Description() - for _, fact := range []string{"/workspace", "skill_name", "virtualenv", "read-only", "non-root", "write_sandbox_file", "edit_sandbox_file", "not automatically saved"} { + for _, fact := range []string{ + "/workspace", "skill_name", "virtualenv", "as root", "die with this session", + "write_sandbox_file", "edit_sandbox_file", "not automatically saved", + } { require.Contains(t, description, fact) } require.NotContains(t, description, "execute_skill_script") @@ -490,14 +497,16 @@ func TestSkillNameFromShellCommandExtractsImageSkill(t *testing.T) { assert.Empty(t, skillNameFromShellCommand(`python3 -c "print(1)"`)) } -func TestShellExecAllowsOverlayInstallThatMentionsTheSkillTree(t *testing.T) { +func TestShellExecAllowsAnInstallThatMentionsTheSkillTree(t *testing.T) { // Previously an up-front command blacklist rejected this recovery path - // because the line contained both `pip install` and the skills root. + // because the line contained both `pip install` and the skills root. It is + // now the recommended one: a missing package goes into the skill's own venv. executor := &fakeShellExecutor{result: &sandbox.ExecuteResult{ExitCode: 0}} tool := NewShellExecTool(executor, nil) result, err := tool.Execute(shellExecTestContext(), json.RawMessage( - `{"command":"python3 -m pip install --target /workspace/.skill-packages/foo -r /opt/weknora/tenant/skills/foo/requirements.txt"}`, + `{"command":"/opt/weknora/tenant/skills/foo/.venv/bin/python -m pip install -r `+ + `/opt/weknora/tenant/skills/foo/requirements.txt"}`, )) require.NoError(t, err) require.True(t, result.Success, result.Error) @@ -527,8 +536,8 @@ func TestShellExecHintsWhenVenvHasNoPip(t *testing.T) { )) require.NoError(t, err) require.True(t, result.Success) - assert.Contains(t, result.Output, "frozen") - assert.Contains(t, result.Output, "/workspace/.skill-packages/律师助手") + assert.Contains(t, result.Output, skillPythonPackageInstallCommand) + assert.NotContains(t, result.Output, "/workspace/.skill-packages") assert.NotContains(t, result.Output, "write_sandbox_file") } @@ -550,3 +559,65 @@ func TestShellExecNeverSilentlyFallsBackFromNamedSkill(t *testing.T) { require.Zero(t, executor.calls) require.Contains(t, result.Error, "no skill environment") } + +func TestShellExecPackageRecoveryKeepsWorkspaceCWD(t *testing.T) { + for _, command := range []string{skillNodePackageInstallCommand, skillPythonPackageInstallCommand} { + executor := &fakeShellExecutor{} + tool := NewShellExecTool(executor, nil).WithSkillEnvironment(shellTestSkillEnvironment(t)) + args, err := json.Marshal(ShellExecInput{ + SkillName: "pdf-tools", Command: strings.ReplaceAll(command, "", "test-package"), + }) + require.NoError(t, err) + result, err := tool.Execute(shellExecTestContext(), args) + require.NoError(t, err) + require.True(t, result.Success, "%+v", result) + require.Equal(t, 1, executor.calls) + require.Equal(t, "/workspace", executor.workDir) + require.Equal(t, sandbox.SkillsImageRoot+"/pdf-tools", executor.env["WEKNORA_SKILL_DIR"]) + require.Contains(t, executor.command, "${WEKNORA_SKILL_DIR:?}") + } +} + +func TestShellExecPackageRecoveryUsesNamedEnvironment(t *testing.T) { + tool := NewShellExecTool(&fakeShellExecutor{}, nil).WithSkillEnvironment(shellTestSkillEnvironment(t)) + for _, name := range []string{"pdf-tools", "host-skill"} { + for _, stderr := range []string{ + "No module named pip", "ModuleNotFoundError: No module named 'docx'", "Cannot find module 'example'", + } { + hint := tool.recoveryHint(name, 1, "python3 script.py", stderr) + require.Contains(t, hint, `skill_name="`+name+`"`) + require.Contains(t, hint, skillPythonPackageInstallCommand) + require.Contains(t, hint, skillPythonVenvCreateCommand) + require.Contains(t, hint, skillNodePackageInstallCommand) + require.NotContains(t, hint, sandbox.SkillsImageRoot) + require.NotContains(t, hint, "work_dir=", "package installation must keep the default workspace CWD") + } + } +} + +func TestShellExecVenvAccessFailuresPrecedeGenericPermissionHints(t *testing.T) { + for _, withEnvironment := range []bool{false, true} { + tool := NewShellExecTool(&fakeShellExecutor{}, nil) + if withEnvironment { + tool.WithSkillEnvironment(shellTestSkillEnvironment(t)) + } + for _, message := range []string{"Permission denied", "Operation not permitted", "EPERM"} { + hint := tool.recoveryHint("pdf-tools", 1, "python3 script.py", + message+": /skill/.venv/lib/site-packages") + require.Contains(t, hint, "skill virtualenv denied access") + require.Contains(t, hint, "Once the environment is writable") + require.Contains(t, hint, skillPythonPackageInstallCommand) + } + for _, message := range []string{"Read-only file system", "Read-only filesystem", "EROFS"} { + hint := tool.recoveryHint("pdf-tools", 1, "python3 script.py", + message+": /skill/.venv/lib/site-packages") + require.Contains(t, hint, "skill virtualenv is on a read-only filesystem") + require.Contains(t, hint, "cannot write through a read-only mount") + require.NotContains(t, hint, "pip install") + unrelated := tool.recoveryHint("pdf-tools", 1, "touch report.txt", + message+": /workspace/output/report.txt") + require.NotContains(t, unrelated, "skill virtualenv") + require.NotContains(t, unrelated, skillPythonPackageInstallCommand) + } + } +} diff --git a/internal/agent/tools/shell_runtime_integration_test.go b/internal/agent/tools/shell_runtime_integration_test.go index ef052a40..333c536e 100644 --- a/internal/agent/tools/shell_runtime_integration_test.go +++ b/internal/agent/tools/shell_runtime_integration_test.go @@ -8,6 +8,7 @@ import ( "fmt" "os" "path/filepath" + "strings" "testing" "time" @@ -40,8 +41,8 @@ func TestShellRuntimeIntegration(t *testing.T) { ctx = WithToolExecContext(ctx, &ToolExecContext{SessionID: sessionID}) t.Cleanup(func() { require.NoError(t, mgr.DestroySession(base, sessionID)) }) - // The install identity deliberately creates a frozen venv with a unique - // module that the system Python cannot import. + // A previously installed image may contain a read-only venv without pip. + // Root sessions must still be able to use and update their own copy. dir := sandbox.SkillsImageRoot + "/runtime-probe" require.NoError(t, mgr.WriteSessionFile(ctx, sessionID, dir+"/SKILL.md", []byte("# Runtime probe\n")), "the installer filesystem must use the maintenance identity") @@ -73,7 +74,7 @@ func TestShellRuntimeIntegration(t *testing.T) { require.Contains(t, resource.Output, `shell_exec(skill_name="runtime-probe"`) environment := call(ToolShellExec, `{"command":"a=(one two); printf '%s:%s' \"$HOME\" \"${#a[@]}\""}`) require.Equal(t, 0, environment.Data["exit_code"], "%+v", environment) - require.Equal(t, "/home/user:2", environment.Data["stdout"], "shell user, HOME and Bash grammar must agree") + require.Equal(t, "/root:2", environment.Data["stdout"], "shell user, HOME and Bash grammar must agree") r := call(ToolWriteSandboxFile, `{"path":"scripts/probe.py","content":"import runtime_probe\nprint(runtime_probe.VALUE + 1)\n"}`) require.True(t, r.Success, "%+v", r) r = call(ToolShellExec, `{"skill_name":"runtime-probe","command":"python3 /workspace/scripts/probe.py","work_dir":"output/new-dir"}`) @@ -81,8 +82,19 @@ func TestShellRuntimeIntegration(t *testing.T) { require.Equal(t, 0, r.Data["exit_code"], "%+v", r) require.Equal(t, "42\n", r.Data["stdout"]) r = call(ToolShellExec, `{"skill_name":"runtime-probe","command":"printf changed > \"$WEKNORA_SKILL_DIR/SKILL.md\""}`) - require.NotEqual(t, 0, r.Data["exit_code"], "ordinary skill commands cannot mutate the installed tree") - require.Contains(t, r.Output, "Permission denied") + require.Equal(t, 0, r.Data["exit_code"], "root sessions may update their own installed tree") + r = call(ToolWriteSandboxFile, `{"path":"npm-package/package.json","content":"{\"name\":\"runtime-node-probe\",\"version\":\"1.0.0\",\"main\":\"index.js\"}"}`) + require.True(t, r.Success, "%+v", r) + r = call(ToolWriteSandboxFile, `{"path":"npm-package/index.js","content":"module.exports = 42;"}`) + require.True(t, r.Success, "%+v", r) + installArgs, err := json.Marshal(ShellExecInput{SkillName: "runtime-probe", + Command: strings.ReplaceAll(skillNodePackageInstallCommand, "", "/workspace/npm-package --offline --ignore-scripts --no-audit --no-fund")}) + require.NoError(t, err) + r = call(ToolShellExec, string(installArgs)) + require.True(t, r.Success, "%+v", r) + require.Equal(t, 0, r.Data["exit_code"], "%+v", r) + r = call(ToolShellExec, `{"skill_name":"runtime-probe","command":"node -e \"console.log(require('runtime-node-probe'))\""}`) + require.Equal(t, "42\n", r.Data["stdout"], "%+v", r) r = call(ToolEditSandboxFile, `{"path":"scripts/probe.py","edits":[{"old_string":"+ 1","new_string":"+ 2"}]}`) require.True(t, r.Success, "%+v", r) r = call(ToolShellExec, `{"skill_name":"runtime-probe","command":"python3 scripts/probe.py"}`) @@ -124,4 +136,13 @@ sys.stdout.write(sys.stdin.read()) require.True(t, r.Success, "%+v", r) require.Equal(t, 0, r.Data["exit_code"], "%+v", r) require.Equal(t, "00ff01\nargument with spaces\n"+stdin, r.Data["stdout"]) + + // Follow the missing-environment guidance for a host skill, then ensure + // the next named call selects the newly created staged virtualenv. + args, err = json.Marshal(ShellExecInput{SkillName: "host-probe", Command: skillPythonVenvCreateCommand}) + require.NoError(t, err) + r = call(ToolShellExec, string(args)) + require.Equal(t, 0, r.Data["exit_code"], "%+v", r) + r = call(ToolShellExec, `{"skill_name":"host-probe","command":"python3 -c \"import os, sys; assert sys.prefix == os.environ['WEKNORA_SKILL_DIR'] + '/.venv'; print('staged venv selected')\""}`) + require.Equal(t, "staged venv selected\n", r.Data["stdout"], "%+v", r) } diff --git a/internal/agent/tools/skill_runtime_guard.go b/internal/agent/tools/skill_runtime_guard.go index 29036015..5aabe96c 100644 --- a/internal/agent/tools/skill_runtime_guard.go +++ b/internal/agent/tools/skill_runtime_guard.go @@ -3,40 +3,54 @@ package tools import ( "strconv" "strings" - - "github.com/Tencent/WeKnora/internal/sandbox" ) -// Session skill trees are snapshotted read-only (root-owned, mode 555). uv -// venv often has no pip. Skills that lazily pip-install extras on first use -// cannot write that venv; session agents must use the /workspace overlay -// instead of chown / ensurepip / pip into /opt/weknora/tenant/skills. +// A skill's dependencies are supposed to be complete when the install +// finishes. When they are not, what the model gets back at chat time carries +// no direction: "No module named pip" from a uv-created venv, or a bare +// permission error against a `.venv` path, says nothing about which of the +// several plausible recoveries is the right one. The hints below attach that +// direction after the fact. // -// That rule is enforced by the filesystem, not by inspecting commands: the -// kernel already refuses the write. What the model needs is a readable reason -// for the EROFS / EPERM / "No module named pip" it gets back, which is what -// the hints below attach after the fact. An up-front command blacklist was -// tried and removed: matching `pip install` next to the skills root also -// rejected the recovery command this guidance recommends (installing into the -// overlay with `-r /requirements.txt`), while any indirection through a -// shell variable walked straight past it. +// The recovery is to install into the skill's own environment, in place. That +// works because the sandbox belongs to this session alone and runs as root, so +// the write lands in the session's own container and dies with it — it never +// reaches the image other sessions start from. The overlay this guidance used +// to recommend (`pip install --target /workspace/.skill-packages/`) +// bought nothing over that and split a skill's packages across two locations. +// +// An up-front command blacklist was tried and removed: matching `pip install` +// next to the skills root also rejected the recovery command this guidance +// recommends, while any indirection through a shell variable walked straight +// past it. -func frozenSkillTreeGuidance(skillName string) string { - pkgDir := sandbox.SessionSkillPackageDir(skillName) +// These commands run with skill_name so the shell environment supplies the +// actual image or staged directory. Keep work_dir at its /workspace default. +const ( + skillPythonPackageInstallCommand = `uv pip install --python ` + + `"${WEKNORA_SKILL_DIR:?}/.venv/bin/python" ` + skillPythonPackageFallbackCommand = `"${WEKNORA_SKILL_DIR:?}/.venv/bin/python" -m ensurepip --upgrade && ` + + `"${WEKNORA_SKILL_DIR:?}/.venv/bin/python" -m pip install ` + skillPythonVenvCreateCommand = `python3 -m venv --without-pip "${WEKNORA_SKILL_DIR:?}/.venv"` + skillNodePackageInstallCommand = `npm --prefix "${WEKNORA_SKILL_DIR:?}" install ` +) + +func missingSkillPackageGuidance(skillName string) string { skillArg := "skill_name=" if skillName != "" { skillArg = "skill_name=" + strconv.Quote(skillName) } - return "the skill tree under " + sandbox.SkillsImageRoot + - " is frozen after install (read-only, root-owned; uv venv often has no pip). " + - "Do not chown, chmod, ensurepip, or pip/npm install into it. " + - "On-demand extras (python-docx, python-pptx, …) go in the session overlay: " + - "`python3 -m pip install --target " + pkgDir + " ` " + - "(system python3, not the skill venv), then shell_exec(" + skillArg + "). " + - "Or ask the user to reinstall the skill so extras are baked into the image." + return "Install missing packages with shell_exec(" + skillArg + ", command=...), leaving work_dir at /workspace. " + + "That named call supplies $WEKNORA_SKILL_DIR, the actual installed or staged skill directory. " + + "For Python, use `" + skillPythonPackageInstallCommand + "`; uv does not need pip in the virtualenv. " + + "If .venv is absent (as with staged host resources), first run `" + skillPythonVenvCreateCommand + "`. " + + "If uv is unavailable in a custom image, use `" + skillPythonPackageFallbackCommand + "`. " + + "For Node, use `" + skillNodePackageInstallCommand + "`. " + + "Then rerun the original command with the same skill_name. " + + "These changes live and die with this session; reinstall the skill if every session needs the package." } -func isFrozenSkillVenvFailure(stderr string) bool { +func isSkillVenvInstallFailure(stderr string) bool { if stderr == "" { return false } @@ -45,10 +59,31 @@ func isFrozenSkillVenvFailure(stderr string) bool { strings.Contains(stderr, "No module named 'pip'") { return true } - if strings.Contains(lower, "read-only file system") || - strings.Contains(lower, "erofs") || - strings.Contains(lower, "read-only filesystem") { - return true - } - return strings.Contains(lower, "permission denied") && strings.Contains(lower, ".venv") + return strings.Contains(lower, ".venv") && + (isReadOnlyFilesystemFailure(lower) || isPermissionFailure(lower)) +} + +func isReadOnlyFilesystemFailure(stderr string) bool { + lower := strings.ToLower(stderr) + return strings.Contains(lower, "read-only file system") || strings.Contains(lower, "erofs") || + strings.Contains(lower, "read-only filesystem") +} + +func isPermissionFailure(stderr string) bool { + lower := strings.ToLower(stderr) + return strings.Contains(lower, "permission denied") || strings.Contains(lower, "operation not permitted") || + strings.Contains(lower, "eperm") +} + +func skillVenvFailureGuidance(skillName, stderr string) string { + if isReadOnlyFilesystemFailure(stderr) { + return "The skill virtualenv is on a read-only filesystem. Root, uv and pip cannot write through " + + "a read-only mount. Configure a writable skill environment before installing packages." + } + if isPermissionFailure(stderr) { + return "The skill virtualenv denied access. Check its permissions and mount restrictions first; " + + "changing package managers does not grant access. Once the environment is writable: " + + missingSkillPackageGuidance(skillName) + } + return missingSkillPackageGuidance(skillName) } diff --git a/internal/agent/tools/skill_runtime_guard_test.go b/internal/agent/tools/skill_runtime_guard_test.go index 92c59787..57b2f0d8 100644 --- a/internal/agent/tools/skill_runtime_guard_test.go +++ b/internal/agent/tools/skill_runtime_guard_test.go @@ -1,18 +1,33 @@ package tools import ( + "context" + "os" + "os/exec" + "path/filepath" + "strings" "testing" + "time" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) -func TestFrozenSkillGuidanceUsesTheUnifiedExecutor(t *testing.T) { - hint := frozenSkillTreeGuidance("律师助手") - require.Contains(t, hint, "/workspace/.skill-packages/律师助手") - require.Contains(t, hint, "python3 -m pip install --target") +func TestMissingSkillPackageGuidanceUsesTheUnifiedExecutor(t *testing.T) { + hint := missingSkillPackageGuidance("律师助手") + require.Contains(t, hint, skillPythonPackageInstallCommand) require.Contains(t, hint, "shell_exec") require.NotContains(t, hint, "execute_skill_script") + require.NotContains(t, hint, "/workspace/.skill-packages", + "the session overlay is gone; a package belongs in the skill's own environment") +} + +// An unnamed hint asks for a named call; every command also refuses an unset +// or empty skill directory before invoking a package manager. +func TestMissingSkillPackageGuidanceWithoutASkillNameStaysConcrete(t *testing.T) { + hint := missingSkillPackageGuidance("") + require.Contains(t, hint, skillPythonVenvCreateCommand) + require.Contains(t, hint, "skill_name=") } func TestIsMissingInterpreterModuleIgnoresMissingPip(t *testing.T) { @@ -21,3 +36,92 @@ func TestIsMissingInterpreterModuleIgnoresMissingPip(t *testing.T) { assert.False(t, isMissingInterpreterModule("No module named pip")) assert.True(t, isMissingInterpreterModule("ModuleNotFoundError: No module named 'docx'\n")) } + +// Run the actual commands advertised in recovery guidance against a local +// wheel. No network or installed pip is needed for the uv path. +func TestSkillPythonPackageRecoveryInstallsWithoutPip(t *testing.T) { + if _, err := exec.LookPath("python3"); err != nil { + t.Skip("python3 is required") + } + for _, variant := range []struct{ name, command string }{ + {"uv", skillPythonPackageInstallCommand}, + {"ensurepip", skillPythonPackageFallbackCommand}, + } { + t.Run(variant.name, func(t *testing.T) { + if variant.name == "uv" { + if _, err := exec.LookPath("uv"); err != nil { + t.Skip("uv is required") + } + } + ctx, cancel := context.WithTimeout(context.Background(), time.Minute) + defer cancel() + dir := t.TempDir() + skillDir := filepath.Join(dir, "staged skill 中文") + require.NoError(t, os.MkdirAll(skillDir, 0o755)) + env := append(os.Environ(), "WEKNORA_SKILL_DIR="+skillDir, + "UV_OFFLINE=1", "UV_CACHE_DIR="+filepath.Join(dir, "uv-cache"), + "PIP_NO_INDEX=1", "PIP_DISABLE_PIP_VERSION_CHECK=1") + run := func(command string) string { + t.Helper() + cmd := exec.CommandContext(ctx, "/bin/bash", "--noprofile", "--norc", "-c", command) + cmd.Dir, cmd.Env = dir, env + out, err := cmd.CombinedOutput() + require.NoError(t, err, "%s: %s", command, out) + return string(out) + } + run(skillPythonVenvCreateCommand) + python := filepath.Join(skillDir, ".venv", "bin", "python") + cmd := exec.CommandContext(ctx, python, "-m", "pip", "--version") + out, err := cmd.CombinedOutput() + require.Error(t, err) + require.Contains(t, string(out), "No module named pip") + build := exec.CommandContext(ctx, "python3", "-c", `import zipfile +files = { + "recovery_probe.py": "VALUE = 42\n", + "recovery_probe-1.0.dist-info/METADATA": "Metadata-Version: 2.1\nName: recovery-probe\nVersion: 1.0\n", + "recovery_probe-1.0.dist-info/WHEEL": ("Wheel-Version: 1.0\nGenerator: test\n" + "Root-Is-Purelib: true\nTag: py3-none-any\n"), +} +record = "recovery_probe-1.0.dist-info/RECORD" +files[record] = "".join(name + ",,\n" for name in [*files, record]) +with zipfile.ZipFile("recovery_probe-1.0-py3-none-any.whl", "w") as wheel: + for name, content in files.items(): + wheel.writestr(name, content) +`) + build.Dir = dir + out, err = build.CombinedOutput() + require.NoError(t, err, "%s", out) + run(strings.ReplaceAll(variant.command, "", "./recovery_probe-1.0-py3-none-any.whl")) + cmd = exec.CommandContext(ctx, python, "-c", "import recovery_probe; print(recovery_probe.VALUE)") + out, err = cmd.CombinedOutput() + require.NoError(t, err, "%s", out) + require.Equal(t, "42\n", string(out)) + }) + } +} + +func TestSkillPackageCommandsRefuseMissingDirectory(t *testing.T) { + dir := t.TempDir() + for _, tool := range []string{"uv", "npm", "python3"} { + script := []byte("#!/bin/sh\necho tool-invoked\n") + require.NoError(t, os.WriteFile(filepath.Join(dir, tool), script, 0o755)) + } + for _, command := range []string{ + skillPythonPackageInstallCommand, skillPythonPackageFallbackCommand, + skillPythonVenvCreateCommand, skillNodePackageInstallCommand, + } { + for _, empty := range []bool{false, true} { + cmd := exec.Command("/bin/bash", "--noprofile", "--norc", "-c", + strings.ReplaceAll(command, "", "test-package")) + cmd.Env = []string{"PATH=" + dir} + if empty { + cmd.Env = append(cmd.Env, "WEKNORA_SKILL_DIR=") + } + out, err := cmd.CombinedOutput() + require.Error(t, err, "%s", command) + require.Contains(t, string(out), "WEKNORA_SKILL_DIR") + require.NotContains(t, string(out), "tool-invoked", + "no package manager may run without a skill directory") + } + } +} diff --git a/internal/application/service/session_attachment_staging.go b/internal/application/service/session_attachment_staging.go index c570d9f7..fc936886 100644 --- a/internal/application/service/session_attachment_staging.go +++ b/internal/application/service/session_attachment_staging.go @@ -272,7 +272,13 @@ func buildSandboxAttachmentsPrompt(attachments []stagedSessionAttachment) string escapeAttachmentXML(attachment.Path), ) } - b.WriteString(" Use these absolute paths as read-only inputs. Inspect them with read_file, or with shell_exec (ls/find) when a shell is available. Create generated files with write_sandbox_file; patch existing ones with edit_sandbox_file; put downloadable artifacts under $WEKNORA_SKILL_OUTPUT_DIR.\n") + b.WriteString(" These are the user's files: read them at the absolute paths above " + + "and do not write into /workspace/input. Inspect them with read_file, " + + "or with shell_exec (ls/find) when a shell is available. " + + "Create generated files with write_sandbox_file " + + "and patch existing ones with edit_sandbox_file. $WEKNORA_SKILL_OUTPUT_DIR (/workspace/output) " + + "is the only directory collected for download, so put finished deliverables there " + + "and keep drafts and intermediate files in any other directory under /workspace.\n") b.WriteString("") return b.String() } diff --git a/internal/application/service/session_attachment_staging_test.go b/internal/application/service/session_attachment_staging_test.go index 5fc1b4a0..7cd0cede 100644 --- a/internal/application/service/session_attachment_staging_test.go +++ b/internal/application/service/session_attachment_staging_test.go @@ -190,7 +190,9 @@ func TestBuildSandboxAttachmentsPromptEscapesMetadata(t *testing.T) { assert.Contains(t, prompt, `name="a<&>.txt"`) assert.Contains(t, prompt, `path="/workspace/input/hash/a.txt"`) - assert.Contains(t, prompt, "read-only inputs") + assert.Contains(t, prompt, "do not write into /workspace/input") + assert.Contains(t, prompt, "only directory collected for download", + "a model that treats /workspace/output as scratch ships the user its drafts") assert.Contains(t, prompt, "read_file") assert.NotContains(t, prompt, "read_sandbox_file") assert.NotContains(t, prompt, "list_sandbox_files") diff --git a/internal/application/service/tenant_skill_install.go b/internal/application/service/tenant_skill_install.go index 8af420d9..ebb54442 100644 --- a/internal/application/service/tenant_skill_install.go +++ b/internal/application/service/tenant_skill_install.go @@ -568,9 +568,10 @@ func (s *TenantSkillService) cleanupContext( // previous version shipped and this one dropped would otherwise live on in // every later snapshot while BundleSHA256 claims the tree equals the archive. // -// Creating and chowning it is what makes the FIRST install work at all: -// seeding goes through the provider file API, which runs as the default exec -// user, and the skills root is not part of the base image. +// Creating the directory is what makes the FIRST install work at all: the +// skills root is not part of the base image. No chown here — the default exec +// account is root under one-session-one-sandbox, so chown root:root would be a +// no-op, and there is no shared-volume tenant boundary to defend with it. func (s *TenantSkillService) resetSkillDir( ctx context.Context, mgr sandbox.Manager, sessionID, skillDir string, ) error { @@ -579,10 +580,9 @@ func (s *TenantSkillService) resetSkillDir( } root := sandbox.ShellQuote(sandbox.SkillsImageRoot) dir := sandbox.ShellQuote(skillDir) - user := sandbox.DefaultSandboxExecUser cmd := fmt.Sprintf( - "rm -rf %s && mkdir -p %s %s && chown %s:%s %s %s && chmod 755 %s %s", - dir, root, dir, user, user, root, dir, root, dir, + "rm -rf %s && mkdir -p %s %s && chmod 755 %s %s", + dir, root, dir, root, dir, ) if _, err := s.execInstall(ctx, mgr, sessionID, cmd); err != nil { return fmt.Errorf("reset skill directory %s: %w", skillDir, err) @@ -659,7 +659,9 @@ func packSkillTar(bundle *SkillBundle) ([]byte, error) { content := bundle.Files[rel] if err := tw.WriteHeader(&tar.Header{ Name: name, - Mode: 0o644, + // The former normalization pass made every bundled file executable. + // Preserve that contract at extraction while keeping the tree writable. + Mode: 0o755, Size: int64(len(content)), }); err != nil { return nil, err @@ -763,16 +765,6 @@ func (s *TenantSkillService) installDependenciesAndVerify( // the next round's tool calls. job.transcript.muteActivityProgress() - // The tree is handed to the execution user BEFORE it is verified. The - // agent created these files as root, and the language passes - // deliberately run as the ordinary user: verifying first would test - // permissions that never reach the image, and a restrictive root umask - // would fail a perfectly good install because the .venv interpreter - // was unreadable. - if err = s.normalizeSkillPermissions(ctx, job.mgr, job.sess.ID, job.skillDir); err != nil { - return err - } - notes, verifyErr := s.verifySkill(ctx, job.mgr, job.sess.ID, job.skillDir, job.bundle) s.reportVerificationNotes(ctx, job, notes) if verifyErr == nil { @@ -792,9 +784,6 @@ func (s *TenantSkillService) installDependenciesAndVerify( Log: fmt.Sprintf("%s verification found %d missing dependency/dependencies; "+ "asking the installer to add them", gate.Language, len(gate.Problems)), }) - if err = s.reopenSkillDirForRepair(ctx, job.mgr, job.sess.ID, job.skillDir); err != nil { - return err - } prompt = buildRepairPrompt(job.skillDir, gate) job.transcript.RecordPrompt(prompt) } @@ -894,28 +883,6 @@ func (s *TenantSkillService) reportVerificationNotes( }) } -// reopenSkillDirForRepair undoes normalizeSkillPermissions for another round. -// -// Verification runs as the ordinary user, so the tree is locked to 555 and root -// before it; a repair then has to install into .venv again. Install commands -// run as root and would get away with writing through those modes, but relying -// on that makes the next reader work out whether it still holds — restoring the -// state the seed left is the same two commands and needs no such argument. -func (s *TenantSkillService) reopenSkillDirForRepair( - ctx context.Context, mgr sandbox.Manager, sessionID, skillDir string, -) error { - if err := guardSkillDir(skillDir); err != nil { - return err - } - dir := sandbox.ShellQuote(skillDir) - user := sandbox.DefaultSandboxExecUser - cmd := fmt.Sprintf("chown -R %s:%s %s && chmod -R u+rwX,go+rX %s", user, user, dir, dir) - if _, err := s.execInstall(ctx, mgr, sessionID, cmd); err != nil { - return fmt.Errorf("reopen skill directory %s for a repair round: %w", skillDir, err) - } - return nil -} - // buildRepairPrompt turns the gate's own findings into the next round's brief. // // It carries no analysis of its own, deliberately: the gate is the only @@ -950,30 +917,6 @@ The same verification runs again as soon as you finish. `, gate.Language, findings.String(), skillDir, skillDir, skillDir) } -// normalizeSkillPermissions makes the skill tree readable and executable by -// the non-root execution user, and writable by nobody. Installs run as root, -// so without the mode change the user that actually runs skills could not read -// them at all — which is also why this runs before verification: the checks -// read every script as that user, so they have to see the permissions the -// snapshot will carry. -// -// Ownership stays with root rather than moving to the execution user because -// this tree is baked into an image every session of the config inherits. A -// session that could write here would be editing the skills every other -// session runs. 555 leaves reads and execs to the "other" bits, which is all a -// skill run needs; the cost is that Python cannot write __pycache__ into the -// tree and silently skips bytecode caching. -func (s *TenantSkillService) normalizeSkillPermissions( - ctx context.Context, mgr sandbox.Manager, sessionID, skillDir string, -) error { - dir := sandbox.ShellQuote(skillDir) - cmd := fmt.Sprintf("chmod -R 555 %s && chown -R root:root %s", dir, dir) - if _, err := s.execInstall(ctx, mgr, sessionID, cmd); err != nil { - return fmt.Errorf("normalize skill permissions (%s): %w", cmd, err) - } - return nil -} - // skillCacheBudgetMB caps the package download caches one image carries into // its next generation, as one total across both accounts. Retaining the caches // lets a future install resolve a package a previous install already fetched @@ -1020,19 +963,18 @@ func (s *TenantSkillService) cleanImageScratch( // and cannot change that code — it is written to always succeed, and the shell // it lands in has no set -e to turn a swallowed prune failure into an abort. func cleanImageScratchCommand() string { - user := sandbox.DefaultSandboxExecUser inputRoot := sandbox.ShellQuote(sandbox.SessionInputRoot) outputRoot := sandbox.ShellQuote(sandbox.SessionOutputRoot) var b strings.Builder - b.WriteString("rm -rf /workspace/* /workspace/.[!.]* || true") - fmt.Fprintf(&b, "; mkdir -p %s %s && chown %s:%s %s %s && chmod 775 %s %s; status=$?", + b.WriteString("rm -rf /workspace/* /tmp/* /workspace/.[!.]* || true") + fmt.Fprintf(&b, "; mkdir -p %s %s && chmod 775 %s %s; status=$?", inputRoot, outputRoot, - user, user, inputRoot, outputRoot, inputRoot, outputRoot, ) - // The prunes run as root, so they only ever trim root's caches. The budget - // guard below covers both accounts on purpose — it needs nothing but du and - // rm, and this runs as root. + // The prunes run as root, so they only ever trim root's caches — which is + // now the only account scripts run as. The budget guard below no longer + // needs to cover a second "user" account's caches; it needs nothing but du + // and rm, and this runs as root. for _, prune := range []struct{ tool, subcommand string }{ {"uv", "cache prune"}, {"npm", "cache verify"}, @@ -1041,10 +983,7 @@ func cleanImageScratchCommand() string { fmt.Fprintf(&b, "; command -v %s >/dev/null 2>&1 && %s %s >/dev/null 2>&1 || true", prune.tool, prune.tool, prune.subcommand) } - paths := append( - packageCachePaths("/root"), - packageCachePaths(path.Join("/home", sandbox.DefaultSandboxExecUser))..., - ) + paths := packageCachePaths("/root") b.WriteString("; ") b.WriteString(cacheBudgetGuardCommand(paths, skillCacheBudgetMB*1024)) b.WriteString("; exit $status") @@ -1769,11 +1708,12 @@ Hard requirements: WEKNORA_SESSION_INPUT_DIR: the sandbox injects those. Other WEKNORA_* names the skill reads (WEKNORA_API_KEY, WEKNORA_BASE_URL, WEKNORA_HOST, WEKNORA_TOKEN, WEKNORA_KB_ID) MUST be declared. -On-demand / optional extras MUST be installed now. After you finish, this -tree is made read-only and session agents cannot pip/npm into it (uv venv also -has no pip). Skills that ship scripts/install_deps.py or say "pip install when -the user needs Word/PPT" will fail at chat time unless those packages are -already in the venv. +On-demand / optional extras MUST be installed now. Every chat session starts +from the image this install produces, and whatever a session installs dies with +it, so an extra deferred to chat time is paid for again on every session and +fails outright wherever the sandbox has no egress. Skills that ship +scripts/install_deps.py or say "pip install when the user needs Word/PPT" will +stall at chat time unless those packages are already in the venv. - Create the venv with pip present: `+"`uv venv --seed %s/.venv`"+` (or `+"`python3 -m venv`"+`). - Install requirements.txt / pyproject.toml with `+"`uv pip install`"+`. - Read SKILL.md and any on-demand installer for extra packages (python-docx, diff --git a/internal/application/service/tenant_skill_install_test.go b/internal/application/service/tenant_skill_install_test.go index 5b4f7075..9a6a6593 100644 --- a/internal/application/service/tenant_skill_install_test.go +++ b/internal/application/service/tenant_skill_install_test.go @@ -48,7 +48,7 @@ func TestRunInstallHappyPathSwitchesPointerLast(t *testing.T) { require.NoError(t, err) require.Equal(t, []string{ "create-session", "prepare-skill-dir", "seed-files", "agent-execute", - "chmod", "verify-structure", "verify-python", "write-manifest", + "verify-structure", "verify-python", "write-manifest", "cleanup-workspace", "create-snapshot", "switch-pointer", "mark-stale", "destroy-sandbox", }, fx.events, "the pointer must move only after the snapshot exists") @@ -63,8 +63,11 @@ func TestRunInstallHappyPathSwitchesPointerLast(t *testing.T) { "the pointer switch must be exactly one config write") require.Empty(t, fx.deletedSnapshots, "a successful install deletes nothing; the previous image stays reachable") - require.False(t, fx.loadCheckRanAsRoot, - "script verification must run as the ordinary sandbox user, not install-mode root") + require.False(t, fx.loadCheckOpts.AsRoot, + "verification runs on the ordinary executor, whose account is already root; "+ + "taking the install-mode escape would test a shell a session never gets") + require.False(t, fx.loadCheckOpts.AllowSkillsRoot, + "verification must not be able to write outside the session workspace") require.Equal(t, []string{"Skill install"}, fx.sessionTitles) skill, err := fx.skillRepo.GetSkill(context.Background(), 7, "cfg-1", "sk-1") @@ -112,11 +115,9 @@ func TestNextSnapshotGenerationSkipsAbandonedLedgerRows(t *testing.T) { } // TestRunInstallIssuesExactlyTheseCommands pins the order, not just the set. -// Ownership and permissions are normalised BEFORE verification on purpose: the -// agent creates the tree as root, so a restrictive root umask would leave the -// .venv interpreter unreadable and fail a perfectly good install in the -// non-root verification pass, which must exercise the same permissions the -// snapshot will carry. +// No permission hand-over appears in it: the tree is built and verified by the +// same account (DefaultSandboxExecUser, root), so there is nobody to hand it +// to between the agent's turn and the verification pass. func TestRunInstallIssuesExactlyTheseCommands(t *testing.T) { fx := newInstallFixture(t) @@ -126,22 +127,12 @@ func TestRunInstallIssuesExactlyTheseCommands(t *testing.T) { installPrepareCommand, installToolsProbeCommand(), seedExtractCommand(installSkillDir), - "chmod -R 555 " + installSkillDir + " && chown -R root:root " + installSkillDir, skillTreeVerifyCommand(installSkillDir, []string{"scripts/extract.py"}), installPythonVerifyCommand, cleanImageScratchCommand(), }, fx.commands) } -func TestRunInstallNormalisesPermissionsBeforeVerifying(t *testing.T) { - fx := newInstallFixture(t) - - require.NoError(t, fx.svc.runInstall(context.Background(), 7, "cfg-1", "sk-1", fx.bundle)) - - require.Less(t, indexOfEvent(fx.events, "chmod"), indexOfEvent(fx.events, "verify-python"), - "the non-root verification pass must execute the permissions that get snapshotted") -} - func TestRunInstallWipesThePreviousTreeBeforeSeeding(t *testing.T) { fx := newInstallFixture(t) @@ -282,7 +273,8 @@ func TestCacheBudgetGuardKeepsSmallWipesBig(t *testing.T) { func TestCleanImageScratchCommandShape(t *testing.T) { cmd := cleanImageScratchCommand() - require.Contains(t, cmd, "rm -rf /workspace/* /workspace/.[!.]* || true") + require.Contains(t, cmd, "rm -rf /workspace/* /tmp/* /workspace/.[!.]* || true", + "the scratch wipe covers /tmp too: installers leave archives and locks there") require.Contains(t, cmd, "mkdir -p") require.Contains(t, cmd, "status=$?") require.Contains(t, cmd, "exit $status") @@ -292,7 +284,8 @@ func TestCleanImageScratchCommandShape(t *testing.T) { require.Contains(t, cmd, "du -skc") require.Contains(t, cmd, fmt.Sprintf("%d", skillCacheBudgetMB*1024)) require.Contains(t, cmd, "/root/.cache/uv") - require.Contains(t, cmd, "/home/"+sandbox.DefaultSandboxExecUser+"/.npm") + // Only /root caches: DefaultSandboxExecUser is root now, so there is no + // second "user" account cache under /home to guard. // And it must parse: the command is one opaque string to the sandbox, so a // quoting mistake would only surface as a runtime failure there. @@ -1631,27 +1624,24 @@ func TestRunInstallHandsVerificationFindingsBackToTheInstaller(t *testing.T) { require.Empty(t, skill.Error) } -// A repair round has to be able to write into .venv again, which the -// verification pass just locked down: the checks run as the ordinary user, so -// the tree is handed over at 555 and root-owned before every one of them. -func TestRunInstallReopensTheTreeBeforeARepairRound(t *testing.T) { +// A repair round writes into the tree a verification pass just looked at, and +// under the default root account it reaches it directly: modes left behind by +// an earlier pass do not stop root, and the tree is never handed to another +// account. What a repair round needs is a second agent turn and a second +// verification — not a permission fix-up. +func TestRunInstallRepairsWithoutReopeningTheTree(t *testing.T) { fx := newInstallFixture(t) fx.loadCheckExitCodes = []int{skillVerifyRepairableExit, 0} require.NoError(t, fx.svc.runInstall(context.Background(), 7, "cfg-1", "sk-1", fx.bundle)) - reopen := indexOfCommandContaining(fx.commands, "chmod -R u+rwX,go+rX "+installSkillDir) - require.GreaterOrEqual(t, reopen, 0, "the tree must be writable again for the repair") - - firstLock := indexOfCommandContaining(fx.commands, "chmod -R 555 "+installSkillDir) - require.GreaterOrEqual(t, firstLock, 0) - require.Greater(t, reopen, firstLock, - "the tree is reopened after the pass that locked it, not before") - - // And locked again for the pass that checks the repair, so the final image - // carries the modes every verification ran against. - require.Greater(t, lastIndexOfCommandContaining(fx.commands, "chmod -R 555 "+installSkillDir), - reopen, "the repaired tree must be locked down again before it is verified") + require.Equal(t, 2, fx.loadCheckPasses, "the repair has to be verified, not trusted") + require.Equal(t, -1, indexOfCommandContaining(fx.commands, "chmod -R u+rwX,go+rX "), + "root writes through whatever modes a verification pass leaves behind") + for _, command := range fx.commands { + require.NotContains(t, command, "chown", + "the tree is built, repaired and verified by one account; there is nothing to re-own") + } } // Installing a package cannot fix a file that does not parse, and the bundle @@ -1892,7 +1882,6 @@ const installSkillDir = "/opt/weknora/tenant/skills/pdf-tools" const ( installPrepareCommand = "rm -rf " + installSkillDir + " && mkdir -p /opt/weknora/tenant/skills " + installSkillDir + - " && chown user:user /opt/weknora/tenant/skills " + installSkillDir + " && chmod 755 /opt/weknora/tenant/skills " + installSkillDir ) @@ -1914,9 +1903,7 @@ func indexOfEvent(events []string, needle string) int { return -1 } -// indexOfCommandContaining and its Last variant locate one shell command in the -// ordered transcript. A repair round issues the same commands twice, so the -// tests that care about ordering need both ends. +// indexOfCommandContaining locates one shell command in the ordered transcript. func indexOfCommandContaining(commands []string, needle string) int { for i, command := range commands { if strings.Contains(command, needle) { @@ -1926,15 +1913,6 @@ func indexOfCommandContaining(commands []string, needle string) int { return -1 } -func lastIndexOfCommandContaining(commands []string, needle string) int { - for i := len(commands) - 1; i >= 0; i-- { - if strings.Contains(commands[i], needle) { - return i - } - } - return -1 -} - // staleMark is one request to mark a config's bound sandboxes stale. The // tenant is part of it because marking the right config of the wrong workspace // would rebuild sandboxes that never carried this image. @@ -1974,10 +1952,13 @@ type installFixture struct { // execResult is scoped to execResultCommand: an unscoped stub result // applies to the first command issued, which is not the command any of // these tests is about. - execResultCommand string - execResult *sandbox.ExecuteResult - loadCheckRanAsRoot bool - agentErr error + execResultCommand string + execResult *sandbox.ExecuteResult + // loadCheckOpts is how the per-language verification pass asked to run. + // It must stay an ordinary exec: verification exists to prove what a real + // skill call will see, so it may not take the install-mode escapes. + loadCheckOpts sandbox.ShellExecOptions + agentErr error // agentPrompts is every prompt the installer engine was handed, in order. // A repair round is a second entry, and what it says is the whole point of // having one. @@ -2977,7 +2958,7 @@ func (m *installSandboxManager) ExecShellCommandWithOptions( return &sandbox.ExecuteResult{ExitCode: m.fx.depsExitCode, Stderr: "deps missing"}, nil } case command == installPythonVerifyCommand: - m.fx.loadCheckRanAsRoot = opts.AsRoot + m.fx.loadCheckOpts = opts m.fx.record("verify-python") if m.fx.loadCheckResult != nil { return m.fx.loadCheckResult, nil @@ -3000,8 +2981,6 @@ func (m *installSandboxManager) ExecShellCommandWithOptions( }, nil case command == cleanImageScratchCommand(): m.fx.record("cleanup-workspace") - case strings.HasPrefix(command, "chmod -R 555 "): - m.fx.record("chmod") } if m.fx.execResult != nil && command == m.fx.execResultCommand { return m.fx.execResult, nil @@ -3415,3 +3394,22 @@ func (s installFileService) DeleteFile(_ context.Context, ref string) error { func (installFileService) CopyFile(context.Context, string, uint64, string) (string, error) { return "", nil } + +func TestSeededSkillHelperIsDirectlyExecutable(t *testing.T) { + raw, err := packSkillTar(&SkillBundle{Files: map[string][]byte{ + "scripts/helper.sh": []byte("#!/bin/sh\nprintf 'helper works'\n"), + }}) + require.NoError(t, err) + dir := t.TempDir() + cmd := exec.Command("tar", "-xf", "-", "-C", dir) + cmd.Stdin = bytes.NewReader(raw) + out, err := cmd.CombinedOutput() + require.NoError(t, err, "%s", out) + helper := filepath.Join(dir, "scripts", "helper.sh") + out, err = exec.Command(helper).CombinedOutput() + require.NoError(t, err, "%s", out) + require.Equal(t, "helper works", string(out)) + info, err := os.Stat(helper) + require.NoError(t, err) + require.NotZero(t, info.Mode().Perm()&0o200, "the executable skill remains writable") +} diff --git a/internal/application/service/tenant_skill_verify.go b/internal/application/service/tenant_skill_verify.go index 2e417f8f..f5900133 100644 --- a/internal/application/service/tenant_skill_verify.go +++ b/internal/application/service/tenant_skill_verify.go @@ -227,9 +227,9 @@ func (s *TenantSkillService) verifyScriptsParse( return notes, nil } -// execVerify runs one verification pass as the ordinary sandbox user, with the -// same working directory and environment a real skill call gets. Running it as -// install-mode root would test permissions that never reach a session. +// execVerify uses the ordinary execution path and workspace bootstrap, with +// the same working directory and skill environment as a session call. Both +// paths currently run as root; AsRoot would select the maintenance bootstrap. func (s *TenantSkillService) execVerify( ctx context.Context, mgr sandbox.Manager, sessionID, skillDir, label, command string, ) ([]string, error) { diff --git a/internal/sandbox/capabilities.go b/internal/sandbox/capabilities.go index f2e4942c..87dbf565 100644 --- a/internal/sandbox/capabilities.go +++ b/internal/sandbox/capabilities.go @@ -92,9 +92,10 @@ type SessionCapabilityProvider interface { } // SessionInstallShellExecutor runs install/maintenance shell commands, which -// need root and the skills image root. It is a separate interface from -// SessionShellExecutor so the privilege is something a caller must ask for by -// name: ordinary chat sessions keep the non-root, /workspace-only contract. +// need the skills image root. It is a separate interface from +// SessionShellExecutor so reaching outside /workspace is something a caller +// must ask for by name: ordinary chat sessions keep the /workspace-only +// contract even though they already run as root. type SessionInstallShellExecutor interface { ExecShellCommandWithOptions( ctx context.Context, diff --git a/internal/sandbox/cube_remote_client.go b/internal/sandbox/cube_remote_client.go index 7b1762e1..49c1130c 100644 --- a/internal/sandbox/cube_remote_client.go +++ b/internal/sandbox/cube_remote_client.go @@ -664,9 +664,11 @@ func (c *CubeRemoteClient) Exec( logCubeDataPlaneExec(ctx, c, sb, request.User, line) startedAt := time.Now() - // User comes from the neutral request rather than being hardcoded: running - // everything as root silently defeats file-mode protections on shared - // volumes, and made this adapter behave differently from E2B's. + // User comes from the neutral request rather than being hardcoded, so the + // account a Cube exec lands on matches the other backends. The default is + // now root (see DefaultSandboxExecUser); the shared-volume concern that + // once made root here a footgun no longer applies under + // one-session-one-sandbox. sdkResult, execErr := sb.Commands().Run(execCtx, line, cubesandbox.CommandOptions{ Timeout: request.Timeout, Envs: envs, diff --git a/internal/sandbox/docker_idle_sweeper.go b/internal/sandbox/docker_idle_sweeper.go index 4608b0c6..3bc2322c 100644 --- a/internal/sandbox/docker_idle_sweeper.go +++ b/internal/sandbox/docker_idle_sweeper.go @@ -173,9 +173,9 @@ func (s *dockerIdleSweeper) ttlFor(summary RemoteSandboxSummary) time.Duration { // lastActivity returns when the container last ran a command, falling back to // when it started for a sandbox that has not executed anything yet. // -// The marker lives inside the container and has to be writable by the -// unprivileged sandbox account, so its mtime is attacker-influenced: a script -// can `touch -d` it. A timestamp in the future is the one form of that which +// The marker lives inside the container and has to be writable by the account +// the execs run as, so its mtime is attacker-influenced: a script can +// `touch -d` it. A timestamp in the future is the one form of that which // would disable reclamation permanently, so it is refused outright and the // container falls back to its start time. Backdating only makes a sandbox look // idle sooner, which costs the container that did it and nothing else. diff --git a/internal/sandbox/docker_idle_sweeper_test.go b/internal/sandbox/docker_idle_sweeper_test.go index 723bcd82..87e05bbf 100644 --- a/internal/sandbox/docker_idle_sweeper_test.go +++ b/internal/sandbox/docker_idle_sweeper_test.go @@ -72,8 +72,8 @@ func TestDockerIdleSweeperFallsBackToCreationTime(t *testing.T) { require.Empty(t, engine.removed) } -// The marker has to be writable by the unprivileged sandbox account, so a -// script can backdate or postdate it. Postdating is the dangerous direction: a +// The marker has to be writable by the account the execs run as, so a script +// can backdate or postdate it. Postdating is the dangerous direction: a // single `touch -d 2099-01-01` would otherwise exempt the container from // reclamation forever. func TestDockerIdleSweeperRejectsFutureActivityMarker(t *testing.T) { diff --git a/internal/sandbox/docker_remote_client.go b/internal/sandbox/docker_remote_client.go index 77f7b7e4..0733b9f7 100644 --- a/internal/sandbox/docker_remote_client.go +++ b/internal/sandbox/docker_remote_client.go @@ -16,12 +16,11 @@ // Exec → POST /containers/{id}/exec → /exec/{id}/start (hijack) // Snapshot → POST /commit (skill images under weknora-skill/) // -// Every file operation — WriteFile, ReadFile, Stat, MakeDir, Remove, ListDir — -// is an exec running as the sandbox account, NOT a call to /archive. The -// archive endpoints run as root and resolve symlinks, so a session that plants -// a link inside its own workspace could read or overwrite anything in the -// container through them. Going through exec puts the kernel back in charge of -// who may touch what. Do not "simplify" these back onto /archive. +// Every file operation uses exec with an explicit account (root by default), +// timeout and activity tracking. Archive endpoints bypass those exec settings. +// Neither root exec nor archive provides containment under a path prefix: +// intermediate symlinks may reach other paths inside the same container. +// See WriteFile for the limits of the file API's path guards. // // ListDir and Stat use `find -printf`, which needs GNU findutils in the image; // the standard WeKnora sandbox image provides it. @@ -63,13 +62,13 @@ const dockerActivityMarker = "/var/lib/weknora-sandbox-activity" // the container is a place to exec into, not a service — and prepares the // activity marker on the way. // -// The marker has to be writable by the sandbox account. PID 1 runs as root so -// that it can create the file at all, but every exec that would refresh it — -// scripts, shell commands, filesystem helpers — runs as the unprivileged user. -// Creating it here, in the container's own entrypoint, avoids an extra API -// round trip per sandbox, and the chmod that follows is what lets that account -// touch it. Without this the idle sweeper would see a session that only ever -// ran scripts as untouched, and reclaim it out from under the user. +// The marker has to be writable by whichever account the execs land on, which +// is DefaultSandboxExecUser by default but stays selectable per call and can +// be a non-root account on a custom image. Creating it here, in the +// container's own entrypoint, avoids an extra API round trip per sandbox, and +// the chmod that follows is what lets a non-root account touch it. Without +// this the idle sweeper would see a session that only ever ran scripts as +// untouched, and reclaim it out from under the user. var dockerSandboxEntrypoint = []string{ "/bin/sh", "-c", "touch " + dockerActivityMarker + " 2>/dev/null; " + @@ -268,9 +267,10 @@ func (c *DockerRemoteClient) Create( created, err := c.api.ContainerCreate(ctx, client.ContainerCreateOptions{ Image: image, Config: &container.Config{ - // The standard image ends with USER user. The entrypoint has to - // create and chmod the activity marker under /var/lib, which only - // root can do; exec still names DefaultSandboxExecUser per call. + // The entrypoint has to create and chmod the activity marker under + // /var/lib, which only root can do. Pinning PID 1 to uid 0 keeps + // that working for a custom image that ends with a non-root USER; + // exec still names DefaultSandboxExecUser per call. User: dockerSandboxPID1User, // Entrypoint rather than Cmd, with Cmd explicitly emptied: the // daemon prepends the image's own ENTRYPOINT to Cmd, so an image @@ -810,19 +810,16 @@ func dockerExecCommand(req RemoteExecRequest, timeout time.Duration) []string { // dockerExecUser resolves which account a command runs as. // -// A blank user resolves to the sandbox account. It must never resolve to root: -// this function is the single choke point for every exec the daemon runs, so a -// caller that forgets to name an account has to lose privileges here, not -// silently gain them. It also makes the backends agree — E2B authenticates its -// data plane as DefaultSandboxExecUser and Cube hands a blank field to envd, -// which defaults the same way. +// A blank user resolves to DefaultSandboxExecUser, which is root: this +// function is the single choke point for every exec the daemon runs, so the +// account a caller lands on when it names none is decided here rather than by +// whatever the image happens to declare. It also makes the backends agree — +// E2B authenticates its data plane as DefaultSandboxExecUser and Cube hands a +// blank field to envd, which defaults the same way. // -// This used to fall back to root for the manager's artifact-directory -// bootstrap. That was a container-escape primitive: chown follows symlinks, so -// a session that replaced its own artifact directory with a link to /etc got -// the root-run bootstrap to hand it ownership of /etc, and from there uid 0 by -// rewriting passwd. The bootstrap now names the account like everyone else and -// simply fails when it is aimed at something the account does not own. +// Root is safe to default to because a sandbox belongs to exactly one session: +// there is no second account inside it whose files the kernel would be keeping +// apart. Host and cross-tenant isolation live at the container boundary. func dockerExecUser(user string) string { if trimmed := strings.TrimSpace(user); trimmed != "" { return trimmed @@ -837,22 +834,19 @@ func dockerExecWasKilled(exitCode int) bool { return exitCode == 137 || exitCode == 124 } -// WriteFile writes one file as the sandbox account. +// WriteFile writes one file through exec as remoteFileUser(ctx). // -// This and its Read/Stat counterparts deliberately avoid the Engine's archive -// endpoints (CopyToContainer, CopyFromContainer, ContainerStatPath). Those are -// served by the daemon, which means two things at once: they ignore the exec -// user and act as root, and they resolve symlinks on the way. That combination -// is unsafe here, because the sandbox account can write anywhere under -// /workspace while every caller-facing path guard in this repository is a -// string prefix test. A model that runs `ln -s /root /workspace/output/esc` -// leaves /workspace/output/esc/secret.txt passing those guards, and the daemon -// then reads it out as root — confirmed against a real daemon, not theorised. +// Read/Stat and the other file operations use the same exec path for explicit +// identity, bounded execution and activity tracking. Archive endpoints run in +// the daemon and do not honor these per-exec settings. // -// Running these as DefaultSandboxExecUser hands the decision to the kernel -// instead: a path the sandbox account cannot reach on its own stays -// unreachable regardless of what a link points at, and there is no window -// between checking and using in which the link could be repointed. +// The default account is root. Exec still follows intermediate symlinks, and +// lexical path guards do not confine access to /workspace or protect /root +// and /etc inside this container. Host and cross-session isolation depend on +// the container and its mount configuration, not in-container ownership. +// Root cannot bypass a read-only mount. A future file API requiring path +// containment must enforce it during resolution and use, not rely on root +// exec or a separate prefix/Stat check. func (c *DockerRemoteClient) WriteFile( ctx context.Context, handle RemoteSandboxHandle, @@ -1242,12 +1236,10 @@ func dockerCleanPath(op, raw string) (string, error) { // dockerReservedPathPrefixes are refused for every file operation. // -// File operations run as the sandbox account (see WriteFile), so the kernel -// already decides what is reachable and this list is not what keeps /etc or -// another session's data safe. It exists for the paths the sandbox account -// legitimately can touch but never should through this API: /proc and /sys -// expose the container's own runtime state, and the activity marker is the -// sweeper's bookkeeping, which a session must not be able to backdate. +// These are lexical API restrictions on runtime paths and the activity marker. +// Root exec can still reach them through intermediate symlinks or shell_exec; +// the list is not a filesystem or tenant boundary. Mounts and container +// isolation remain authoritative. var dockerReservedPathPrefixes = []string{ "/proc", "/sys", diff --git a/internal/sandbox/docker_remote_client_test.go b/internal/sandbox/docker_remote_client_test.go index 58fe9f0c..14495296 100644 --- a/internal/sandbox/docker_remote_client_test.go +++ b/internal/sandbox/docker_remote_client_test.go @@ -456,8 +456,8 @@ func TestDockerClientCreateAppliesIsolationAndMetadata(t *testing.T) { require.Len(t, engine.created, 1) created := engine.created[0] // PID 1 both keeps the container alive and prepares the activity marker so - // that root and the unprivileged sandbox user can each refresh it; the - // idle sweeper reads nothing else. + // that any account an exec may land on can refresh it; the idle sweeper + // reads nothing else. require.Equal(t, dockerSandboxPID1User, created.Config.User, "PID 1 must be root so the entrypoint can chmod the activity marker") require.Equal(t, "/bin/sh", created.Config.Entrypoint[0]) @@ -862,10 +862,8 @@ func TestDockerClientExecResumesAStoppedContainerAndRetries(t *testing.T) { require.Len(t, engine.execOptions, 2) } -// The archive endpoint would apply this write as root and resolve symlinks on -// the way, so a link planted under the writable workspace could redirect an -// upload onto a file the sandbox account cannot touch. Writing through exec -// puts the kernel back in charge. +// Parent creation and writes share the explicit execution identity and pass +// file content through stdin. This is not a symlink-containment test. func TestDockerClientWriteFileRunsAsSandboxUserOverExec(t *testing.T) { engine := newFakeDockerEngine() docker := newTestDockerClient(t, engine) @@ -879,7 +877,7 @@ func TestDockerClientWriteFileRunsAsSandboxUserOverExec(t *testing.T) { require.Contains(t, mkdir.Cmd, "mkdir") require.Equal(t, DefaultSandboxExecUser, mkdir.User, - "mkdir as root would leave nested dirs unwritable by skill scripts") + "parent creation must use the same account as subsequent file and script operations") require.Equal(t, DefaultSandboxExecUser, write.User) require.True(t, write.AttachStdin) @@ -963,10 +961,9 @@ func TestDockerClientStatReportsSymlinkAsOther(t *testing.T) { "a symlink must not be reported as the file it points at") } -// Guards the property the symlink fix rests on. The archive endpoints ignored -// the requested user and ran as root; if any file operation goes back to one, -// this catches it without needing a daemon to prove the consequence. -func TestDockerClientFileOperationsNeverRunAsRoot(t *testing.T) { +// File operations retain the common exec path and explicitly select the +// default identity. This does not assert symlink containment or non-root access. +func TestDockerClientFileOperationsUseExplicitDefaultUser(t *testing.T) { engine := newFakeDockerEngine() engine.execStdout = "f\t3\t1786565482.0000000000\t/workspace/output/a.txt\n" docker := newTestDockerClient(t, engine) @@ -986,7 +983,7 @@ func TestDockerClientFileOperationsNeverRunAsRoot(t *testing.T) { require.NotEmpty(t, engine.execOptions) for i, opts := range engine.execOptions { require.Equal(t, DefaultSandboxExecUser, opts.User, - "exec %d (%v) must not run as root", i, opts.Cmd) + "exec %d (%v) must explicitly select the default sandbox account", i, opts.Cmd) } } diff --git a/internal/sandbox/e2b_remote_client.go b/internal/sandbox/e2b_remote_client.go index ab3ce87b..a620c628 100644 --- a/internal/sandbox/e2b_remote_client.go +++ b/internal/sandbox/e2b_remote_client.go @@ -864,10 +864,12 @@ func (c *E2BRemoteClient) Exec( } // Filesystem operations name DefaultSandboxExecUser explicitly rather than -// relying on the daemon's default account. It keeps ownership aligned with the -// account scripts run as, and it is required for interoperability: E2B Cloud -// falls back to "user" when the request omits it, while other E2B-compatible -// control planes reject the call outright. +// relying on the daemon's default account. Naming the user is required for +// interoperability: E2B Cloud falls back to "user" when the request omits it, +// while other E2B-compatible control planes reject the call outright. The +// default account is root, which matches what scripts run as; under +// one-session-one-sandbox there is no shared volume here to defend with +// file-mode ownership. func (c *E2BRemoteClient) WriteFile( ctx context.Context, handle RemoteSandboxHandle, diff --git a/internal/sandbox/envd_compat_transport_test.go b/internal/sandbox/envd_compat_transport_test.go index d06226f4..5101564a 100644 --- a/internal/sandbox/envd_compat_transport_test.go +++ b/internal/sandbox/envd_compat_transport_test.go @@ -39,7 +39,7 @@ func (r *recordingRoundTripper) RoundTrip(req *http.Request) (*http.Response, er func TestEnvdCompatTransportAuthenticatesDataPlaneCalls(t *testing.T) { recorder := &recordingRoundTripper{} - transport := NewEnvdCompatTransport(recorder, "user") + transport := NewEnvdCompatTransport(recorder, DefaultSandboxExecUser) request := httptest.NewRequest( http.MethodPost, @@ -50,7 +50,7 @@ func TestEnvdCompatTransportAuthenticatesDataPlaneCalls(t *testing.T) { require.NoError(t, err) require.Equal(t, - "Basic "+base64.StdEncoding.EncodeToString([]byte("user:")), + "Basic "+base64.StdEncoding.EncodeToString([]byte(DefaultSandboxExecUser+":")), recorder.request.Header.Get("Authorization"), ) } diff --git a/internal/sandbox/remote_client.go b/internal/sandbox/remote_client.go index aa6ba3b5..fa9d9b36 100644 --- a/internal/sandbox/remote_client.go +++ b/internal/sandbox/remote_client.go @@ -323,19 +323,27 @@ type RemoteExecRequest struct { // default". Both backends support selecting it (E2B WithUser, Cube // CommandOptions.User). // - // Callers that rely on filesystem permissions for isolation MUST set a - // non-root user: root bypasses mode bits entirely, which would defeat - // read-only protection on shared volumes. + // The default is root: each chat session owns its own sandbox + // (one-session-one-sandbox, single tenant), so there is no shared-volume + // tenant boundary inside a sandbox for file-mode isolation to defend. + // Cross-tenant and host isolation live at the container boundary, not in + // the exec account. Callers that still rely on in-container filesystem + // permissions should not treat mode bits as a root isolation boundary. + // Enforce read-only access at the mount level instead. User string // Timeout bounds a single exec call. Zero means "use provider default". Timeout time.Duration } -// DefaultSandboxExecUser is the non-root account WeKnora runs sandboxed -// scripts as. The sandbox template must provision this user; E2B base -// templates ship a "user" account, and Cube templates are expected to match. -const DefaultSandboxExecUser = "user" +// DefaultSandboxExecUser is the account WeKnora runs sandboxed scripts as. +// It is root: every chat session gets its own sandbox, so the in-container +// account is not a tenant boundary and root is the least surprising default +// for an agent that installs packages and writes wherever it needs. The +// adapters resolve an empty request user to this constant, independent of +// the image USER. The image retains a "user" compatibility account for +// E2B/Cube tooling that explicitly selects it. +const DefaultSandboxExecUser = "root" // RemoteExecResult is the neutral shape returned by Exec. type RemoteExecResult struct { diff --git a/internal/sandbox/session_manager.go b/internal/sandbox/session_manager.go index fba770c4..d261fb32 100644 --- a/internal/sandbox/session_manager.go +++ b/internal/sandbox/session_manager.go @@ -675,8 +675,8 @@ func (m *SessionBoundManager) WriteSessionFile( } // ShellExecOptions carries per-call shell execution knobs. The install-only -// flags are explicit so skill image maintenance can write under /opt without -// loosening work_dir or user privileges for ordinary chat sessions. +// flags select the installer working-directory allowlist and bootstrap. Both +// ordinary and install calls currently execute as root. type ShellExecOptions struct { WorkDir string Timeout time.Duration @@ -686,10 +686,11 @@ type ShellExecOptions struct { // See cleanSessionWorkDir for why the work_dir allowlist is lexical only. // Never set this from a model-authored tool such as shell_exec. AllowSkillsRoot bool - // AsRoot is reserved for install/maintenance commands that need to write - // outside /workspace; ordinary sessions must keep the provider default user. - // Never set this from a model-authored tool such as shell_exec: root inside - // the sandbox bypasses file-mode isolation on the image. + // AsRoot forces root and selects the maintenance bootstrap: only WorkDir + // is prepared, without requiring /workspace/input or /workspace/output. + // The default account is already root, but the bootstrap still differs. + // AllowSkillsRoot separately permits a work_dir under the skills image root; + // it is not a filesystem boundary for commands running as root. AsRoot bool } diff --git a/internal/sandbox/session_manager_test.go b/internal/sandbox/session_manager_test.go index a9dacd71..c83a3c5f 100644 --- a/internal/sandbox/session_manager_test.go +++ b/internal/sandbox/session_manager_test.go @@ -91,9 +91,8 @@ func TestSessionBoundManagerExecuteEnsuresOutputDir(t *testing.T) { "the attachment directory is prepared alongside the artifact one; a "+ "snapshot-derived image carries neither") require.Equal(t, DefaultSandboxExecUser, execs[0].User, - "chown follows symlinks, so a root-run bootstrap can be aimed at /etc by "+ - "a session that swaps its artifact directory for a link; running as the "+ - "sandbox account is what makes that attempt fail") + "the bootstrap names its account like every other caller, so the directories "+ + "it creates belong to whoever the execs that follow will run as") } func TestWorkspaceBootstrapPreservesExistingData(t *testing.T) { @@ -193,7 +192,7 @@ func TestCleanSessionWorkDirStillRejectsArbitraryPathsInInstallMode(t *testing.T require.Error(t, err, "install mode widens the allowlist, it does not remove it") } -func TestExecShellCommandWithOptionsRunsAsRootOnlyWhenAsked(t *testing.T) { +func TestExecShellCommandWithOptionsSelectsMaintenanceBootstrap(t *testing.T) { ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(10000)) mgr, client := newSessionManagerExecTestHarness(t) @@ -201,7 +200,8 @@ func TestExecShellCommandWithOptionsRunsAsRootOnlyWhenAsked(t *testing.T) { require.NoError(t, err) last := lastExecRequest(t, client) require.Equal(t, DefaultSandboxExecUser, last.User, - "ordinary shell_exec must stay on the non-root sandbox account") + "ordinary shell_exec must stay on the default sandbox account rather than "+ + "taking the install-mode escape") skillDir := mustSkillDir(t, "sk-1") _, err = mgr.ExecShellCommandWithOptions(ctx, "sess-1", "echo hi", ShellExecOptions{ @@ -213,6 +213,13 @@ func TestExecShellCommandWithOptionsRunsAsRootOnlyWhenAsked(t *testing.T) { last = lastExecRequest(t, client) require.Equal(t, "root", last.User) require.Equal(t, skillDir, last.WorkDir) + client.mu.Lock() + execs := append([]RemoteExecRequest(nil), client.execRequests...) + client.mu.Unlock() + require.Len(t, execs, 4, "each command has one bootstrap and one execution") + ordinaryBootstrap := workspaceBootstrapCommand(SessionInputRoot, SessionOutputRoot, SessionWorkspaceRoot) + require.Equal(t, ordinaryBootstrap, execs[0].Command) + require.Equal(t, workspaceBootstrapCommand(skillDir), execs[2].Command) } func TestExecShellCommandKeepsOrdinaryRemoteRequest(t *testing.T) { diff --git a/internal/sandbox/skill_paths.go b/internal/sandbox/skill_paths.go index 1b02dd86..634b87d8 100644 --- a/internal/sandbox/skill_paths.go +++ b/internal/sandbox/skill_paths.go @@ -163,20 +163,6 @@ func SkillDirForImageScript(scriptPath string) (string, bool) { return dir, true } -// SessionSkillPackageDir is the per-session extra-packages overlay for one -// skill. The image venv is frozen after install (root-owned, mode 555, and -// often created with `uv venv` so it has no pip). Skills that lazily -// `pip install` on first use cannot write there; packages installed with -// `python3 -m pip install --target` this directory are visible to -// execute_skill_script via PYTHONPATH / NODE_PATH. The directory is under -// /workspace so it dies with the session and never mutates the snapshot. -func SessionSkillPackageDir(skillName string) string { - if !IsValidSkillName(skillName) { - return path.Join(SessionWorkspaceRoot, ".skill-packages") - } - return path.Join(SessionWorkspaceRoot, ".skill-packages", skillName) -} - // SkillVenvPython is where a skill's own Python interpreter lives when the // install created one. It is exported because the model needs to be told: the // system python3 deliberately carries no skill dependencies, so anything that diff --git a/internal/sandbox/skill_paths_test.go b/internal/sandbox/skill_paths_test.go index efb37e50..5dc89c3d 100644 --- a/internal/sandbox/skill_paths_test.go +++ b/internal/sandbox/skill_paths_test.go @@ -15,9 +15,9 @@ func TestSkillDirFor(t *testing.T) { require.Equal(t, "/opt/weknora/tenant/skills/sk-1", dir) } -func TestSessionSkillPackageDir(t *testing.T) { - require.Equal(t, "/workspace/.skill-packages/律师助手", SessionSkillPackageDir("律师助手")) - require.Equal(t, "/workspace/.skill-packages", SessionSkillPackageDir("../escape")) +func TestSkillVenvPython(t *testing.T) { + require.Equal(t, "/opt/weknora/tenant/skills/律师助手/.venv/bin/python", + SkillVenvPython(SkillsImageRoot+"/律师助手")) } func TestSkillDirForRejectsPathEscape(t *testing.T) {