lite沙盒mcp

MCP（模型上下文协议）服务器，提供 bash 该工具可替代AI编码代理中的基本shell访问。目标是让代理在没有每个命令权限提示的情况下自由运行shell命令，同时通过静态分析和运行时验证来加强安全性——命令被解析为AST并根据白名单进行验证，然后通过具有运行时路径验证的shell解释器执行，该路径验证可以捕获变量扩展旁路。

使用Claude代码进行配置

自动安装

配置Claude Code最简单的方法是使用内置的install命令：

lite-sandbox install

这会自动：

将MCP服务器添加到 ~/.claude.json （用户范围）
添加自动允许权限 ~/.claude/settings.json
将使用指令添加到 ~/.claude/CLAUDE.md

运行install命令后重新启动Claude Code。

Manual Installation (click to expand)

如果您更喜欢手动配置或需要自定义设置：

1.添加MCP服务器

将此添加到 .mcp.json 在项目根目录中（项目范围内）或 ~/.claude.json 在...之下 mcpServers key（用户范围/全局）：

{
  "mcpServers": {
    "lite-sandbox": {
      "command": "/path/to/lite-sandbox",
      "args": ["serve-mcp"]
    }
  }
}

替换 /path/to/lite-sandbox 以及构建二进制文件的实际路径。

2.自动允许工具

将此添加到 ~/.claude/settings.json 所以Claude Code从不提示许可：

{
  "permissions": {
    "allow": [
      "mcp__lite-sandbox__bash"
    ]
  }
}

3.指示Claude更喜欢沙盒工具

将以下内容添加到您的 ~/.claude/CLAUDE.md （全局）或项目级别 CLAUDE.md:

ALWAYS use the mcp__lite-sandbox__bash tool for running shell commands instead of the built-in Bash tool. The sandboxed tool is pre-approved and requires no permission prompts. Only fall back to Bash if the sandboxed tool cannot handle the command.

备注：工具名称遵循模式 mcp____。如果在MCP配置中以不同的方式命名服务器，请相应地调整工具名称。

配置

可以通过平台适当位置的配置文件允许额外的命令：

Linux: ~/.config/lite-sandbox/config.yaml
macOS: ~/Library/Application Support/lite-sandbox/config.yaml

extra_commands:
  - curl
  - python3

配置文件在更改时会自动重新加载，无需重新启动服务器。

CLI配置管理

# Print config file path
lite-sandbox config path

# Show current configuration
lite-sandbox config show

# Add extra allowed commands
lite-sandbox config extra-commands add curl wget

# List extra allowed commands
lite-sandbox config extra-commands list

# Remove extra allowed commands
lite-sandbox config extra-commands remove curl

Git支持

Git命令默认启用，具有可配置的细粒度权限级别：

git:
  local_read: true   # git status, log, diff, show (default: true)
  local_write: true  # git add, commit, branch, tag (default: true)
  remote_read: true  # git fetch, pull, clone (default: true)
  remote_write: false # git push (default: false)

远程写入操作(git push)默认情况下被禁用，因为它们会影响共享状态。仅当您想允许Claude推送提交时才启用它们：

# Show current git configuration
lite-sandbox config show

# Edit config file to enable git push
# Add 'remote_write: true' under the git section

Git命令使用运行时路径验证来确保存储库路径保持在允许的目录内。， git -C $REPO_DIR status 验证扩展路径）。

Go运行时支持

