agentic-dev3o/sandbox-shell
GitHub: agentic-dev3o/sandbox-shell
基于macOS Seatbelt的轻量级沙箱CLI，以默认拒绝策略隔离文件系统和网络，保护开发环境中的敏感凭证不被恶意依赖包窃取。
Stars: 14 | Forks: 1
# sx - 用于安全开发的 macOS Sandbox CLI
[](https://github.com/agentic-dev3o/sandbox-shell/actions/workflows/QA.yaml)
[](LICENSE)
[](https://developer.apple.com/documentation/security/app_sandbox)
一个轻量级的 Rust CLI，用于将 shell 命令封装在 macOS Seatbelt 沙箱中。你刚安装的那个 npm 包？它无法读取你的 `~/.ssh` 密钥或 `~/.aws` 凭证。看不见的东西就无法窃取。
供应链攻击无处不在。单个受损的依赖项试图窃取你的机密？它做不到——文件系统默认为拒绝。即使启用了网络，你的凭证也无法被读取。无需容器，无需 VM，仅使用原生 macOS 沙箱技术。
## 快速开始
```
brew tap agentic-dev3o/sx
brew install sx
# 就这样。现在运行不受信任的代码：
sx -- npm run build
sx -- cargo test
sx -- ./build.sh
# 或者启动一个交互式沙箱 shell
sx
```
你的机密保持机密。恶意的 postinstall 脚本什么也得不到。
## 配置文件
配置文件可以叠加。组合使用它们：`sx online rust -- cargo build`
| Profile | 作用 |
|---------|--------------|
| `base` | 最小沙箱（始终包含） |
| `online` | 完整网络访问 |
| `localhost` | 仅限 127.0.0.1 |
| `rust` | Cargo/rustup 路径 |
| `bun` | `~/.bun` + 用于模块解析的父目录列表 |
| `claude` | Claude Code 路径（包含 `online`） |
| `gpg` | GPG 签名 |
### 示例
```
# Bun
sx bun -- bun install # Offline, from cache
sx bun online -- bun install # Download deps
# Rust
sx rust -- cargo test # Offline tests
sx rust online -- cargo build # Download crates
# Claude Code - 核心意义
sx claude -- claude --dangerously-skip-permissions --continue
# 带网络的交互式 shell
sx online
```
## Claude Code 集成
Claude Code 有一个内置的沙箱模式。听起来不错，但它允许**只读访问你的整个文件系统**。受损的依赖项仍然可以读取你的 `~/.ssh` 密钥、`~/.aws` 凭证并将其窃取。
`sx` 是默认拒绝的。敏感路径被阻止*读取*，而不仅仅是写入。恶意代码无法窃取它看不见的东西。
```
sx claude -- claude --dangerously-skip-permissions --continue
```
Claude 以代理方式运行，没有权限提示。依赖项中的供应链攻击？它们也会被沙箱化。这就是我使用的设置。
## 安装
### Homebrew
```
brew tap agentic-dev3o/sx
brew install sx
```
### 从源码构建
```
git clone https://github.com/agentic-dev3o/sandbox-shell.git
cd sandbox-shell
cargo install --path .
```
需要 macOS 和 Rust 1.70+。
## 配置
### 全局配置 (`~/.config/sx/config.toml`)
你的个人路径放在这里。Terminal、shell 提示符、目录跳转...
```
[filesystem]
allow_read = [
# Shell prompt
"~/.config/starship.toml",
"~/.cache/starship/",
# zoxide
"~/.local/share/zoxide/",
# Ghostty users - you need this or terminal breaks in sandbox
"/Applications/Ghostty.app/Contents/Resources/terminfo",
# Claude Code plugins
# "~/projects/my-plugins/",
]
allow_write = [
"~/.local/share/zoxide/",
"~/Library/Application Support/zoxide/",
"~/.cache/",
]
```
**Ghostty 用户：** 添加该 terminfo 路径，否则会出现显示问题。
### 项目配置 (`.sandbox.toml`)
针对项目的覆盖设置：
```
sx --init
```
```
[sandbox]
profiles = ["rust"]
[filesystem]
allow_write = ["/tmp/build"]
[shell]
pass_env = ["NODE_ENV", "DEBUG"]
```
自定义配置文件放在 `~/.config/sx/profiles/name.toml` 中。它们支持文件系统路径、环境变量、exec sugid 和用于高级沙箱操作的原始 seatbelt 规则。参见 [docs/PROFILES.md](docs/PROFILES.md)。
## 用法
```
sx [OPTIONS] [PROFILES]... [-- ...]
```
```
# 离线 (默认)
sx -- npm run build
sx -- ./scripts/setup.sh
# 仅 Localhost - 用于开发服务器
sx localhost -- npm start
# 在线
sx online rust -- cargo audit
sx bun online -- bun install
# 调试被拦截的内容
sx --trace -- cargo build # Real-time violation log
sx --explain rust # Show allowed/denied
sx --dry-run rust # Preview seatbelt profile
```
### 选项
| 选项 | 描述 |
|--------|-------------|
| `-v, --verbose` | 显示沙箱配置 |
| `-d, --debug` | 记录所有拒绝操作 |
| `-t, --trace` | 实时违规流 |
| `--trace-file ` | 将跟踪写入文件 |
| `-n, --dry-run` | 打印配置文件，不执行 |
| `-c, --config ` | 使用指定配置 |
| `--no-config` | 忽略所有配置 |
| `--explain` | 显示允许/拒绝的内容 |
| `--init` | 创建 `.sandbox.toml` |
| `--offline` | 阻止网络（默认） |
| `--online` | 允许网络 |
| `--localhost` | 仅限 127.0.0.1 |
| `--allow-read ` | 允许读取 |
| `--allow-write ` | 允许写入 |
| `--deny-read ` | 拒绝读取（覆盖允许规则） |
| `--trace` 显示系统上*所有*沙箱进程的违规，而不仅仅是你的。macOS 限制。
## 安全模型
### 始终拒绝（即使你允许了 `~`）
这些路径被显式阻止。即使你的配置允许主目录，这些路径仍受保护：
| 路径 | 内容 |
|------|------|
| `~/.ssh` | SSH 密钥 |
| `~/.aws` | AWS 凭证 |
| `~/.docker/config.json` | Docker 凭证 |
| `~/Documents`, `~/Desktop`, `~/Downloads` | 个人文件 |
其他所有内容（`~/.config/gh`, `~/.netrc`, `~/.gnupg`...）均被默认拒绝策略阻止。需要时使用 `gpg` 等配置文件允许特定路径。
### 网络模式
| 模式 | 标志 | 效果 |
|------|------|--------|
| Offline | (默认) | 全部阻止 |
| Localhost | `localhost` | 仅限 127.0.0.1 |
| Online | `online` | 完整访问 |
### 工作原理
**读取：** 默认拒绝。仅允许 `/usr`, `/bin`, `/Library`, `/System`。
**写入：** 默认拒绝。仅允许工作目录和 `/tmp`。
**网络：** 默认阻止。
## 使用案例
供应链攻击是主要威胁。依赖树中那个受损的包运行 postinstall 脚本，将 `~/.aws` 窃取到某个随机服务器。或者更糟，投放恶意软件。
`sx` 使 npm/bun/yarn 变得安全。此外：不受信任的仓库、随机构建脚本、本地 CI/CD 隔离、Claude Code 代理循环、安全研究...
## Shell 集成
提示符指示器、Tab 补全、别名。
**Zsh** (`~/.zshrc`):
```
source $(brew --prefix)/share/sx/sx.zsh
```
**Bash** (`~/.bashrc`):
```
source $(brew --prefix)/share/sx/sx.bash
```
**Fish**:
```
cp $(brew --prefix)/share/sx/sx.fish ~/.config/fish/conf.d/
```
### 提示符颜色
- `[sx:offline]` 红色 - 网络已阻止
- `[sx:localhost]` 黄色 - 仅限 localhost
- `[sx:online]` 绿色 - 完整网络
### 别名
| 别名 | 命令 |
|-------|---------|
| `sxo` | `sx online` |
| `sxl` | `sx localhost` |
| `sxb` | `sx bun online` |
| `sxr` | `sx online rust` |
| `sxc` | `sx online gpg claude` |
## 比较
| 工具 | 平台 | 开销 | 凭证保护 | 网络控制 |
|------|----------|----------|----------------------|-----------------|
| **sx** | macOS | 无 | ✅ 默认拒绝 | ✅ Offline/localhost/online |
| Docker | 跨平台 | 容器运行时 | ⚠️ 手动 | ⚠️ 手动 |
| Firejail | Linux | 最小 | ✅ Profiles | ✅ Profiles |
| Claude sandbox | macOS | 无 | ❌ 到处只读 | ❌ 无 |
| VM | 跨平台 | 重 | ✅ 完整 | ✅ 完整 |
## 开发
```
cargo fmt
cargo test
cargo build
cargo run -- --help
```
## 许可证
MIT
## 贡献
欢迎 PR。在修改沙箱行为之前，请阅读安全模型。
标签：Agentic Workflow, AWS安全, Claude Code, devsecops, DNS 反向解析, GPG, Homebrew, JSONLines, npm安全, Python安全, Rust, Sandbox, Seatbelt, SSH安全, XML 请求, 供应链攻击, 凭据保护, 可视化界面, 安全开发, 恶意软件防护, 文件系统隔离, 文档安全, 构建安全, 沙箱, 网络安全审计, 网络流量审计, 进程隔离, 通知系统, 通知系统, 隔离执行, 零信任, 默认拒绝