Skip to content

hypnguyen1209/offensive-claude / skills/vulnerability-analysis

vulnerability-analysis

Unverified

Use when auditing source code for vulnerabilities — drive CodeQL/Semgrep/Joern to taint untrusted data source-to-sink across injection, memory safety, deserialization/prototype-pollution, secrets/crypto/authz/race, and supply-chain risks

references/variant-hunting.md

View on GitHub
# Variant Hunting — one finding → all siblings (root-cause clustered)

A single confirmed bug is rarely alone. A SQLi via one helper usually recurs wherever that helper
is called; an unsafe `pickle.loads` is often copy-pasted. CLAUDE.md mandates **VARIANT-COMPLETE**
analysis: when you confirm one instance, mechanically find every sibling and decide whether the fix
is *one central change* or *many*. This is the protocol behind
`skills/vulnerability-analysis/scripts/variant_hunt.py`.

## When to run

Right after a finding-validator **PASS** (or a `[CONFIRMED]` finding). The seed is that finding's
CWE class (or a specific sink regex). Run before writing the report so the remediation section can
say "one fix" or "N sites".

## HUNT protocol

1. **HUNT-1 Seed.** Take the confirmed finding's class (`--seed-finding finding.json` reads its
   `cwe`) or a sink pattern (`--sink-cwe CWE-89`, `--sink-regex '\.execute\('`).
2. **HUNT-2 Sweep.** Enumerate every sink of that class across the tree, per language, reusing the
   `taint_trace` sink model (`py/js/php/java`).
3. **HUNT-3 Qualify.** Classify each site by same-function taint reachability:
   - `tainted` — an untrusted source reaches the sink in one function with **no sanitizer** on the path (strongest lead);
   - `likely` — an untrusted source exists in the file but not provably in the sink's function;
   - `unlikely` — no untrusted source near the sink;
   - `false_positive` — a source reaches the sink but a **sanitizer is on the path**.
   A label is a *lead*, not a proof — each `tainted`/`likely` site still goes through the normal
   evidence bar and finding-validator before it becomes a finding.
4. **HUNT-4 Cluster by root cause** — answer "one fix or many":
   - `copy_paste` — identical sink code in ≥2 files → likely one root cause; fix once, propagate;
   - `framework_misuse` — same dangerous API across ≥3 files → a safe wrapper + lint rule (many fixes);
   - `localized` — a few sites → fix individually and re-sweep.
5. **HUNT-5 Rank & report.** Clusters are ranked by best qualification then site count. **False
   positives are KEPT** in the output with their reason but excluded from the fix recommendation —
   never silently dropped (a future refactor can reintroduce taint, and the reviewer should see why
   a site was set aside).

## Usage

```bash
# Seed from a confirmed finding, write the machine-readable map
python skills/vulnerability-analysis/scripts/variant_hunt.py ./src \
    --seed-finding .engage/exploit/finding-014.json --lang py,js --json variants.json

# Seed by class directly
python skills/vulnerability-analysis/scripts/variant_hunt.py ./src --sink-cwe CWE-89 --lang py
```

`variants.json` carries `{seed, summary, clusters[]}`; each cluster has `kind`, `one_fix_hint`,
`site_count`, `file_count`, `max_quality`, `recommend`, and the per-site list. Feed the
`recommend:true` clusters into the report's remediation priorities; cite the `copy_paste`/
`framework_misuse` kind to justify a central fix.

## Limits (don't over-claim)

- Heuristic + intraprocedural: cross-function/cross-file taint is **not** followed — a `likely` may
  be real and an `unlikely` may still be reachable through a call. Use it to *rank* deep review, and
  promote with CodeQL/Joern + the evidence bar, not on the label alone.
- Clustering keys on the sink API + code text; a refactor that renames the helper splits a cluster.
  Re-run after large changes.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall