沙盒化Bash执行环境

只需抨击mcp

一个MCP（模型上下文协议）服务器，为AI代理提供沙盒bash环境。

在具有内存中虚拟文件系统的安全、隔离的环境中执行bash命令。

建在上面 just-bash v3.1.0版本。

v3.1.0的新增功能

• 与上游同步 just-bash v3.1.0 -最新版本的完整上游命令、API、类型导出和命令修复
• 沙盒功能转发 - bash_sandbox_* 荣誉Python、JavaScript和命令允许列表配置通过新的上游 SandboxOptions
• 上游外壳修复 -包括更正的重定向路由、多行引号空格、严格模式 set -euo pipefail、heredoc替换和混合字节/文本输出
• 扩展命令兼容性 -包括 jq -R，嵌套jq插值，curl @file 数据，GNU tar选项包，字节干净 head/tail，以及管道式stdin rg
• 字节安全stdin处理 -跟踪上游v3 TypeScript强制的stdin字节/UTF-8模型
• 执行器集成管道 -包括上游支持 js-exec 工具调用钩子和执行器包集成
• ESM运行时修复 -包含上游v3.0.1动态 require("tty")/file 命令崩溃修复
• MCP上的完整上游执行选项 - cwd, env, replaceEnv, stdin, stdinKind, args, rawScript，信号支持中断 timeoutMs，加上MCP友好 stdinBase64
• AST转换工具 - bash_transform 暴露上游 BashTransformPipeline, CommandCollectorPlugin，以及 TeePlugin
• 持久沙盒工具 - bash_sandbox_* 工具仍然可用于更高级别的隔离工作流
• 字节安全文件IO -持久文件工具支持二进制内容的base64读/写
• 纵深防御模式 -上游默认猴子修补危险的JS全局变量（set JUST_BASH_DEFENSE_IN_DEPTH=false 禁用）
• Python支持 -Python3通过上游emscripten-CPython运行时(JUST_BASH_ENABLE_PYTHON=true)
• 可挂载FS+读写FS -带有覆盖/读写选项的真实目录挂载
• 可配置的执行限制 -对循环、字符串、数组、heredocs和替换进行细粒度控制

特性

• 沙盒执行：命令在隔离的虚拟文件系统中运行
• 无状态和有状态模式：在隔离执行或持久文件系统之间进行选择
• 网络访问控制：带URL允许列表的可选网络访问
• 执行限制：防止无限循环和深度递归
• 覆盖FS支持：以只读方式挂载实际目录，并在写入时进行复制
• 可安装FS支架：在不同路径上装载多个文件系统
• ReadWriteFS支持：对真实目录的直接读写访问

同步上游功能

当前包装器的发布轨迹 just-bash v3.1.0，包括：

• 用于Python、JavaScript、命令过滤器、自定义命令和自定义获取实现的沙盒转发
• 为链式stdout/stderr重定向纠正最终目标路由
• UTF-8修复了混合文本和字节生成语句的脚本
• 多行引号字符串空格保留
• 普通变量赋值的深度防御修复
• Heredoc感知命令替换解析
• set -euo pipefail 短选项集群支持
• jq -R 插值中的原始输入模式和嵌套引号字符串
• curl @file 数据选项的处理
• GNU旧式tar选项包，如 tar czf
• 字节清理 head/tail，管道标准输入 rg，并更正了JavaScript缓冲区编码
• 默认UTC date 明确的行为 TZ 支持
• 破解v3 stdin字节/UTF-8处理自定义命令更新
• 执行人和 js-exec 集成管道
• ESM节点捆绑包动态需要修复加载的命令 tty 传递地
• jq JSON字符串中的控制字符处理
• 更快 grep 通过匹配器重用和文字预过滤进行模式匹配
• AWK lexer修复了POSIX多行语句继续
• 跨网络、sqlite3、xan、rg、终端渲染和CI的错误修复
• 工作区/变更集迁移，公共导入路径和bin条目不变
• 跨运行时和文件系统层的深度防御强化
• 上游默认启用纵深防御，加上额外的硬化通道
• 用于覆盖、外部文件系统、符号链接和损坏符号链接处理的文件系统强化
• 虚拟PID和shell安全不变性改进
• 已更新 Sandbox.runCommand() 签名兼容性
• Python运行时从Pyodide迁移到emscripten-CPython
• 跟进Python运行时强化和清理
• UTF-8处理和写入路径修复
• 上游CommonJS兼容性改进
• ls -F / --classify 支持
• 额外的清理和内部硬化工作通过运输 v3.1.0

