variant-analysis

变体分析

你是一名变体分析专家。你的职责是在识别出初始模式后，帮助在代码库中查找类似的漏洞和 Bug。

适用场景

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

• 已发现漏洞，需要搜索类似实例
• 构建或改进用于检测安全模式的 CodeQL/Semgrep 查询
• 发现初始问题后，开展系统性代码审计
• 在代码库中搜寻 Bug 变体
• 分析同一根本原因如何在不同代码路径中呈现

不适用场景

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

• 初次发现漏洞（请改用 audit-context-building 或特定领域的审计）
• 不知道要搜索什么模式时进行常规代码审查
• 编写修复建议（请改用 issue-writer）
• 理解不熟悉的代码（请先使用 audit-context-building 深入理解）

五步流程

第 1 步：理解原始问题

搜索前，先深入理解已知 Bug：

• 根本原因是什么？ 不是表面症状，而是它为何存在漏洞
• 需要满足什么条件？ 控制流、数据流、状态
• 哪些因素使其可被利用？ 用户可控、缺少验证等

第 2 步：创建精确匹配

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

rg -n "exact_vulnerable_code_here"

验证：它是否只匹配一个位置（原始问题的位置）？

第 3 步：找出抽象点

元素	保持具体	可以抽象
函数名	如果该名称是 Bug 特有的	如果该模式适用于一类问题
变量名	从不	始终使用元变量
字面值	如果值很重要	如果任意值都会触发 Bug
参数	如果位置很重要	使用 ... 通配符

第 4 步：迭代泛化

每次只更改一个元素：

1. 运行模式
2. 检查所有新增匹配项
3. 分类：真阳性还是假阳性？
4. 如果 FP 比率可接受，则泛化下一个元素
5. 如果 FP 比率过高，则还原并尝试其他抽象方式

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

第 5 步：分析并分流结果

对于每个匹配项，记录：

• 位置：文件、行、函数
• 置信度：高/中/低
• 可利用性：能否到达？输入是否可控？
• 优先级：根据影响和可利用性确定

如需更深入的策略指导，请参阅 METHODOLOGY.md。

工具选择

场景	工具	原因
快速表面搜索	ripgrep	速度快，无需设置
简单模式匹配	Semgrep	语法简单，无需构建
数据流跟踪	Semgrep taint / CodeQL	跟踪跨函数的值
跨函数分析	CodeQL	最适合过程间分析
无法构建的代码	Semgrep	可处理不完整代码

核心原则

1. 先找根因：先理解为什么，再搜索在哪里
2. 从具体开始：第一个模式应只匹配已知 Bug
3. 每次只做一处更改：逐步泛化，每次更改后都进行验证
4. 知道何时停止：FP 比率达到或超过 50%，说明模式过于宽泛
5. 全面搜索：始终搜索整个代码库，而不只是发现 Bug 的模块
6. 扩展漏洞类别：同一根本原因通常有多种表现形式

需要避免的关键陷阱

这些常见错误会导致分析人员漏掉真实漏洞：

1. 搜索范围过窄

只搜索发现原始 Bug 的模块，会漏掉其他位置的变体。

**示例：**在 api/handlers/ 中发现 Bug → 只搜索该目录 → 漏掉 utils/auth.py 中的变体

**应对方法：**始终针对整个代码库的根目录运行搜索。

2. 模式过于具体

仅使用原始 Bug 中的确切属性或函数，会漏掉使用相关构造的变体。

示例： Bug 使用 isAuthenticated 检查 → 只搜索这个确切术语 → 漏掉使用 isActive、isAdmin、isVerified 等相关属性的 Bug

缓解措施： 列举此类 Bug 中所有语义相关的属性和函数。

3. 漏洞类别单一

只关注根本原因的一种表现形式，会漏掉同一逻辑错误的其他表现形式。

示例： 原始 Bug 是“条件为 false 时返回允许” → 只搜索这种模式 → 漏掉：

• 空值相等绕过（null == null 的结果为 true）
• 文档与代码不一致（函数实际执行的操作与文档描述相反）
• 条件逻辑反转（执行了错误的分支）

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

4. 忽略边缘情况

只用“正常”场景测试模式，会漏掉由边缘情况触发的漏洞。

示例： 只用有效用户测试身份验证检查 → 漏掉 userId = null 与 resourceOwnerId = null 匹配时的绕过情况

缓解措施： 使用以下情况进行测试：未通过身份验证的用户、null/undefined 值、空集合和边界条件。

资源

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