vault backup: 2026-06-09 23:15:17
This commit is contained in:
@@ -1,13 +1,20 @@
|
||||
---
|
||||
tags: [tree-sitter, bash, AST, 安全, 权限, feature-flag]
|
||||
create time: 2026-06-09 22:30
|
||||
---
|
||||
|
||||
# TREE_SITTER_BASH — Bash AST 解析
|
||||
|
||||
> Feature Flag: `FEATURE_TREE_SITTER_BASH=1`
|
||||
> 实现状态：完整可用（纯 TypeScript 实现，~7000+ 行）
|
||||
> 引用数：3
|
||||
|
||||
## 一、功能概述
|
||||
## 概述
|
||||
|
||||
TREE_SITTER_BASH 启用一个完整的 Bash AST 解析器，用于安全验证 Bash 命令。它用完整的树遍历安全分析器取代了旧的基于正则表达式的 shell-quote 解析器。关键属性是 **fail-closed**：任何无法识别的内容都被归类为 `too-complex` 并需要用户批准。
|
||||
|
||||
> [!info]
|
||||
> Feature Flag: `FEATURE_TREE_SITTER_BASH=1`
|
||||
> 实现状态：完整可用（纯 TypeScript 实现，~7000+ 行）
|
||||
|
||||
## 正文
|
||||
|
||||
### 关联 Feature
|
||||
|
||||
| Feature | 说明 |
|
||||
@@ -15,64 +22,55 @@ TREE_SITTER_BASH 启用一个完整的 Bash AST 解析器，用于安全验证 B
|
||||
| `TREE_SITTER_BASH` | 激活用于权限检查的 AST 解析器 |
|
||||
| `TREE_SITTER_BASH_SHADOW` | Shadow/观测模式：运行解析器但丢弃结果，仅记录遥测 |
|
||||
|
||||
## 二、安全架构
|
||||
### 安全架构
|
||||
|
||||
### 2.1 Fail-Closed 设计
|
||||
#### Fail-Closed 设计
|
||||
|
||||
核心设计使用 **allowlist** 遍历模式：
|
||||
|
||||
- `walkArgument()` 只处理已知安全的节点类型（`word`、`number`、`raw_string`、`string`、`concatenation`、`arithmetic_expansion`、`simple_expansion`）
|
||||
- 任何未知节点类型 → `tooComplex()` → 需要用户批准
|
||||
- 解析器加载但失败（超时/节点预算/panic）→ 返回 `PARSE_ABORTED` 符号（区别于"模块未加载"）
|
||||
- 任何未知节点类型 -> `tooComplex()` -> 需要用户批准
|
||||
- 解析器加载但失败（超时/节点预算/panic）-> 返回 `PARSE_ABORTED` 符号（区别于"模块未加载"）
|
||||
|
||||
### 2.2 解析结果
|
||||
#### 解析结果
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
parseForSecurity(cmd) 返回：
|
||||
{ kind: 'simple', commands: SimpleCommand[] } // 可静态分析
|
||||
{ kind: 'too-complex', reason, nodeType } // 需要用户批准
|
||||
{ kind: 'parse-unavailable' } // 解析器未加载
|
||||
```
|
||||
|
||||
### 2.3 安全检查层次
|
||||
#### 安全检查层次
|
||||
|
||||
```
|
||||
parseForSecurity(cmd)
|
||||
│
|
||||
▼
|
||||
parseCommandRaw(cmd) → AST root node
|
||||
│
|
||||
▼
|
||||
预检查：控制字符、Unicode 空白、反斜杠+空白、
|
||||
zsh ~[ ] 语法、zsh =cmd 展开、大括号+引号混淆
|
||||
│
|
||||
▼
|
||||
walkProgram(root) → collectCommands(root, commands, varScope)
|
||||
│
|
||||
├── 'command' → walkCommand()
|
||||
├── 'pipeline'/'list' → 结构性，递归子节点
|
||||
├── 'for_statement' → 跟踪循环变量为 VAR_PLACEHOLDER
|
||||
├── 'if/while' → 作用域隔离的分支
|
||||
├── 'subshell' → 作用域复制
|
||||
├── 'variable_assignment' → walkVariableAssignment()
|
||||
├── 'declaration_command' → 验证 declare/export flags
|
||||
├── 'test_command' → walk test expressions
|
||||
└── 其他 → tooComplex()
|
||||
│
|
||||
▼
|
||||
checkSemantics(commands)
|
||||
├── EVAL_LIKE_BUILTINS（eval, source, exec, trap...）
|
||||
├── ZSH_DANGEROUS_BUILTINS（zmodload, emulate...）
|
||||
├── SUBSCRIPT_EVAL_FLAGS（test -v, printf -v, read -a）
|
||||
├── Shell keywords as argv[0]（误解析检测）
|
||||
├── /proc/*/environ 访问
|
||||
├── jq system() 和危险 flags
|
||||
└── 包装器剥离（time, nohup, timeout, nice, env, stdbuf）
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["parseForSecurity(cmd)"] --> B["parseCommandRaw(cmd) -> AST root node"]
|
||||
B --> C["预检查: 控制字符、Unicode 空白、反斜杠+空白、zsh 语法"]
|
||||
C --> D["walkProgram(root) -> collectCommands(root, commands, varScope)"]
|
||||
D --> E{"节点类型"}
|
||||
E -->|"command"| F["walkCommand()"]
|
||||
E -->|"pipeline/list"| G["结构性，递归子节点"]
|
||||
E -->|"for_statement"| H["跟踪循环变量为 VAR_PLACEHOLDER"]
|
||||
E -->|"if/while"| I["作用域隔离的分支"]
|
||||
E -->|"subshell"| J["作用域复制"]
|
||||
E -->|"variable_assignment"| K["walkVariableAssignment()"]
|
||||
E -->|"declaration_command"| L["验证 declare/export flags"]
|
||||
E -->|"test_command"| M["walk test expressions"]
|
||||
E -->|"其他"| N["tooComplex()"]
|
||||
D --> O["checkSemantics(commands)"]
|
||||
O --> P["EVAL_LIKE_BUILTINS eval/source/exec/trap..."]
|
||||
O --> Q["ZSH_DANGEROUS_BUILTINS zmodload/emulate..."]
|
||||
O --> R["SUBSCRIPT_EVAL_FLAGS test -v/printf -v/read -a"]
|
||||
O --> S["Shell keywords as argv0 误解析检测"]
|
||||
O --> T["/proc/*/environ 访问"]
|
||||
O --> U["jq system() 和危险 flags"]
|
||||
O --> V["包装器剥离 time/nohup/timeout/nice/env/stdbuf"]
|
||||
```
|
||||
|
||||
## 三、实现架构
|
||||
### 实现架构
|
||||
|
||||
### 3.1 核心模块
|
||||
#### 核心模块
|
||||
|
||||
| 模块 | 文件 | 行数 | 职责 |
|
||||
|------|------|------|------|
|
||||
@@ -82,7 +80,7 @@ checkSemantics(commands)
|
||||
| AST 分析辅助 | `src/utils/bash/treeSitterAnalysis.ts` | 507 | 引号上下文、复合结构、危险模式提取 |
|
||||
| 权限检查入口 | `src/tools/BashTool/bashPermissions.ts` | — | 集成 AST 结果到权限决策 |
|
||||
|
||||
### 3.2 Bash 解析器
|
||||
#### Bash 解析器
|
||||
|
||||
文件：`src/utils/bash/bashParser.ts`（4437 行）
|
||||
|
||||
@@ -91,7 +89,7 @@ checkSemantics(commands)
|
||||
- 关键类型：`TsNode`（type、text、startIndex、endIndex、children）
|
||||
- 安全限制：`PARSE_TIMEOUT_MS = 50`、`MAX_NODES = 50_000` — 防止对抗性输入导致 OOM
|
||||
|
||||
### 3.3 安全分析器
|
||||
#### 安全分析器
|
||||
|
||||
文件：`src/utils/bash/ast.ts`（2680 行）
|
||||
|
||||
@@ -106,7 +104,7 @@ checkSemantics(commands)
|
||||
| `walkArgument()` | Allowlist 参数遍历 |
|
||||
| `collectCommands()` | 递归收集所有命令 |
|
||||
|
||||
### 3.4 AST 分析辅助
|
||||
#### AST 分析辅助
|
||||
|
||||
文件：`src/utils/bash/treeSitterAnalysis.ts`（507 行）
|
||||
|
||||
@@ -118,11 +116,11 @@ checkSemantics(commands)
|
||||
| `extractDangerousPatterns()` | 检测命令替换、参数展开、heredocs |
|
||||
| `analyzeCommand()` | 单次遍历提取 |
|
||||
|
||||
### 3.5 Shadow 模式
|
||||
#### Shadow 模式
|
||||
|
||||
`TREE_SITTER_BASH_SHADOW` 运行解析器但**从不影响权限决策**：
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
// Shadow 模式：记录遥测，然后强制使用旧版路径
|
||||
astResult = { kind: 'parse-unavailable' }
|
||||
astRoot = null
|
||||
@@ -131,16 +129,16 @@ astRoot = null
|
||||
|
||||
记录 `tengu_tree_sitter_shadow` 事件，包含与旧版 `splitCommand()` 的对比数据。用于在不影响行为的情况下收集遥测。
|
||||
|
||||
## 四、关键设计决策
|
||||
### 关键设计决策
|
||||
|
||||
1. **Allowlist 遍历**：只处理已知安全的节点类型，未知类型直接 `tooComplex()`
|
||||
2. **PARSE_ABORTED 符号**：区分"解析器未加载"和"解析器加载但失败"。后者阻止回退旧版（旧版缺少 `EVAL_LIKE_BUILTINS` 检查）
|
||||
3. **变量作用域跟踪**：`VAR=value && cmd $VAR` 模式。静态值解析为真实字符串，`$()` 输出使用 `VAR_PLACEHOLDER`
|
||||
4. **PS4/IFS Allowlist**：PS4 赋值使用严格字符白名单 `[A-Za-z0-9 _+:.\/=\[\]-]`，只允许 `${VAR}` 引用
|
||||
5. **包装器剥离**：从 argv 前面剥离 `time/nohup/timeout/nice/env/stdbuf`，未知标志 → fail-closed
|
||||
5. **包装器剥离**：从 argv 前面剥离 `time/nohup/timeout/nice/env/stdbuf`，未知标志 -> fail-closed
|
||||
6. **Shadow 安全性**：Shadow 模式**总是**强制 `astResult = { kind: 'parse-unavailable' }`，绝不影响权限
|
||||
|
||||
## 五、使用方式
|
||||
### 使用方式
|
||||
|
||||
```bash
|
||||
# 激活 AST 解析用于权限检查
|
||||
@@ -150,7 +148,7 @@ FEATURE_TREE_SITTER_BASH=1 bun run dev
|
||||
FEATURE_TREE_SITTER_BASH_SHADOW=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
### 文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
@@ -159,3 +157,7 @@ FEATURE_TREE_SITTER_BASH_SHADOW=1 bun run dev
|
||||
| `src/utils/bash/ast.ts` | 2680 | 安全分析器（核心） |
|
||||
| `src/utils/bash/treeSitterAnalysis.ts` | 507 | AST 分析辅助 |
|
||||
| `packages/builtin-tools/src/tools/BashTool/bashPermissions.ts` | ~140 | 权限集成 + Shadow 遥测 |
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[claude-code-best/docs/features/bash-classifier]]
|
||||
|
||||
Reference in New Issue
Block a user