variant-analysis

پس از کشف یک باگ، نمونه‌های مشابه آن را در کل codebase پیدا و اعتبارسنجی کنید.

این مهارت پس از شناسایی یک vulnerability، باگ منطقی یا الگوی نادرست، علت ریشه‌ای آن را استخراج می‌کند و برای یافتن نمونه‌های مشابه در مسیرهای دیگر codebase جست‌وجو انجام می‌دهد. جست‌وجو از تطبیق دقیق شروع می‌شود و سپس مرحله‌به‌مرحله به الگوی عمومی‌تر تبدیل می‌شود.

با استفاده از variant analysis می‌توانید candidateها را از false positiveها جدا کنید، شدت موارد واقعی را بسنجید و برای CodeQL یا Semgrep الگوی قابل‌استفاده بسازید. نتیجه شامل موارد مشابه، الگوهای ناموفق و پیشنهاد یک قانون CI برای جلوگیری از بازگشت باگ است.

چه چیزی می‌گیرید

  • استخراج root cause به‌جای تمرکز صرف بر شکل ظاهری باگ
  • جست‌وجوی مرحله‌ای برای پیدا کردن variantهای مشابه در کل codebase
  • تحلیل و triage کردن candidateها همراه با severity
  • الگوهای CodeQL یا Semgrep برای شناسایی خودکار خانوادهٔ باگ
  • پیشنهاد قانون CI برای جلوگیری از regression

برای چه کاری خوب است

  • تیم‌های امنیتی که یک vulnerability را پیدا کرده‌اند و می‌خواهند نمونه‌های دیگر آن را بررسی کنند
  • ممیزی codebaseهای بزرگ با چندین manifestation از یک root cause
  • ساخت یا اصلاح queryهای CodeQL و Semgrep بر اساس یک نمونهٔ واقعی
  • بررسی مجموعه‌ای از candidateهای مشابه و تفکیک موارد واقعی از false positive

برای چه کاری نیست

  • کشف اولیهٔ آسیب‌پذیری وقتی هنوز نمونه یا pattern مشخصی در دست ندارید
  • code review عمومی بدون یک باگ یا root cause شناخته‌شده
  • نوشتن fix recommendation یا آشنایی اولیه با ساختار codebase

دربارهٔ این اسکیل

plugins/variant-analysis/skills/variant-analysis/SKILL.md

plugins/variant-analysis/skills/variant-analysis/SKILL.md

  • Branch: main
  • Repository: trailofbits/skills

name: variant-analysis
description: Hunts for the other instances of a bug already found — the variants of one root cause across a codebase. Use immediately after a vulnerability, logic bug, or bad pattern turns up in a specific file and the question becomes where else it occurs, including the bare conversational form ("are there others like this?", "is this the same bug?"). Also for generalizing one known instance into a CodeQL or Semgrep query for its whole pattern family, and for triaging a set of look-alike candidates against a known root cause. Not for initial discovery with no bug in hand.
---

Variant Analysis

Find the other instances of a bug you have already found. One root cause usually has several
manifestations, and they are rarely in the module where you found the first one.

When to Use

  • A vulnerability has been found and you need to search for similar instances
  • Building or refining CodeQL/Semgrep queries for security patterns
  • Performing systematic code audits after an initial issue discovery
  • Analyzing how a single root cause manifests in different code paths

When NOT to Use

  • Initial vulnerability discovery — use audit-context-building or a domain-specific audit
  • General code review with no known pattern to search for
  • Writing fix recommendations — use issue-writer
  • Understanding unfamiliar code — use audit-context-building first

The Five Steps

Read the reference for a step when you reach it.

1. Understand the original issue. Extract the root cause — why the code is wrong, not
what it does — and enumerate the directions a variant could hide in: related identifiers,
other manifestations of the same mistake, data-type edge cases.
→ references/root-cause.md

2. Create an exact match. Write a pattern matching ONLY the known instance and confirm
it hits. A pattern that matches nothing means you have misunderstood the bug, and every
search built on it is calibrated against the wrong code.

3–4. Generalize one element at a time. Climb from the exact match toward the pattern
family, running and reading all matches after each single change. Stop when more than half
the matches are noise.
→ references/searching.md — abstraction ladder, tool selection,
false-positive filters

5. Triage. Decide which candidates are real, and say so with a severity attached.
→ references/triage.md

Then write it up, including the patterns that failed and a CI rule to prevent regression.
→ references/reporting.md

Running it as a Workflow

This plugin ships /variant-analysis:variants, which runs the five steps across parallel
subagents — one per expansion axis, looping until the sweep stops finding anything new.
Each stage reads the reference above that matches its job.

Use the workflow when the codebase is large or the root cause has many manifestations. Work
the steps directly when the sear

دانلود ZIP