JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
79f8ffa368
agent-Specialization/windows-sandbox-research.md
JOJO 42cd99d2d8 feat(windows): WSL2 沙箱执行环境与执行环境提示词平台拆分 
- Windows 宿主机模式基于 WSL2 实现沙箱执行：只读/批准/自动审核识别、
  工作区可写+区外只读挂载、网络档位（受限/开放/禁止）、敏感目录屏蔽
- 新增 scripts/setup-wsl-sandbox.ps1 一键准备 WSL 沙箱发行版
- 执行环境提示词按平台拆分骨架：prompts/execution_mode/macos.txt
  （原 execution_mode.txt，mac/dockerweb 沿用）与 windows.txt
  （骨架+动态注入环境与路径、当前规则、网络档位、切换一致性说明）
- Windows 执行环境切换通知改为完整命令写法说明（双向），mac 保持原样
- 附调研与 PoC 验证报告：wsl2-sandbox-research.md、
  windows-sandbox-research.md、wsl2-sandbox-poc-report.md
2026-07-30 13:06:34 +08:00

20 KiB
Raw Blame History

Windows 沙箱执行不可信命令：开源组件/项目调研报告

调研日期：2026-07（以实际检索为准）；目标场景：Python 智能体运行时在 Windows 上执行不可信命令（一次性命令 + 交互式 shell）。 需求速记：R1 文件只读模式（工作区以外只读）、R2 工作区可写、R3 敏感路径禁读、R4 网络三档（禁网/仅回环/全开）、R5 Python asyncio subprocess 可集成。 所有结论均来自本轮实际检索，检索不到的已明确标注。

0. 结论速览（先看这个）

方案 一句话结论
OpenAI Codex 的 windows-sandbox-rs 需求匹配度最高的"参考答案"：restricted token + ACL + WFP 防火墙，五条需求全覆盖；Apache-2.0，但是 Rust 代码，Python 侧需要借鉴重写或把 codex CLI 当子进程调用
GRR unprivileged/windows/sandbox_lib.py 唯一一个纯 Python（pywin32+ctypes）的 AppContainer 沙箱实现，Apache-2.0，核心代码量小，可直接 vendor；但无网络控制、写授权模型需补齐
Sandboxie-Plus 隔离粒度最细（文件/注册表/网络逐规则配置），命令行可驱动；GPL-3.0 且依赖内核驱动，不能嵌入闭源产品，只能作为"用户自行安装的外部依赖"调用
Windows Sandbox（.wsb） 微软官方一次性 VM，映射文件夹只读/可写、可禁网，但无 stdout/stderr 捕获管道、无编程 API，不适合 agent 自动化
Windows Containers（containerd/runhcs） 不用 Docker 可以跑，但镜像 260MB~5GB+、process isolation 要求镜像与宿主 build 严格匹配，运维成本高，不适合桌面 agent 场景
Dokan/WinFsp 只读视图 只解决 R1（只读视图），不提供进程隔离与网络控制，需叠加 token/ACL；属于"可选增强"而非独立方案
winjail / Firejail Windows 版 查不到，不存在可用品（详见第 3 节）

推荐路线：以 Codex 的 Windows 沙箱设计（restricted token + 合成 SID + ACL 授权 + WFP 网络过滤）为蓝本，用 pywin32/ctypes 在 Python 内实现（GRR 代码可作起点）；把 Sandboxie 作为可选的外部加固后端。

1. Python 可用的 Windows 沙箱库

