【Claude Code源码剖析】05-权限与安全系统

Claude Code 最精密的子系统之一。每个工具执行前都经过多层安全审查。

---

一、安全设计第一性原理

核心矛盾：

• AI Agent 需要 自主执行 文件编辑、命令运行（否则效率太低）
• 但用户需要 控制权 和 安全保障（AI 可能犯错或执行危险操作）

解决方案：分层权限模型 + 智能分类器 + 用户确认

---

二、权限模式 (PermissionMode)

// utils/permissions/PermissionMode.ts
type PermissionMode =
  | 'default'     // 默认模式：每个操作都询问
  | 'auto'        // 自动模式：分类器辅助决策
  | 'bypass'      // 绕过模式：跳过权限检查 (危险)
  | 'plan'        // 计划模式：只能读不能写

模式详情

模式	读操作	写操作	命令执行	适用场景
default	自动允许	逐个询问	逐个询问	日常使用
auto	自动允许	分类器判断	分类器判断	信任 AI 的场景
bypass	自动允许	自动允许	自动允许	测试/CI 环境
plan	自动允许	禁止	只读命令	先规划后执行

---

三、权限检查完整流程

工具请求 (如 BashTool: "npm install lodash")
       │
       ▼
[1] 工具级验证 ── tool.validateInput(input)
       │ 输入格式/范围检查
       ▼
[2] 权限规则匹配 ── matchPermissionRules()
       │
       ├─ alwaysAllowRules: 匹配 → 直接通过 ✅
       ├─ alwaysDenyRules:  匹配 → 直接拒绝 ❌
       └─ alwaysAskRules:   匹配 → 强制询问用户 ❓
       │
       ▼ (未匹配任何规则)
[3] 权限模式判断
       │
       ├─ mode === 'bypass' → 直接通过 ✅
       ├─ mode === 'plan'   → 拒绝写操作 ❌
       ├─ mode === 'default' → 询问用户 ❓
       └─ mode === 'auto'   → 进入分类器
       │
       ▼
[4] 分类器判断 (auto 模式)
       │ ── bashClassifier / yoloClassifier
       │
       ├─ 安全 → 自动允许 ✅
       ├─ 危险 → 拒绝 ❌
       └─ 不确定 → 询问用户 ❓
       │
       ▼
[5] 用户确认对话框
       │
       ├─ Allow (允许本次)
       ├─ Always Allow (添加到 allow 规则)
       ├─ Deny (拒绝本次)
       └─ Always Deny (添加到 deny 规则)

---

四、权限规则系统

4.1 规则来源 (PermissionRuleSource)

type PermissionRuleSource =
  | 'user'        // 用户手动设置
  | 'project'     // 项目 .claude/settings.json
  | 'enterprise'  // 企业策略
  | 'plugin'      // 插件设置

优先级：enterprise > project > user > plugin

4.2 规则格式

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm *)",           // 允许所有 npm 命令
      "Bash(git *)",           // 允许所有 git 命令
      "FileEdit(**/src/**)",   // 允许编辑 src 目录
      "FileRead"               // 允许所有文件读取
    ],
    "deny": [
      "Bash(rm -rf *)",        // 禁止 rm -rf
      "Bash(sudo *)",          // 禁止 sudo
      "FileEdit(**/node_modules/**)"  // 禁止编辑 node_modules
    ]
  }
}

4.3 通配符匹配算法

// bashPermissions.ts
function matchWildcardPattern(pattern: string, command: string): boolean {
  // 支持的通配符:
  // *   — 匹配任意字符序列
  // ?   — 匹配单个字符
  // **  — 匹配跨目录路径

  // 例子:
  // "npm *" 匹配 "npm install lodash"
  // "git commit *" 匹配 "git commit -m 'fix'"
  // "**/src/**" 匹配 "src/utils/file.ts"
}

// 前缀提取（优化：不需要每次都匹配整个字符串）
function permissionRuleExtractPrefix(rule: string): string {
  // "Bash(npm *)" → "npm "
  // 先匹配前缀，不匹配就直接跳过
}

---

五、BashTool 安全分类器

5.1 Bash 命令解析

// utils/bash/ast.ts
function parseForSecurity(command: string): SecurityAnalysis {
  // 1. 解析 shell 语法（管道、重定向、子shell、变量展开）
  // 2. 识别每个原子命令
  // 3. 检测危险模式:
  //    - rm -rf / (递归删除根目录)
  //    - curl | bash (远程代码执行)
  //    - chmod 777 (权限开放)
  //    - dd of=/dev/sda (写入磁盘设备)
  //    - > /etc/passwd (覆盖系统文件)
}

5.2 危险命令模式

// utils/permissions/dangerousPatterns.ts
const DANGEROUS_PATTERNS = [
  // 文件系统破坏
  /rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|rf)\s/,
  /rm\s+-[a-zA-Z]*f[a-zA-Z]*r\s/,

  // 权限提升
  /sudo\s/,
  /chmod\s+777/,
  /chown\s+root/,

  // 远程代码执行
  /curl.*\|\s*(ba)?sh/,
  /wget.*\|\s*(ba)?sh/,

  // 系统文件修改
  />\s*\/etc\//,
  />\s*\/dev\//,

  // 数据泄露
  /curl\s+.*-d\s+@/,  // 上传文件内容
];

