sandbox-runtime

GitHub
3.8k 261 简单 1 次阅读 今天Apache-2.0Agent插件
AI 解读 由 AI 自动生成，仅供参考

sandbox-runtime 是 Anthropic 推出的一款轻量级沙箱工具，旨在操作系统层面为任意进程强制实施文件系统和网络访问限制，且无需依赖传统的容器技术。它主要解决了 AI 智能体、本地服务或脚本在运行时可能意外泄露敏感数据（如 SSH 密钥）或发起未授权网络连接的安全隐患，通过“默认安全”的理念，让进程仅在明确授权的范围内活动。

这款工具特别适合开发者、研究人员以及致力于构建安全 AI 代理系统的工程师使用。无论是隔离本地 MCP 服务器、限制 Bash 命令权限，还是测试不受信任的代码片段，sandbox-runtime 都能提供可靠的防护边界。

其核心技术亮点在于巧妙利用了操作系统的原生沙箱机制：在 macOS 上动态生成 Seatbelt 配置文件调用 sandbox-exec，而在 Linux 上则借助 bubblewrap 实现命名空间隔离。此外，它还支持基于代理的网络过滤和 Unix 套接字访问控制，并能实时监控系统违规日志。作为一个开源的研究预览项目，sandbox-runtime 正帮助社区以更低的成本构建默认更安全的智能应用生态。

使用场景

某开发团队在本地部署 AI 助手时，需要让模型调用文件系统工具（MCP Server）来整理项目文档，但极度担心模型因“幻觉”误删核心代码或泄露 SSH 密钥。

没有 sandbox-runtime 时

  • 权限过大风险：AI 进程以当前用户全权限运行，一旦生成错误指令（如 rm -rf），可直接删除整个主目录下的敏感文件。
  • 数据泄露隐患：模型若被诱导执行恶意命令，可随意读取 ~/.ssh/id_rsa 等隐私凭证并外传，毫无阻拦。
  • 网络不可控：进程可能擅自连接外部未知域名，导致内部代码库被偷偷上传至攻击者服务器。
  • 防御成本高昂：若要限制权限，通常需配置复杂的 Docker 容器或虚拟机，增加了本地开发的资源消耗和维护难度。
  • 缺乏实时反馈：当违规操作发生时，系统仅静默失败或直接崩溃，开发者难以定位是 AI 行为异常还是环境配置错误。

使用 sandbox-runtime 后

  • 最小权限原则：通过配置文件明确只允许 AI 读写当前项目目录，尝试访问 ~/sensitive-folder 时直接报错“操作不被允许”。
  • 精准文件隔离：利用操作系统原生原语（如 macOS 的 sandbox-exec），从内核层阻断对 SSH 密钥等特定文件的读取请求。
  • 网络白名单机制：默认禁止所有网络连接，仅放行必要的官方 API 域名，彻底切断数据外泄通道。
  • 轻量无感集成：无需启动沉重的容器，只需在 MCP 配置中将命令包裹在 srt 内，即可实现秒级沙箱化。
  • 违规透明监控：当 AI 试图越界时，系统会实时拦截并返回清晰的错误日志，帮助开发者快速修正提示词或策略。

sandbox-runtime 通过操作系统级的轻量隔离，让本地 AI 代理在享受文件操作便利的同时，默认拥有“防弹”般的安全边界。

运行环境要求

操作系统
  • Linux
  • macOS
GPU

未说明

内存

未说明

依赖
notes该工具是一个基于 Node.js 的沙箱运行时，无需容器即可在操作系统级别限制进程的文件系统和网络访问。Linux 端依赖 bubblewrap 进行隔离，macOS 端使用原生的 sandbox-exec (Seatbelt profiles)。网络过滤通过代理服务器（HTTP/SOCKS5）实现。默认配置下网络访问被完全禁止，需显式配置允许的域名；写操作默认禁止，需显式允许路径。
python未说明
bubblewrap (Linux)
sandbox-exec (macOS 原生)
Node.js/npm
sandbox-runtime hero image

快速开始

Anthropic 沙箱运行时 (srt)

一种轻量级的沙箱工具，可在操作系统级别对任意进程强制实施文件系统和网络限制，而无需使用容器。

