Variant Analysis

​

Installation

/plugin install trailofbits/skills/plugins/variant-analysis

​

Overview

• Five-step systematic process from understanding to reporting
• Tool selection guidance (ripgrep, Semgrep, CodeQL)
• Critical pitfall catalog to avoid missing variants
• Ready-to-use templates for CodeQL and Semgrep in multiple languages
• Detailed methodology for abstraction and generalization

​

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
• Hunting for bug variants across a codebase
• Analyzing how a single root cause manifests in different code paths

​

When NOT to Use

• Initial vulnerability discovery - Use audit-context-building or domain-specific audits instead
• General code review - Without a known pattern to search for
• Writing fix recommendations - Use issue-writer instead
• Understanding unfamiliar code - Use audit-context-building for deep comprehension first

​

The Five-Step Process

rg -n "exact_vulnerable_code_here"

​

Tool Selection

​

The Abstraction Ladder

# Original vulnerable code
query = "SELECT * FROM users WHERE id=" + request.args.get('id')

# Level 0 pattern
rg 'SELECT \* FROM users WHERE id=" \+ request\.args\.get'

# Level 1 pattern
pattern: $QUERY = "SELECT * FROM users WHERE id=" + $INPUT

# Level 2 pattern
patterns:
  - pattern: $Q = "..." + $INPUT
  - pattern-inside: |
      def $FUNC(...):
        ...
        cursor.execute($Q)

# Level 3 pattern (taint mode)
mode: taint
pattern-sources:
  - pattern: request.args.get(...)
  - pattern: request.form.get(...)
pattern-sinks:
  - pattern: cursor.execute(...)

​

Choosing Your Level

​

Critical Pitfalls to Avoid

​

1. Narrow Search Scope

​

2. Pattern Too Specific

​

3. Single Vulnerability Class

• Null equality bypasses (null == null evaluates to true)
• Documentation/code mismatches (function does opposite of docs)
• Inverted conditional logic (wrong branch taken)

​

4. Missing Edge Cases

​

Expanding Vulnerability Classes

def check_restricted_permission(user, perm):
    """Returns True if access should be DENIED."""
    if user.has_perm(perm):
        return True  # BUG: This GRANTS access
    return False

# If both are None, None == None is True
if order.owner_id == current_user.id:
    return True  # Allows access!

​

Ready-to-Use Templates

import python

from CallExpr call, Expr arg
where
  call.getFunc().getName() = "dangerous_func" and
  arg = call.getArg(0) and
  exists(DataFlow::Node source |
    source.asExpr() = arg and
    source.getALocalSource() instanceof UntrustedInput
  )
select call, "Untrusted input to dangerous function"

rules:
  - id: variant-search
    mode: taint
    pattern-sources:
      - pattern: request.args.get(...)
    pattern-sinks:
      - pattern: dangerous_func(...)
    message: Variant of CVE-XXXX
    severity: ERROR
    languages: [python]

​

Commands

/variants

1. The original bug/vulnerability that was found
2. The codebase to search

​

Variant Report Template

## Variant Analysis: [Original Bug ID]

### Root Cause
[Statement of the vulnerability pattern]

### Patterns Tried
| Pattern | Level | Matches | True Pos | False Pos | Notes |
|---------|-------|---------|----------|-----------|-------|
| exact   | 0     | 1       | 1        | 0         | Baseline |

### Confirmed Variants
| Location | Severity | Status | Notes |
|----------|----------|--------|-------|
| file:line| High     | Fixed  | ...   |

### False Positive Patterns
- Pattern X: Always FP because [reason]

​

Key Principles

​

Related Skills

​

Example Workflow

# Found in api/auth.py:42
if user.isAuthenticated == request.token:
    return allow_access()

rg "user.isAuthenticated == request.token"
# Result: 1 match (the original)

pattern: $USER.isAuthenticated == $INPUT
# Result: 3 matches (2 new variants found)

patterns:
  - pattern-either:
      - pattern: $USER.isAuthenticated == $INPUT
      - pattern: $USER.isActive == $INPUT
      - pattern: $USER.isVerified == $INPUT
# Result: 7 matches (4 more variants found)

​

The Expert Mindset

1. Understand before searching - Root cause analysis is non-negotiable
2. Start specific - First pattern should match exactly one thing
3. Climb the ladder - Generalize one step at a time
4. Measure as you go - Track matches and FP rates at each step
5. Know when to stop - High FP rate means you’ve gone too far
6. Iterate ruthlessly - Refine patterns based on what you learn
7. Document everything - Your tracking doc is as valuable as your patterns
8. Expand vulnerability classes - One root cause has many manifestations
9. Check semantics - Verify code matches documentation intent
10. Test edge cases - Null values and boundary conditions reveal hidden bugs