沙箱与安全

原则上，Claude 运行的每个 Bash 命令都可以读取您的 SSH 密钥、窃取文件或写入您的设置。 沙箱系统在操作系统级别阻止这种情况发生——在任何进程可以打开文件或进行网络调用之前。 本课涵盖：

Claude Code 本身不实现沙箱原语。 它包裹着 @anthropic-ai/sandbox-runtime - 这 BaseSandboxManager - 通过一个瘦适配器，添加设置集成、工作树感知和 Claude 特定的安全规则。 公共表面是一个单一的 SandboxManager object.

平台后端

沙箱后端在运行时自动选择：

// sandbox-adapter.ts — memoized dependency check
const checkDependencies = memoize((): SandboxDependencyCheck => {
  const { rgPath, rgArgs } = ripgrepCommand()
  return BaseSandboxManager.checkDependencies({
    command: rgPath,
    args: rgArgs,
  })
})

// memoized platform check
const isSupportedPlatform = memoize((): boolean => {
  return BaseSandboxManager.isSupportedPlatform()
})

// SandboxDependenciesTab.tsx — Linux dep check display
// bwrap: bubblewrap (required)
// socat: network proxy (required)
// seccomp filter: optional — blocks unix domain sockets
bwrapMissing   && "apt install bubblewrap"
socatMissing   && "apt install socat"
seccompMissing && "npm install -g @anthropic-ai/sandbox-runtime"

用户通过选择沙箱行为 /sandbox，这呈现 SandboxSettings 有三个选择：

模式源自两个布尔设置： sandbox.enabled and sandbox.autoAllowBashIfSandboxed。 还有一个 sandbox.allowUnsandboxedCommands 控制命令是否明确从沙箱中排除的标志（sandbox.excludedCommands）仍然允许在沙箱外运行。

// SandboxSettings.tsx
type SandboxMode = 'auto-allow' | 'regular' | 'disabled'

const getCurrentMode = (): SandboxMode => {
  if (!currentEnabled) return "disabled"
  if (currentAutoAllow) return "auto-allow"
  return "regular"
}

// sandbox-adapter.ts — mapping mode → settings
// auto-allow:  { enabled: true,  autoAllowBashIfSandboxed: true  }
// regular:     { enabled: true,  autoAllowBashIfSandboxed: false }
// disabled:    { enabled: false }
async function setSandboxSettings(options: {
  enabled?: boolean
  autoAllowBashIfSandboxed?: boolean
  allowUnsandboxedCommands?: boolean
}): Promise<void> {
  updateSettingsForSource('localSettings', {
    sandbox: {
      ...existingSettings?.sandbox,
      ...options,
    },
  })
}

排除特定命令

某些工具（例如 Docker 守护进程管理或硬件接触命令）无法在沙箱内运行。 这 /sandbox exclude "pattern" 命令将模式附加到 sandbox.excludedCommands 在本地设置中。 适配器还暴露了 addToExcludedCommands() 用于沙箱违规事件后的程序排除。