srt 使用原生操作系统沙箱原语（macOS 上的 sandbox-exec，Linux 上的 bubblewrap）以及基于代理的网络过滤。它可以用于沙箱化智能体、本地 MCP 服务器、bash 命令和任意进程的行为。

测试版研究预览

沙箱运行时是为 Claude Code 开发的研究预览版本，旨在实现更安全的 AI 智能体。我们将其作为早期开源预览版本提供，以帮助更广泛的生态系统构建更加安全的智能体系统。由于这仍处于早期研究阶段，API 和配置格式可能会发生变化。我们欢迎反馈和贡献，以使 AI 智能体在默认情况下更加安全！

安装

npm install -g @anthropic-ai/sandbox-runtime

基本用法

# 网络限制
$ srt "curl anthropic.com"
正在运行: curl anthropic.com
<html>...</html>  # 请求成功

$ srt "curl example.com"
正在运行: curl example.com
连接被网络白名单阻止  # 请求被拦截

# 文件系统限制
$ srt "cat README.md"
正在运行: cat README.md
# Anthropic Sandb...  # 当前目录访问被允许

$ srt "cat ~/.ssh/id_rsa"
正在运行: cat ~/.ssh/id_rsa
cat: /Users/ollie/.ssh/id_rsa: 操作未被授权  # 特定文件被拦截

概述

该软件包提供了一个独立的沙箱实现，既可用作命令行工具，也可作为库使用。它采用“默认安全”的设计理念，专为常见的开发者用例而设计：进程启动时仅具有最小权限，您只需显式地打开所需的访问通道。

关键功能：

  • 网络限制：控制可通过 HTTP/HTTPS 及其他协议访问的主机/域名
  • 文件系统限制：控制可读/写的文件/目录
  • Unix 套接字限制：控制对本地 IPC 套接字的访问
  • 违规监控：在 macOS 上，可接入系统的沙箱违规日志存储，以获取实时警报

示例用例：MCP 服务器的沙箱化

一个关键用例是将模型上下文协议 (MCP) 服务器进行沙箱化，以限制其能力。例如，要对文件系统 MCP 服务器进行沙箱化：

未沙箱化（.mcp.json）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

已沙箱化（.mcp.json）：

