BashTool 权限系统深度解析

// ast.ts:42-46
export type ParseForSecurityResult =
  | { kind: 'simple'; commands: SimpleCommand[] }
  | { kind: 'too-complex'; reason: string; nodeType?: string }
  | { kind: 'parse-unavailable' }

// ast.ts:54-59 — 结构性节点（允许递归遍历）
const STRUCTURAL_TYPES = new Set([
  'program', 'list', 'pipeline', 'redirected_statement',
])

// ast.ts:186-205 — 危险节点类型（立即返回 too-complex）
const DANGEROUS_TYPES = new Set([
  'command_substitution',   // $()
  'process_substitution',   // <() >()
  'expansion',              // ${}
  'simple_expansion',       // $VAR (未跟踪)
  'brace_expression',       // {a,b}
  'subshell',               // (cmd)
  'compound_statement',     // { cmd; }
  'for_statement',          // for/do/done
  'while_statement',        // while/do/done
  'if_statement',           // if/then/fi
  'case_statement',         // case/esac
  'function_definition',    // function foo()
  'test_command',           // [[ ]]
  'ansi_c_string',          // $'...'
  'translated_string',      // $"..."
  'heredoc_redirect',       // <<EOF
  'herestring_redirect',    // <<<
])

// ast.ts:31-40
export type SimpleCommand = {
  argv: string[]           // 命令名+参数，引号已解析
  envVars: { name: string; value: string }[]  // 前置 VAR=val
  redirects: Redirect[]    // 重定向操作符和目标
  text: string             // 原始源码片段
}

// ast.ts:408-437
if (CONTROL_CHAR_RE.test(cmd))           // 控制字符
  return { kind: 'too-complex', ... }
if (UNICODE_WHITESPACE_RE.test(cmd))     // Unicode 空白
  return { kind: 'too-complex', ... }
if (BACKSLASH_WHITESPACE_RE.test(cmd))   // 反斜杠转义空白
  return { kind: 'too-complex', ... }
if (ZSH_TILDE_BRACKET_RE.test(cmd))      // zsh ~[ 扩展
  return { kind: 'too-complex', ... }
if (ZSH_EQUALS_EXPANSION_RE.test(cmd))   // zsh =cmd 扩展
  return { kind: 'too-complex', ... }
if (BRACE_WITH_QUOTE_RE.test(...))       // 花括号+引号混淆
  return { kind: 'too-complex', ... }

// bashSecurity.ts:2308-2378
const earlyValidators = [
  validateEmpty,              // 空命令 → allow
  validateIncompleteCommands, // 不完整片段 → ask
  validateSafeCommandSubstitution, // 安全 heredoc $() → allow
  validateGitCommit,          // git commit -m "msg" → allow
]

const validators = [
  validateJqCommand,                  // jq system() 函数检查
  validateObfuscatedFlags,            // 混淆标志检测 ($'', ""-, etc.)
  validateShellMetacharacters,        // 元字符在引号中的检查
  validateDangerousVariables,         // 变量在重定向/管道中的使用
  validateCommentQuoteDesync,         // # 注释中的引号不同步
  validateQuotedNewline,              // 引号内换行+注释行攻击
  validateCarriageReturn,             // \r 的解析分歧
  validateNewlines,                   // 换行分隔多个命令
  validateIFSInjection,               // $IFS 注入
  validateProcEnvironAccess,          // /proc/*/environ 访问
  validateDangerousPatterns,          // 反引号、$()、>(), <() 等
  validateRedirections,               // < > 重定向
  validateBackslashEscapedWhitespace, // 反斜杠转义空白
  validateBackslashEscapedOperators,  // 反斜杠转义操作符 (\; \| 等)
  validateUnicodeWhitespace,          // Unicode 空白字符
  validateMidWordHash,                // 词中 # (shell-quote 分歧)
  validateBraceExpansion,             // 花括号展开 {a,b}
  validateZshDangerousCommands,       // zmodload, emulate 等
  validateMalformedTokenInjection,    // 畸形 token + 命令分隔符
]