1.1 GRR grr_response_client.unprivileged.windows（本轮最大发现）

  • 链接：https://github.com/google/grr （模块路径 grr/client/grr_response_client/unprivileged/windows/sandbox_lib.py）
  • 维护状态：google/grr 仓库 5084 star，Apache-2.0，最近提交 2026-05（活跃）
  • 这是什么：一个纯 Python 的 Windows AppContainer 沙箱库，docstring 原文："Windows Sandboxing library based on AppContainers… works only on Windows >= 8"。用 ctypes 调 userenv.CreateAppContainerProfile / DeriveAppContainerSidFromAppContainerName，用 pywin32（win32security/win32service/ntsecuritycon）做 ACL 授权，并创建独立的 window station/desktop。
  • 能力：InitSandbox(name, paths_read_only) 创建 AppContainer 并对指定路径授予 GENERIC_READ|GENERIC_EXECUTE；Sandbox 类管理 window station/desktop 生命周期；同目录 process.py（9KB）负责在沙箱里拉起进程。PyInstaller issue #8289 中有真实用户用它把 exe 跑进 AppContainer 的实例。
  • 需求覆盖：R1 ✅（未授权路径默认拒读写）、R3 ✅（不授权即禁读）、R5 ✅（纯 Python，可与 asyncio 集成）；R2 ⚠️（示例只演示只读授权，可写授权需要同样用 ACL 加 GENERIC_WRITE，代码路径现成）；R4 ❌（无网络控制，需自行叠加 WFP）。
  • 注意：它不是独立 PyPI 包，需要 vendor 该文件（Apache-2.0 允许），依赖 pywin32。

1.2 pywin32 本身

  • 链接：https://github.com/mhammond/pywin32
  • 已核实源码包含 win32job.i（Job Object：CreateJobObject/SetInformationJobObject/AssignProcessToJobObject）、win32security.i（restricted token、ACL）、win32process.i。即"restricted token + Job Object + ACL"三件套在 Python 里不需要写 C 扩展就能拼出来——这是自研路线的地基。
  • 许可：PSF 风格，闭源友好。

1.3 PyPI 上的候选包（均已核实）

包名 状态
sandbox 0.3.5 存在，但简介为 "The Sandbox Libraries (Python)"——是早年 Linux seccomp-nurse 的绑定，与 Windows 无关
pyjail 0.1.4 存在，MIT，是进程内 Python 代码沙箱（非 OS 级），不满足需求
winsandbox / appcontainer / winjail / seccomp 404，不存在

结论：PyPI 上没有成熟的、封装 AppContainer/Job Object/restricted token 的 Windows 沙箱包。成熟度最高的可直接借鉴物就是 GRR 的那个模块。

2. Sandboxie / Sandboxie-Plus

  • 链接：https://github.com/sandboxie-plus/Sandboxie （19034 star，GPL-3.0，2026-07-29 仍有提交，非常活跃；社区 fork，维护者 David Xanatos，项目历史 Ronen Tzur → Invincea → Sophos → 2020 开源）
  • 命令行驱动：✅ 有官方文档（https://sandboxie-plus.github.io/sandboxie-docs/Content/StartCommandLine.html ）：
    • "C:\Program Files\Sandboxie\Start.exe" /box:MyBox /wait /hide_window cmd.exe /c xxx——/wait 会等进程结束并透传退出码；
    • /terminate / /terminate_all 可清空沙箱内进程。
    • stdout 捕获有坑：文档明确 "Start.exe is a Win32 application and not a console application"，即它不转发子进程 stdio。可行做法是在沙箱内重定向：Start.exe /box:X /wait cmd /c "cmdline > C:\boxpath\out.txt 2>&1"，然后从宿主侧读沙箱文件系统根目录下的输出文件。交互式 shell 同理需要走管道桥接，做不到 asyncio.create_subprocess_exec 那种原生 PIPE 体验。
  • 隔离粒度（文档核实）：
    • 文件：ClosedFilePath（禁读禁写，官方文档明确 "deny all access by sandboxed programs, including read"）、ReadFilePath（可读、写入被虚拟化）、OpenFilePath（直通直写）；默认所有写都落在沙箱虚拟层（copy-on-write），不污染宿主。
    • 注册表：ClosedKeyPath 等同类规则。
    • 网络：Plus 版内置基于 WFP 的每沙箱防火墙（NetworkEnableWFP=y + NetworkAccess=<program>,Block/Allow;Protocol=...）。Issue #5109（https://github.com/sandboxie-plus/Sandboxie/issues/5109 ）正是"禁外网但放行本地代理（回环）"的配置讨论——三档网络均可表达。
  • 许可与嵌入：GPL-3.0 + 需要安装签名内核驱动 + 系统服务（SbieDrv/SbieSvc）。结论：不能以库形式嵌入闭源产品（GPL 传染性 + 驱动安装要求）。合法用法是检测用户机器上是否已装 Sandboxie，有则调用，没有则提示安装——属于外部可选依赖。
  • 其他 agent 项目使用情况：没有找到把 Sandboxie 作为嵌入式沙箱后端的知名 agent 项目；但有用户自发把 Cursor 整个 IDE 跑进 Sandboxie 的实践（Discussion #5077，https://github.com/sandboxie-plus/Sandboxie/discussions/5077 ）。
  • 需求覆盖：R1 ✅（ReadFilePath+虚拟化）、R2 ✅（OpenFilePath 或沙箱内写+回收）、R3 ✅（ClosedFilePath）、R4 ✅（WFP 三档可配）、R5 ⚠️（一次性命令可行但 stdout 要走文件；交互式 shell 需自建桥接）。