5.3 Auto 模式分类器

// utils/permissions/yoloClassifier.ts (auto 模式的核心分类器)
// "YOLO" = You Only Live Once (自动允许看起来安全的操作)

function classifyBashCommand(command: string, context): ClassifierResult {
  return {
    decision: 'allow' | 'deny' | 'ask',
    reason: string,
    confidence: number,
  };
}

// utils/permissions/bashClassifier.ts (基于 ML 的分类器)
// 更高级的分类器，可能调用 LLM side-query 来判断

---

六、ToolPermissionContext — 权限上下文

type ToolPermissionContext = DeepImmutable<{
  mode: PermissionMode;
  additionalWorkingDirectories: Map<string, AdditionalWorkingDirectory>;
  alwaysAllowRules: ToolPermissionRulesBySource;
  alwaysDenyRules: ToolPermissionRulesBySource;
  alwaysAskRules: ToolPermissionRulesBySource;
  isBypassPermissionsModeAvailable: boolean;
  isAutoModeAvailable?: boolean;
  strippedDangerousRules?: ToolPermissionRulesBySource;
  shouldAvoidPermissionPrompts?: boolean;
  awaitAutomatedChecksBeforeDialog?: boolean;
  prePlanMode?: PermissionMode;
}>;

为什么用 DeepImmutable？

权限上下文是 不可变的。修改权限必须通过 PermissionUpdate 创建新的上下文对象。这防止了：

• 工具执行期间偷偷修改自己的权限
• Race condition 导致的权限泄露
• 回滚操作不一致

---

七、路径验证

// utils/permissions/pathValidation.ts
function isPathWithinAllowedDirectories(
  path: string,
  cwd: string,
  additionalDirs: Map<string, AdditionalWorkingDirectory>
): boolean {
  // 1. 解析为绝对路径
  const resolved = resolve(cwd, path);

  // 2. 检查是否在 cwd 或其子目录内
  if (resolved.startsWith(cwd)) return true;

  // 3. 检查是否在额外允许的目录内
  for (const [dir] of additionalDirs) {
    if (resolved.startsWith(dir)) return true;
  }

  // 4. 拒绝访问 cwd 之外的路径
  return false;
}

Symlink 攻击防护

// 防止通过 symlink 逃逸出允许的目录
const realPath = realpathSync(path);
if (!realPath.startsWith(allowedDir)) {
  throw new Error('Symlink escape detected');
}

---

八、拒绝追踪

// utils/permissions/denialTracking.ts
type DenialTrackingState = {
  denials: Array<{
    toolName: string;
    input: unknown;
    reason: string;
    timestamp: number;
  }>;
};

系统追踪所有被拒绝的操作，用于：

1. 在自动压缩时保留拒绝信息（告诉 LLM “这个操作被拒绝过”）
2. 分析模式（如果同一操作被反复拒绝，可能 LLM 策略有问题）
3. 安全审计日志

---

九、沙箱执行

// utils/sandbox/sandbox-adapter.ts
class SandboxManager {
  // 对于高风险命令，在受限沙箱中执行
  static async execute(command: string, options): Promise<ExecResult> {
    // 沙箱提供:
    // - 文件系统隔离 (只能访问白名单路径)
    // - 网络限制 (可选)
    // - 资源限制 (CPU/内存/时间)
    // - 写操作审计
  }
}

// tools/BashTool/shouldUseSandbox.ts
function shouldUseSandbox(command: string, context): boolean {
  // 根据命令风险等级决定是否使用沙箱
  // 例如：安装依赖、构建项目等可能在沙箱中执行
}

---

十、权限持久化

// utils/permissions/PermissionUpdate.ts
type PermissionUpdate = {
  tool: string;           // 工具名
  rule: string;           // 规则表达式
  behavior: 'allow' | 'deny';
  destination: 'session' | 'project' | 'user';
};

// 用户在权限对话框中选择 "Always Allow" 后:
async function persistPermissionUpdate(update: PermissionUpdate) {
  if (update.destination === 'project') {
    // 写入 .claude/settings.json
    await updateProjectSettings(update);
  } else if (update.destination === 'user') {
    // 写入 ~/.claude/settings.json
    await updateGlobalSettings(update);
  } else {
    // 仅当前会话有效
    applyToCurrentContext(update);
  }
}

---

十一、安全设计总结

        Enterprise Policy (最高优先级)
               │
               ▼
         Project Rules (.claude/)
               │
               ▼
         User Rules (~/.claude/)
               │
               ▼
    Permission Mode (default/auto/plan/bypass)
               │
               ▼
       ┌───────┴───────┐
       │               │
Classifier          Rule Matcher
(ML/规则)           (通配符匹配)
       │               │
       └───────┬───────┘
               │
               ▼
       User Confirmation
       (权限对话框)
               │
               ▼
     Sandbox / Direct Execution

核心原则：

1. Defense in Depth — 多层防御，任何一层都能阻止危险操作
2. Least Privilege — 默认拒绝，需要显式授权
3. Fail Safe — 不确定时询问用户，而不是自动允许
4. Auditability — 所有操作和决策都有日志