{
  "mcpServers": {
    "filesystem": {
      "command": "srt",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

然后在 ~/.srt-settings.json 中配置限制：

{
  "filesystem": {
    "denyRead": [],
    "allowWrite": ["."],
    "denyWrite": ["~/sensitive-folder"]
  },
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  }
}

现在 MCP 服务器将被阻止写入被拒绝的路径：

> 向 ~/sensitive-folder 写入文件
✗ 错误：EPERM：操作未被授权，无法打开 '/Users/ollie/sensitive-folder/test.txt'

工作原理

该沙箱使用操作系统级别的原语来强制实施适用于整个进程树的限制：

0d1c612947c798aef48e6ab4beb7e8544da9d41a-4096x2305

双重隔离模型

有效的沙箱化需要同时实现文件系统和网络隔离。如果没有文件隔离，被攻陷的进程可能会窃取 SSH 密钥或其他敏感文件。如果没有网络隔离，进程可能会逃出沙箱并获得不受限制的网络访问权限。

文件系统隔离 强制实施读写限制：

  • 读取（先禁止再允许模式）：默认情况下，所有位置都允许读取。您可以先禁止某些大范围区域（如 /Users），然后再重新允许其中的特定路径（如 .）。allowRead 的优先级高于 denyRead——与写入相反，后者中 denyWrite 的优先级高于 allowWrite。
  • 写入（仅允许模式）：默认情况下，所有位置均禁止写入。您必须显式地允许某些路径（如 . 或 /tmp）。如果允许列表为空，则表示无写入权限。

网络隔离（仅允许模式）：默认情况下，所有网络访问都被禁止。您必须显式地允许特定域名。如果 allowedDomains 列表为空，则表示无网络访问权限。网络流量会通过主机上运行的代理服务器路由：

  • Linux：请求通过文件系统经由 Unix 域套接字路由。被沙箱化的进程的网络命名空间会被完全移除，因此所有网络流量都必须经过主机上运行的代理（这些代理监听绑定到沙箱内的 Unix 套接字）。

  • macOS：Seatbelt 配置文件仅允许与特定的本地回环端口通信。代理监听该端口，从而为所有网络访问创建一个受控通道。

无论是 HTTP/HTTPS（通过 HTTP 代理）还是其他 TCP 流量（通过 SOCKS5 代理），都会由这些代理中介，以强制执行您的域名白名单和黑名单。

有关 Claude Code 中沙箱化的更多信息，请参阅：

架构

src/
├── index.ts                  # 库导出
├── cli.ts                    # CLI 入口点（srt 命令）
├── utils/                    # 共享工具
│   ├── debug.ts             # 调试日志记录
│   ├── settings.ts          # 设置读取器（权限 + 沙箱配置）
│   ├── platform.ts          # 平台检测
│   └── exec.ts              # 命令执行工具
└── sandbox/                  # 沙箱实现
    ├── sandbox-manager.ts    # 主沙箱管理器
    ├── sandbox-schemas.ts    # Zod 模式验证
    ├── sandbox-violation-store.ts # 违规跟踪
    ├── sandbox-utils.ts      # 共享沙箱工具
    ├── http-proxy.ts         # 用于网络过滤的 HTTP/HTTPS 代理
    ├── socks-proxy.ts        # 用于网络过滤的 SOCKS5 代理
    ├── linux-sandbox-utils.ts # Linux bubblewrap 沙箱实现
    └── macos-sandbox-utils.ts # macOS sandbox-exec 沙箱实现

使用方法

作为命令行工具

srt 命令（Anthropic 沙箱运行时）会将任何命令包裹在安全边界内：

# 在沙箱中运行命令
srt echo "hello world"

# 带调试日志
srt --debug curl https://example.com

# 指定自定义设置文件
srt --settings /path/to/srt-settings.json npm install

作为库使用

import {
  SandboxManager,
  type SandboxRuntimeConfig,
} from '@anthropic-ai/sandbox-runtime'
import { spawn } from 'child_process'

// 定义你的沙盒配置
const config: SandboxRuntimeConfig = {
  network: {
    allowedDomains: ['example.com', 'api.github.com'],
    deniedDomains: [],
  },
  filesystem: {
    denyRead: ['~/.ssh'],
    allowWrite: ['.', '/tmp'],
    denyWrite: ['.env'],
  },
}

// 初始化沙盒（启动代理服务器等）
await SandboxManager.initialize(config)

// 将命令包裹在沙盒限制中
const sandboxedCommand = await SandboxManager.wrapWithSandbox(
  'curl https://example.com',
)

// 执行沙盒化的命令
const child = spawn(sandboxedCommand, { shell: true, stdio: 'inherit' })

// 处理子进程退出并进行清理
child.on('exit', async code => {
  console.log(`命令退出，退出码为 ${code}`)
  // 完成后清理（可选，进程退出时会自动清理）
  await SandboxManager.reset()
})

可用的导出内容

// 主沙盒管理器
export { SandboxManager } from '@anthropic-ai/sandbox-runtime'

// 违规跟踪
export { SandboxViolationStore } from '@anthropic-ai/sandbox-runtime'

// TypeScript 类型
export type {
  SandboxRuntimeConfig,
  NetworkConfig,
  FilesystemConfig,
  IgnoreViolationsConfig,
  SandboxAskCallback,
  FsReadRestrictionConfig,
  FsWriteRestrictionConfig,
  NetworkRestrictionConfig,
} from '@anthropic-ai/sandbox-runtime'

配置

设置文件位置

默认情况下，沙盒运行时会在 ~/.srt-settings.json 中查找配置。你可以使用 --settings 标志指定自定义路径：

srt --settings /path/to/srt-settings.json <command>

完整配置示例

{
  "network": {
    "allowedDomains": [
      "github.com",
      "*.github.com",
      "lfs.github.com",
      "api.github.com",
      "npmjs.org",
      "*.npmjs.org"
    ],
    "deniedDomains": ["malicious.com"],
    "allowUnixSockets": ["/var/run/docker.sock"],
    "allowLocalBinding": false
  },
  "filesystem": {
    "denyRead": ["~/.ssh"],
    "allowRead": [],
    "allowWrite": [".", "src/", "test/", "/tmp"],
    "denyWrite": [".env", "config/production.json"]
  },
  "ignoreViolations": {
    "*": ["/usr/bin", "/System"],
    "git push": ["/usr/bin/nc"],
    "npm": ["/private/tmp"]
  },
  "enableWeakerNestedSandbox": false,
  "enableWeakerNetworkIsolation": false
}

配置选项

网络配置

采用“仅允许模式”——默认情况下所有网络访问均被禁止。

  • network.allowedDomains：允许访问的域名数组（支持通配符，如 *.example.com）。空数组表示无网络访问。
  • network.deniedDomains：禁止访问的域名数组（优先级高于 allowedDomains）。
  • network.allowLocalBinding：是否允许绑定到本地端口（布尔值，默认为 false）。

Unix 套接字设置（平台相关行为）：

设置 macOS Linux
allowUnixSockets: string[] 允许列表中的套接字路径 忽略（seccomp 无法按路径过滤）
allowAllUnixSockets: boolean 允许所有套接字 禁用 seccomp 阻止

Unix 套接字在两个平台上都默认被阻止。

  • macOS：使用 allowUnixSockets 允许特定路径（如 ["/var/run/docker.sock"]），或设置 allowAllUnixSockets: true 来允许所有。
  • Linux：阻塞通过 seccomp 过滤器实现（仅适用于 x64 和 arm64 架构）。如果 seccomp 不可用，套接字将不受限制，并显示警告。使用 allowAllUnixSockets: true 明确禁用阻塞。

文件系统配置

采用两种不同的模式：

读取限制（先拒绝再允许模式）——默认允许所有读取：

  • filesystem.denyRead：拒绝读取访问的路径数组。空数组表示完全允许读取。
  • filesystem.allowRead：在被拒绝区域中重新允许读取的路径数组（优先于 denyRead）。注意：这与写入限制相反，后者是“先允许再拒绝”的模式。

写入限制（仅允许模式）——默认禁止所有写入：

  • filesystem.allowWrite：允许写入访问的路径数组。空数组表示无写入权限。
  • filesystem.denyWrite：在允许写入的路径内进一步拒绝写入的路径数组（优先于 allowWrite）。

路径语法（macOS）：

在 macOS 上，路径支持类似于 .gitignore 的 Git 风格通配符模式：

  • *：匹配除 / 以外的任意字符（如 *.ts 匹配 foo.ts，但不匹配 foo/bar.ts）。
  • **：匹配包括 / 在内的任意字符（如 src/**/*.ts 匹配 src/ 目录及其子目录中的所有 .ts 文件）。
  • ?：匹配除 / 以外的单个字符（如 file?.txt 匹配 file1.txt）。
  • [abc]：匹配集合中的任意字符（如 file[0-9].txt 匹配 file3.txt）。

示例：

  • "allowWrite": ["src/"]：允许对整个 src/ 目录进行写入。
  • "allowWrite": ["src/**/*.ts"]：允许对 src/ 及其子目录中的所有 .ts 文件进行写入。
  • "denyRead": ["~/.ssh"]：拒绝访问 SSH 目录。
  • "denyRead": ["/Users"], "allowRead": ["."]：拒绝访问 /Users 下的所有目录，但重新允许当前目录。
  • "denyWrite": [".env"]：即使当前目录被允许写入，也禁止对 .env 文件进行写入。

路径语法（Linux）：

Linux 目前不支持通配符匹配。 只能使用精确路径：

  • "allowWrite": ["src/"]：允许对 src/ 目录进行写入。
  • "denyRead": ["/home/user/.ssh"]：拒绝访问 SSH 目录。
  • "denyRead": ["/home"], "allowRead": ["."]：拒绝访问 /home 下的所有目录，但重新允许当前目录。

所有平台：

  • 路径可以是绝对路径（如 /home/user/.ssh）或相对于当前工作目录的路径（如 ./src）。
  • ~ 展开为用户的主目录。

其他配置

  • ignoreViolations：一个对象，将命令模式映射到应忽略违规的路径数组。
  • enableWeakerNestedSandbox：为 Docker 环境启用较弱的沙盒模式（布尔值，默认为 false）。
  • enableWeakerNetworkIsolation：在 macOS 沙盒中允许访问 com.apple.trustd.agent（布尔值，默认为 false）。这对于 Go 程序（如 gh、gcloud、terraform、kubectl 等）在使用 httpProxyPort 并配合 MITM 代理和自定义 CA 时验证 TLS 证书是必要的。安全警告： 启用此选项可能会通过 trustd 服务导致数据泄露。

常见配置示例

允许访问 GitHub（所有必要端点）：

{
  "network": {
    "allowedDomains": [
      "github.com",
      "*.github.com",
      "lfs.github.com",
      "api.github.com"
    ],
    "deniedDomains": []
  },
  "filesystem": {
    "denyRead": [],
    "allowWrite": ["."],
    "denyWrite": []
  }
}

限制为特定目录：

{
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  },
  "filesystem": {
    "denyRead": ["~/.ssh"],
    "allowWrite": [".", "src/", "test/"],
    "denyWrite": [".env", "secrets/"]
  }
}

仅限工作区的文件系统访问（拒绝读取工作区外的内容）：

{
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  },
  "filesystem": {
    "denyRead": ["/Users"],
    "allowRead": ["."],
    "allowWrite": ["."],
    "denyWrite": []
  }
}