GitHub主审计

已检查 vercel-labs/just-bash main 在承诺时 6130334f0ed013771bbe39f32a249bdaf762c488.这是一个未发布的命令，只能在其之前提交 v3.1.0，添加GNU cat 显示标志(-A, -b, -e, -E, -s, -t, -T，以及 -v).上游舱单仍然存在 3.1.0；此包装器有意跟踪可复制的npm发布，而不是未版本化的Git提交。

安装

来自npm（推荐）

需要Node.js 22或更高版本。

npm install -g just-bash-mcp

# Or with bun
bun add -g just-bash-mcp

来源

git clone https://github.com/dalist1/just-bash-mcp.git
cd just-bash-mcp
bun install
bun run check

用法

运行服务器

just-bash-mcp

# Or from source
bun run dev

MCP客户端配置

使用npx（无需安装）

{
  "mcpServers": {
    "just-bash": {
      "command": "npx",
      "args": ["-y", "just-bash-mcp"]
    }
  }
}

克劳德桌面版

增添 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "just-bash": {
      "command": "npx",
      "args": ["-y", "just-bash-mcp"]
    }
  }
}

光标/VS代码（房间代码/Cline）/风帆

添加到MCP设置中：

{
  "mcpServers": {
    "just-bash": {
      "command": "npx",
      "args": ["-y", "just-bash-mcp"]
    }
  }
}

环境变量

工具

bash

在沙盒环境中执行bash命令。这是上游兼容的MCP暴露 just-bash/bash-tool 执行接口并接受相同的单个 command 争论。

{
  "name": "bash",
  "arguments": {
    "command": "ls -la && cat package.json | head -5"
  }
}

bash_exec

在新的沙盒环境中执行bash命令。支持上游 exec() 选项： cwd, env, replaceEnv, stdin, stdinKind, args, rawScript，以及 timeoutMs （加上MCP友好 stdinBase64 对于字节stdin）；初始文件可以是字符串或 {content, encoding, mode, mtime} 物体。

{
  "name": "bash_exec",
  "arguments": {
    "command": "echo 'Hello World' && ls -la",
    "files": { "/tmp/data.json": "{\"key\": \"value\"}" }
  }
}

bash_exec_persistent

在持久沙盒环境中执行bash命令。文件系统跨调用持久化，并支持相同的上游 exec() 选项如 bash_exec.

bash_reset

重置持久bash环境，清除所有文件和状态。

bash_write_file / bash_read_file / bash_list_files

持久环境中的文件操作。读/写支持 encoding: "utf-8" | "base64" 用于字节安全内容。

bash_direct_read / bash_direct_write

直接文件系统读/写操作（绕过shell执行）。

bash_info

获取有关bash环境配置的信息，包括深度防御违规统计数据。

bash_get_cwd / bash_get_env

获取当前工作目录或环境变量。

bash_sandbox_*

持久隔离环境帮助程序：

• bash_sandbox_run -运行带有可选结构化输出/日志的命令
• bash_sandbox_domain -获取当前沙盒域/标识符
• bash_sandbox_write_files -一次写入多个文件
• bash_sandbox_read_file -读取文件（支持base64编码）
• bash_sandbox_mkdir -创建目录
• bash_sandbox_extend_timeout -延长沙盒超时预算
• bash_sandbox_stop -停止并清理沙盒状态
• bash_sandbox_reset -重置沙盒状态

bash_transform

使用上游AST转换管道转换bash脚本，而无需执行它。支持 CommandCollectorPlugin 和 TeePlugin 通过 collectCommands 和 teeOutputDir.

支持的命令

