Back to Details

trailmark-variant-neighborhood

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Trailmark Variant Neighborhood

Trailmark Variant Neighborhood

Expand one seed issue into graph-derived variant candidates. This skill generates review targets, not confirmed findings.
将一个种子漏洞扩展为基于图生成的变体候选对象。本工具生成的是评审目标，而非已确认的漏洞结果。

When to Use

使用场景

  • A finding is confirmed or plausible and variants may exist
  • The vulnerable pattern depends on call context
  • The issue involves a shared sink, source, validator, interface, override, trait, hook, handler, adapter, or critical type
  • The next step is to seed 
    variant-analysis
    , 
    semgrep-rule-creator
    , 
    static-analysis
    , or manual review
  • 已确认或疑似存在漏洞，且可能存在变体
  • 漏洞模式依赖调用上下文
  • 问题涉及共享sink、源、验证器、接口、重写、 trait、钩子、处理器、适配器或关键类型
  • 下一步需要为
    variant-analysis
    、
    semgrep-rule-creator
    、
    static-analysis
    或人工评审提供分析起点

When NOT to Use

不适用场景

  • No seed issue exists. Use discovery or triage first.
  • The pattern is purely syntactic and already obvious. Use 
    semgrep-rule-creator
    directly.
  • The question is exploit-chain composition across multiple findings. Use a composition workflow.
  • The goal is remediation verification. Use a remediation-review workflow.
  • The seed cannot be bound to a graph node.
  • 无种子漏洞。应先使用发现或分类流程。
  • 漏洞模式纯语法层面且已明确。可直接使用
    semgrep-rule-creator
    。
  • 问题涉及跨多个漏洞的利用链组合。应使用组合工作流。
  • 目标是验证修复效果。应使用修复评审工作流。
  • 种子漏洞无法绑定到图节点。

Rationalizations to Reject

常见错误认知及纠正

RationalizationWhy It Is WrongRequired Action
"Nearby code means variant"Proximity is only a candidate reasonRank it as a review target
"Only exact same names matter"Variants often share sinks or preconditions, not namesExpand across callers, callees, interfaces, and types
"Every candidate is a finding"This skill outputs candidates for reviewAvoid vulnerability claims
"Unreachable candidates can be ignored completely"They may become reachable after refactorsRank lower or list as deferred
"Graph candidates replace semantic pattern work"Graph structure finds locations, not root-cause semanticsHand off to variant-analysis, Semgrep, CodeQL, or manual review
错误认知错误原因要求操作
"邻近代码即为变体"代码邻近性仅作为候选参考因素之一将其列为评审目标并进行排序
"只有完全相同的名称才重要"变体通常共享sink或前置条件，而非名称扩展至调用方、被调用方、接口及类型范围
"每个候选都是漏洞"本工具仅输出供评审的候选对象避免直接断言存在漏洞
"不可达候选可完全忽略"重构后这类候选可能变为可达降低优先级或列为待处理项
"图候选可替代语义模式分析"图结构仅用于定位，无法分析根本原因语义移交至variant-analysis、Semgrep、CodeQL或人工评审

Workflow

工作流程

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
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

Step 1: Normalize And Bind The Seed

步骤1：标准化并绑定种子漏洞

Accept finding text, file/line, function name, or output from 
trailmark-finding-triage
. Bind the seed to a Trailmark node and record the root cause in plain language.
If the seed has no concrete graph binding, stop before inventing variants.
接收漏洞描述文本、文件/行号、函数名称或
trailmark-finding-triage
的输出结果。将种子漏洞绑定到Trailmark节点，并以自然语言记录根本原因。
如果种子漏洞无法绑定到具体的图节点，则停止生成变体候选。

Step 2: Expand Neighborhoods

步骤2：扩展邻域范围

Use the dimensions in references/neighborhood-patterns.md:
  • shared callers
  • shared callees and sinks
  • entrypoint path neighbors
  • interface, override, trait, and implementation siblings
  • file or module cluster neighbors
  • taint or privilege-boundary peers
  • type and state-reference neighbors
Bound expansion to avoid candidate floods.
参考references/neighborhood-patterns.md中的维度：
  • 共享调用方
  • 共享被调用方与sink
  • 入口路径邻节点
  • 接口、重写、trait及实现的同类节点
  • 文件或模块集群邻节点
  • 污点或权限边界对等节点
  • 类型与状态引用邻节点
限制扩展范围以避免生成过多候选对象。

Step 3: Rank Candidates

步骤3：候选对象排序

Rank with references/ranking.md. Prioritize entrypoint-reachable, tainted, boundary-adjacent, high-blast-radius, shared sink, same-interface, and close-distance candidates. Penalize test, mock, generated, vendor, unreachable, and trusted-internal-only candidates.
参考references/ranking.md进行排序。优先处理入口可达、存在污点、靠近边界、影响范围大、共享sink、同接口、距离近的候选对象。降低测试代码、模拟代码、生成代码、第三方代码、不可达代码及仅内部可信代码的优先级。

Step 4: Extract Pattern Guidance

步骤4：提取模式指导

Summarize what should be searched for syntactically and what requires semantic review. Identify whether follow-up belongs in:
  • variant-analysis
  • semgrep-rule-creator
  • static-analysis
    with CodeQL or SARIF-producing tools
  • manual review
总结需要进行语法搜索的内容以及需要语义评审的内容。确定后续工作应移交至：
  • variant-analysis
  • semgrep-rule-creator
  • 使用CodeQL或生成SARIF的工具进行
    static-analysis
  • 人工评审

Step 5: Emit Handoff Packet

步骤5：输出移交包

Use references/output-format.md. Include ranked candidates, inclusion reasons, exclusions, limitations, and the variant-analysis handoff.
参考references/output-format.md。包含已排序的候选对象、入选理由、排除项、局限性及变体分析移交信息。

Stop Conditions

停止条件

  • No graph binding exists
  • Candidate count is too high and the root cause is underspecified
  • Trailmark cannot analyze the target language
  • The seed is only in test, generated, or vendor code and the user did not say that code is in scope
  • 无法绑定到图节点
  • 候选对象数量过多且根本原因未明确
  • Trailmark无法分析目标语言
  • 种子漏洞仅存在于测试代码、生成代码或第三方代码中，且用户未将此类代码纳入分析范围