此配置会拒绝读取 /Users 目录下的任何内容（在 Linux 上则是 /home），然后重新允许当前工作目录的读取权限。系统路径（如 /usr、/lib 等）仍然可以被读取。

常见问题与提示

运行 Jest： 使用 --no-watchman 标志以避免沙箱违规：

srt "jest --no-watchman"

Watchman 会访问沙箱边界之外的文件，从而触发权限错误。禁用 Watchman 后，Jest 将使用内置的文件监视器来运行。

平台支持

  • macOS：使用 sandbox-exec 结合自定义配置文件（无需额外依赖）
  • Linux：使用 bubblewrap（bwrap）进行容器化
  • Windows：暂不支持

平台特定依赖项

Linux 需要：

  • bubblewrap - 容器运行时
    • Ubuntu/Debian：apt-get install bubblewrap
    • Fedora：dnf install bubblewrap
    • Arch：pacman -S bubblewrap
  • socat - 用于代理桥接的套接字中继工具
    • Ubuntu/Debian：apt-get install socat
    • Fedora：dnf install socat
    • Arch：pacman -S socat
  • ripgrep - 用于检测禁止路径的快速搜索工具
    • Ubuntu/Debian：apt-get install ripgrep
    • Fedora：dnf install ripgrep
    • Arch：pacman -S ripgrep

