bashSecurity.ts` 2592 行 — Bash 危险命令检测规则集¶

重要性：⭐⭐⭐（Bash 工具安全层——25+ 个独立 validator 组成规则集） 真实位置：src/tools/BashTool/bashSecurity.ts（2592 行）角色：检测 bash 命令中的危险模式（heredoc 注入、变量劫持、重定向攻击、转义绕过、ZSH 危险命令等）关联：topics/deep-dive-bash-parser.md、topics/deep-dive-bash-ast.md、topics/deep-dive-bash-permissions.md

1. 文件全景¶

bashSecurity.ts (2592 行)
│
├── 行 1-110  ：imports + 常量
│   ├── HEREDOC_IN_SUBSTITUTION (正则)
│   ├── COMMAND_SUBSTITUTION_PATTERNS (16 行)
│   ├── ZSH_DANGEROUS_COMMANDS (45 行)
│   └── BASH_SECURITY_CHECK_IDS (~25 项)
│
├── 行 103-230：类型 + 工具
│   ├── ValidationContext type (行 103)
│   ├── QuoteExtraction type (行 119)
│   ├── extractQuotedContent (行 128, ~50 行)
│   ├── stripSafeRedirections (行 176, ~33 行)
│   └── hasUnescapedChar (行 209, ~25 行)
│
├── 行 233-580：基础 validator
│   ├── validateEmpty (行 233, ~10 行)
│   ├── validateIncompleteCommands (行 244, ~75 行)
│   ├── isSafeHeredoc (行 317, ~200 行) — heredoc 安全判定
│   ├── stripSafeHeredocSubstitutions (行 521, ~60 行)
│   ├── hasSafeHeredocSubstitution (行 581, ~5 行)
│   └── validateSafeCommandSubstitution (行 585, ~28 行)
│
├── 行 612-740：特定命令 validator
│   ├── validateGitCommit (行 612, ~130 行) — git commit 安全
│   └── validateJqCommand (行 742, ~40 行) — jq 注入检测
│
├── 行 783-1180：通用 validator
│   ├── validateShellMetacharacters (行 783, ~40 行)
│   ├── validateDangerousVariables (行 823, ~22 行)
│   ├── validateDangerousPatterns (行 846, ~30 行)
│   ├── validateRedirections (行 875, ~30 行)
│   ├── validateNewlines (行 905, ~65 行)
│   ├── validateCarriageReturn (行 971, ~45 行)
│   ├── validateIFSInjection (行 1017, ~25 行)
│   ├── validateProcEnvironAccess (行 1041, ~40 行)
│   └── validateMalformedTokenInjection (行 1082, ~50 行)
│
├── 行 1130-1550：转义 + 混淆检测
│   ├── validateObfuscatedFlags (行 1130, ~420 行) — **超大 validator**
│   ├── hasBackslashEscapedWhitespace (行 1549, ~35 行)
│   └── validateBackslashEscapedWhitespace (行 1583, ~45 行)
│
├── 行 1629-1750：operator 转义
│   ├── SHELL_OPERATORS
│   ├── hasBackslashEscapedOperator (行 1631, ~65 行)
│   ├── validateBackslashEscapedOperators (行 1696, ~30 行)
│   └── isEscapedAtPosition (行 1727, ~25 行)
│
├── 行 1751-2180：复杂模式 validator
│   ├── validateBraceExpansion (行 1751, ~150 行)
│   ├── validateUnicodeWhitespace (行 1902, ~17 行)
│   ├── validateMidWordHash (行 1919, ~70 行)
│   ├── validateCommentQuoteDesync (行 1990, ~120 行)
│   └── validateQuotedNewline (行 2109, ~75 行)
│
├── 行 2186-2250：ZSH 特殊
│   └── validateZshDangerousCommands (行 2186, ~65 行)
│
└── 行 2251-2592：入口（DEPRECATED）
    ├── CONTROL_CHAR_RE
    ├── bashCommandIsSafe_DEPRECATED (行 2257, ~170 行)
    └── bashCommandIsSafeAsync_DEPRECATED (行 2426, ~165 行)

2. 25+ 个 Validator¶

每个 validator 是一个独立函数 —— 规则集模式。

function validateXxx(context: ValidationContext): PermissionResult { ... }

统一签名： - context —— 待检查的命令 + 元数据 - 返回 PermissionResult —— allow / deny + reason

3. 核心常量¶

3.1 `HEREDOC_IN_SUBSTITUTION`¶

const HEREDOC_IN_SUBSTITUTION = /\$\(.*<</

$(cmd << EOF) 模式 —— heredoc 在命令替换里（可绕过 heredoc 安全检查）。

3.2 `COMMAND_SUBSTITUTION_PATTERNS`¶

const COMMAND_SUBSTITUTION_PATTERNS = [
  // 16 行
]

16 个正则 —— 检测各种命令替换 / 进程替换 / 危险扩展。

3.3 `ZSH_DANGEROUS_COMMANDS`¶

const ZSH_DANGEROUS_COMMANDS = new Set([
  // 45 行
])

45 个 ZSH 特有危险命令（如 zmodload, autoload, compctl 等）。

3.4 `BASH_SECURITY_CHECK_IDS`¶

const BASH_SECURITY_CHECK_IDS = {
  // ~25 个 ID
}

25 个 安全检查 ID —— 用于 logging / telemetry。

4. 类型¶

type ValidationContext = {
  command: string
  // ... 元数据
}

type QuoteExtraction = {
  quoted: string
  unquoted: string
}

5. 4 个 Helper¶

extractQuotedContent(command)        // 提取引号内 / 外内容
stripSafeRedirections(content)       // 移除安全重定向
hasUnescapedChar(content, char)      // 是否有未转义字符
isEscapedAtPosition(content, pos)    // 该位置是否被转义

4 个 helper —— 给 validator 用。

6. 25+ 个 Validator 详解¶

6.1 基础（3 个）¶

Validator	检查
`validateEmpty`	空命令
`validateIncompleteCommands`	不完整命令（`cmd1 &&`）
`isSafeHeredoc`	heredoc 是否安全（200 行）

isSafeHeredoc 200 行 —— heredoc 安全判定非常复杂。

6.2 特定命令（2 个）¶

Validator	命令	行
`validateGitCommit`	git commit	130
`validateJqCommand`	jq	40

validateGitCommit 130 行 —— git commit -m "$user_input" 是高危模式（commit message 注入）。

6.3 通用（9 个）¶

Validator	行	检查
`validateShellMetacharacters`	40	危险 shell 字符
`validateDangerousVariables`	22	危险变量（LD_PRELOAD 等）
`validateDangerousPatterns`	30	危险字符串模式
`validateRedirections`	30	重定向攻击
`validateNewlines`	65	换行注入（CRLF）
`validateCarriageReturn`	45	CR 注入
`validateIFSInjection`	25	IFS 注入（拆分参数）
`validateProcEnvironAccess`	40	/proc/self/environ 访问
`validateMalformedTokenInjection`	50	畸形 token

6.4 转义绕过（4 个）¶

Validator	行	检查
`validateObfuscatedFlags`	420	混淆 flag（最大！）
`validateBackslashEscapedWhitespace`	45	`\` + 空白绕过
`validateBackslashEscapedOperators`	30	`\` + 操作符绕过
`validateBraceExpansion`	150	花括号扩展（`{a,b}`）

validateObfuscatedFlags 420 行 —— flag 混淆检测是最难的（攻击者用各种方式隐藏 flag）。

6.5 复杂模式（4 个）¶

Validator	行	检查
`validateUnicodeWhitespace`	17	Unicode 空白
`validateMidWordHash`	70	词中 `#`（如 `foo#bar`）
`validateCommentQuoteDesync`	120	注释-引号不同步
`validateQuotedNewline`	75	引号内换行