// commands/sandbox-toggle/sandbox-toggle.tsx — /sandbox exclude subcommand
if (subcommand === 'exclude') {
  const cleanPattern = commandPattern.replace(/^["']|["']$/g, '')
  addToExcludedCommands(cleanPattern)
  // writes to localSettings: sandbox.excludedCommands
}

// sandbox-adapter.ts — policy lock detection
function areSandboxSettingsLockedByPolicy(): boolean {
  const overridingSources = ['flagSettings', 'policySettings'] as const
  for (const source of overridingSources) {
    const settings = getSettingsForSource(source)
    if (
      settings?.sandbox?.enabled !== undefined ||
      settings?.sandbox?.autoAllowBashIfSandboxed !== undefined ||
      settings?.sandbox?.allowUnsandboxedCommands !== undefined
    ) return true
  }
  return false
}

沙箱在操作系统级别强制执行网络访问。 Claude Code 将其权限规则和设置转换为 NetworkRestrictionConfig that BaseSandboxManager 通过平台后端强制执行。

域允许/拒绝列表

允许的域来自合并在一起的两个来源：

1. sandbox.network.allowedDomains — 设置 JSON 中的显式列表
2. permissions.allow 形式规则 WebFetch(domain:example.com)

被拒绝的域名来自 permissions.deny 遵循相同的规则 WebFetch(domain:...) pattern.

// sandbox-adapter.ts — convertToSandboxRuntimeConfig()
for (const ruleString of permissions.allow || []) {
  const rule = permissionRuleValueFromString(ruleString)
  if (rule.toolName === WEB_FETCH_TOOL_NAME &&
      rule.ruleContent?.startsWith('domain:')) {
    allowedDomains.push(rule.ruleContent.substring('domain:'.length))
  }
}
// Same pattern for deniedDomains using permissions.deny

// sandbox-adapter.ts — initialize()
const wrappedCallback: SandboxAskCallback = async (hostPattern) => {
  if (shouldAllowManagedSandboxDomainsOnly()) {
    logForDebugging(
      `[sandbox] Blocked network request to ${hostPattern.host} (allowManagedDomainsOnly)`
    )
    return false  // silently deny
  }
  return sandboxAskCallback(hostPattern)
}

附加网络设置

文件系统配置由四个列表构建 - allowWrite, denyWrite, allowRead, denyRead - 从多个来源组装并传递给 BaseSandboxManager.

始终允许的写入路径

无论用户设置如何，两个路径都是无条件可写的：当前工作目录（'.') 和 Claude 临时目录。 这是任何有用工作所需的最低限度。

// sandbox-adapter.ts — baseline writable paths
const allowWrite: string[] = ['.', getClaudeTempDir()]

始终拒绝写入路径（安全硬编码）

无条件拒绝多个路径，以防止通过设置操作进行沙箱逃逸：

• All settings.json and settings.local.json 每个设置源的文件
• 托管设置放置目录
• .claude/skills 在原始的 Cwd 和当前的 Cwd 中 - 技能在沙盒中运行并且具有完整的 Claude 功能
• 裸 git repo 哨兵文件 (HEAD, objects, refs, hooks, config) — 阻止 git core.fsmonitor 逃逸向量（CVE 模式，作为问题 #29316 进行跟踪）

// sandbox-adapter.ts — settings escape prevention
const settingsPaths = SETTING_SOURCES.map(source =>
  getSettingsFilePathForSource(source)
).filter((p): p is string => p !== undefined)
denyWrite.push(...settingsPaths)

// skills escape prevention
denyWrite.push(resolve(originalCwd, '.claude', 'skills'))

// sandbox-adapter.ts — post-command scrub
function scrubBareGitRepoFiles(): void {
  for (const p of bareGitRepoScrubPaths) {
    try {
      rmSync(p, { recursive: true })
    } catch {
      // ENOENT is the expected case — nothing was planted
    }
  }
}

路径解析：权限规则与 sandbox.filesystem

两种不同的路径解析约定并存，并且将它们混合在一起是一个有记录的脚枪（问题＃30067）：

// resolvePathPatternForSandbox — permission-rule convention
// "/foo/**" → "${settingsRootDir}/foo/**"
if (pattern.startsWith('/') && !pattern.startsWith('//')) {
  const root = getSettingsRootPathForSource(source)
  return resolve(root, pattern.slice(1))
}

// resolveSandboxFilesystemPath — sandbox.filesystem convention
// "/Users/foo/.cargo" → "/Users/foo/.cargo" (absolute, as written)
return expandPath(pattern, getSettingsRootPathForSource(source))

// sandbox-adapter.ts
if (worktreeMainRepoPath && worktreeMainRepoPath !== cwd) {
  allowWrite.push(worktreeMainRepoPath)
}

实时配置刷新

沙箱配置不是静态的。 每次用户更新权限或设置文件时， settingsChangeDetector 订阅火爆 refreshConfig()，这称为 BaseSandboxManager.updateConfig(newConfig) 同步地。 这意味着授予新的文件编辑权限会立即生效 - 无需重新启动。

// sandbox-adapter.ts — live settings subscription
settingsSubscriptionCleanup = settingsChangeDetector.subscribe(() => {
  const settings = getSettings_DEPRECATED()
  const newConfig = convertToSandboxRuntimeConfig(settings)
  BaseSandboxManager.updateConfig(newConfig)
})

Claude Code 通过 OAuth 存储 OAuth 令牌（和旧版 API 密钥） SecureStorage 具有两个具体实现的接口：macOS 钥匙串和明文后备。 适配器在运行时选择正确的实现并将它们与 createFallbackStorage() combinator.

macOS 钥匙串存储

凭据使用 Apple 的通用密码项存储在 macOS 钥匙串中 security(1) 命令行工具。 服务名称源自配置目录路径的稳定哈希，因此多个 Claude 实例具有不同的 CLAUDE_CONFIG_DIR 值获取单独的钥匙串条目：

// macOsKeychainHelpers.ts — service name derivation
export function getMacOsKeychainStorageServiceName(
  serviceSuffix: string = '',
): string {
  const isDefaultDir = !process.env.CLAUDE_CONFIG_DIR
  const dirHash = isDefaultDir
    ? ''
    : `-${createHash('sha256').update(configDir).digest('hex').substring(0, 8)}`
  return `Claude Code${OAUTH_FILE_SUFFIX}${serviceSuffix}${dirHash}`
}

凭证 JSON 在写入之前会序列化为十六进制。 这避免了逃避问题 security(1)的参数解析器，并且还击败了企业端点安全工具（例如 CrowdStrike）中的朴素纯文本 grep 规则：

// macOsKeychainStorage.ts — write path
const hexValue = Buffer.from(jsonString, 'utf-8').toString('hex')

// Prefer stdin so process monitors see only "security -i", not the payload
const command =
  `add-generic-password -U -a "${username}" -s "${serviceName}" -X "${hexValue}"\n`

if (command.length <= SECURITY_STDIN_LINE_LIMIT) {
  result = execaSync('security', ['-i'], { input: command })
} else {
  // Payload too large for stdin buffer (4032B limit): fall back to argv
  result = execaSync('security', ['add-generic-password', '-U', ...])
}

// macOsKeychainHelpers.ts
export const KEYCHAIN_CACHE_TTL_MS = 30_000

export const keychainCacheState: {
  cache: { data: SecureStorageData | null; cachedAt: number }
  generation: number  // incremented on every invalidation
  readInFlight: Promise<SecureStorageData | null> | null
} = { cache: { data: null, cachedAt: 0 }, generation: 0, readInFlight: null }

启动预取

keychainPrefetch.ts 开火两 security 子进程在最顶层并行运行 main.tsx，在模块评估之前约 65ms。 当应用程序的异步初始化程序需要凭据时，结果已被缓存并且同步 security 完全避免了生成。

// keychainPrefetch.ts — parallel startup reads
export function startKeychainPrefetch(): void {
  if (process.platform !== 'darwin' || prefetchPromise || isBareMode()) return

  // Fire both subprocesses immediately — they run in parallel with
  // each other AND with main.tsx import evaluation (~65ms saved)
  const oauthSpawn  = spawnSecurity(getMacOsKeychainStorageServiceName(CREDENTIALS_SERVICE_SUFFIX))
  const legacySpawn = spawnSecurity(getMacOsKeychainStorageServiceName())

  prefetchPromise = Promise.all([oauthSpawn, legacySpawn]).then(([oauth, legacy]) => {
    if (!oauth.timedOut)  primeKeychainCacheFromPrefetch(oauth.stdout)
    if (!legacy.timedOut) legacyApiKeyPrefetch = { stdout: legacy.stdout }
  })
}

明文后备存储

在 Linux 上，或当 macOS 钥匙串不可用时（例如 SSH 会话），凭据将回退到 ~/.config/claude/.credentials.json 权限设置为 0o600。 每次写入时都会发出警告：

// plainTextStorage.ts — write path
writeFileSync_DEPRECATED(storagePath, jsonStringify(data), { encoding: 'utf8' })
chmodSync(storagePath, 0o600)  // owner-only read/write
return {
  success: true,
  warning: 'Warning: Storing credentials in plaintext.',
}

后备存储组合器

在macOS， createFallbackStorage(primary, secondary) 用精心排序的迁移逻辑包装这两种实现：

// fallbackStorage.ts — update() with migration
update(data: SecureStorageData) {
  const primaryDataBefore = primary.read()
  const result = primary.update(data)

  if (result.success) {
    // First-time migration to keychain: delete secondary (plaintext)
    // so the stale .credentials.json doesn't shadow the fresh keychain entry
    if (primaryDataBefore === null) secondary.delete()
    return result
  }

  // Keychain write failed — use plaintext fallback
  const fallbackResult = secondary.update(data)
  if (fallbackResult.success) {
    // Best-effort: remove stale keychain entry so it can't shadow
    // the fresh plaintext data (login loop fix, issue #30337)
    if (primaryDataBefore !== null) primary.delete()
    return { success: true, warning: fallbackResult.warning }
  }

  return { success: false }
}

当沙盒命令被阻止时，违规事件存储在 SandboxViolationStore。 两个 UI 表面消耗这个：

• 标准错误注释： annotateStderrWithSandboxFailures() 当违规匹配时，将人类可读的解释附加到命令的 stderr。
• SandboxDoctorSection: 在助手的响应区域中呈现，显示哪个路径或域被阻止，并提供有关如何允许它的建议。

在 UI 中显示错误消息时还需要剥离违规标签 - <sandbox_violations> 原始 stderr 中出现的 XML 块被删除以供显示：

// sandbox-ui-utils.ts — strip violation XML from display text
export function removeSandboxViolationTags(text: string): string {
  return text.replace(
    /<sandbox_violations>[\s\S]*?<\/sandbox_violations>/g,
    '',
  )
}