JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
a93f17010c
agent-Specialization/docs/host_sandbox_and_permission_model.md
JOJO a93f17010c feat(security): unify host sandbox controls across command/python/terminal/sub-agent and add path authorization UI 
This commit lands a broad host-security architecture update focused on enforceable sandbox execution, clearer permission semantics, and operator usability.

Core execution/security changes
- Introduce and wire a unified host sandbox runner for multi-OS execution:
  - macOS: sandbox-exec
  - Linux: bubblewrap + seccomp
  - Windows: WSL2 path
- Remove silent fallback behavior in failure paths; sandbox-unavailable cases now fail closed instead of dropping to unsafe host execution.
- Ensure host execution mode (sandbox/direct) is propagated consistently into runtime components, including sub-agent startup.

Permission mode model upgrade
- Rework readonly/approval behavior for run_command from brittle command-text gating to execution-layer enforcement:
  - readonly: run_command executes in read-only sandbox profile.
  - approval: run_command first executes read-only; when permission-denied is detected, request approval and retry once with writable sandbox for that single call.
- Tool loop now returns final post-approval execution result, not intermediate permission-denied payloads.
- Update permission-mode system messaging to describe user-visible behavior without exposing internal implementation details.

Path authorization system
- Add dynamic host policy module and persisted policy file.
- Support dual path classes:
  - writable_paths (read+write)
  - readable_extra_paths (read-only)
- Enforce file access in file_manager by access type (read vs write) under host mode.
- Add host-only frontend 路径授权 management dialog (settings三级菜单入口), including mode switch between 可读可写 and 仅可读 with separate drafts and save flow.

Sub-agent and terminal alignment
- Sub-agent process launch now respects host execution mode and sandbox controls in host mode.
- Keep terminal session model compatible with sandbox-first behavior and execution-mode propagation.

Tool surface updates
- Remove legacy file-management tools from active tool definitions (create_file/create_folder/rename_file/delete_file) while preserving historical conversation compatibility.

Docs updates
- Add dedicated architecture doc: docs/host_sandbox_and_permission_model.md
- Refresh README and AGENTS sections to reflect updated permission/execution model and path-authorization semantics.

Validation performed
- python unittest smoke suite passes: test.test_server_refactor_smoke
- frontend build passes: npm run build
- syntax checks for touched Python modules completed
2026-05-11 13:41:30 +08:00

4.9 KiB
Raw Blame History

宿主机沙箱与权限系统说明（2026-05）

本文档用于完整说明当前项目在 宿主机模式（TERMINAL_SANDBOX_MODE=host） 下的安全执行机制，包括：

  • OS 级沙箱执行
  • 执行环境（Execution Mode）
  • 权限模式（Permission Mode）
  • 路径授权（Path Authorization）
  • run_command / run_python / terminal / sub_agent 的实际行为

1. 设计目标

在保留宿主机开发效率的前提下，降低误操作与越权风险，核心目标是：

  1. 默认命令执行必须经过系统沙箱（而非裸 host）
  2. 权限控制尽量由执行层强制（减少“猜指令”误判）
  3. 对高风险写操作引入用户审批与单次授权机制
  4. 保持可运维：可配置、可回退、可解释

2. 两层控制模型

当前系统分为两层控制，且叠加生效：

2.1 权限模式（产品层）

  • readonly
  • approval
  • unrestricted

作用：决定工具是否允许调用、是否先只读执行、是否需要用户审批。

2.2 执行环境（系统层）

  • sandbox（默认）
  • direct

作用：决定进程最终在 OS 沙箱中执行，还是直接在宿主机执行。

推荐默认：permission_mode=approval + execution_mode=sandbox

3. OS 级沙箱方案

宿主机模式下，默认执行环境为 sandbox，各系统实现如下：

  • macOS：sandbox-exec
  • Linux：bubblewrap (bwrap) + seccomp
  • Windows：WSL2

若宿主机沙箱不可用，关键执行路径会拒绝执行，不允许静默回退到裸 host。

4. 路径授权模型

路径授权分两类：

  1. 可读可写路径（writable_paths）
  2. 仅可读路径（readable_extra_paths）

语义：

  • 可读集合 = 可读可写 + 仅可读
  • 可写集合 = 可读可写

前端“路径授权”弹窗支持这两类路径的维护（新增/编辑/删除），并由后端策略模块统一读取。

5. 各权限模式的实际行为

5.1 readonly

  • run_command：允许调用，但在只读沙箱执行
  • 若命令触发写入：由系统返回权限拒绝（例如 Operation not permitted）
  • write_file / edit_file / 其他写入类工具：直接拒绝

5.2 approval

  • run_command 采用“两段式”：
    1. 先在只读沙箱执行
    2. 若出现权限拒绝，再发起前端审批
    3. 审批通过后，仅该次命令以可写沙箱重试
  • 工具结果返回“最终执行结果”（即重试后结果），不会把中间权限拒绝作为最终结果返回给模型
  • 审批拒绝或超时：返回 rejected，不执行写入重试

5.3 unrestricted

  • 权限模式层不拦截工具
  • 是否沙箱执行取决于执行环境：
    • sandbox：仍在 OS 沙箱中执行
    • direct：宿主机直接执行

6. 执行环境（sandbox/direct）细节

6.1 sandbox（默认）

  • 命令在 OS 沙箱执行
  • 配合路径授权限制写边界（与读边界策略）
  • 可结合权限模式实现只读优先与单次升级写权限

6.2 direct（高权限）

  • 命令直接在宿主机执行
  • 仅建议临时用于必须操作
  • 支持 TTL 自动回退（会话级）到 sandbox

7. 关键工具与执行路径

7.1 run_command

  • 支持权限模式联动（readonly/approval/unrestricted）
  • 在 host + sandbox 下可走只读沙箱或可写沙箱
  • 在 approval 模式可触发“权限拒绝 -> 审批 -> 单次可写重试”

7.2 run_python

  • 复用 run_command 执行路径与执行环境策略
  • 与 run_command 一致受 sandbox/direct 与权限模式影响

7.3 terminal 系列

  • 终端会话从启动时就在沙箱里（host+sandbox）
  • 同一会话中的后续输入继承该会话沙箱上下文
  • 若路径授权更新，需要新开终端会话才能让该会话使用新策略

7.4 子智能体（sub_agent）

  • 宿主机下已接入执行环境策略：
    • sandbox：子智能体进程经宿主机沙箱启动
    • direct：直接宿主机启动
  • Docker 模式维持容器执行

8. 配置与运行建议

8.1 推荐默认策略

  1. TERMINAL_SANDBOX_MODE=host
  2. 执行环境默认 sandbox
  3. 权限模式默认 approval
  4. 路径授权默认最小化（工作区 + 临时目录）

8.2 何时使用 direct

仅在以下场景短时开启：

  • 明确需要系统级高权限访问
  • 沙箱下无法完成且替代方案不可行

执行完成后应尽快回到 sandbox。

9. 已知权衡

  1. run_command 若严格收紧读路径，可能导致大量系统命令可用性下降
  2. 权限拒绝识别基于错误特征，需持续优化误判/漏判边界
  3. 不同 OS 的沙箱能力不完全对齐（Windows 侧为 WSL2 路径）

10. 文案与产品约束

  • 面向用户的提示词仅描述“能力边界”和“可操作建议”
  • 不暴露内部实现细节（如内部判定逻辑、实现细节名称）
  • 审批流程文案要强调“单次授权、最小权限、可回退”