# Bughunt

> >

- **Type:** Skill
- **Install:** `agentstack add skill-robzilla1738-roberts-skills-bughunt`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [robzilla1738](https://agentstack.voostack.com/s/robzilla1738)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [robzilla1738](https://github.com/robzilla1738)
- **Source:** https://github.com/robzilla1738/roberts-skills/tree/main/plugins/bughunt-suite/skills/bughunt
- **Website:** https://robertcourson.com

## Install

```sh
agentstack add skill-robzilla1738-roberts-skills-bughunt
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Bughunt

An **offensive, hotspot-driven bug-hunting workflow**. Where the **autoreview** skill (`/review`)
is a defensive gate on *your own diff*, bughunt assumes the code is **guilty** and goes looking
for hidden defects in the riskiest parts of the target with explicit coverage reporting.

Read this hub first, run **recon**, then open only the spokes your hunt plan selects.

## Mission

Find the bugs that tests, linters, and a tired reviewer miss — and make each claim carry
evidence. The output is a ranked, evidence-backed report, not a vibe. Default behavior is
**report-only**:
hunt, document, hand fixing to a human or the **autoreview** skill (`/review`). Never edit
product code unless the user asks.

## What makes this powerful (not just a checklist)

1. **A deterministic spine** — a bundled zero-dependency toolkit (`bughunt.py`) ranks hotspots
   by churn × complexity × boundary × test-gap, surfaces pain signals (aged TODOs, config
   drift, risky deps), and owns structured findings: fingerprint, dedupe, suppress,
   baseline-diff, and render to markdown/HTML/SARIF with CI exit codes. See
   [tooling.md](tooling.md). Degrades to a pure-markdown pipeline when `python3` is absent.
2. **Breadth via fan-out** — split the target into a grid of **(lens × hotspot)** cells and
   run them as independent parallel hunters, so every risky area is examined through every
   relevant lens. A capability ladder runs the same phases on whatever fan-out machinery the
   tool has — the Workflow tool, an **external coding-CLI fan-out** (Composer 2.5 / Grok via
   `cursor-agent`, the fast variant), parallel Tasks, or a sequential walk. See
   [orchestration.md](orchestration.md).
3. **Depth via specialized lenses + platform catalogs** — 13 lenses, each a distinct
   adversarial discipline (bugs, perf, DX, UX, supply-chain, data safety); each platform
   catalog encodes that ecosystem's specific footguns.
4. **Signal via mandatory verify + triage** — a skeptic pass tries to **refute every finding
   before it's reported** ([verification.md](verification.md)); survivors are confidence-rated,
   cross-validated, and reproduced by [triage](../triage/SKILL.md).

## First principle: signal over noise

A short list of **real, reproducible** bugs beats a long list of maybes. Every reported
finding names its **evidence** (`file:line` + trace + trigger + impact) and its
**confidence**. Speculative items are quarantined in their own section — never mixed in.
Before reporting anything, try to kill it (see the false-positive filter in
[triage](../triage/SKILL.md)). If it survives, report it.

## Operating principles

- **Assume guilt.** The code is wrong until you've checked. Read it for what it *does*, not
  what it's supposed to do.
- **Evidence-first.** No `file:line` + trace + trigger + impact → it's a question, not a finding.
- **Do not overstate proof.** Static skeptic-upheld findings are Probable unless reproduced
  or traced beyond plausible refutation. Runtime/property-test proof is what earns Confirmed.
- **Report, don't edit.** This skill is read-only by default. Surface and prove bugs; hand
  fixing to a human or the **autoreview** skill (`/review`). Only edit code if the user asks.
- **Scope before you scale.** On a large/unfamiliar repo, do recon and confirm scope/budget
  with the user before launching a deep hunt (see [recon-and-scoping.md](recon-and-scoping.md)).
- **Be honest about coverage.** Always state what you examined and what you did not.
- **Enforce verification and coverage in CI.** `ci` runs must merge with
  `--require-verified --require-coverage --strict` so skipped skeptic verdicts or missing
  coverage metadata fail instead of becoming trusted findings.
- **Don't invent bugs.** A clean result is a valid, valuable outcome — see *When the hunt
  finds nothing* below. Never pad the report to look productive.

## Modes

| Mode | When | How |
|------|------|-----|
| **Quick scan** | Small target, a single file/module, or a diff; minutes | Single-agent sweep; pick 2–3 lenses + the platform catalog |
| **Deep hunt** | Whole codebase; the flagship mode | Full recon → fan-out across the (lens × hotspot) grid |
| **Targeted hunt** | User names a module/feature/file | Recon scoped to it → fan-out within scope |

Default to the mode the request implies; ask only if genuinely ambiguous.

## The hunt loop

Execute in order. Spokes carry the detail.

| Step | Do | Spoke |
|------|-----|-------|
| 1 | **Recon & pre-pass** — detect platform, run the deterministic pre-pass (census/hotspots/signals/deps), map trust boundaries, build the hunt plan | [recon-and-scoping.md](recon-and-scoping.md), [tooling.md](tooling.md) |
| 2 | **Fan-out** — build the (lens × hotspot) grid, dispatch hunters via the capability ladder (Workflow / parallel Tasks / sequential) | [orchestration.md](orchestration.md) |
| 3 | **Hunt** — each hunter runs one lens over one area using the relevant platform catalog; returns evidence as JSON | lens + platform spokes below |
| 4 | **Verify (mandatory)** — a skeptic pass tries to refute every candidate before it counts as a finding | [verification.md](verification.md) |
| 5 | **Merge & cross-validate** — `bughunt.py merge`: fingerprint, dedupe, cross-validate, suppress, baseline-diff | [orchestration.md](orchestration.md), [tooling.md](tooling.md) |
| 6 | **Triage** — severity × confidence (+ impact rubric), filter false positives, build minimal repros | [triage](../triage/SKILL.md) |
| 7 | **Confirm (optional)** — prove high-value findings dynamically or at runtime; in parallel isolated sandboxes via the E2B rung | [confirm.md](confirm.md), [fuzz](../fuzz/SKILL.md), `verify` |
| 8 | **Report** — `bughunt.py render` the ranked markdown/HTML/SARIF; hand fixing off | [tooling.md](tooling.md), [triage](../triage/SKILL.md) report layout |

## Toolkit & capability ladder

The hunt has a **deterministic spine** and a **portable execution model**, so it works the same
on Claude Code, Cursor, or Codex.

- **Toolkit** — `bughunt.py` (zero-dependency, stdlib `python3`) under [`scripts/`](tooling.md)
  does the non-judgment work: rank hotspots, mine pain signals, audit deps, and
  fingerprint/dedupe/suppress/baseline-diff/render the findings. The automated dependency
  support is strongest for npm/Python-style manifests; other ecosystems rely more on platform
  catalogs and agent inspection. **Always probe `python3 --version`
  first.** If it's missing, run the **markdown fallback** — rank by the recon heuristics, keep
  findings in markdown, skip SARIF; nothing in the toolkit is required for the hunt to work.
- **Capability ladder** ([orchestration.md](orchestration.md)) — same five phases
  (Recon → Hunt → **Verify** → Merge → Report) on every rung: **(A)** invoke the shipped
  `hunt-workflow.js` when the Workflow tool is available; **(A-CLI)** the shipped
  `hunt-cursor.mjs` to fan out Composer 2.5 / Grok hunters via `cursor-agent` — the **fast
  variant**, and the highest rung available inside Cursor; **(B)** parallel Tasks on standard
  Claude Code; **(C)** a sequential walk on single-agent tools. Verify is mandatory on every
  rung, and always on a strong reasoner even when hunters run on a fast model.

## Example: one trip through the loop (condensed)

A small Node API repo, deep hunt:

1. **Recon** — detects Express + Postgres. Trust boundaries: HTTP routes, SQL. Hotspots by
   churn + boundary: `routes/invoices.js` (recently changed, near auth + SQL, no tests),
   `lib/pricing.js` (money math), `db/query.js`.
2. **Fan-out grid** — dispatch hunters: `auth-access × routes/invoices.js`,
   `taint × routes/invoices.js`, `logic-correctness × lib/pricing.js`,
   `resource-performance × db/query.js`. Platform catalog: web.
3. **Hunters report** (evidence-backed candidates):
   - `auth-access`: `GET /invoices/:id` loads by id with no ownership check → **IDOR**.
   - `logic-correctness`: discount applied after tax in `applyDiscount()` → wrong total.
   - `resource-performance`: invoice list issues one query per line item → **N+1**.
4. **Merge & cross-validate** — three distinct findings, no dupes; taint hunter found nothing
   new (SQL is parameterized — correctly *not* reported).
5. **Triage** — IDOR = `High-Confirmed` (wrote a failing test: user A reads user B's invoice);
   discount = `High-Probable` (traced values: $100 + 10% tax then −10% = $99, expected $90);
   N+1 = `Medium-Probable`.
6. **Report** — three findings, ranked, each with repro/trace; recommend fixing then `/review`.
   No product-code edits made; `.bughunt/` report/state files may be written.

## When the hunt finds nothing

A clean result is a real outcome — report it honestly, never invent findings. Emit a short
report stating: what was examined (which lenses × hotspots), what was deliberately out of
scope, your confidence level, and any *Speculative* items worth a human glance. "I hunted X
with lenses Y and found no confirmed defects; here's the coverage" is a valid deliverable.

## Lens index (analysis disciplines)

Read on demand — only the lenses the hunt plan selects.

| Lens | Hunts for |
|------|-----------|
| [lens-dataflow-taint.md](lens-dataflow-taint.md) | Untrusted input reaching dangerous sinks: injection, deserialization, path traversal, SSRF, secret leakage |
| [lens-state-lifecycle.md](lens-state-lifecycle.md) | Illegal state transitions, resource/handle leaks, init/teardown order, idempotency, cache invalidation |
| [lens-concurrency.md](lens-concurrency.md) | Data races, TOCTOU, deadlock, reentrancy, async ordering & cancellation, shared mutable state |
| [lens-boundaries-numeric.md](lens-boundaries-numeric.md) | Off-by-one, overflow/truncation, precision, null/optional, empty/limit cases, encoding, time/DST |
| [lens-error-failure.md](lens-error-failure.md) | Swallowed errors, fail-open, partial writes, missing rollback, retry/timeout/cancel correctness |
| [lens-contract-spec.md](lens-contract-spec.md) | Code vs docs/tests/types/comments, violated invariants, dead/contradictory logic, copy-paste divergence |
| [lens-auth-access.md](lens-auth-access.md) | Broken authn/authz, IDOR, privilege escalation, tenant isolation, session/token/crypto/secret misuse |
| [lens-logic-correctness.md](lens-logic-correctness.md) | Internally wrong logic: inverted conditions, wrong operators/formulas, branch/case errors, wrong variable used |
| [lens-resource-performance.md](lens-resource-performance.md) | O(n²)+ complexity, N+1 queries, unbounded growth, memory blowups, DoS amplification at scale |
| [lens-dx-pain.md](lens-dx-pain.md) | Developer-experience friction: aged TODO/FIXME debt, flaky-test patterns, slow/serial scripts, config drift, unhelpful errors |
| [lens-product-ux.md](lens-product-ux.md) | User-facing pain: missing loading/empty/error states, swallowed feedback, dead feature flags, friction & dead ends |
| [lens-dependency-supply.md](lens-dependency-supply.md) | Supply-chain risk: vulnerable/unpinned/abandoned deps, lockfile drift, typosquats, unsafe install/CI |
| [lens-data-migration.md](lens-data-migration.md) | Data safety: destructive/irreversible migrations, unsafe backfills, schema/code skew, serialization drift |

## Platform index (ecosystem footguns)

Pick the one(s) recon identifies.

| Platform | Catalog |
|----------|---------|
| Apple — Swift/ObjC (iOS, macOS) | [platform-apple.md](platform-apple.md) |
| Web — JS/TS, browser, Node | [platform-web.md](platform-web.md) |
| Systems — C/C++/Rust/Go | [platform-systems.md](platform-systems.md) |
| Backend + CLI — Python/Ruby/Java + terminal tools | [platform-backend-cli.md](platform-backend-cli.md) |
| Other (Android/Kotlin, .NET/C#, PHP, Flutter/RN, SQL, IaC) **+ generic fallback for any unlisted language** | [platform-other.md](platform-other.md) |

## Spoke index

| File | Contents |
|------|----------|
| [recon-and-scoping.md](recon-and-scoping.md) | Deterministic pre-pass, platform detection, trust boundaries, hotspot ranking, hunt plan |
| [orchestration.md](orchestration.md) | (Lens × hotspot) grid, hunter prompt, capability ladder (Workflow/Tasks/sequential), merge/cross-validate |
| [verification.md](verification.md) | The mandatory adversarial skeptic pass — four refutation questions, verdict contract |
| [confirm.md](confirm.md) | Optional E2B-backed Confirm rung — parallel isolated repros that earn Confirmed verdicts (`confirm-e2b.py`) |
| [tooling.md](tooling.md) | `bughunt.py` reference — census/hotspots/signals/deps/merge/render/diff, state dir, CI mode |
| [lens-dataflow-taint.md](lens-dataflow-taint.md) | Source→sink tracing |
| [lens-state-lifecycle.md](lens-state-lifecycle.md) | State machines & resource lifecycle |
| [lens-concurrency.md](lens-concurrency.md) | Races, ordering, deadlock |
| [lens-boundaries-numeric.md](lens-boundaries-numeric.md) | Numeric & boundary conditions |
| [lens-error-failure.md](lens-error-failure.md) | Error & failure paths |
| [lens-contract-spec.md](lens-contract-spec.md) | Contract vs implementation |
| [lens-auth-access.md](lens-auth-access.md) | Authorization & access control |
| [lens-logic-correctness.md](lens-logic-correctness.md) | Business-logic correctness |
| [lens-resource-performance.md](lens-resource-performance.md) | Resource & performance at scale |
| [lens-dx-pain.md](lens-dx-pain.md) | Developer-experience pain |
| [lens-product-ux.md](lens-product-ux.md) | Product & UX pain |
| [lens-dependency-supply.md](lens-dependency-supply.md) | Dependency & supply chain |
| [lens-data-migration.md](lens-data-migration.md) | Data & migration safety |
| [platform-apple.md](platform-apple.md) | Swift/ObjC catalog |
| [platform-web.md](platform-web.md) | JS/TS/Node catalog |
| [platform-systems.md](platform-systems.md) | C/C++/Rust/Go catalog |
| [platform-backend-cli.md](platform-backend-cli.md) | Backend + CLI catalog |
| [platform-other.md](platform-other.md) | Android, .NET, PHP, Flutter/RN, SQL, IaC + generic fallback |

## When not to use

- **Just reviewing your own session diff for quality** → the **autoreview** skill (`/review`).
- **You already have one suspected bug to assess** → [triage](../triage/SKILL.md) directly.
- **You want to harden one function dynamically** → [fuzz](../fuzz/SKILL.md) directly.

## Related skills

- [triage](../triage/SKILL.md) — scoring, repro, and the report format bughunt emits
- [fuzz](../fuzz/SKILL.md) — confirm Probable findings dynamically
- the **autoreview** skill (`/review`) — the recommended fix/quality gate after reporting
- **verify** / `/verify` — drive the real app to reproduce a runtime-only bug

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [robzilla1738](https://github.com/robzilla1738)
- **Source:** [robzilla1738/roberts-skills](https://github.com/robzilla1738/roberts-skills)
- **License:** MIT
- **Homepage:** https://robertcourson.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-robzilla1738-roberts-skills-bughunt
- Seller: https://agentstack.voostack.com/s/robzilla1738
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.