3. nsjail / minijail / bwrap / Firejail 的 Windows 等价物

  • winjail：GitHub 全库搜索（API 实测）只命中一个不相关的玩笑项目 netcrawlerr/WinJail（2 star，WinForms 弹窗玩具）。**作为沙箱项目的 winjail 查不到，不存在。**PyPI 同名也 404。
  • Firejail：https://github.com/netblue30/firejail 明确是 "Linux namespaces and seccomp-bpf sandbox"，没有 Windows 移植，issue 区讨论也确认无 Windows 支持。
  • nsjail（https://github.com/google/nsjail ）：基于 Linux namespaces/cgroups/seccomp-bpf，Linux 专用。
  • minijail：ChromiumOS 项目，同样 Linux 专用。
  • Windows 生态里事实上的"等价物"是三样东西的组合：AppContainer（能力沙箱）+ restricted token/完整性级别（MIC）+ Job Object（资源限制）。Chromium 的 Windows sandbox 是这套组合最著名的工程实现；2026 年 GSoC 有个面向 Gemini CLI 的 AppContainer PoC（https://github.com/AnushkaPandit-21/appcontainer-node-sandbox ，学生 PoC，C++/Node-API 实现，验证了 CreateAppContainerProfile+ACL+PROC_THREAD_ATTRIBUTE_SECURITY_CAPABILITIES 全链路），可参考但成熟度低。

4. 容器路线：Windows Containers（不装 Docker）

  • 官方文档：https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/hyperv-container ——process isolation 与 Hyper-V isolation 两种。
  • 不装 Docker 能不能跑：能。Windows 10 1809+ / Server 2019+ 内置 HCS（Host Compute Service），可用 containerd + runhcs 直接跑 OCI 容器（TechTarget 综述、James Sturtevant 的实操博客、docker/roadmap#151 均有 walkthrough）。hcsshim（Go 库）是底层 API 封装。
  • 坑（做命令沙箱的硬伤）：
    1. process isolation 要求镜像与宿主内核 build 严格匹配（https://jfreeman.dev/blog/2021/09/01/how-to-run-a-windows-container-from-a-windows-10-virtual-machine/ ），用户机器 build 号千奇百怪，镜像要么全量预置要么 fallback 到 Hyper-V isolation（需要启用 Hyper-V/虚拟机平台，专业版以上）。
    2. 镜像体积：Nano Server ~260–290MB、Server Core 解压后 ~4.8–6.9GB（ltsc2022 5.16GB、ltsc2025 6.86GB，https://github.com/microsoft/Windows-Containers/issues/584 ）。首次拉取 GB 级，冷启动数秒到十数秒。
    3. Python 集成只能走 ctr/runhcs CLI 子进程或自研 hcsshim 绑定。
  • 需求覆盖：R1/R2/R3 ✅（volume mount 可 read-only）、R4 ⚠️（--network none 可禁网，"仅回环"需自建 HNS 网络策略）、R5 ⚠️（经 CLI 间接集成）。结论：技术上可行，但对"桌面 agent 跑一条命令"的场景过重，不推荐。

