trailmark-variant-neighborhood

Trailmark 变体邻域

将一个种子问题扩展为从图中派生的变体候选项。此技能生成的是待审查目标，而非已确认的问题。

适用场景

• 某个问题已确认或具有合理性，且可能存在变体
• 易受攻击的模式取决于调用上下文
• 问题涉及共享的接收点、来源、验证器、接口、重写、trait、钩子、处理程序、适配器或关键类型
• 下一步是启动 variant-analysis、semgrep-rule-creator、static-analysis 或人工审查

不适用场景

• 不存在种子问题。请先进行发现或分类。
• 模式纯粹是语法层面的，且一目了然。请直接使用 semgrep-rule-creator。
• 问题是跨多个问题组合利用链。请使用组合工作流。
• 目标是验证修复情况。请使用修复审查工作流。
• 无法将种子绑定到图节点。

应驳斥的合理化说法

合理化说法	错误原因	必须采取的行动
“附近的代码就是变体”	邻近性只是候选理由	将其列为待审查目标并进行排序
“只有名称完全相同才重要”	变体通常共享接收点或前置条件，而非名称	扩展到调用者、被调用者、接口和类型
“每个候选项都是一个问题”	此技能输出的是待审查候选项	避免声称存在漏洞
“完全不可达的候选项可以彻底忽略”	重构后它们可能变得可达	降低优先级或列为待处理
“图候选项可以取代语义模式分析”	图结构能找到位置，但无法确定根因语义	移交给 variant-analysis、Semgrep、CodeQL 或人工审查

工作流

Variant Neighborhood Progress:
- [ ] Step 1: Normalize and bind the seed
- [ ] Step 2: Expand graph neighborhoods
- [ ] Step 3: Rank candidates
- [ ] Step 4: Extract variant pattern guidance
- [ ] Step 5: Emit handoff packet

步骤 1：规范化并绑定种子

接受问题描述、文件/行号、函数名称或 trailmark-finding-triage 的输出。将种子绑定到 Trailmark 节点，并用 通俗语言记录根因。

如果种子没有具体的图绑定，请停止，不要臆造变体。

步骤 2：扩展邻域

使用 references/neighborhood-patterns.md 中的维度：

• 共享调用者
• 共享被调用者和接收点
• 入口路径邻近项
• 接口、重写、trait 和实现的同级项
• 文件或模块集群邻近项
• 污点或权限边界同类项
• 类型和状态引用邻近项

限制扩展范围，避免候选项过多。

步骤 3：为候选项排序

使用 references/ranking.md 排序。优先考虑可从入口到达、受污点影响、邻近边界、影响范围大、共享接收点、属于同一接口以及距离较近的候选项。降低测试、模拟、生成、供应商、不可达和仅限受信任内部代码的候选项的优先级。

步骤 4：提取模式指导

总结应通过语法方式搜索的内容，以及需要语义审查的内容。确定后续工作应交由：

• variant-analysis
• semgrep-rule-creator
• 使用 CodeQL 或生成 SARIF 的工具进行 static-analysis
• 人工审查

步骤 5：生成交接包

使用 references/output-format.md。包括 已排序的候选项、纳入理由、排除项、局限性以及 variant-analysis 交接内容。

停止条件

• 不存在图绑定
• 候选项过多，且根因描述不充分
• Trailmark 无法分析目标语言
• 种子仅存在于测试、生成或供应商代码中，且用户未说明这些代码属于审查范围