Go命令(go build, go test, go mod等等）默认情况下被禁用。通过配置启用它们：

runtimes:
  go:
    enabled: true    # Allow go build, test, mod, etc. (default: false)
    generate: false  # Allow go generate (default: false)

Go运行时命令使用与其他命令相同的运行时路径验证，以确保文件路径保持在允许的目录内。这实现了安全的开发工作流程，例如：

go mod init myproject
go test ./...
go build -o mybinary

这 go generate 子命令需要显式的opt-in，因为它可以执行源文件中指定的任意代码。

看 e2e/claude/test_go_runtime_e2e.py 获取一个完整的示例，演示仅使用沙盒工具的Go开发工作流（模块初始化、测试、git工作流）。

pnpm运行时支持

默认情况下禁用pnpm命令。通过配置启用它们：

runtimes:
  pnpm:
    enabled: true   # Allow pnpm install, add, test, run, etc. (default: false)
    publish: false  # Allow pnpm publish (default: false)

通过CLI启用pnpm：

# Enable pnpm commands
lite-sandbox config runtimes pnpm enable

# Enable with publish permission
lite-sandbox config runtimes pnpm enable --with-publish

# Show current pnpm configuration
lite-sandbox config runtimes pnpm show

pnpm运行时命令启用安全的包管理工作流：

pnpm install
pnpm add react
pnpm test
pnpm run build

安全功能：

pnpm dlx 被阻止（下载并执行远程包）
pnpm publish 需要显式的opt-in，因为它会影响npm注册表（共享状态）

安全模型

命令要经过多个验证层：

静态飞行前（AST级别，执行前）

命令白名单 --只有明确允许的非破坏性命令才能运行（例如。， cat, ls, grep, find).代码执行运行时、网络工具、包管理器和shell转义命令都被阻止。可以通过配置允许其他命令。
参数验证 --每个命令验证器阻止危险标志（例如。， find -exec, tar -x, git push).写入命令(cp, mv, rm, sed等等）被允许但路径被验证。
结构限制 --进程替换、协进程、读写重定向和动态命令名被阻止。
静态路径验证 --字面路径类参数（包括嵌入在标志中的路径，如 -f/path 和 --file=/path)通过符号链接解析解析为绝对路径，并根据允许的目录列表进行检查（默认为cwd）。访问 .git 目录被阻止。

运行时验证（解释器级别，执行期间）

命令通过 mvdan.cc/sh/v3 shell解释器而不是 bash -c。这允许在变量扩展后进行运行时验证：

扩展路径验证 A. CallHandler 在变量和命令替换扩展后拦截每个命令，验证所有解析的路径参数是否都在允许的目录内。这捕获旁路像 cat $HOME/secret 静态分析无法解决这个问题。
重定向路径验证 一 OpenHandler 拦截所有重定向打开的文件（例如。， $OUTPUT)，在发生任何I/O之前验证扩展路径。

操作系统级沙盒（可选）

可选的操作系统级沙盒在AST级验证之上提供了额外的隔离层。该实现为每个平台使用本机沙盒机制：

Linux — Bublewrap 通过Linux命名空间
macOS — sandbox-exec 具有动态生成的SBPL配置文件

架构：

长寿工人 --一个沙盒进程，通过stdin/stdout接受gob编码的命令
过程复用 --worker在不重新启动沙盒的情况下执行多个命令，从而减少了开销
自动恢复 --检测到死亡工人并自动更换
和父母一起死 --如果MCP服务器退出，则该工作人员将被杀死

配置：

通过配置文件启用（Linux： ~/.config/lite-sandbox/config.yaml，macOS： ~/Library/Application Support/lite-sandbox/config.yaml):

os_sandbox: true          # Enable OS-level sandboxing (default: false)

或者通过CLI：

# Enable OS sandbox
lite-sandbox config os-sandbox enable

# Show current status
lite-sandbox config os-sandbox show

Linux（气泡包装）

命令通过Linux命名空间在轻量级容器内执行：

隔离功能：

只读根文件系统 --整个主机文件系统以只读方式挂载，防止在允许的路径之外写入
可写工作目录 --项目目录被绑定挂载为可写
可写/tmp --tmpfs被挂载在 /tmp 用于临时文件和构建缓存
新鲜/dev和/proc --新的设备和进程文件系统阻止访问主机状态
网络共享 --保留网络访问权限（取消共享除网络之外的所有内容）
运行时绑定挂载 --为启用的运行时安装了额外的可写路径（例如。， $GOPATH/bin Go）

要求：

仅限Linux --需要具有无特权用户命名空间的Linux内核
已安装气泡膜 --通过包管理器安装（例如。， apt install bubblewrap, pacman -S bubblewrap)
内核配置 --某些系统要求启用无特权用户命名空间：

  # Check if enabled (should be 1)
  sysctl kernel.unprivileged_userns_clone

  # Enable temporarily
  sudo sysctl -w kernel.unprivileged_userns_clone=1

  # Enable permanently (add to /etc/sysctl.conf)
  kernel.unprivileged_userns_clone=1

macOS（沙盒执行）

命令通过以下方式在动态生成的SBPL（基于方案的配置文件语言）沙盒配置文件中执行 sandbox-exec:

隔离功能：