6.6 ZSH 特殊（1 个）¶

Validator	行	检查
`validateZshDangerousCommands`	65	ZSH 特有

7. 2 个 DEPRECATED 入口¶

export function bashCommandIsSafe_DEPRECATED(...) { ... }  // 同步
export async function bashCommandIsSafeAsync_DEPRECATED(...) { ... }  // 异步

2 个入口——保持向后兼容。

bashCommandIsSafeAsync_DEPRECATED 165 行： - 调 parseForSecurity - 调 checkSandboxAutoAllow / checkEarlyExitDeny 等 - 跑所有 validator - 聚合结果

8. 关键设计模式¶

8.1 25+ Validator 规则集¶

每个 validator 独立 —— 可单独启用 / 禁用 / 调试。

8.2 统一签名¶

function validateXxx(context: ValidationContext): PermissionResult

一致 —— 易扩展。

8.3 优先级¶

虽然每个 validator 独立，但有"快速失败"层（checkEarlyExitDeny）和"深度检查"层（validateObfuscatedFlags）。

8.4 ID 系统¶

BASH_SECURITY_CHECK_IDS —— 给每个检查一个 ID，用于 logging / metrics / 用户报告。

8.5 DEPRECATED 入口¶

bashCommandIsSafe_DEPRECATED —— 老 API 仍可用，新代码用新接口。

