docs.rs failed to build window-sand-box-0.1.1
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

window-sand-box (wsbx)

Windows 沙盒终端执行工具 — 为 AI 提供安全的 Windows 命令行执行环境。

使用 Windows 受限令牌（Restricted Token）、ACL 权限控制和私有桌面隔离技术，在不创建额外用户账号的情况下实现进程级沙盒隔离。

快速开始

安装

cargo install window-sand-box

或从源码构建：

git clone https://github.com/WeiChens/window-sand-box.git
cd window-sand-box
cargo build --release
# 将 target\release\wsbx.exe 添加到 PATH

基本用法

# 只读模式执行（最安全，无需管理员权限）
wsbx exec --readonly cmd /c dir /b

# 可写模式执行（首次会自动弹出 UAC 提权配置 ACL）
wsbx exec cmd /c "echo hello > test.txt && type test.txt"

# 指定工作目录
wsbx exec --cwd C:\projects\my-app git status

# 带超时（10 秒后自动终止）
wsbx exec --timeout 10 python long_running_script.py

安全机制

三层防御体系

┌─────────────────────────────────────────────┐
│ 第一层：受限令牌（进程身份限制）                │
│                                             │
│  CreateRestrictedToken 创建的子进程：          │
│  ├─ DISABLE_MAX_PRIVILEGE → 禁用所有特权      │
│  ├─ LUA_TOKEN → 模拟标准用户，无法提权         │
│  └─ WRITE_RESTRICTED → 限制写入权限           │
└─────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────┐
│ 第二层：Capability SID（会话级别隔离）          │
│                                             │
│  每个工作目录有一个唯一随机 SID。               │
│  只有包含此 SID 的令牌才能写入该目录。           │
│  不同工作目录的 SID 不同，互不干扰。             │
└─────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────┐
│ 第三层：ACL 权限（文件系统控制）                │
│                                             │
│  Allow ACE → 工作目录可读写                    │
│  Deny Write ACE → 敏感目录（.git 等）不可写    │
└─────────────────────────────────────────────┘

权限模型

位置	只读模式	可写模式
工作目录	可读	✅ 可读写删除
工作目录内 .git/.env 等	可读	✅ 可读，不可写
白名单路径	可读	✅ 可读写删除
C:\Windows 等系统路径	✅ 可读	✅ 可读，不可写
黑名单路径	❌ 不可访问	❌ 不可访问

命令参考

`wsbx exec`

在沙盒中执行命令。

wsbx exec [选项] <命令...>

选项：

选项	说明
`--cwd <目录>`	工作目录（默认：当前目录）
`--readonly`	只读模式 — 进程完全没有文件写入权限
`--timeout <秒>`	超时时间，超时自动终止
`--whitelist <路径>`	额外的可写入路径（可多次使用）
`--no-desktop`	禁用桌面隔离（默认启用）

外部命令（.exe）直接执行：

wsbx exec git status
wsbx exec node --version
wsbx exec python -c "print('hello')"

CMD 内部命令需加 cmd /c：

wsbx exec cmd /c dir /b
wsbx exec cmd /c "mkdir test && copy file1.txt file2.txt"

`wsbx clean`

清理当前目录中 wsbx exec 自动添加的所有 ACL 条目（需要管理员权限）。

wsbx clean

库使用（Rust 项目集成）

将 window-sand-box 作为库集成到你的 Rust 项目中：

[dependencies]
window-sand-box = "0.1"

use window_sand_box::SandboxRunner;
use std::collections::HashMap;

let runner = SandboxRunner::new()?;
let cwd = std::env::current_dir()?;
let session = runner.create_session(cwd.clone())?;

// 可写模式执行
let cmd = vec!["cmd".into(), "/c".into(), "echo Hello && dir /b".into()];
let result = runner.execute(&session, &cmd, HashMap::new(), None)?;
println!("退出码: {}", result.exit_code);
print!("{}", result.stdout);

// 只读模式执行（无需管理员权限）
let result = runner.execute_readonly(&cmd, &cwd, HashMap::new(), None)?;

配置

配置文件位于 %USERPROFILE%\.wsbx\config.json（默认）。

{
  "blacklist": [
    "C:\\Windows\\System32\\config"
  ],
  "whitelist": [],
  "sensitive_patterns": [
    ".git",
    ".env",
    ".ssh",
    "node_modules"
  ]
}

常见问题

Q: 为什么命令外的 `&&` 不按预期工作？

wsbx exec cmd /c rmdir ..\hello && dir /b

原因：&& 被你当前的终端解析了，根本没有传到沙盒内部。

解决：用引号包裹整个命令：

wsbx exec cmd /c "rmdir ..\hello && dir /b"

Q: 提示需要管理员权限？

设置 ACL 需要管理员权限。首次在可写模式下执行时，会自动弹出 UAC 提权对话框，点击「是」即可自动完成配置。

Q: 中文输出乱码？

✅ 已自动修复。输出会自动从 GBK/系统代码页转为 UTF-8。

许可证

本项目使用 MIT 许可证。

window-sand-box 0.1.1