agentleFS
scadastrangelovescadastrangelove/rust-in-peace/.agents/skills/variant-scan/SKILL.md

variant-scan

Skill25 starsChanged 4 months agoApache-2.0View on GitHub

Seed-diverse multi-pass find: run the same target through THREE independent find passes — blind, threat-model-first, and CVE/history-seeded — union the candidates with vote-counting, then hit each with a 3-skeptic adversarial verify panel (correctness / reachability / impact). This is the recall engine the real-OSS campaigns were run on; it complements /vuln-scan (single-pass focus-area fan-out) rather than replacing it. Use when asked to "run the three passes", "variant scan", "blind + threat-model + CVE-seeded", "find everything in <crate>", or when a target has known history (CVEs/RUSTSEC) worth seeding from. Read-only. Its dispositions are TRIAGE, not verdicts — every survivor still needs an independent PoC (see the discipline gate below).

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run all three by default and union.

    line 54
  2. Very specific:

    Treat unverified-from-infra-failure as no signal, not tacit refutation — re-run verify or hand-check the highest-severity ones.

    line 124
  3. Very specific:

    Only what survives 1–3 goes downstream to /triage → grade/reattack (execution-verified) → predisclose.

    line 127

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/variant-scan

Three seed-diverse find passes over one target, unioned, then adversarially verified. This is the workhorse that ran every real-OSS campaign (x509-parser, lopdf, zune-jpeg, object, gimli, httparse, quick-xml, miniz_oxide, ciborium, png/image, rmp-serde, ttf-parser, gitoxide). Until now it lived only as a scratchpad workflow script; this skill is its permanent home.

Why three passes and not one. They have different strengths and converge only on the "big" bug — everything else, each finds alone (LESSONS.md L21, L25; the design note is docs/variant-analysis.md):

  • blind — generic "find security bugs", no class hint. Catches whole bug-classes a threat model didn't anticipate.
  • threat-model-first — lenses seeded from THREAT_MODEL.md §3 (entry points, trust boundaries, the declared defect-origin class). Reaches depth and differential surface a blind pass skips.
  • CVE/history-seeded — variant analysis ("bugs travel in packs"): for each historical advisory/CVE/RUSTSEC on this crate or a sibling, extract the pattern (not the specific bug) and hunt the same pattern in code paths the original fix didn't cover. Seed from confirmed and refuted prior findings too — control coverage is non-uniform. This is where net-new siblings of already-patched bugs come from.

Run all three by default and union. Dropping one to "save budget" is the one optimization L25 explicitly warns against.

There is a fourth, separate mode — /sast-driven (tool-first: every static analyser's default rules, clustered into cells and reachability-judged before a finder reads code). It is deliberately not folded into these three passes: injecting its hits here would destroy the measurement of what the blind pass finds on its own. Run it alongside and compare the sets.

Arguments

  • <target-dir> (required) — source tree to scan.
  • --passes blind,tm,cve — which seed sources to run (default: all three).
  • --seed-cves <file> — a list of advisory IDs / patterns to seed the CVE pass (else derive from THREAT_MODEL.md, capabilities.json, and a quick RustSec/GitHub-advisory lookup for the crate + siblings).
  • --focus <area> — restrict all passes to one subsystem (repeatable).

How it runs

Each pass is one invocation of the reference orchestration find_engine.mjs (for the Workflow tool), with that pass's lenses:

  1. Find — N lens-agents in parallel, each emitting FIND_SCHEMA findings (bug_class, file, line, symbol, mechanism, reachability_from_entry, poc_sketch, severity, confidence).
  2. Union-of-N dedup — collapse by bug_class-prefix @ file:symbol, counting votes across lenses.
  3. Verify — per candidate, 3 skeptic lenses (correctness / reachability / impact), each told to refute and to cite a concrete where_checked (file:line of the guard, or of the unguarded path). Disposition: confirmed (≥2 real&&reachable), contested (1), refuted (0 but voted), unverified (no verifier returned — e.g. an infra failure).

Then union the three passes the same way (dedup by the same key across passes; a candidate found by two seed sources is the strongest signal it's real, not a seed artifact).

Without the Workflow tool, run the same shape with plain Task subagents: N finders → dedup in-message → 3 verifiers per candidate → same disposition rule.

The discipline gate — dispositions are TRIAGE, not verdicts

This is the point of the skill, not a footnote. A confirmed from the vote panel means "worth your time", never "it's real". Every campaign that skipped this gate shipped a false positive:

  • gitoxide tar-slip — 3/3 unanimous "confirmed HIGH" (and 2/3 on a second pass). Refuted only by building an independent PoC and running it: the tar crate's own ..-guard and rawzip's path-normalization, plus an index_from_tree gate upstream, all sat on the path the verifiers never traced. (JOURNAL, gitoxide Stage 3.)
  • x509 RSA over-claim — "confirmed" by both a finder and a curator layer; refuted by reading that asn1-rs rejects the input and the sink re-parses (LESSONS.md L1/L8, the two-layer over-claim).
  • gitoxide NTFS git~1 / protect_hfs asymmetries — looked novel; a faithful port of real git's own code once compared against upstream path.c.

So before any survivor is called real:

  1. Read the actual verifier text, not the vote count. find_engine.mjs carries verifier_reasons for exactly this — one skeptic lens is often right and outvoted 2-to-1.
  2. Build an independent PoC (or read the gating call site end-to-end) that exercises the finding through the real entry point on crafted/untrusted input. Construction-via-builder-API is not parse-reachable (L12).
  3. Verify against the actual shipping target — release AND current default branch, plus the maintainer's own tests/docs — before treating it as reportable (L15/L32).
  4. Treat unverified-from-infra-failure as no signal, not tacit refutation — re-run verify or hand-check the highest-severity ones.

Only what survives 1–3 goes downstream to /triage → grade/reattack (execution-verified) → predisclose.

Output

Per pass and for the union: confirmed / contested / refuted / unverified lists, each candidate carrying lenses, votes, real_votes, where_checked, and verifier_reasons. Write VARIANT-FINDINGS.json (+ .md) in the same shape /triage ingests, with a per-candidate disposition and an explicit independently_verified: false until step 2 above is done by hand.

Relationship to the rest of the pipeline

/variant-scan is the recall front-end (static, read-only, multi-pass). It feeds /triage; execution-verification still happens in vuln-pipeline (grade, the find→fuzz reattack bridge, run_crash_track). It does not replace /vuln-scan — use /vuln-scan for a quick single-pass focus-area review, /variant-scan when you want maximum recall and the target has history worth seeding from.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.