8.6 Heredoc 200 行单独处理¶

isSafeHeredoc 200 行 —— heredoc 是最常被攻击的向量。

8.7 validateObfuscatedFlags 420 行超大¶

flag 混淆是攻击者最爱的绕过方式 —— 400+ 行的检测规则。

8.8 ZSH 特殊处理¶

validateZshDangerousCommands —— ZSH 有 bash 没有的危险命令。

8.9 Unicode 攻击¶

validateUnicodeWhitespace —— 攻击者用 Unicode 空白（U+2028 等）绕过 ASCII 检查。

9. 复杂度分析¶

维度	数字
总行数	2592
Validator	25+
核心命令 validator	2 (git commit, jq)
通用 validator	9
转义绕过	4
复杂模式	4
ZSH 特殊	1
入口	2 (DEPRECATED)

10. 性能特征¶

10.1 单次检查¶

普通命令：< 5ms
大命令：~10-50ms
病态命令：~50-100ms

10.2 优化¶

早期退出（空命令 / 不完整）
isSafeHeredoc 单独优化

11. 与其他文件的关系¶

bashSecurity.ts
  ├──→ bashParser.ts
  ├──→ bash/ast.ts
  ├──→ bashPermissions.ts (调 validator)
  └──→ classifier (LLM)

12. 关键洞察¶

12.1 25+ Validator 是"安全集大成"¶

每个攻击面都有对应 validator —— 纵深防御。

12.2 统一签名便于扩展¶

新攻击出现 → 加新 validator，不破坏其他。

12.3 isSafeHeredoc 200 行 = heredoc 是高危面¶

heredoc 是 bash 最常被攻击的向量 —— 详细检查必要。

12.4 validateObfuscatedFlags 420 行 = flag 混淆是难点¶

攻击者用各种方式隐藏 flag —— 检测很难。

12.5 Unicode 攻击¶

validateUnicodeWhitespace —— 现代攻击向量，不可忽略。

12.6 ZSH 单独处理¶

不同 shell 有不同危险命令 —— 每种 shell 都要查。

12.7 DEPRECATED 入口¶

老 API 仍工作 —— 迁移期友好。

13. 阅读建议¶

看 BASH_SECURITY_CHECK_IDS（行 77）—— 25+ 检查 ID
看 isSafeHeredoc 200 行（行 317）—— heredoc 核心
看 validateGitCommit 130 行（行 612）—— git commit 注入
看 validateObfuscatedFlags 420 行（行 1130）—— flag 混淆
看 bashCommandIsSafeAsync_DEPRECATED 165 行（行 2426）—— 入口

14. 与其他深度拆解的关系¶

文件	关系
`bashParser.ts`	parse
`bash/ast.ts`	AST walk
`bashPermissions.ts`	决策中心

15. 阅读清单¶

✅ 看 BASH_SECURITY_CHECK_IDS（行 77）
✅ 看 isSafeHeredoc（行 317）
✅ 看 validateGitCommit（行 612）
✅ 看 validateObfuscatedFlags（行 1130）
✅ 看 bashCommandIsSafeAsync_DEPRECATED（行 2426）
📌 对照 topics/deep-dive-bash-permissions.md

16. 练习任务¶

数 validator（grep ^function validate) —— 25+
数 check IDs（grep BASH_SECURITY_CHECK_IDS）—— 25+
画 validator 分类图 —— 基础/特定命令/通用/转义/复杂/ZSH
手写 1 个 validator（~30 行）—— 拒绝 LD_PRELOAD
思考：如果新出 0day bash 漏洞，怎么加 validator？

Deep Dive ｜ src/tools/BashTool/bashSecurity.ts 2592 行 — Bash 危险命令检测规则集¶