variant-analysis
- Use it when:
- You've found one bug and want to know where else its root cause shows up, including "are there others like this?".
- It does:
- States the root cause, writes a pattern matching only the known bug, then generalizes one element at a time until over half the matches are noise.
- You get:
- A report of confirmed variants by severity, every pattern tried with its match and false-positive counts, and a CI rule against regressions.
- Works with:
- ripgrep for recon, Semgrep for iteration and CodeQL for precision, with starter queries for Python, JavaScript, Java, Go and C++.
- Not for:
- Finding a first bug with nothing in hand; it points to audit-context-building for that.
The parallel /variant-analysis:variants workflow comes with its Claude Code plugin; installed alone, the skill's five steps are worked by hand.
TL;DR
From Trail of Bits. One root cause usually shows up in several places, and rarely in the module where the first instance was found. The skill works in five steps. It first pins down why the code is wrong, not what it does, and lists where variants could hide: related identifiers, other forms of the same mistake, data-type edge cases. It then writes an exact pattern that must hit the known bug, since a pattern that misses it means the bug was misunderstood. Generalizing changes one element at a time, from variable names to surrounding structure to the security property itself, rereading every match after each change. Triage argues against each candidate, looking for guards, sanitizers and type constraints, and checks whether it is reachable, attacker-controlled and unprotected; code nothing calls yet is still reported, at lower severity. Null-equality bypasses and code that contradicts its own docs get checked on purpose. The report fills a bundled template and keeps the patterns that failed. Its plugin also ships /variant-analysis:variants, which runs the steps across parallel subagents, one per direction of search, until a sweep finds nothing new.
Summarizes the skill at e4dd0bb.
npx skills add https://github.com/trailofbits/skills --skill variant-analysis skills.sh pageSource on GitHubAll skills from trailofbits/skills
- Total Downloads
- 7,000 on skills.sh, Nov 9, 2026
- Repo stars
- 8,081 trailofbits/skills
- First seen
- Jan 19, 2026 on skills.sh
Weekly values
| Week to | Installs |
|---|---|
| Sep 21 | 152 |
| Sep 28 | 160 |
| Oct 5 | 166 |
| Oct 12 | 183 |
| Oct 19 | 227 |
| Oct 26 | 265 |
| Nov 2 | 282 |
| Nov 9 | 280 |
| Category |
Compliance, guardrails, skill vetting and browser fingerprinting. Find root causes, review code and test what you built. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills. |
|---|---|
| Type |
A multi-step process the agent follows: interview, debug, run a TDD loop, review. |
| Effect |
Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code. |
| Needs |
A specific command-line tool or desktop app must be installed, such as gh, agent-browser, LibreOffice, Obsidian or a vendor CLI. |
| Publisher |
A verified publisher on skills.sh, or the company or maintainer behind the product the skill operates. |
| Topics | |
| Stack |
SKILL.md
From trailofbits/skills at e4dd0bb. Checked daily, last changed Nov 6, 2026.
Frontmatter
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 search is narrow or you want a say in each generalization.
What Makes Hunts Fail
- Narrow scope — searching only the module the original bug was in
- Pattern too specific — searching one attribute and missing the family around it
- One vulnerability class — chasing a single manifestation of the root cause
- Happy-path testing — never trying the null, empty, and boundary cases
- Generalizing too fast — abstracting several elements at once, so noise cannot be attributed to any one of them
The first three are covered in root-cause.md and searching.md, the fourth in triage.md.
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
Report: resources/variant-report-template.md