Ubuntu 24.04+ 注意事项： 这些发行版默认启用了 kernel.apparmor_restrict_unprivileged_userns，该设置允许使用 unshare(CLONE_NEWUSER)，但会移除新用户命名空间中的能力。而 bubblewrap 和 seccomp 隔离层都需要具备能力的用户命名空间。可通过以下命令禁用该限制：

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

或者为相关二进制文件添加一个授予 userns 能力的 AppArmor 配置文件。

可选的 Linux 依赖项（用于 seccomp 备用方案）：

该软件包包含针对 x86-64 和 arm 架构预生成的 seccomp BPF 过滤器。这些依赖项仅在您使用的架构没有预生成过滤器时才需要：

  • gcc 或 clang - C 编译器
  • libseccomp-dev - Seccomp 库开发文件
    • Ubuntu/Debian：apt-get install gcc libseccomp-dev
    • Fedora：dnf install gcc libseccomp-devel
    • Arch：pacman -S gcc libseccomp

macOS 需要：

开发

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 类型检查
npm run typecheck

# 代码格式化
npm run lint

# 代码格式化
npm run format

构建 Seccomp 二进制文件

BPF 过滤器和 apply-seccomp 加载程序是从 vendor/seccomp-src/ 中的 C 源代码编译而来，通过 npm run build:seccomp 命令完成（仅限 Linux；需要 gcc 和 libseccomp-dev）。CI 会在每次 Linux 架构的测试前运行此命令，发布流程则会构建两种架构的版本，并将其打包到发布的软件包中。

实现细节

网络隔离架构

沙箱在宿主机上运行 HTTP 和 SOCKS5 代理服务器，根据权限规则过滤所有网络请求：

  1. HTTP/HTTPS 流量：HTTP 代理服务器拦截请求，并根据允许/禁止的域名对其进行验证。
  2. 其他网络流量：SOCKS5 代理处理所有其他 TCP 连接（SSH、数据库连接等）。
  3. 权限执行：代理会强制执行您配置中的 permissions 规则。