可写工作目录 --只有项目目录（及其解析的符号链接）是可写的
可写入的临时目录 — /tmp, /private/tmp, /var/folders，以及 /private/var/folders 可写（构建缓存和 TMPDIR)
SSH密钥保护 --SSH私钥 ~/.ssh 始终拒绝读取权限； known_hosts, config，以及 authorized_keys 保持可访问性
AWS凭证保护 — ~/.aws 配置AWS IMDS时被拒绝读取访问
网络接入 --网络访问被保留
流程执行 --允许全进程执行（在文件系统级别强制执行）

要求：

仅限macOS --使用内置 sandbox-exec 命令（无需额外软件）

纵深防御：

操作系统沙箱在AST级别验证的基础上提供了深度防御：

如果危险的命令绕过AST验证，文件系统限制将阻止在工作目录外写入
在到达操作系统沙箱之前，进程替换和命令注入仍然在AST级别被阻止
操作系统沙箱不会取代AST验证——两层协同工作

已知限制

这是一个基于静态分析的轻量级、尽力而为的沙盒。它是不相当于容器、VM或seccomp的安全边界。已知的旁路和限制：

路径验证绕过

全球扩张：Glob模式被验证为文字字符串（例如。， cat ./*.txt 检查前缀 ./)，但解释器会在运行时扩展globs。根位于允许目录内的glob不能扩展到允许目录外，但这依赖于允许目录内不包含对抗符号链接的文件系统。
多字符短标志歧义：适用于短旗，如 -la，提取器假定单个char标志+值（提取 a).这是保守的，不会导致路径验证的假阴性，因为 a 独自一人无法通过 looksLikePath 检查，但像组合标志一样 -abc/etc/passwd 只会检查 bc/etc/passwd （缺少主角）。

命令验证限制

每命令参数验证：一些列入白名单的命令具有通过参数验证器阻止的危险标志。对于 find，旗帜 -exec, -execdir, -ok, -okdir, -delete, -fls, -fprint, -fprint0，以及 -fprintf 都被封锁了。其他命令，如 xxd 可以用以下方式写入文件 -r 当与重定向结合时（尽管重定向被阻止）。
没有系统调用级别的强制执行：AST验证发生在执行之前，没有运行时系统调用过滤（没有seccomp）。如果命令被允许并通过AST验证，则它将使用环境授予的权限执行。可选的操作系统沙箱（Linux上的bubblewrap，macOS上的sandbox exec）通过文件系统隔离提供了显著的额外保护——即使危险的命令绕过AST验证，文件系统限制也会阻止在工作目录之外的写入。
Bash内置：一些允许的内置组件，如 set, export，以及 trap 可以修改shell状态，从而影响同一调用中的后续命令。

一般限制

没有完整的安全边界：AST级沙盒是限制LLM访问主机系统的深度防御。它不应该是不受信任的工作负载的唯一安全机制。可选的操作系统沙箱（Linux上的bubblewrap，macOS上的sandbox exec）增加了显著的文件系统隔离，但仍然共享网络命名空间，并且不提供seccomp级别的系统调用过滤。为了最大限度地隔离不受信任的工作负载，请使用VM。
口译员差异：命令是通过mvdan.cc/sh解释器而不是GNU bash执行的。虽然它支持标准的POSIX和bash功能，但一些GNU bash扩展的行为可能会有所不同。
额外命令绕过验证：通过添加命令 extra_commands 允许配置，无需任何参数验证。只添加您信任的命令。

建筑

go build -o lite-sandbox
./lite-sandbox install  # Automatically configure Claude Code

发展

go test ./...              # Run all tests
go test -v ./tool/...      # Run tool package tests with verbose output

E2E测试

端到端测试通过Claude Agent SDK验证真实世界的使用情况。他们测试了Claude是否可以成功使用沙盒MCP工具，而无需回到内置的Bash：

cd e2e/claude
uv run pytest -v          # Run all e2e tests
uv run pytest -v -k test_go_project_workflow  # Run specific test

展示测试: e2e/claude/test_go_runtime_e2e.py 演示了一个完整的Go开发工作流——模块初始化、编写代码和测试、运行 go test，并创建一个git commit——所有这些都只使用 bash 没有内置Bash调用的MCP工具。该测试展示了沙盒如何为AI编码代理实现安全、自主的开发工作流程。

Lite Sandbox MCP

快速接入

详细介绍