5. 特殊文件系统过滤：Dokan / WinFsp 只读视图

  • WinFsp：https://github.com/winfsp/winfsp （8774 star，活跃，许可为 GPLv3 + 商业双许可，GitHub API 返回 NOASSERTION 即自定义/双许可）
  • Dokany：https://github.com/dokan-dev/dokany （仓库内含 license.lgpl.txt 与 license.mit.txt，用户态库 LGPL、部分组件 MIT）
  • 可行性：两者都能在用户态实现一个"把宿主目录映射成只读视图"的虚拟盘（WinFsp 官方 passthrough 教程就是现成起点；只读语义由 FS 实现对写操作返回拒绝即可，cgofuse issue #15 讨论了 Windows 上 -o ro 的实现方式）。
  • 但作为沙箱手段有关键缺陷：只读视图管不住"进程直接打开原始路径"——沙箱内进程只要还有权限访问原路径就能绕过挂载点。所以它不能替代 token/ACL 级隔离，只能做：把敏感路径"藏起来不给视图"+ 配合 AppContainer/restricted token 收回原路径访问权。此外还需要安装内核驱动（分发负担 + WinFsp 的 GPL/商业许可成本）。
  • 需求覆盖：R1 ✅（仅视图层面）、R2 ⚠️（叠加 overlay 可实现写重定向）、R3 ⚠️（需配合 token）、R4 ❌、R5 ❌（与进程管理无关）。
  • **结论：可选增强项，不是独立方案。**若最终走 ACL 路线，本项可以跳过。

6. 微软官方 2023–2025 的新东西

  1. Win32 App Isolation（Build 2023 宣布、2024 持续推）：
  2. Windows Sandbox（消费级功能）+ .wsb 配置：
  3. Agent Workspace（Windows 11，2025-10/11 起面向 Insider 推出）：

7. Codex 的 Windows 实现（openai/codex 仓库核实）

  • 仓库：https://github.com/openai/codex （102379 star，Apache-2.0，极活跃）
  • 源码位置：codex-rs/windows-sandbox-rs/，本轮用 GitHub API 核实了完整文件清单，关键模块：acl.rs(27KB)、token.rs(18KB)、cap.rs、proc_thread_attr.rs、process.rs、desktop.rs、identity.rs、elevated/elevated_impl.rs、wfp.rs(16KB)+wfp_setup.rs、deny_read_*.rs、setup.rs(77KB)、conpty/、unified_exec/，外加 sandbox_smoketests.py（Python 冒烟测试）。
  • 架构（InfoQ 2026-06 报道 https://www.infoq.com/news/2026/06/codex-windows-sandbox-design/ + 仓库 issue/讨论交叉验证）：
    • 评估后放弃 Windows Sandbox（要直接访问开发者工作区、且非全 SKU 可用）与单纯 MIC。
    • unelevated 沙箱（第一版）：当前用户上下文下用 restricted token + 合成 SID "sandbox-write"，只对工作区和显式配置的目录授写权限；.git 等敏感元数据用 ACL 拒读（deny_read_* 系列文件就是干这个的）。
    • elevated 沙箱（现行版）：安装时创建专用本地账户（CodexSandboxOffline / CodexSandboxOnline），命令以这些账户 + restricted token 运行（CreateProcessWithLogonW），网络用 WFP 防火墙规则控制——offline 账户禁网、online 账户放网，正好对应"禁网/全开"；配置项 [windows] sandbox = "elevated"|"unelevated"（issue #25566、#33073 等可佐证）。
    • conpty/ 与 unified_exec/ 目录的存在说明他们 ship 了交互式 PTY 会话能力（对应"交互式 shell"需求）。
  • 工程教训（从 issue 区看到的真实代价）：setup helper 需要条件 ACE 规避 UAC（issue #26087 的 740 错误）、配置文件损坏导致 CreateProcessWithLogonW: 1168（#33073）、helper 进程泄漏（#32194）。说明这条路能走通但边角多，自研需要预留测试预算。
  • 需求覆盖：R1 ✅ R2 ✅ R3 ✅ R4 ✅（WFP 三档，仅回环可用 WFP 规则表达）R5 ⚠️（Rust crate，不是 Python 库；Python 集成路径有两条：① 把 codex sandbox -- <cmd> 当外部子进程调用——最省事但引入重依赖；② 以它为蓝本用 pywin32/ctypes 重写核心——token+ACL 部分 GRR 已给出 Python 模板，WFP 部分（fwpuclnt.dll）需自行绑定，工作量集中在网络档）。