平台特定的代理通信方式：

  • Linux：请求通过文件系统经由 Unix 域套接字路由（使用 socat 进行桥接）。bubblewrap 容器中会移除网络命名空间，确保所有网络流量必须经过代理。
  • macOS：Seatbelt 配置文件仅允许与代理监听的特定本地回环端口通信。其他所有网络访问均被阻止。

文件系统隔离

文件系统限制在操作系统级别强制执行：

  • macOS：使用 sandbox-exec 结合动态生成的 Seatbelt 配置文件，指定允许的读写路径。
  • Linux：使用 bubblewrap 结合绑定挂载，根据配置将目录标记为只读或读写。

默认文件系统权限：

  • 读取（先禁止再允许）：默认情况下处处允许。您可以先禁止大范围区域，然后再重新允许其中的特定路径。allowRead 的优先级高于 denyRead。

    • 示例：denyRead: ["~/.ssh"] 以阻止访问 SSH 密钥。
    • 示例：denyRead: ["/Users"], allowRead: ["."] 以阻止访问整个 /Users 目录，仅保留工作区的访问权限。
    • 如果 denyRead: []，则表示完全开放读取权限（无任何禁止）。

  • 写入（仅允许）：默认情况下处处禁止。您必须显式地允许某些路径。

    • 示例：allowWrite: [".", "/tmp"] 允许向当前目录和 /tmp 写入。
    • 如果 allowWrite: []，则表示完全禁止写入（无任何允许）。
    • denyWrite 则是在允许的路径内创建例外情况（禁止优先于允许）。

读取与写入的优先级恰好相反： allowRead 会覆盖 denyRead，而 denyWrite 则会覆盖 allowWrite。这样您就可以在被禁止的区域内划出可读取的区域，同时在可写入的区域内划定受保护的区域。

强制拒绝路径（自动保护的文件）

某些敏感文件和目录始终禁止写入，即使它们位于允许写入的路径范围内。这为防范沙箱逃逸和配置篡改提供了纵深防御。

始终阻止的文件：

  • Shell 配置文件：.bashrc、.bash_profile、.zshrc、.zprofile、.profile
  • Git 配置文件：.gitconfig、.gitmodules
  • 其他敏感文件：.ripgreprc、.mcp.json

始终阻止的目录：

  • IDE 目录：.vscode/、.idea/
  • Claude 配置目录：.claude/commands/、.claude/agents/
  • Git 钩子与配置：.git/hooks/、.git/config

这些路径会自动被阻止——您无需将其添加到 denyWrite 中。例如，即使设置了 allowWrite: ["."]，尝试写入 .bashrc 或 .git/hooks/pre-commit 仍会失败：

$ srt 'echo "malicious" >> .bashrc'
/bin/bash: .bashrc: 操作不允许

$ srt 'echo "bad" > .git/hooks/pre-commit'
/bin/bash: .git/hooks/pre-commit: 操作不允许

注意（Linux）： 在 Linux 上，强制拒绝路径仅会阻止已存在的文件。对于这些模式下的不存在文件，bubblewrap 的绑定挂载方式无法进行拦截。而 macOS 使用 glob 模式匹配，能够同时阻止现有文件和新创建的文件。

Linux 搜索深度： 在 Linux 上，沙箱会使用 ripgrep 扫描允许写入路径中的子目录，查找危险文件。默认情况下，为了性能考虑，它最多搜索 3 层深度。您可以通过设置 mandatoryDenySearchDepth 来调整此值：

{
  "mandatoryDenySearchDepth": 5,
  "filesystem": {
    "allowWrite": ["."]
  }
}
  • 默认值：3（搜索最多 3 层）
  • 范围：1 至 10
  • 值越高，防护越全面，但性能会有所下降
  • 当前工作目录（深度 0）中的文件无论此设置如何都会受到保护。

Unix 套接字限制（Linux）

在 Linux 上，沙箱利用 seccomp BPF（伯克利数据包过滤器） 在系统调用层面阻止 Unix 域套接字的创建。这一机制提供了一层额外的安全保障，防止进程通过本地 IPC 创建新的 Unix 域套接字（除非明确允许）。