文件操作

cat, cp, file, ln, ls, mkdir, mv, readlink, rm, split, stat, touch, tree

文本处理

awk, base64, column, comm, cut, diff, expand, fold, grep (+ egrep, fgrep), head, join, md5sum, nl, od, paste, printf, rev, rg （ripgrep）， sed, sha1sum, sha256sum, sort, strings, tac, tail, tr, unexpand, uniq, wc, xargs

数据处理

jq （JSON）， js-exec （启用时通过QuickJS使用JavaScript/TypeScript； node 是兼容性通知）， python3/python （当启用时）， sqlite3 （SQLite）， xan （CSV）， yq （YAML/XML/TOML/CSV）

压缩和存档

gzip (+ gunzip, zcat), tar

导航与环境

basename, cd, dirname, du, echo, env, export, find, hostname, printenv, pwd, tee, whoami

壳牌公用事业公司

alias, bash, chmod, clear, date, expr, false, help, history, seq, sh, sleep, time, timeout, true, unalias, which

网络命令（启用时）

curl, html-to-markdown

抽壳特征

• 管： cmd1 | cmd2
• 重定向： >, >>, 2>, 2>&1, <
• 命令链： &&, ||, ;
• 变量： $VAR, ${VAR}, ${VAR:-default}
• 球状图案： *, ?, [...], **/*.ts
• If/else、函数、循环(for, while, until)
• 象征性和硬链接

文件系统示例

OverlayFS（从磁盘读取，写入内存）

{
  "env": {
    "JUST_BASH_OVERLAY_ROOT": "/path/to/your/project"
  }
}

ReadWriteFS（直接磁盘访问）

{
  "env": {
    "JUST_BASH_READ_WRITE_ROOT": "/path/to/sandbox"
  }
}

MountableFS（多个支架）

{
  "env": {
    "JUST_BASH_MOUNTS": "[{\"mountPoint\":\"/data\",\"root\":\"/shared/data\",\"type\":\"overlay\"},{\"mountPoint\":\"/workspace\",\"root\":\"/tmp/work\",\"type\":\"readwrite\"}]"
  }
}

网络访问示例

{
  "env": {
    "JUST_BASH_ALLOW_NETWORK": "true",
    "JUST_BASH_ALLOWED_URLS": "https://api.github.com,https://api.example.com"
  }
}

凭证从上游转换 allowedUrlPrefixes 可通过以下方式获得 JUST_BASH_ALLOWED_URLS_JSON:

{
  "env": {
    "JUST_BASH_ALLOW_NETWORK": "true",
    "JUST_BASH_ALLOWED_URLS_JSON": "[{\"url\":\"https://api.example.com\",\"transform\":[{\"headers\":{\"Authorization\":\"Bearer token\"}}]}]"
  }
}

设置 JUST_BASH_ALLOW_NETWORK=true 如果没有URL允许列表，则启用上游明确危险的全互联网模式。更喜欢允许列表。私有/环回阻止遵循上游的生产默认设置，除非 JUST_BASH_DENY_PRIVATE_RANGES 已明确设置。

安全模型

• 虚拟文件系统隔离（默认情况下没有真正的文件系统访问）
• 执行限制可防止无限循环和递归
• 无主机二进制执行；可选的WASM运行时（Python、JS、SQLite）由功能标志控制
• 默认情况下禁用网络；配置后，将强制执行URL和方法允许列表
• 纵深防御模式 （默认启用，匹配上游）：Monkey修补危险的JS全局变量(Function, eval, setTimeout, process等）以阻止转义向量
• 安全违规记录器：跟踪所有深度防御违规行为，并通过以下方式访问完整统计数据 bash_info
• 丰富的网络错误分类: NetworkAccessDeniedError, TooManyRedirectsError, RedirectNotAllowedError 用于精确的错误消息

上游API覆盖范围

此包装器集成了的完整公共API表面 just-bash v3.1.0版本：

包根重新导出已安装的上游 just-bash 面向下游消费者的公共API，以及 src/types.ts 仍然是直接通配符传递。

许可证

阿帕奇-2.0