本文作者：Zoar-yalz，浙江大学硕士生，研究方向为编译优化、软件分析等。github主页：github.com/Zoar-yalz
1. 这是什么？
YASA Checker 是一个 OpenCode 智能体 Skill，它把三种分析手段串联成自动化管线：静态污点追踪（YASA-Engine）做精确筛查、模式匹配（grep）做广撒网、AI 读源码做上下文判定。产出的包确认、哪些误报、附带修复建议的漏洞报告。
你可以像这样用它：「审查 XX 项目的命令注入漏洞」— 智能体自动安装 YASA、生成规则、跑扫描、做审计、AI 复核，最后把报告交到你手里。
地址：https://github.com/Zoar-yalz/YASA-SKILL
2. 为什么需要它？
一个现实的对比：以 OpenHands 项目（218 个 Python 文件，约 3.3 万行代码）为例：
| 分析方式 | 发现 | 说明 |
|---|---|---|
| 纯 YASA 静态污点追踪 | 0 个漏洞 | 无法追踪 f-string、方法包装器、字符串拼接等运行时模式 |
| 加 Phase 2（pattern grep） | 12 个可疑点 | 捕获了 YASA 盲区，但混入了 10 个误报 |
| 再加 Phase 3（AI 审查） | 2 个确认漏洞 + 10 个排除 | 准确分类，自动给出修复方案 |
结论：单一分析手段都不够——YASA 精确但覆盖窄，grep 覆盖广但噪音大，AI 能根据源代码上下文去伪存真。三者组合才能交付可用的结果。
YASA 的盲区主要包括：
- f-string 注入：
subprocess.run(f"rm {user_input}")——YASA 看到的是字符串字面量，不是污点流 - 方法包装器抽象：
workspace.execute_command(user_input)——除非把包装方法加入 sink 配置，否则追踪在包装边界断裂 - 跨层调用链：
A → B → C每一步做部分字符串拼接，污点在函数边界稀释
3. 架构概览
用户输入（项目路径、语言、漏洞类型） │ ▼ ┌───────────────────────────────────────────────────────────────┐ │ Phase 1：YASA 污点扫描（精准手术刀） │ │ AST 级 source→sink 追踪，输出 SARIF + codeFlow │ │ 强项：高精度、证据结构化；弱项：看不到运行时字符串拼接 │ ├───────────────────────────────────────────────────────────────┤ │ Phase 2：Post-Scan Audit（猎犬嗅探） │ │ 14 种模式正则 grep → YASA sink 交叉比对 → 污点变量反向追踪 → 评分 │ │ 强项：高召回、捕获 YASA 盲区；弱项：正则追踪会产生误报 │ ├───────────────────────────────────────────────────────────────┤ │ Phase 3：AI 上下文审查（分诊医生） │ │ 读取源代码 ±15 行 → 判源可控性 → 判定 CONFIRMED/LIKELY/FP │ │ → 覆盖严重度 → 生成修复代码 → 写回 ai_verdict 等字段 │ └───────────────────────────────────────────────────────────────┘ │ ▼ 综合报告（YASA 指标 + 审查后的漏洞列表 + 修复建议）4. 目录结构
yasa-skills/ ├── .opencode/ ← OpenCode 插件：智能体 + 命令 + Skills 定义 ├── yasa-checker/ │ ├── scripts/ (10 个 Python) ← 管线脚本（预检、安装、规则生成、扫描、审计） │ ├── references/ (10 个文档) ← 参考文档（规则手册、调试指南、审查协议） │ └── evals/ ← 评估用例 ├── README.md ← 项目主页 ├── AGENTS.md ← 开发者指南 └── DESIGN.zh-CN.md ← 本文件核心脚本按功能分组：
| 分组 | 脚本 | 作用 |
|---|---|---|
| 环境 & 安装 | preflight_yasa.py、install_yasa_release.py、write_local_config.py | 检测 YASA、安装引擎、写配置 |
| 规则工程 | normalize_rule_config.py、validate_rule_config.py | RuleGen → 生成 → 校验 |
| Phase 1 | extract_scan_metrics.py、sarif_to_evidence.py | 提取扫描指标、SARIF 转证据 |
| Phase 2 | grep_signals.py、taint_trace.py、post_scan_audit.py | 模式匹配 → 变量追踪 → 评分 |
| Phase 3 | 无需脚本（智能体推理） | AI 读源码 → 判源 → 分类 → 生成修复 |
5. 快速上手
5.1 环境要求
| 依赖 | 版本 | 说明 |
|---|---|---|
| Python | 3.9+ | 所有脚本支持 Python 3.9+ |
| YASA-Engine | 0.3.1 | 自动下载（install_yasa_release.py） |
ripgrep（rg） | — | 可选，Phase 2 加速（检测到自动使用） |
| OpenCode | — | 智能体运行时 |
5.2 安装
# 1. 安装 YASA-Engine 到 .yasa-tools/ 目录（仅首次）python yasa-checker/scripts/install_yasa_release.py# 2. 验证环境python yasa-checker/scripts/preflight_yasa.py# 输出：{"ok": true, "mode": "full"} ← 表示一切就绪5.3 跑一次完整扫描
# 方式一：通过 OpenCode 命令触发/yasa-checkproject=/path/to/targetlanguage=pythonvuln=PythonCommandInjection# 方式二：通过智能体调用@yasa-checker audit /path/to/projectforcommandinjection智能体会自动完成：
- 预检环境 → 确定模式（full / config-only / evidence-only）
- 生成
rule_config.json（定义 sources、sinks、entrypoints） - 运行 YASA 引擎（Phase 1）
- 运行 post-scan audit（Phase 2）
- 对每个发现做 AI 上下文审查（Phase 3）
- 产出综合报告
6. 三阶段详解
6.1 Phase 1 — YASA 污点扫描
角色：精准手术刀，做 AST 级别的 source→sink 污点追踪。
关键概念：
- Source：用户可控的输入来源（请求体
body、查询参数query_params、路径参数path_params、HTTP 头headers等） - Sink：危险函数调用（
subprocess.run、open、os.remove、httpx.AsyncClient.get等） - Entrypoint：分析的入口函数（通常是路由处理函数）
- Taint Flow：从 source 到 sink 的变量传递链
工作流：
用户指定（项目路径 + 漏洞类型） → 生成 rule_config.json（定义 sources / sinks / entrypoints） → validate_rule_config.py 校验配置 → 运行 yasa-engine-linux-x64 → 输出 scan_summary.json + report.sarif + entrypoints.json → sarif_to_evidence.py 将 SARIF 转为证据 JSONYASA 的局限性：无法追踪运行时字符串拼接（f-string、+拼接、.format()），也无法穿透方法包装器抽象。
6.2 Phase 2 — Post-Scan Audit
角色：猎犬嗅探，用正则模式匹配捕获 YASA 盲区的漏洞。
六步管线：
grep_signals.py（14 种模式） → 交叉比对 YASA sink 配置（标记 yasa_blind） → 按 (file, line) 去重 → taint_trace.py（每条命中做变量反向追踪） → 置信度评分（0.0～1.0） → 输出 audit_findings.json + 终端可读表格14 种扫描模式（按漏洞类型分组）：
| 模式 ID | 匹配目标 | 严重度 | 说明 |
|---|---|---|---|
fstring-subprocess | subprocess.run(f"...") | HIGH | f-string 中的用户输入直接拼入命令 |
concat-subprocess | os.system(cmd + arg) | MEDIUM | 字符串拼接后传入 shell |
execute-command-wrapper | .execute_command( | LOW | 方法包装器，可能是安全封装也可能是裸传 |
shell-true | shell=True | MEDIUM | subprocess 启用 shell 模式 |
fstring-open | open(f"...") | MEDIUM | f-string 作为文件路径 |
pickle-loads | pickle.loads( | HIGH | 不安全的反序列化 |
| … | … | … | 共计 14 种 |
变量污点追踪（taint_trace.py）：
从 sink 行提取被污染的变量 → 在文件内向上搜索该变量的赋值链 → 检测赋值源是否为用户输入（request、args、body、form、json、sys.argv等）→ 检测是否有消毒处理（shlex.quote、.escape()、验证函数等）→ 尝试跨函数边界追踪。
重要设计选择：追踪使用正则而非 AST。优点是跨语言、无外部依赖；缺点是无法追踪对象属性、列表推导、装饰器。这是刻意的取舍——这个阶段是高召回率的补充，精确度由 Phase 3 的 AI 审查来补偿。
6.3 Phase 3 — AI 上下文审查
角色：分诊医生。用模型推理能力逐个读源码，确认哪些是真漏洞、哪些是误报，并给出修复方案。
为什么不用脚本实现？有三个判断是正则和代码做不到的：
- 源可控性判断：「
process.pid是用户可控的吗？」— 正则只能匹配字符串，模型知道这是操作系统本机进程号，不可控 - 上下文模式识别：「隔壁第 362 行用了
shlex.quote，第 300 行怎么没用？」— 需要对比同一文件的不同代码区域，发现不一致 - 修复代码生成：「这里加
shlex.quote就好，跟 362 行保持一致」— 需要理解项目已有的安全写法并适配到新位置
审查流程（完整协议见references/ai-review-guide.md）：
- 读源码：按文件分组，对每个文件用
Read工具读 sink 周围 ±15 行，一次覆盖该文件的所有发现 - 判来源：变量是从用户输入（请求体、设置 API、环境变量）来的，还是可信源（本地整型、硬编码常量、系统路径）？
- 查清洗：路径上有没有
shlex.quote、re.match白名单、参数化 API、类型校验？ - 归类：
CONFIRMED— 源可控 + 未清洗 + 利用路径直接，附上精确的变量 → sink链路LIKELY— 源看上去可控但链路间接，差人工确认一步FALSE_POSITIVE— 源不可控，引用代码证据说明为什么NEEDS_MANUAL_REVIEW— 模棱两可，说明还需要什么信息才能判断
- 调严重度：LOW 但源确认可控 → 升为HIGH；MEDIUM 确认为误报 → 降为INFO
- 出方案：给
CONFIRMED和LIKELY生成修复代码，优先使用项目里已有的安全写法（比如同文件其他地方已经用了shlex.quote，就照着来） - 写回去：给每条发现加上
ai_verdict、ai_rationale、ai_severity、ai_fix字段
7. 脚本职责一览
| 脚本 | 输入 | 输出 |
|---|---|---|
preflight_yasa.py | .yasa-agent.json | 模式判定 JSON |
install_yasa_release.py | GitHub Release URL | .yasa-tools/目录 |
normalize_rule_config.py | RuleGen 选择 JSON | rule_config.json |
validate_rule_config.py | rule_config.json | 问题列表 |
extract_scan_metrics.py | scan_summary.json | 指标 JSON |
sarif_to_evidence.py | report.sarif | 证据 JSON（含 codeFlow） |
grep_signals.py | 源码树 + 语言 | 命中列表 + 扫描统计 |
taint_trace.py | sink 文件:行号 | TaintResult（源、消毒、跳数） |
post_scan_audit.py | grep 命中 + YASA sink 配置 | audit_findings.json |
write_local_config.py | CLI 参数 | .yasa-agent.json |
8. 置信度评分模型
Phase 2 的每条发现会被打一个 0.0～1.0 的分数，由四个加权因素计算——你可以把它理解为「这个发现有多大可能是真漏洞」的量化评估：
| 因素 | 权重 | 判断方式 | 设计理由 |
|---|---|---|---|
| 源可达性 | 0.40 | taint_trace.py确认用户输入到达 sink 参数 | 最强信号——没有用户输入，就不是漏洞而是代码规范问题 |
| 无消毒 | 0.25 | 追踪路径上缺少shlex.quote、.escape()、validate等 | 消毒过的输入是纵深防御；未消毒离利用只一步之遥 |
| 危险 sink | 0.20（HIGH）/ 0.10（MEDIUM） | 模式严重度分类 | os.system和eval本质上比open()更危险 |
| 直接插值 | 0.15 | f-string、拼接、.format()或直接变量传递 | 直接插值意味着用户数据未经转换直达 sink |
计算公式：
得分 = (源可达 × 0.40) + (无消毒 × 0.25) + (sink危险度 × 权重) + (直接插值 × 0.15)置信度分级：
| 得分范围 | 标签 | 含义 |
|---|---|---|
| 0.70 – 1.00 | HIGH | 源已确认 + 无消毒 + 危险 sink。很可能可利用，优先修复。 |
| 0.40 – 0.69 | MEDIUM | 源追踪不完整但模式可疑。需人工审查。 |
| 0.00 – 0.39 | LOW | 可疑模式但源未确认。信息级——大概率是误报。 |
设计关键：源可达性 0.40 的权重确保了没有确认用户输入来源的发现永远不可能达到 HIGH——审计阶段是高召回的，评分模型提供了精度控制闸门。
9. 扩展指南
9.1 添加新的漏洞模式
编辑scripts/grep_signals.py，在对应漏洞类别下添加新模式：
# 在 PATTERNS_BY_CLASS["python"]["command-injection"] 中添加{"id":"my-new-pattern","regex":r"dangerous_func\s*\(\s*f\"","severity":"HIGH","glob":"*.py","description":"Detects dangerous_func with f-string injection"}9.2 添加新语言支持
- 在
grep_signals.py中添加PATTERNS_BY_CLASS["your-lang"]字典 - 在
sink-catalog.md中添加对应语言的 sink 签名 - 在
references/中创建your-lang-yasa-rules.md - 更新
post_scan_audit.py中的_PATTERN_TO_SINKS映射
9.3 添加新的 sink 类型
- 在
sink-catalog.md中添加 sink 函数签名 - 在
grep_signals.py中添加匹配该 sink 的正则模式 - 在 RuleGen 选择中注册该 sink 类型
9.4 发布新版本
# 语法检查所有脚本python3-mpy_compile yasa-checker/scripts/*.py# 打包zip-ryasa-checker-opencode-$(date+%Y%m%d).zip\.opencode/\yasa-checker/\-x"*.pyc"-x"__pycache__/*"-x".git/*"10. 运行效果
点击了解【开放式统一多语言程序分析产品YASA】