// bashSecurity.ts:2343-2346
const nonMisparsingValidators = new Set([
  validateNewlines,
  validateRedirections,
])

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' },
  { pattern: /\$\[/, message: '$[] legacy arithmetic expansion' },
  { pattern: /~\[/,  message: 'Zsh-style parameter expansion' },
  // ... 更多
]

const ZSH_DANGEROUS_COMMANDS = new Set([
  'zmodload', 'emulate',
  'sysopen', 'sysread', 'syswrite', 'sysseek',
  'zpty', 'ztcp', 'zsocket', 'mapfile',
  'zf_rm', 'zf_mv', 'zf_ln', 'zf_chmod', 'zf_chown', 'zf_mkdir', 'zf_rmdir',
])

// bashPermissions.ts:870-934 — filterRulesByContentsMatchingInput
switch (bashRule.type) {
  case 'exact':    // 完全匹配命令
    return bashRule.command === cmdToMatch
  case 'prefix':   // 前缀匹配 "git commit"
    return cmdToMatch.startsWith(bashRule.prefix + ' ')
  case 'wildcard': // 通配符匹配 "npm run *"
    return matchWildcardPattern(bashRule.pattern, cmdToMatch)
}

// 1. 精确匹配 deny → deny (最高优先级)
// 2. 精确匹配 ask → ask
// 3. 精确匹配 allow → allow
// 4. 前缀匹配 deny → deny
// 5. 前缀匹配 ask → ask
// 6. 路径约束检查 → ask/deny (如果路径越界)
// 7. 精确匹配 allow → allow
// 8. 前缀匹配 allow → allow
// 9. sed 约束检查 → ask (危险 sed 操作)
// 10. 模式检查 → allow (acceptEdits 模式)
// 11. 只读检查 → allow (白名单命令)
// 12. passthrough → 触发用户确认

// bashPermissions.ts:378-430 — SAFE_ENV_VARS
const SAFE_ENV_VARS = new Set([
  'GOEXPERIMENT', 'GOOS', 'GOARCH', 'CGO_ENABLED', 'GO111MODULE',
  'RUST_BACKTRACE', 'RUST_LOG',
  'NODE_ENV',
  'PYTHONUNBUFFERED', 'PYTHONDONTWRITEBYTECODE',
  'LANG', 'LANGUAGE', 'LC_ALL', 'TERM', 'NO_COLOR', 'FORCE_COLOR',
  // ... 安全的环境变量
])

// bashPermissions.ts:447-497 — ANT_ONLY_SAFE_ENV_VARS (内部员工专用)
const ANT_ONLY_SAFE_ENV_VARS = new Set([
  'KUBECONFIG', 'DOCKER_HOST',  // 注意：有安全风险，仅内部使用
  'AWS_PROFILE', 'CLOUDSDK_CORE_PROJECT',
  // ...
])

// bashPermissions.ts:532-560 — stripSafeWrappers
const SAFE_WRAPPER_PATTERNS = [
  /^timeout[ \t]+(...复杂的 GNU 标志解析...)[ \t]+/,
  /^time[ \t]+(?:--[ \t]+)?/,
  /^nice(?:[ \t]+-n[ \t]+-?\d+|[ \t]+-\d+)?[ \t]+(?:--[ \t]+)?/,
  /^stdbuf(?:[ \t]+-[ioe][LN0-9]+)+[ \t]+(?:--[ \t]+)?/,
  /^nohup[ \t]+(?:--[ \t]+)?/,
]

const DESTRUCTIVE_PATTERNS = [
  { pattern: /\bgit\s+reset\s+--hard\b/, warning: '可能丢弃未提交的更改' },
  { pattern: /\bgit\s+push\b.*--force/, warning: '可能覆盖远程历史' },
  { pattern: /\bgit\s+clean\b.*-f/, warning: '可能永久删除未跟踪文件' },
  { pattern: /\brm\s+-[a-zA-Z]*[rR][a-zA-Z]*f/, warning: '可能递归强制删除' },
  { pattern: /\bDROP\s+TABLE\b/i, warning: '可能删除数据库表' },
  { pattern: /\bkubectl\s+delete\b/, warning: '可能删除 K8s 资源' },
  { pattern: /\bterraform\s+destroy\b/, warning: '可能销毁基础设施' },
]

// 即使有 allow 规则，以下路径仍需用户确认：
// /, /usr, /bin, /sbin, /etc, /var, /home, /tmp, /opt, /lib
if (isDangerousRemovalPath(absolutePath)) {
  return { behavior: 'ask', message: '危险的 rm 操作...' }
}

// bashPermissions.ts:2202-2225
// 防止通过 cd 到恶意目录 + git status 触发 bare repo 的 core.fsmonitor RCE
if (compoundCommandHasCd) {
  const hasGitCommand = subcommands.some(cmd => isNormalizedGitCommand(cmd))
  if (hasGitCommand) {
    return { behavior: 'ask', reason: 'cd + git 组合需要批准以防止 bare repository 攻击' }
  }
}

// COMMAND_ALLOWLIST 中的命令示例：
xargs: { safeFlags: { '-I': '{}', '-n': 'number', ... } }
git: { /* 大量 git 子命令+标志 */ }
grep: { safeFlags: { '-e': 'string', '-i': 'none', ... } }
sed: { safeFlags: { '-n': 'none', '-e': 'string', ... },
       additionalCommandIsDangerousCallback: (cmd) => !sedCommandIsAllowedByAllowlist(cmd) }

type CommandConfig = {
  safeFlags: Record<string, FlagArgType>  // 允许的标志
  regex?: RegExp                           // 可选的额外验证
  additionalCommandIsDangerousCallback?: (cmd, args) => boolean
  respectsDoubleDash?: boolean             // 是否尊重 POSIX --
}

// bashPermissions.ts:1459-1481 — buildPendingClassifierCheck
// 在用户看到权限提示时，异步运行分类器
// 如果 LLM 高置信度允许 → 自动批准
export async function executeAsyncClassifierCheck(...) {
  const classifierResult = await classifyBashCommand(command, cwd, descriptions, ...)
  if (feature('BASH_CLASSIFIER') && classifierResult.matches && classifierResult.confidence === 'high') {
    callbacks.onAllow({ type: 'classifier', reason: `Allowed by prompt rule: "..."` })
  }
}

// bashPermissions.ts:1270-1359 — checkSandboxAutoAllow
// 沙箱模式下的自动放行，但仍尊重 deny/ask 规则
if (SandboxManager.isSandboxingEnabled() && SandboxManager.isAutoAllowBashIfSandboxedEnabled()) {
  // 检查显式 deny/ask 规则
  // 无规则 → auto-allow (沙箱提供隔离)
}

// modeValidation.ts:38-50
// acceptEdits 模式自动放行文件系统操作
if (toolPermissionContext.mode === 'acceptEdits' && isFilesystemCommand(baseCmd)) {
  return { behavior: 'allow', decisionReason: { type: 'mode', mode: 'acceptEdits' } }
}
// 自动放行的命令: mkdir, touch, rm, rmdir, mv, cp, sed

// bashPermissions.ts:103
export const MAX_SUBCOMMANDS_FOR_SECURITY_CHECK = 50
// 超过 50 个子命令 → ask（防止 ReDoS 和事件循环阻塞）

// bashPermissions.ts:110
export const MAX_SUGGESTED_RULES_FOR_COMPOUND = 5
// 复合命令最多建议 5 条规则

// bashPermissions.ts:1663-2557
export async function bashToolHasPermission(
  input: z.infer<typeof BashTool.inputSchema>,
  context: ToolUseContext,
  getCommandSubcommandPrefixFn = getCommandSubcommandPrefix,
): Promise<PermissionResult> {
  // Step 0: AST parse
  let astResult = await parseForSecurity(input.command)

  // too-complex → ask (respect deny rules first)
  if (astResult.kind === 'too-complex') {
    const earlyExit = checkEarlyExitDeny(input, context)
    if (earlyExit !== null) return earlyExit
    return { behavior: 'ask', ... }
  }

  // simple → checkSemantics (eval, zsh builtins, etc.)
  if (astResult.kind === 'simple') {
    const sem = checkSemantics(astResult.commands)
    if (!sem.ok) { /* deny/ask rules first, then ask */ }
  }

  // Steps 1-7: 精确匹配 → LLM → 管道 → 子命令拆分 → 最终决策
  // ... (见第2节流程图)
}

// bashPermissions.ts:524-615
export function stripSafeWrappers(command: string): string {
  // Phase 1: 剥离环境变量（仅 SAFE_ENV_VARS）
  // SECURITY: 使用 [ \t]+ 而非 \s+  —— \s 匹配 \n/\r（命令分隔符）
  const ENV_VAR_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)=([A-Za-z0-9_./:-]+)[ \t]+/

  // Phase 2: 剥离包装命令（timeout, time, nice, nohup）
  // 两阶段分离的原因：
  // 包装命令后的 VAR=val 被视为要执行的命令，不是环境变量
  // HackerOne #3543050
}