工作原理：

  1. 内置 BPF 过滤器：该软件包为 x64 和 arm64 架构分别提供了静态编译的 apply-seccomp 二进制文件，其中已嵌入 seccomp BPF 过滤器。该过滤器针对特定架构设计，但独立于 libc，因此无论使用 glibc 还是 musl，该二进制文件均可正常运行。

  2. 运行时检测：沙箱会自动检测您的系统架构，并选择对应的 apply-seccomp 二进制文件。

  3. 系统调用过滤：BPF 过滤器会拦截 socket() 系统调用，通过返回 EPERM 错误来阻止 AF_UNIX 套接字的创建。这样可以防止沙箱内的代码创建新的 Unix 域套接字。

  4. 使用 apply-seccomp 二进制文件的两阶段应用：

    • 外层 bwrap 创建包含文件系统、网络和 PID 命名空间限制的沙箱。
    • 网络桥接进程（socat）会在沙箱内部启动（需要 Unix 域套接字）。
    • apply-seccomp 会创建一个嵌套的 user+PID+mount 命名空间，并重新挂载 /proc。
    • 在嵌套命名空间内，apply-seccomp 作为 PID 1（不可转储的 init/reaper）运行。
    • apply-seccomp 会 fork 子进程，通过 prctl() 应用 seccomp 过滤器，然后 exec 用户命令。
    • 用户命令将在所有沙箱限制的基础上，额外受到 Unix 域套接字创建的阻断。

PID 命名空间隔离： 嵌套的 PID 命名空间确保用户命令无法看到或访问任何未应用 seccomp 过滤器的进程（bwrap 的 init、shell 包装器或 socat 辅助进程）。这样一来，无论 kernel.yama.ptrace_scope 设置为何，seccomp 边界都能保持完整，因为未经过滤的辅助进程无法通过 ptrace 或 /proc/N/mem 访问。内部的 PID 1 会将 PR_SET_DUMPABLE=0，使其同样无法被 ptrace。如果嵌套命名空间创建失败，apply-seccomp 将直接终止，而不是在缺乏隔离的情况下继续运行。

安全限制： 该过滤器会阻止 socket(AF_UNIX, ...) 以及 io_uring_setup、io_uring_enter 和 io_uring_register 系统调用（后三者是因为在 Linux 5.19 及以上版本中，IORING_OP_SOCKET 会绕过 socket() 规则）。但它无法阻止对从父进程继承或通过 SCM_RIGHTS 传递的 Unix 域套接字文件描述符的操作。对于大多数沙箱场景而言，阻止套接字创建足以防止未经授权的 IPC。

零运行时依赖： 预编译的静态 apply-seccomp 二进制文件及预生成的 BPF 过滤器已分别针对 x64 和 arm64 架构打包提供，运行时无需任何编译工具或外部依赖。

架构支持： 目前完全支持 x64 和 arm64 架构，其他架构暂不支持。若要在不支持的架构上使用沙箱功能但不禁用 Unix 域套接字，请在配置中设置 allowAllUnixSockets: true。

违规检测与监控

当沙箱进程尝试访问受限制的资源时：

  1. 在操作系统层面阻止该操作（返回 EPERM 错误）
  2. 记录违规日志（平台特定机制）
  3. 通知用户（在 Claude Code 中，这会触发权限提示）。

macOS： 沙箱运行时会接入 macOS 的系统沙箱违规日志存储。这可提供实时通知，详细说明尝试了什么操作以及为何被阻止。这也是 Claude Code 用于违规检测的相同机制。

# 实时查看沙箱违规
log stream --predicate 'process == "sandbox-exec"' --style syslog

Linux： Bubblewrap 并不提供内置的违规报告功能。您可以使用 strace 来跟踪系统调用并识别被阻止的操作：

# 跟踪所有被拒绝的操作
strace -f srt <your-command> 2>&1 | grep EPERM

# 跟踪特定文件操作
strace -f -e trace=open,openat,stat,access srt <your-command> 2>&1 | grep EPERM

# 跟踪网络操作
strace -f -e trace=network srt <your-command> 2>&1 | grep EPERM

高级：自定义代理

对于更复杂的网络过滤需求，您可以配置沙箱使用自己的代理服务器，而非内置代理。这样可以实现：

  • 流量检查：使用如 mitmproxy 等工具检查和修改流量。
  • 自定义过滤逻辑：实施超越简单域名白名单的复杂规则。
  • 审计日志记录：记录所有网络请求以满足合规性或调试需求。

使用 mitmproxy 的示例：

