# Variant Analysis

> 基于模式分析，在代码库中查找相似的漏洞和缺陷。适用于：搜寻缺陷变体、构建 CodeQL/Semgrep 查询、分析安全漏洞、或在发现初始问题后进行系统性代码审计。

- Skill: `kscz0000/variant-analysis` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/variant-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/variant-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/variant-analysis

---


# 变体分析

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

## 适用场景
以下情况应使用此技能：
- 已发现漏洞，需要搜索类似实例
- 构建或优化用于安全模式的 CodeQL/Semgrep 查询
- 在发现初始问题后进行系统性代码审计
- 在代码库中搜寻缺陷变体
- 分析单一根因如何在不同代码路径中表现

## 不适用场景

以下情况不应使用此技能：
- 初始漏洞发现（改用 audit-context-building 或领域特定审计）
- 没有已知模式可搜索的常规代码审查
- 编写修复建议（改用 issue-writer）
- 理解陌生代码（先用 audit-context-building 进行深度理解）

## 五步流程

### 第一步：理解原始问题

在搜索之前，深入理解已知缺陷：
- **根因是什么？** 不是症状，而是为什么存在漏洞
- **需要哪些条件？** 控制流、数据流、状态
- **什么使其可被利用？** 用户控制、缺少验证等

### 第二步：创建精确匹配

从一个仅匹配已知实例的模式开始：
```bash
rg -n "exact_vulnerable_code_here"
```
验证：是否仅匹配一个位置（原始位置）？

### 第三步：识别抽象点

| 元素 | 保持具体 | 可以抽象 |
|------|----------|----------|
| 函数名 | 如果是缺陷独有 | 如果模式适用于函数族 |
| 变量名 | 永远不要 | 始终使用元变量 |
| 字面值 | 如果值很关键 | 如果任何值都会触发缺陷 |
| 参数 | 如果位置很重要 | 使用 `...` 通配符 |

### 第四步：迭代泛化

**每次只修改一个元素：**
1. 运行模式
2. 审查所有新匹配
3. 分类：真阳性还是假阳性？
4. 如果假阳性率可接受，泛化下一个元素
5. 如果假阳性率过高，回退并尝试不同的抽象

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

### 第五步：分析和分类结果

对每个匹配项记录：
- **位置**：文件、行号、函数
- **置信度**：高/中/低
- **可利用性**：是否可达？输入是否可控？
- **优先级**：基于影响和可利用性

更深入的战略指导请参见 METHODOLOGY.md。

## 工具选择

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

## 核心原则

1. **根因优先**：先理解为什么，再搜索哪里
2. **从具体开始**：第一个模式应精确匹配已知缺陷
3. **每次只改一处**：逐步泛化，每次修改后验证
4. **知道何时停止**：假阳性率超过 50% 说明过于宽泛
5. **全面搜索**：始终搜索整个代码库，而非仅缺陷所在模块
6. **扩展漏洞类别**：一个根因往往有多种表现形式

## 必须避免的关键陷阱

以下常见错误会导致分析师遗漏真实漏洞：

### 1. 搜索范围过窄

仅在发现原始缺陷的模块中搜索，会遗漏其他位置的变体。

**示例：** 在 `api/handlers/` 中发现缺陷 → 仅搜索该目录 → 遗漏 `utils/auth.py` 中的变体

**应对措施：** 始终对整个代码库根目录运行搜索。

### 2. 模式过于具体

仅使用原始缺陷中的确切属性/函数，会遗漏使用相关构造的变体。

**示例：** 缺陷使用 `isAuthenticated` 检查 → 仅搜索该确切术语 → 遗漏使用 `isActive`、`isAdmin`、`isVerified` 等相关属性的缺陷

**应对措施：** 枚举该缺陷类别的所有语义相关属性/函数。

### 3. 单一漏洞类别

仅关注根因的一种表现形式，会遗漏同一逻辑错误出现的其他方式。

**示例：** 原始缺陷是"条件为假时返回允许" → 仅搜索该模式 → 遗漏：
- 空值相等绕过（`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`

## 局限性
- 仅当任务明确符合上述范围时才使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少所需输入、权限、安全边界或成功标准，请停下来请求澄清。