// ast.ts:2213-2384 — checkSemantics
// 递归剥离包装命令后检查实际命令名
for (;;) {
  if (a[0] === 'time' || a[0] === 'nohup') { a = a.slice(1) }
  else if (a[0] === 'timeout') { /* 解析 GNU 标志 + 时长 */ }
  else if (a[0] === 'nice') { /* 解析 -n N / -N / bare */ }
  else if (a[0] === 'env') { /* 解析 VAR=val + 安全标志 */ }
  else if (a[0] === 'stdbuf') { /* 解析 -o0 / --output=M */ }
  else { break }
}
// 然后检查实际命令名是否危险
const name = a[0]
// EVAL_LIKE_BUILTINS: eval, source, exec, trap, enable, hash
if (EVAL_LIKE_BUILTINS.has(name)) return { ok: false, ... }

// pathValidation.ts:190-509 — PATH_EXTRACTORS
// 每个命令有专门的参数解析逻辑
export const PATH_EXTRACTORS: Record<PathCommand, (args: string[]) => string[]> = {
  cd:    args => (args.length === 0 ? [homedir()] : [args.join(' ')]),
  ls:    args => { const p = filterOutFlags(args); return p.length > 0 ? p : ['.'] },
  find:  args => { /* 处理 -path, -newer 等带路径的标志 */ },
  grep:  args => parsePatternCommand(args, flagsWithArgs),
  sed:   args => { /* 处理 -e, -f, 脚本参数 */ },
  git:   args => { /* git diff --no-index 是特殊情况 */ },
  // ...
}

// sedValidation.ts:473-629 — containsDangerousOperations
// 即使通过白名单匹配，仍需检查以下危险操作：
// - w/W 命令（写文件）
// - e/E 命令（执行命令）
// - 非 ASCII 字符（Unicode 同形字攻击）
// - 花括号块（过于复杂）
// - 否定操作符 (!)
// - 波浪号步进地址 (~)