深入剖析 Claude Code 权限与安全系统

// 权限规则的核心数据结构
type PermissionRule = {
  source:
    | 'localSettings'
    | 'userSettings'
    | 'projectSettings'
    | 'policySettings'
    | 'flagSettings'
    | 'command'
    | 'cliArg'
    | 'session'
  ruleBehavior: 'allow' | 'deny' | 'ask'
  ruleValue: {
    toolName: string // 如 "Bash", "Edit", "WebFetch"
    ruleContent?: string // 如 "npm publish:*", "domain:github.com"
  }
}

1a. 整个工具被 deny 规则拦截 → 直接拒绝
1b. 整个工具有 ask 规则 → 弹出审批（沙箱内命令可豁免）
1c. 工具自身的 checkPermissions 检查（如 Bash 的子命令匹配）
1d. 工具实现返回 deny → 拒绝
1e. 工具标记 requiresUserInteraction → 强制交互审批
1f. 内容级 ask 规则（如 Bash(npm publish:*)）→ 即使在 bypass 模式也必须审批
1g. 安全检查（.git/, .claude/ 等敏感路径）→ bypass 不可豁免

2a. bypassPermissions 模式 → 允许（但 1f/1g 除外）
2b. 工具在 always-allow 列表 → 允许
3.  以上均未匹配 → 转为 ask，弹出用户审批

// sandbox-adapter.ts 中的路径配置逻辑
const allowWrite: string[] = ['.', getClaudeTempDir()] // 默认可写：当前目录 + 临时目录
const denyWrite: string[] = []
const denyRead: string[] = []

network: {
  allowedDomains: [],      // 从 WebFetch(domain:*) 规则中提取
  deniedDomains: [],
  allowUnixSockets: boolean | undefined,
  allowLocalBinding: boolean | undefined,
  httpProxyPort: number | undefined,
  socksProxyPort: number | undefined,
}

// bashSecurity.ts 中的危险模式检测
const COMMAND_SUBSTITUTION_PATTERNS = [
  { pattern: /<\(/, message: 'process substitution <()' },
  { pattern: />\(/, message: 'process substitution >()' },
  { pattern: /=\(/, message: 'Zsh process substitution =()' },
  { pattern: /\$\(/, message: '$() command substitution' },
  { pattern: /\$\{/, message: '${} parameter substitution' },
  // ... 更多模式
]

const CROSS_PLATFORM_CODE_EXEC = [
  'python', 'python3', 'node', 'deno', 'ruby', 'perl',
  'npx', 'bunx', 'npm run', 'yarn run', 'pnpm run',
  'bash', 'sh', 'ssh', 'eval', 'exec', 'sudo', ...
]

// 策略限制的核心检查逻辑
export function isPolicyAllowed(policy: string): boolean {
  const restrictions = getRestrictionsFromCache()
  if (!restrictions) {
    // HIPAA 合规：essential-traffic-only 模式下特定策略 fail closed
    if (isEssentialTrafficOnly() && ESSENTIAL_TRAFFIC_DENY_ON_MISS.has(policy)) {
      return false
    }
    return true // 默认 fail open
  }
  return restrictions[policy]?.allowed ?? true
}

// TrustDialog 检测的风险维度
- hasMcpServers:     项目配置了 MCP 服务器（可能执行任意代码）
- hasHooks:          配置了 PreToolUse 等钩子
- hasBashExecution:  权限规则允许 Bash 执行
- hasApiKeyHelper:   配置了 API Key Helper（执行外部命令）
- hasAwsCommands:    配置了 AWS CLI 命令
- hasGcpCommands:    配置了 GCP CLI 命令
- hasOtelHeadersHelper: 配置了 OpenTelemetry（可能泄露数据）
- hasDangerousEnvVars:  配置了危险环境变量

用户进入工作区
    ↓
检查 hasTrustDialogAccepted
    ↓ 未信任
展示 TrustDialog（扫描所有风险源）
    ↓ 用户选择"Yes, I trust this folder"
    ↓
根据目录类型存储信任状态
  ├─ $HOME → 会话内存（setSessionTrustAccepted）
  └─ 其他 → 项目配置文件（saveCurrentProjectConfig）
    ↓
允许 Claude Code 开始工作

┌─────────────────────────────────────────────┐
│               用户 / 管理员                    │
│  (TrustDialog / policySettings / permissions) │
└──────────────┬──────────────────────────────┘
               ↓
┌──────────────────────────────────────────────┐
│           权限决策管线                         │
│  deny规则 → ask规则 → checkPermissions        │
│  → requiresUserInteraction → 内容级ask规则     │
│  → safetyCheck → bypassPermissions → allow   │
│  → ask (默认)                                 │
└──────────────┬───────────────────────────────┘
               ↓
┌──────────────────────────────────────────────┐
│           Auto Mode 分类器                    │
│  acceptEdits 快速路径 → allowlist 快速路径     │
│  → AI 分类器（两阶段）→ denial tracking        │
└──────────────┬───────────────────────────────┘
               ↓
┌──────────────────────────────────────────────┐
│           BashTool 安全层                      │
│  Tree-sitter AST → 危险模式检测               │
│  → Shell 引号验证 → Zsh 攻击面防护             │
└──────────────┬───────────────────────────────┘
               ↓
┌──────────────────────────────────────────────┐
│           OS 级沙箱                            │
│  macOS: sandbox-exec                          │
│  Linux: bubblewrap (bwrap)                    │
│  文件系统隔离 + 网络隔离 + 配置文件保护         │
└──────────────────────────────────────────────┘