# 启动带有自定义过滤脚本的 mitmproxy
mitmproxy -s custom_filter.py --listen-port 8888

注意：自定义代理配置尚未在新配置格式中支持。此功能将在未来的版本中加入。

重要的安全考量： 即使启用了域名白名单，仍可能存在信息泄露途径。例如，允许访问 github.com 就会让进程向任意仓库推送内容。通过自定义 MITM 代理并正确配置证书，您可以检查和过滤特定的 API 调用，从而避免此类风险。

安全限制

  • 网络沙箱限制：网络过滤系统通过限制进程允许连接的域名来工作。它不会对通过代理传输的流量进行其他检查，因此用户有责任确保其策略中仅允许受信任的域名。

<警告> 用户应注意，允许诸如 github.com 等广泛域名可能带来的风险，因为这可能导致数据外泄。此外，在某些情况下，攻击者可能通过 域名伪装 来绕过网络过滤。 </警告>

  • 通过 Unix 套接字提升权限：allowUnixSockets 配置可能会无意中授予对强大系统服务的访问权限，从而导致沙箱被绕过。例如，如果该配置用于允许访问 /var/run/docker.sock，则可通过利用 Docker 套接字有效地获得对宿主机系统的访问权限。建议用户谨慎考虑允许通过沙箱访问的任何 Unix 套接字。
  • 文件系统权限提升：过于宽泛的文件系统写入权限可能引发权限提升攻击。允许向 $PATH 中包含可执行文件的目录、系统配置目录或用户 shell 配置文件（如 .bashrc、.zshrc）写入内容，当其他用户或系统进程访问这些文件时，可能导致在不同安全上下文中执行代码。
  • Linux 沙箱强度：Linux 实现提供了强大的文件系统和网络隔离，但包含一个 enableWeakerNestedSandbox 模式，使其能够在不使用特权命名空间的 Docker 环境中运行。此选项会显著削弱安全性，应仅在已通过其他方式强制实施额外隔离的情况下使用。
  • 较弱的网络隔离（macOS）：enableWeakerNetworkIsolation 选项会重新启用对 com.apple.trustd.agent 的访问权限，而该服务是 Go 程序通过 macOS 安全框架验证 TLS 证书所必需的。这将打开一条通过 trustd 服务进行数据外泄的潜在途径，因此仅应在需要 Go TLS 验证时才启用此选项（例如，使用 httpProxyPort 并配合 MITM 代理及自定义 CA 时）。

已知限制与未来工作

Linux 代理绕过：目前使用环境变量（HTTP_PROXY、HTTPS_PROXY、ALL_PROXY）将流量导向代理。这对大多数应用程序有效，但某些不尊重这些环境变量的程序可能会忽略它们，从而无法连接到互联网。

未来改进方向：

  • Proxychains 支持：在 Linux 上添加对 proxychains 和 LD_PRELOAD 的支持，以便在更低级别拦截网络调用，从而增加绕过难度。
  • Linux 违规监控：为 Linux 实现基于 strace 的自动违规检测功能，并将其与违规存储集成。目前，Linux 用户必须手动运行 strace 才能查看违规情况，而 macOS 则可通过系统日志存储实现自动违规监控。

版本历史

v0.0.492026/04/03
v0.0.482026/04/03
v0.0.472026/04/02
v0.0.462026/03/31
v0.0.452026/03/31
v0.0.442026/03/30
v0.0.432026/03/28
v0.0.422026/03/12
v0.0.412026/03/12
v0.0.402026/03/09
v0.0.392026/02/26
v0.0.382026/02/19

相似工具推荐

openclaw

OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。 这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。 OpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你

★ 349.3k|★★★☆☆|1周前
Agent开发框架图像

stable-diffusion-webui

stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。 无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。

★ 162.1k|★★★☆☆|1周前
开发框架图像Agent

everything-claude-code

everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。 通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。 这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上

★ 159.6k|★★☆☆☆|今天
开发框架Agent语言模型

opencode

OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。 这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。 在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信

★ 144.3k|★☆☆☆☆|昨天
Agent插件

ComfyUI

ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。 这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。 无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。

★ 108.3k|★★☆☆☆|1周前
开发框架图像Agent

gemini-cli

gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。 这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。 它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。

★ 100.8k|★★☆☆☆|1周前
插件Agent图像