# window-sand-box (wsbx)
[](https://crates.io/crates/window-sand-box)
[](https://docs.rs/window-sand-box)
[](LICENSE-MIT)
**Windows 沙盒终端执行工具** — 为 AI 提供安全的 Windows 命令行执行环境。
使用 Windows **受限令牌**（Restricted Token）、**ACL 权限控制**和**私有桌面隔离**技术，
在不创建额外用户账号的情况下实现进程级沙盒隔离。
---
## 快速开始
### 安装
```bash
cargo install window-sand-box
```
或从源码构建：
```bash
git clone https://github.com/WeiChens/window-sand-box.git
cd window-sand-box
cargo build --release
# 将 target\release\wsbx.exe 添加到 PATH
```
### 基本用法
```bash
# 只读模式执行（最安全，无需管理员权限）
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`
在沙盒中执行命令。
```bash
wsbx exec [选项] <命令...>
```
**选项：**
| `--cwd <目录>` | 工作目录（默认：当前目录） |
| `--readonly` | 只读模式 — 进程完全没有文件写入权限 |
| `--timeout <秒>` | 超时时间，超时自动终止 |
| `--whitelist <路径>` | 额外的可写入路径（可多次使用） |
| `--no-desktop` | 禁用桌面隔离（默认启用） |
**外部命令（.exe）直接执行：**
```bash
wsbx exec git status
wsbx exec node --version
wsbx exec python -c "print('hello')"
```
**CMD 内部命令需加 `cmd /c`：**
```bash
wsbx exec cmd /c dir /b
wsbx exec cmd /c "mkdir test && copy file1.txt file2.txt"
```
### `wsbx clean`
清理当前目录中 `wsbx exec` 自动添加的所有 ACL 条目（需要管理员权限）。
```bash
wsbx clean
```
---
## 库使用（Rust 项目集成）
将 `window-sand-box` 作为库集成到你的 Rust 项目中：
```toml
[dependencies]
window-sand-box = "0.1"
```
```rust
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`（默认）。
```json
{
"blacklist": [
"C:\\Windows\\System32\\config"
],
"whitelist": [],
"sensitive_patterns": [
".git",
".env",
".ssh",
"node_modules"
]
}
```
---
## 常见问题
### Q: 为什么命令外的 `&&` 不按预期工作？
```bash
wsbx exec cmd /c rmdir ..\hello && dir /b
```
**原因**：`&&` 被**你当前的终端**解析了，根本没有传到沙盒内部。
**解决**：用引号包裹整个命令：
```bash
wsbx exec cmd /c "rmdir ..\hello && dir /b"
```
### Q: 提示需要管理员权限？
设置 ACL 需要管理员权限。首次在可写模式下执行时，会自动弹出 UAC 提权对话框，
点击「是」即可自动完成配置。
### Q: 中文输出乱码？
✅ 已自动修复。输出会自动从 GBK/系统代码页转为 UTF-8。
---
## 许可证
本项目使用 [MIT 许可证](LICENSE-MIT)。