domains / security / variant-analysis / variant-analysis

variant-analysis

Skill card

combined

The trailofbits copy is the canonical, self-contained procedure: it defines the five steps, the stop condition, the failure modes, and points to bundled reference files and query resources. The sickn33 copy is a catalog mirror that reproduces the same five-step structure but adds material the trailofbits copy lacks: an explicit authorization/confirmation gate, a tool-selection table, a concrete abstraction-points table, and a note that the supporting resources are external prerequisites. Because the sickn33 copy contains real steps and constraints (authorization gate, tool selection, abstraction table) that the trailofbits copy does not, crowning one would hide a real alternative. The copies also disagree on whether the supporting resources are bundled (trailofbits) or external prerequisites (sickn33).

Repositories

Other copies

Combined skill

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

## Authorization Gate

Before running any command that probes, exploits, changes, persists on, extracts data from, or attempts credential access against a target:
1. Ask the user to state the exact target URL, IP, account, or resource.
2. Ask the user to confirm written authorization and the permitted scope.
3. Show the exact command(s) and explain their expected effect.
4. Wait for explicit confirmation in the current conversation.

Without that confirmation, remain read-only and provide defensive guidance only. Prefer a sandbox, disposable VM, or controlled lab.

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

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

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

Use this abstraction table to decide what to keep specific and what to abstract:

| Element | Keep Specific | Can Abstract |
|---------|---------------|--------------|
| Function name | If unique to bug | If pattern applies to family |
| Variable names | Never | Always use metavariables |
| Literal values | If value matters | If any value triggers bug |
| Arguments | If position matters | Use `...` wildcards |

**5. Triage.** Decide which candidates are real, and say so with a severity attached. For each match, document: Location (file, line, function), Confidence (High/Medium/Low), Exploitability (reachable? controllable inputs?), and Priority (based on impact and exploitability).

**Then write it up**, including the patterns that failed and a CI rule to prevent regression.

## Tool Selection

| Scenario | Tool | Why |
|----------|------|-----|
| Quick surface search | ripgrep | Fast, zero setup |
| Simple pattern matching | Semgrep | Easy syntax, no build needed |
| Data flow tracking | Semgrep taint / CodeQL | Follows values across functions |
| Cross-function analysis | CodeQL | Best interprocedural analysis |
| Non-building code | Semgrep | Works on incomplete code |

## Key Principles

1. Root cause first: Understand WHY before searching for WHERE
2. Start specific: First pattern should match exactly the known bug
3. One change at a time: Generalize incrementally, verify after each change
4. Know when to stop: 50%+ FP rate means you've gone too generic
5. Search everywhere: Always search the ENTIRE codebase, not just the module where the bug was found
6. Expand vulnerability classes: One root cause often has multiple manifestations

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

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

Note: If these resources are not bundled in your installation, ask for the original supporting material or an existing installation before using a step that depends on these paths. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user's authorized scope; report any dependent step as unavailable.