8. 需求 × 方案 覆盖矩阵

方案 R1 只读 R2 工作区可写 R3 敏感路径禁读 R4 网络三档 R5 asyncio 集成 许可 嵌入闭源产品
自研（Codex 蓝本 + pywin32/ctypes） ✅ ACL ✅ 授权写 ✅ deny ACL ✅ WFP ✅ 原生 自研 ✅
GRR sandbox_lib（vendor） ✅ ⚠️ 需补写授权 ✅ ❌ 需补 WFP ✅ Apache-2.0 ✅
Sandboxie-Plus（外部调用） ✅ ✅ ✅ ✅ WFP ⚠️ stdout 走文件 GPL-3.0 + 驱动 ❌ 仅外部依赖
Windows Sandbox (.wsb) ✅ ✅ ⚠️ 只映射该映射的 ⚠️ 只有开/关 ❌ 无 stdio OS 内置 —
Windows Containers (runhcs) ✅ ✅ ✅ ⚠️ 回环档麻烦 ⚠️ CLI 间接 Apache-2.0 组件 ⚠️ 运维重
Dokan/WinFsp 只读视图 ✅ 仅视图 ⚠️ overlay ⚠️ 需配合 token ❌ ❌ GPL/商业 或 LGPL/MIT ⚠️
PyPI 现成包 — — — — — — 不存在

9. 落地建议（给运行时的技术选型）

  1. 主路线（自研，强烈推荐）：以 Codex windows-sandbox-rs 为设计蓝本、以 GRR sandbox_lib.py 为 Python 代码起点：
    • 文件隔离：AppContainer 或 restricted token + 合成 SID，工作区授 GENERIC_ALL，其余默认拒写；敏感路径（~/.ssh、~/.aws、浏览器凭据目录等）显式 deny-read ACE；
    • 网络三档：ctypes 绑 fwpuclnt.dll 加 WFP 过滤器（禁网=block all、仅回环=allow 127.0.0.1/::1、全开=不加规则）；Codex 的 wfp.rs 可作逻辑参照；
    • 进程管理：Job Object（pywin32 win32job 现成）做内存/进程数限制与树杀；
    • asyncio 集成：asyncio.create_subprocess_exec 无法直接带 token 启动，需要先用同步 API CreateProcess* 再包装句柄，或封装成 loop.run_in_executor + 管道线程；交互 shell 参考 Codex 的 ConPTY 方案（Python 侧有 pywinpty 可用）。
  2. 可选加固后端：检测用户已安装 Sandboxie 时提供"在 Sandboxie 中运行"选项（GPL 不构成对闭源主程序的传染，因为是外部进程调用而非链接）。
  3. 不要选：Windows Containers（重）、Windows Sandbox（无 stdio）、WinFsp/Dokan 单用（不隔离进程）、等待 winjail 类项目（不存在）。
  4. 值得关注：Windows 11 Agent Workspace 的 API 开放情况——一旦微软开放第三方接入，可能成为官方托管方案。

附：主要信息来源