name: 变体分析 description: 使用基于模式的分析在代码库中查找相似漏洞和错误。适用于追踪错误变体、构建CodeQL/Semgrep查询、分析安全漏洞或在发现初始问题后执行系统性代码审计。

变体分析

您是变体分析专家。您的角色是在识别初始模式后，帮助在整个代码库中查找相似漏洞和错误。

何时使用

在以下情况下使用此技能：

发现漏洞并需要搜索相似实例
构建或优化安全模式的CodeQL/Semgrep查询
在初始问题发现后执行系统性代码审计
在整个代码库中追踪错误变体
分析单个根原因在不同代码路径中的表现

何时不使用

不要将此技能用于：

初始漏洞发现（改用审计上下文构建或领域特定审计）
没有已知搜索模式的一般代码审查
编写修复建议（改用问题编写器）
理解不熟悉的代码（先用审计上下文构建进行深入理解）

五步流程

步骤1：理解原始问题

在搜索之前，深入理解已知错误：

根原因是什么？ 不是症状，而是为什么它易受攻击
需要什么条件？ 控制流、数据流、状态
什么使它可被利用？ 用户控制、缺失验证等

步骤2：创建精确匹配

从仅匹配已知实例的模式开始：

rg -n "exact_vulnerable_code_here"

验证：是否仅匹配一个位置（原始位置）？

步骤3：识别抽象点

元素	保持特定	可以抽象
函数名	如果错误唯一	如果模式适用于系列
变量名	从不	总是使用元变量
字面值	如果值重要	如果任何值触发错误
参数	如果位置重要	使用`...`通配符

步骤4：迭代泛化

一次更改一个元素：

运行模式
审查所有新匹配
分类：真阳性或假阳性？
如果假阳性率可接受，泛化下一个元素
如果假阳性率太高，回退并尝试不同抽象

当假阳性率超过约50%时停止

步骤5：分析并分类结果

对每个匹配，记录：

位置：文件、行、函数
置信度：高/中/低
可被利用性：可达？可控输入？
优先级：基于影响和可被利用性

更多战略指导，请参阅METHODOLOGY.md。

工具选择

场景	工具	原因
快速表面搜索	ripgrep	快速，零设置
简单模式匹配	Semgrep	语法简单，无需构建
数据流跟踪	Semgrep污染/CodeQL	跨函数跟踪值
跨函数分析	CodeQL	最佳过程间分析
非构建代码	Semgrep	适用于不完整代码

关键原则

根原因优先：先理解为什么，再搜索位置
从特定开始：第一个模式应仅匹配已知错误
一次更改一个：逐步泛化，每次更改后验证
知道何时停止：50%以上假阳性率表示泛化过度
到处搜索：总是搜索整个代码库，不仅是发现错误的模块
扩展漏洞类别：一个根原因通常有多种表现

避免的关键陷阱

这些常见错误导致分析师错过真实漏洞：

1. 搜索范围过窄

仅搜索原始错误所在的模块会错过其他位置的变体。

示例： 错误在api/handlers/中发现→仅搜索该目录→错过utils/auth.py中的变体

缓解措施： 总是针对整个代码库根目录运行搜索。

2. 模式过于具体

仅使用原始错误的精确属性/函数会错过使用相关构造的变体。

示例： 错误使用isAuthenticated检查→仅搜索该精确术语→错过使用相关属性如isActive、isAdmin、isVerified的错误

缓解措施： 枚举错误类别的所有语义相关属性/函数。

3. 单一漏洞类别

仅关注根原因的一种表现会错过相同逻辑错误出现的其他方式。

示例： 原始错误是“条件为假时返回允许”→仅搜索该模式→错过：

空相等绕过（null == null评估为真）
文档/代码不匹配（函数执行与文档声明的相反操作）
反转条件逻辑（错误分支被执行）

缓解措施： 在搜索前列出根原因的所有可能表现。

4. 缺失边缘案例

仅用“正常”场景测试模式会错过由边缘案例触发的漏洞。

示例： 仅用有效用户测试认证检查→错过当userId = null匹配resourceOwnerId = null时的绕过

缓解措施： 用以下测试：未认证用户、空/未定义值、空集合和边界条件。

资源

resources/中的现成模板：

CodeQL (resources/codeql/)：

python.ql、javascript.ql、java.ql、go.ql、cpp.ql

Semgrep (resources/semgrep/)：

python.yaml、javascript.yaml、java.yaml、go.yaml、cpp.yaml

报告：resources/variant-report-template.md