AutoGineer
Generated banner for Variant Analysis
Generated logo for Variant Analysis

Variant Analysis

Trail of BitsOfficialPublished by Trail of Bits

  • Skill
  • Workflow
  • Security
  • CC-BY-SA-4.0
  • No issues found
Download ZIP

From the author

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.
— the description by Trail of Bits

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Variant Analysis is a structured process for hunting down recurring bugs. Once a root cause is identified, this skill guides you through defining the vulnerability, creating an exact match pattern, and iteratively generalizing that pattern to discover similar manifestations elsewhere in the codebase. It emphasizes a methodical approach—moving from specific instances to broader pattern families—while providing a framework for triaging findings and documenting the search process to ensure reproducibility and prevent future regressions.

What it does

  • Extracts the root cause of a known vulnerability to define search parameters.
  • Guides the creation of exact-match patterns to confirm the initial bug.
  • Facilitates iterative generalization of patterns to find related bug variants.
  • Provides a triage framework to validate findings and assess severity.
  • Supports the creation of regression tests and CI rules based on discovered variants.
  • Offers a parallelized workflow for large codebases to maximize search efficiency.

When to use it

  • Immediately after discovering a vulnerability, logic bug, or bad pattern.
  • When you need to determine if a bug exists in other parts of the codebase.
  • When refining security queries for tools like CodeQL or Semgrep.
  • During systematic code audits following an initial issue discovery.

Advantages

  • Reduces the likelihood of leaving similar vulnerabilities unfixed.
  • Provides a reproducible methodology for security audits.
  • Helps identify the full scope of a root cause beyond the initial finding.
  • Prevents regression by generating CI-ready rules from successful patterns.

Usage examples

“I found a SQL injection in user_controller.py. Are there others like this?”
The agent will initiate the variant analysis workflow, starting by extracting the root cause and searching for similar patterns across the codebase.
“Is this the same bug? I found a similar pattern in the auth module.”
The agent will compare the new finding against the known root cause and guide you through triaging the candidate.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/trailofbits/variant-analysis/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip variant-analysis.zip -d .agents/skills

Documentation by Trail of Bits

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

  1. Narrow scope — searching only the module the original bug was in

  2. Pattern too specific — searching one attribute and missing the family around it

  3. One vulnerability class — chasing a single manifestation of the root cause

  4. Happy-path testing — never trying the null, empty, and boundary cases

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

Files

resources/codeql/java.ql

/**
 * @name [VARIANT_NAME]
 * @description Find variants of [ORIGINAL_BUG_ID]
 * @kind path-problem
 * @problem.severity error
 * @tags security variant-analysis
 */

import java
import semmle.code.java.dataflow.TaintTracking
import semmle.code.java.dataflow.FlowSources
import DataFlow::PathGraph

module VariantConfig implements DataFlow::ConfigSig {
  predicate isSource(DataFlow::Node source) {
    // HttpServletRequest.getParameter/getHeader
    exists(MethodAccess ma |
      ma.getMethod().getName() in ["getParameter", "getHeader", "getCookies", "getQueryString"] and
      ma.getMethod().getDeclaringType().getASupertype*().hasQualifiedName("javax.servlet", "ServletRequest") and
      source.asExpr() = ma
    )
    or
    // Spring @RequestParam, @PathVariable
    exists(Parameter p |
      p.getAnAnnotation().getType().hasQualifiedName("org.springframework.web.bind.annotation", ["RequestParam", "PathVariable", "RequestBody"]) and
      source.asParameter() = p
    )
  }

  predicate isSink(DataFlow::Node sink) {
    // Command injection
    exists(MethodAccess ma |
      ma.getMethod().hasQualifiedName("java.lang", "Runtime", "exec") and
      sink.asExpr() = ma.getArgument(0)
    )
    or
    exists(ClassInstanceExpr cie |
      cie.getConstructedType().hasQualifiedName("java.lang", "ProcessBuilder") and
      sink.asExpr() = cie.getArgument(0)
    )
    or
    // SQL injection
    exists(MethodAccess ma |
      ma.getMethod().getName() in ["executeQuery", "executeUpdate", "execute"] and
      ma.getMethod().getDeclaringType().getASupertype*().hasQualifiedName("java.sql", "Statement") and
      sink.asExpr() = ma.getArgument(0)
    )
    or
    // Path traversal
    exists(ClassInstanceExpr cie |
      cie.getConstructedType().hasQualifiedName("java.io", "File") and
      sink.asExpr() = cie.getArgument(0)
    )
  }

  predicate isBarrier(DataFlow::Node node) {
    exists(MethodAccess ma |
      ma.getMethod().getName() in ["escape", "sanitize", "parseInt", "valueOf"] and
      node.asExpr() = ma
    )
  }
}

module VariantFlow = TaintTracking::Global<VariantConfig>;
import VariantFlow::PathGraph

from VariantFlow::PathNode source, VariantFlow::PathNode sink
where VariantFlow::flowPath(source, sink)
select sink.getNode(), source, sink,
  "Tainted data from $@ flows to dangerous sink.",
  source.getNode(), "user input"

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Trail of Bits
Publisher
Trail of Bits (Official)
Source
trailofbits/skills · plugins/variant-analysis/skills/variant-analysis · commit e4dd0bb
Licence
Creative Commons Attribution-ShareAlike 4.0 International (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Trail of Bits or Trail of Bits.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download variant-analysis.zip