Skip to content
Back to search

bug-hunter

SkillWorks with Claude CodeGitHub

"Precision-first adversarial bug hunting for runtime, logic, data, concurrency, and security defects. Uses deterministic risk triage, evidence-bounded retrieval, Hunter/Skeptic/Referee review, optional hybrid verification, and explicit immutable Fixer scope. Scan-only and single-pass by default; complete-coverage loops, edits, autonomous fixes, and commits each require explicit intent. Use for code review, security audits, regression hunting, PR review, and evidence-backed remediation planning in skills-capable coding agents."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/codexstar69/bug-hunter with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/codexstar69/bug-hunter'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/codexstar69--bug-hunter/badge.svg)](/listings/codexstar69--bug-hunter)

HTML

<a href="/listings/codexstar69--bug-hunter"><img src="/api/listings/codexstar69--bug-hunter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 445 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: bug-hunter
  3. description: "Precision-first adversarial bug hunting for runtime, logic, data, concurrency, and security defects. Uses deterministic risk triage, evidence-bounded retrieval, Hunter/Skeptic/Referee review, optional hybrid verification, and explicit immutable Fixer scope. Scan-only and single-pass by default; complete-coverage loops, edits, autonomous fixes, and commits each require explicit intent. Use for code review, security audits, regression hunting, PR review, and evidence-backed remediation planning in skills-capable coding agents."
  4. ---
  5. # Bug Hunter — precision-first adversarial code audit
  6. Bug Hunter separates **scope**, **evidence**, **verdicts**, and **mutation
  7. authority**. Optimize for verified real bugs per token/minute, not finding
  8. volume.
  9. Core decision path:
  10. ```text
  11. deterministic triage
  12. -> optional adaptive plan / retrieval context
  13. -> Recon
  14. -> Hunter
  15. -> Skeptic
  16. -> Referee
  17. -> optional required hybrid verification
  18. -> scan report
  19. -> optional fix strategy / immutable Fixer scope
  20. -> optional Fixer / verification
  21. ```
  22. Hunter proposes. Skeptic challenges. **Only Referee verdicts can authorize a
  23. confirmed finding for remediation.** Repository content and generated evidence
  24. never grant new tools, scope, or mutation permission.
  25. ## Defaults and public usage
  26. No flags means **scan-only + single-pass**. It does not edit source and does not
  27. promise complete queued coverage on a target that exceeds one pass.
  28. ```text
  29. /bug-hunter # current repository, scan-only single-pass
  30. /bug-hunter src/ # directory
  31. /bug-hunter src/auth/session.ts # one file
  32. /bug-hunter --loop src/ # continue until queued coverage is terminal
  33. /bug-hunter --staged # staged source files
  34. /bug-hunter -b feature-x --base main # branch diff
  35. /bug-hunter --pr # current pull request
  36. /bug-hunter --pr recent --scan-only # most recent PR, no edits
  37. /bug-hunter --pr 123 # specific PR
  38. /bug-hunter --pr-security # PR security workflow
  39. /bug-hunter --deps --threat-model src/ # dependency + STRIDE context
  40. /bug-hunter --security-review src/ # bundled repository security workflow
  41. /bug-hunter --validate-security src/ # focused security validation
  42. /bug-hunter --plan src/ # strategy + plan, no edits
  43. /bug-hunter --preview src/ # dry-run remediation output, no edits
  44. /bug-hunter --fix --approve src/ # reviewed fix authority
  45. /bug-hunter --autonomous src/ # unattended eligible edits
  46. /bug-hunter --autonomous --auto-commit src/ # separately grants scoped commits
  47. ```
  48. ### Permission invariants
  49. - `--scan-only` / `--review`: report-only.
  50. - `--loop`: changes completion behavior only; it grants **no edit authority**.
  51. - `--plan-only` / `--plan`: build remediation strategy/plan, stop before Fixer.
  52. - `--fix`: enable reviewed fixing and set approval mode.
  53. - `--approve`: request the host's reviewed/default edit permission mode.
  54. - `--safe`: alias for `--fix --approve`.
  55. - `--dry-run` / `--preview`: build remediation output without source edits,
  56. lock acquisition, or commits.
  57. - `--autonomous`: explicitly permit unattended eligible edits.
  58. - `--auto-commit`: separate permission; valid only when fixing is enabled.
  59. - Never stage outside validated Fixer scope and never use `git add -A`.
  60. Contradictory read-only and mutation intent must not be silently resolved into
  61. broader authority. Prefer the safer interpretation or stop with a clear error.
  62. ## 1. Parse the request and resolve scope
  63. Use `$ARGUMENTS` and initialize:
  64. ```text
  65. LOOP_MODE=false
  66. FIX_MODE=false
  67. APPROVE_MODE=false
  68. AUTONOMOUS_MODE=false
  69. AUTO_COMMIT=false
  70. DRY_RUN_MODE=false
  71. PLAN_ONLY_MODE=false
  72. DEP_SCAN=false
  73. THREAT_MODEL_MODE=false
  74. PR_SECURITY_MODE=false
  75. SECURITY_REVIEW_MODE=false
  76. VALIDATE_SECURITY_MODE=false
  77. ```
  78. Apply public aliases/flags:
  79. - `--loop` -> `LOOP_MODE=true`; `--no-loop` keeps single-pass behavior.
  80. - `--scan-only` or `--review` -> keep `FIX_MODE=false`.
  81. - `--fix` -> `FIX_MODE=true`, `APPROVE_MODE=true`.
  82. - `--approve` -> `FIX_MODE=true`, `APPROVE_MODE=true`.
  83. - `--safe` -> same as `--fix --approve`.
  84. - `--autonomous` -> `FIX_MODE=true`, `AUTONOMOUS_MODE=true`,
  85. `APPROVE_MODE=false`.
  86. - `--auto-commit` -> `AUTO_COMMIT=true`; reject unless `FIX_MODE=true`.
  87. - `--dry-run` or `--preview` -> `FIX_MODE=true`, `DRY_RUN_MODE=true`.
  88. - `--plan-only` or `--plan` -> `PLAN_ONLY_MODE=true`.
  89. - `--deps` -> `DEP_SCAN=true`.
  90. - `--threat-model` -> `THREAT_MODEL_MODE=true`.
  91. - `--pr-security` -> `PR_SECURITY_MODE=true`, `DEP_SCAN=true`,
  92. `THREAT_MODEL_MODE=true`, `FIX_MODE=false`; default PR selector to `current`.
  93. - `--security-review` -> `SECURITY_REVIEW_MODE=true`, `DEP_SCAN=true`,
  94. `THREAT_MODEL_MODE=true`, `FIX_MODE=false`.
  95. - `--validate-security` -> `VALIDATE_SECURITY_MODE=true`.
  96. - `--review-pr` -> `--pr current`; bare `--pr` -> `--pr current`;
  97. `--last-pr` -> `--pr recent`.
  98. ### PR scope
  99. For `--pr <current|recent|N>` run:
  100. ```bash
  101. node "$SKILL_DIR/scripts/pr-scope.cjs" resolve "<selector>" \
  102. --repo-root "$PWD" [--base <base-branch>]
  103. ```
  104. Save the resolver result to `.bug-hunter/pr-scope.json` and scan the full
  105. contents of `changedFiles`. If a trustworthy base cannot be resolved, fail
  106. explicitly; do not silently assume one.
  107. ### Staged scope
  108. For `--staged`, resolve with `git diff --cached --name-only`. Stop cleanly when
  109. nothing is staged.
  110. ### Branch scope
  111. For `-b <branch> [--base <base>]`, resolve `<base>...<branch>` and scan full
  112. contents of the resulting source files. If no explicit base is supplied for
  113. this public branch form, `main` is the documented default.
  114. ### Path scope
  115. Otherwise treat the remaining argument as a file/directory path; empty means
  116. the current repository.
  117. Use the maintained source classifier in triage/indexing rather than duplicating
  118. an ad-hoc extension allowlist in agent reasoning. Exclude docs/assets/build
  119. output/vendor content according to the deterministic runtime. If no scannable
  120. source remains, report that and stop.
  121. ## 2. Preflight
  122. Resolve `SKILL_DIR` from this `SKILL.md` when possible. Fallback locations may
  123. include agent-specific skill directories for Claude Code, Codex, Cursor, Kiro,
  124. Copilot, Windsurf, OpenCode, Factory Droid CLI, and generic `~/.agents/skills`.
  125. Before creating run state:
  126. 1. Require Node.js 22+.
  127. 2. Create `.bug-hunter/payloads` and `.bug-hunter/domains`.
  128. 3. Verify required role files and runtime helpers exist.
  129. 4. Run the core preflight when possible:
  130. ```bash
  131. node "$SKILL_DIR/scripts/run-bug-hunter.cjs" preflight --skill-dir "$SKILL_DIR"
  132. ```
  133. 5. Documentation lookup is optional. Prefer `scripts/doc-lookup.cjs`; use the
  134. bundled Context7 path as fallback. Missing docs lower confidence for
  135. version-sensitive claims; they do not authorize guessing.
  136. 6. Select one supported orchestration backend for the run. Delegation is an
  137. optimization, not a correctness requirement; `local-sequential` is a valid
  138. complete backend.
  139. When delegating, read only `modes/dispatch.md`. The deterministic renderer
  140. reads the wrapper and role skill; the orchestrator does not load either.
  141. Validate canonical artifacts after completion.
  142. ## 3. Deterministic triage before model work
  143. Run triage after target resolution:
  144. ```bash
  145. node "$SKILL_DIR/scripts/triage.cjs" scan "<TARGET_PATH>" \
  146. --output .bug-hunter/triage.json
  147. ```
  148. Use its `strategy`, `fileBudget`, `scanOrder`, `riskMap`, `domains`, and
  149. `needsLoop`. Triage and indexing share the maintained source classifier; keep
  150. its risk-prioritized order through state initialization, indexing, delta scope,
  151. and expansion.
  152. ### Source-token budget
  153. The runtime builds adaptive chunks from the **combined estimated source tokens
  154. of the actual assigned files**, preserving risk order. Default source-token
  155. budget is 48,000 (`SOURCE_TOKEN_BUDGET=48000`) unless an integration/caller
  156. explicitly overrides it. A single oversized file is isolated and marked instead of being hidden inside an
  157. oversized mixed chunk.
  158. See `docs/precision-protocol.md` for exact fail-closed evidence invariants.
  159. ### Single-pass vs loop
  160. If triage reports `needsLoop: true` and `LOOP_MODE=false`, warn truthfully:
  161. ```text
  162. This target exceeds one-pass queued coverage. Single-pass mode is active.
  163. The report may be partial; run `/bug-hunter --loop <path>` for complete queued
  164. coverage.
  165. ```
  166. Do **not** say that `LOOP_MODE=false` implies the user passed `--no-loop`—it is
  167. the normal default.
  168. If `LOOP_MODE=true`, read `modes/loop.md` (or `modes/fix-loop.md` when fixing)
  169. and use the supported loop driver. Initialize/consult the guarded experiment
  170. state as defined there. Do not pretend a loop will continue without an active
  171. driver.
  172. ## 4. Optional measurable context
  173. Schema-valid `adaptive-plan.json`, `retrieval-plan.json`, `benchmark-report.json`,
  174. and exact source/content-addressed cache facts may narrow context, never scope
  175. or authority. Explicit caller settings win; recheck current source. Read
  176. `docs/world-class-protocol.md` only when these integration artifacts are supplied.
  177. ## 5. Optional security context
  178. ### Threat model
  179. When `THREAT_MODEL_MODE=true`, read:
  180. `skills/threat-model-generation/SKILL.md`
  181. Generate or reuse Bug Hunter-native `.bug-hunter/threat-model.md` and related
  182. security configuration according to that skill. Existing current threat-model
  183. context may be reused as read-only evidence.
  184. ### Dependency evidence
  185. When `DEP_SCAN=true`, run:
  186. ```bash
  187. node "$SKILL_DIR/scripts/dep-scan.cjs" \
  188. --target "<TARGET_PATH>" --output .bug-hunter/dep-findings.json
  189. ```
  190. Supported parsing/reachability is currently for JavaScript/TypeScript projects
  191. using npm, pnpm, Yarn, or Bun lockfiles. `scanner-unsupported` is unresolved,
  192. not clean.
  193. ### Bundled security workflows
  194. Route these flags through their bundled local skills:
  195. - `--pr-security` -> `skills/commit-security-scan/SKILL.md`
  196. - `--security-review` -> `skills/security-review/SKILL.md`
  197. - `--threat-model` -> `skills/threat-model-generation/SKILL.md`
  198. - `--validate-security` -> `skills/vulnerability-validation/SKILL.md`
  199. Security workflow intent alone never grants Fixer authority.
  200. ## 6. Load roles progressively
  201. Canonical role instructions live under `skills/`; compatibility files under
  202. `prompts/` are generated copies and are not an independent source of truth.
  203. For local-sequential execution, read only the current role. Delegated execution
  204. uses `payload-guard.cjs render`; the renderer loads role text from disk without
  205. passing it through the orchestrator. Do not read role skills to prepare dispatches.
  206. | Phase | Canonical instructions |
  207. |---|---|
  208. | Recon | `skills/recon/SKILL.md` |
  209. | Hunter | `skills/hunter/SKILL.md` |
  210. | Skeptic | `skills/skeptic/SKILL.md` |
  211. | Referee | `skills/referee/SKILL.md` |
  212. | Fixer | `skills/fixer/SKILL.md` |
  213. | Documentation | `skills/doc-lookup/SKILL.md` |
  214. Calibration examples are **progressive**, not mandatory context for every
  215. assignment. Follow each role skill's instructions: load Hunter/Skeptic examples
  216. only for ambiguous/lower-confidence cases or when explicitly useful. Do not
  217. spend context on examples for settled cases.
  218. For delegated phases, include only the assigned bugs/files and necessary prior
  219. evidence. Do not copy whole merged ledgers into every worker prompt.
  220. ## 7. Choose execution mode
  221. Use `triage.strategy` as the size/partitioning strategy:
  222. - `single-file` -> `modes/single-file.md`
  223. - `small` -> `modes/small.md`
  224. - `parallel` -> `modes/parallel.md`
  225. - `extended` -> `modes/extended.md`
  226. - `scaled` -> `modes/scaled.md`
  227. - `large-codebase` -> `modes/large-codebase.md`
  228. If the selected backend is local-sequential, use
  229. `modes/local-sequential.md` as the execution implementation while retaining the
  230. triage scope/order/budget.
  231. Do not automatically turn a large-codebase request into loop mode. If the user
  232. did not request `--loop`, execute an honest single pass and report partial
  233. queued coverage. When `--loop` is active, combine the size mode with the loop
  234. contract.
  235. Extended/scaled/persisted execution should use `.bug-hunter/state.json`, exact
  236. source hashes, bounded retries, and fresh per-attempt output. The composition
  237. runner requires a real worker command that writes the requested canonical
  238. artifact; there is no no-op worker.
  239. ## 8. Evidence and source-integrity invariants
  240. These rules are non-negotiable across every mode:
  241. - Assigned paths are canonicalized through real paths and remain inside the
  242. repository.
  243. - A worker may report findings only for its exact assigned source files.
  244. - Capture source hashes before dispatch and recheck them immediately before
  245. committing findings/fact cards/completion state.
  246. - Source mutation, deletion, unreadability, or symlink escape fails the affected
  247. chunk closed.
  248. - Resume retains the original source baseline; changed content cannot silently
  249. become a new baseline for an interrupted run.
  250. - Missing/invalid canonical artifacts are failed phases, never clean evidence.
  251. - Coverage is derived from per-file evidence; a parent chunk marked done cannot
  252. manufacture file completion.
  253. - Duplicate observations preserve the strongest evidence and useful unioned
  254. cross-references/security metadata.
  255. - Findings without completed adversarial review stay `unreviewed` or
  256. `manual-review` and cannot authorize fixing.
  257. ## 9. Hunter -> Skeptic -> Referee
  258. ### Hunter
  259. Read assigned production source in risk/retrieval order. Findings require a
  260. concrete runtime trigger and repository evidence. Security findings must satisfy
  261. the canonical findings schema, including actionable STRIDE/CWE evidence when
  262. required. Test files are context-only.
  263. Canonical output: `.bug-hunter/hunter-findings.json`.
  264. ### Skeptic
  265. Challenge each finding from current code and relevant cross-references. Verify
  266. framework-dependent disprovals against documentation when possible. Generic
  267. rate-limit suggestions may be cheap to dismiss, but reachable credential
  268. stuffing, OTP/reset abuse, lockout bypass, measurable amplification, and
  269. attacker-triggered expensive work receive normal analysis.
  270. Canonical output: `.bug-hunter/skeptic.json`.
  271. ### Referee
  272. Referee independently owns final `REAL_BUG`, `NOT_A_BUG`, or `MANUAL_REVIEW`
  273. verdicts. Missing/failed Referee review leaves the finding unresolved and
  274. non-writable.
  275. Canonical output: `.bug-hunter/referee.json`.
  276. ## 10. Hybrid verification
  277. When a verification plan is supplied/required, execute it through the bounded
  278. hybrid verifier. Checks run as inert argv arrays with repository containment,
  279. secret stripping/redaction, output/time budgets, and `shell:false` semantics.
  280. A required check that fails, times out, or is unavailable makes verification
  281. fail closed. **Required verification failure prevents Fixer authorization.** A
  282. passing test/compiler/static check is evidence; it is not proof that unrelated
  283. bugs do not exist.
  284. Canonical output: `.bug-hunter/verification-report.json`.
  285. ## 11. Join and present the scan result
  286. Always preserve canonical Hunter/Referee artifacts and build the joined
  287. `.bug-hunter/scan-report.json`. Render `.bug-hunter/report.md` as a human view.
  288. JSON is the automation source of truth.
  289. Final results must distinguish:
  290. - `confirmed` — Referee accepted the finding;
  291. - `dismissed` — evidence disproved it;
  292. - `manualReview` — a human/wider decision remains;
  293. - `unreviewed` — adversarial review did not finish;
  294. - failed/pending coverage;
  295. - required-verification failure when applicable.
  296. Do not claim “audit complete”, “full coverage”, or “clean” while the requested
  297. scope still has unresolved review, failed coverage, or required-verification
  298. failure.
  299. If `LOOP_MODE=true`, continue according to the loop contract until every queued
  300. source file reaches a terminal outcome or an explicit hard blocker/user stop
  301. ends the run. If `LOOP_MODE=false`, report exactly what one pass covered and
  302. recommend `--loop` when full queued coverage is desired.
  303. ## 12. Plan and fix only with authority
  304. Confirmed bugs with `PLAN_ONLY_MODE=true` or `FIX_MODE=true` route to
  305. `modes/fix-pipeline.md`. Only eligible `safe-autofix` entries in validated
  306. `fixer-scope.json` are writable. `DRY_RUN_MODE=true` stops before edits, locks,
  307. or commits; planning alone never grants mutation authority.
  308. ## Canonical artifacts
  309. Important schema-backed artifacts under `.bug-hunter/`:
  310. | Artifact | Purpose |
  311. |---|---|
  312. | `triage.json` | deterministic risk/scope/budget input |
  313. | `adaptive-plan.json` | bounded adaptive context/review policy |
  314. | `recon.json` | architecture/trust-boundary context |
  315. | `retrieval-plan.json` | hypothesis-ranked bounded evidence |
  316. | `hunter-findings.json` | Hunter claims |
  317. | `skeptic.json` | adversarial challenges |
  318. | `referee.json` | final verdicts |
  319. | `verification-report.json` | hybrid verification evidence |
  320. | `scan-report.json` | joined final machine result |
  321. | `coverage.json` | per-file coverage state |
  322. | `fix-strategy.json` | remediation classifications |
  323. | `fix-plan.json` | canary/rollout plan |
  324. | `fixer-scope.json` | immutable mutation boundary |
  325. | `fix-report.json` | remediation/verification/rollback result |
  326. | `benchmark-report.json` | precision/recall/calibration/stability/cost/latency metrics |
  327. ## Failure policy
  328. Fail closed for:
  329. - invalid/missing required canonical artifacts;
  330. - source-integrity or repository-containment failure;
  331. - required verification failure;
  332. - invalid delegated payload;
  333. - Referee failure for affected findings;
  334. - immutable Fixer-scope violation;
  335. - unsafe Git/worktree preservation state.
  336. Recoverable worker failures may retry within configured bounds using fresh
  337. attempt outputs. Unrecoverable chunks remain failed/partial and visible.
  338. Never convert unavailable evidence, unsupported scanners, failed review, or
  339. failed safety checks into a clean result.
README.md · README · 915 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. title: Bug Hunter
  3. description: >
  4. Install and use the measurable adversarial code-audit skill with scan-only
  5. defaults and explicit permission before source edits.
  6. prompt: |
  7. Explain and use the current Bug Hunter protocol accurately. Keep scan-only
  8. and single-pass defaults unless the user explicitly requests loop coverage or
  9. mutation. Prefer canonical JSON artifacts, evidence-backed adversarial review,
  10. bounded adaptive/retrieval context, and fail-closed verification.
  11. ---
  12. <p align="center">
  13. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/hero.png" alt="Bug Hunter pipeline: triage, recon, Hunter, Skeptic, Referee, Fixer, and verification" width="720">
  14. </p>
  15. <h1 align="center">Bug Hunter</h1>
  16. <p align="center"><strong>Adversarial code auditing for AI coding agents.</strong></p>
  17. <p align="center">
  18. <a href="https://www.npmjs.com/package/@codexstar/bug-hunter"><img src="https://img.shields.io/npm/v/@codexstar/bug-hunter" alt="npm version"></a>
  19. <a href="https://github.com/codexstar69/bug-hunter/actions/workflows/ci.yml"><img src="https://github.com/codexstar69/bug-hunter/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
  20. <a href="https://github.com/codexstar69/bug-hunter/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@codexstar/bug-hunter" alt="MIT license"></a>
  21. <img src="https://img.shields.io/badge/node-%3E%3D22-blue" alt="Node.js 22 or newer">
  22. </p>
  23. Bug Hunter is an AI-agent skill for code review and security auditing. A Hunter finds possible bugs, a Skeptic challenges each claim, and a Referee decides what the evidence supports. The default run only scans and reports. It is single-pass unless `--loop` is explicitly requested. Editing, autonomous fixing, and commits each require explicit permission.
  24. ## v3.2.0 source — measurable, adaptive bug hunting
  25. The current v3.2.0 source makes the precision-first pipeline measurable and adaptive while preserving the scan-only default and fail-closed safety boundaries. The latest published npm release may lag GitHub `main`; use the current-source command below when you need the exact implementation documented on this page.
  26. - **Measurable benchmark quality gate** scores one-to-one finding matches, precision, recall, F1, severity-weighted recall, false positives per KLOC, calibration, repeat stability, token usage, latency, and cost data when supplied.
  27. - **Adaptive execution profiles** select `fast`, `balanced`, or `assurance` behavior from triage risk, security scope, benchmark evidence, stability, calibration, and token efficiency.
  28. - **Hybrid verification** safely runs argv-only tests, type checks, static checks, fuzz checks, and security-static checks, and fails closed when required verification fails or is unavailable.
  29. - **Exact evidence caching** reuses evidence only when source content, protocol identity, role, and relevant configuration match exactly; changed source cannot inherit stale conclusions.
  30. - **Hypothesis-driven retrieval** prioritizes direct files, symbols, dependencies, dependents, cross-references, and trust boundaries under hard context budgets.
  31. - **Stronger source integrity** keeps scan scope, source hashes, resume identity, coverage state, and Fixer authorization explicit and rejects source drift.
  32. - **Permanent CI quality gates** verify Node.js 22 and 24; the Node.js 24 lane also runs the benchmark quality gate and package inventory verification.
  33. - **Bundled security workflows** cover PR-focused security review, full repository security review, STRIDE threat modeling, vulnerability validation, and supported dependency CVE scanning.
  34. The bundled deterministic regression fixture currently records precision `1.00`, recall `1.00`, F1 `1.00`, repeat stability `1.00`, zero false positives, median `12,090` tokens per true positive, p95 duration `61.3s`, and expected calibration error about `0.048`. These figures validate the bundled harness and fixture; they are not an independent benchmark of every repository or model.
  35. See [the measurable world-class protocol](docs/world-class-protocol.md) for the full architecture, artifact contracts, quality thresholds, and verification design.
  36. ## TL;DR
  37. Install the exact current GitHub source documented here. Replace `codex` with a target from the table below.
  38. ```bash
  39. npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex
  40. npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex
  41. ```
  42. For the latest published npm release—which may lag current GitHub source—use:
  43. ```bash
  44. npm exec --yes --package=@codexstar/bug-hunter@latest -- bug-hunter install --agent codex
  45. npm exec --yes --package=@codexstar/bug-hunter@latest -- bug-hunter doctor --agent codex
  46. ```
  47. Restart the agent if it was open during installation. Then send this prompt from the repository you want to audit:
  48. ```text
  49. Use the bug-hunter skill to scan this repository. Do not edit files.
  50. Return the final report and call out every item that needs manual review.
  51. ```
  52. That is the recommended first run. It is scan-only and single-pass. Request `--loop` when complete queued coverage is required.
  53. ## Choose your agent
  54. | Agent | Install target |
  55. |---|---|
  56. | Claude Code | `claude-code` |
  57. | Codex | `codex` |
  58. | Cursor | `cursor` |
  59. | GitHub Copilot | `copilot` |
  60. | Kiro | `kiro` |
  61. | Windsurf | `windsurf` |
  62. | OpenCode | `opencode` |
  63. | Factory Droid CLI | `droid` |
  64. | Other file-based agents | `agents` |
  65. Always pass `--agent` when more than one coding agent is installed. Auto-detection is available, but an explicit target prevents installation into the wrong skill directory.
  66. Factory Droid CLI (`droid`) installs into `~/.factory/skills/bug-hunter` and loads the skill for every repository. Use `--path "$PWD/.factory/skills/bug-hunter"` instead when the skill should be checked into a single repository. Droid also reads the legacy `~/.agents/skills` location, so an existing `--agent agents` install already works there.
  67. See [agent installation](docs/agent-installation.md) for paths, source installs, updates, removal, and custom targets.
  68. ## Use it with any agent
  69. Natural language is the portable interface:
  70. ```text
  71. Use the bug-hunter skill to scan src/auth. Do not edit files.
  72. ```
  73. Agents that expose skill commands may also accept:
  74. ```text
  75. /bug-hunter src/auth
  76. ```
  77. For a reviewed fix run:
  78. ```text
  79. Use the bug-hunter skill to scan this repository. Build a fix plan.
  80. Ask for approval before every edit. Do not commit.
  81. ```
  82. The closest flag-based mode is:
  83. ```text
  84. /bug-hunter --fix --approve
  85. ```
  86. `--approve` requests the host agent's reviewed/default permission mode. The
  87. host decides when approval prompts appear. Use `--plan` or `--preview` when
  88. source edits must be impossible.
  89. For a plan without edits:
  90. ```text
  91. /bug-hunter --plan
  92. ```
  93. Do not use `--autonomous` or `--auto-commit` unless you intend to grant those permissions.
  94. See [usage guide](docs/usage-guide.md) for common human and agent prompts.
  95. ## What happens during a scan
  96. ```text
  97. your code
  98. -> risk triage
  99. -> optional adaptive plan
  100. -> architecture recon
  101. -> hypothesis-driven retrieval
  102. -> Hunter findings
  103. -> documentation checks
  104. -> Skeptic challenges
  105. -> Referee verdicts
  106. -> optional hybrid verification
  107. -> report
  108. -> optional approved fix plan
  109. -> optional approved fixes and verification
  110. ```
  111. The pipeline:
  112. - prioritizes high-risk files before lower-risk files
  113. - keeps adaptive/retrieval context within explicit file and token budgets
  114. - records claims with file evidence and runtime triggers
  115. - checks version-sensitive behavior against available documentation
  116. - challenges findings before reporting them as confirmed
  117. - separates confirmed, dismissed, unreviewed, and manual-review results
  118. - validates canonical JSON artifacts between phases
  119. - fails closed on assigned-source drift and required verification failure
  120. - keeps source edits disabled unless fixing is requested
  121. Read [how it works](docs/how-it-works.md) for the full model and safety boundaries.
  122. ## Common workflows
  123. | Goal | Skill request |
  124. |---|---|
  125. | Scan the whole repository once | `/bug-hunter` |
  126. | Complete queued coverage | `/bug-hunter --loop` |
  127. | Scan one path | `/bug-hunter src/auth` |
  128. | Review staged changes | `/bug-hunter --staged` |
  129. | Review the current pull request | `/bug-hunter --pr` |
  130. | Run a pull-request security review | `/bug-hunter --pr-security` |
  131. | Add Node.js dependency scanning | `/bug-hunter --deps` |
  132. | Generate a STRIDE threat model | `/bug-hunter --threat-model` |
  133. | Create a fix plan without edits | `/bug-hunter --plan` |
  134. | Request host-interactive fixing | `/bug-hunter --fix --approve` |
  135. | Build a no-edit remediation preview | `/bug-hunter --preview` |
  136. | Allow unattended fixing | `/bug-hunter --autonomous` |
  137. The executable `bug-hunter` command installs and verifies the skill. Scans are started through your coding agent, not by running `bug-hunter scan` in a shell.
  138. See [CLI reference](docs/cli-reference.md) for installer commands and skill arguments.
  139. ## Security skill routing
  140. The security flags use bundled local skills:
  141. - PR-focused security review routes into `commit-security-scan` through
  142. `--pr-security`.
  143. - `--threat-model` routes into `threat-model-generation`.
  144. - enterprise/full security review routes into `security-review` through
  145. `--security-review`.
  146. - `--validate-security` routes into `vulnerability-validation`.
  147. These skills are part of the managed runtime. They do not require separate
  148. installation.
  149. <p align="center">
  150. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/2026-03-12-security-pack.png" alt="Bundled Bug Hunter security skills for pull-request scanning, repository security review, STRIDE threat modeling, and vulnerability validation" width="100%">
  151. </p>
  152. ## Complete product guide
  153. - [Why adversarial AI code review](#why-adversarial-ai-code-review)
  154. - [How the code-audit pipeline works](#how-the-code-audit-pipeline-works)
  155. - [Hunter, Skeptic, and Referee](#hunter-skeptic-and-referee)
  156. - [Core code-analysis capabilities](#core-code-analysis-capabilities)
  157. - [Security vulnerability classification](#security-vulnerability-classification)
  158. - [STRIDE threat modeling](#stride-threat-modeling)
  159. - [Dependency CVE scanning](#dependency-cve-scanning)
  160. - [Pull-request and changed-code review](#pull-request-and-changed-code-review)
  161. - [Strategic fix planning and safe remediation](#strategic-fix-planning-and-safe-remediation)
  162. - [Structured JSON for CI/CD](#structured-json-for-cicd)
  163. - [Output files](#output-files)
  164. - [Supported languages and frameworks](#supported-languages-and-frameworks)
  165. - [Skill argument reference](#skill-argument-reference)
  166. - [Project architecture](#project-architecture)
  167. ## Why adversarial AI code review
  168. Many AI code-review tools produce a long list of possible issues but leave the
  169. developer to discover which claims are real. A plausible explanation is not
  170. proof that a runtime bug is reachable. Framework behavior, middleware,
  171. validation in another file, and language guarantees can turn an alarming
  172. finding into a false positive.
  173. Bug Hunter treats a finding as a claim that must survive opposition:
  174. 1. The Hunter explains the exact runtime failure, source evidence, trigger,
  175. severity, and cross-file dependencies.
  176. 2. The Skeptic tries to disprove the claim by tracing the same code and checking
  177. protections the Hunter may have missed.
  178. 3. The Referee compares both sides, independently checks the strongest or most
  179. serious claims, and issues the final verdict.
  180. For teams comparing an AI code-review tool, security code scanner,
  181. vulnerability scanner, or static-analysis assistant, this separation matters:
  182. automated code review stays useful only when the evidence and uncertainty are
  183. visible.
  184. This adversarial code review is designed to reduce false-positive overload
  185. without hiding uncertainty. Results that cannot be settled become
  186. `MANUAL_REVIEW` or `unreviewed`; they are not silently presented as clean.
  187. The system focuses on behavioral correctness and security. It is not a style
  188. linter. Naming preferences, formatting, unused code, missing comments, and
  189. general refactoring suggestions are outside the Hunter's reporting scope unless
  190. they create a reachable runtime problem.
  191. ## How the code-audit pipeline works
  192. <p align="center">
  193. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/pipeline-overview.png" alt="Bug Hunter adversarial code-audit pipeline from deterministic triage through Hunter, Skeptic, Referee, reporting, optional fix planning, and verification" width="100%">
  194. </p>
  195. Every phase has a separate job. Role, report, coverage, fix, adaptive, retrieval, verification, and benchmark artifacts use schema-validated JSON; triage JSON is deterministic pipeline input.
  196. | Stage | What it does | Main evidence |
  197. |---|---|---|
  198. | Risk triage | Classifies source files and selects risk-ordered scan scope without an AI model | `triage.json` |
  199. | Adaptive policy | Chooses bounded `fast`, `balanced`, or `assurance` context/review/verification policy when requested or supplied | `adaptive-plan.json` |
  200. | Recon | Adds stack, architecture, and trust-boundary context for multi-file scans | `recon.json` |
  201. | Retrieval planning | Selects hypothesis-relevant mandatory and optional evidence under hard budgets | `retrieval-plan.json` |
  202. | Hunter | Finds reachable logic, security, concurrency, data, and error-path bugs | `hunter-findings.json` |
  203. | Documentation lookup | Checks version-sensitive library or framework assumptions | Evidence added to the finding or challenge |
  204. | Skeptic | Tries to disprove every Hunter claim with code and counter-evidence | `skeptic.json` |
  205. | Referee | Delivers `REAL_BUG`, `NOT_A_BUG`, or `MANUAL_REVIEW` verdicts | `referee.json` |
  206. | Hybrid verification | Runs bounded tests, type/static/build/reproduction/fuzz/security-static checks when configured | `verification-report.json` |
  207. | Report join | Separates confirmed, dismissed, manual-review, and unreviewed results | `scan-report.json` and `report.md` |
  208. | Fix strategy | Classifies confirmed bugs by remediation risk | `fix-strategy.json` |
  209. | Fix plan | Records bug details, files, claimed ranges, remediation class, and rollout order | `fix-plan.json` |
  210. | Fix and verify | Applies only authorized work and records checks or rollback results | `fix-report.json` |
  211. A malformed or missing required canonical artifact is a failed phase, not
  212. evidence of a clean scan. For schema-backed phases, JSON is the source of truth;
  213. Markdown reports are readable views of those contracts.
  214. Bug Hunter adjusts execution to the repository and the agent runtime. A
  215. single-file scan stays small. Larger scans may use bounded parallel,
  216. chunked, persisted-state, domain-scoped, or local-sequential modes. Most
  217. delegated modes use the canonical role artifacts. Large-codebase mode currently
  218. uses per-domain variants before its final merge.
  219. ## Hunter, Skeptic, and Referee
  220. <p align="center">
  221. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/adversarial-debate.png" alt="Hunter reports evidence-backed bugs, Skeptic challenges them, and Referee decides the final code-review verdict" width="100%">
  222. </p>
  223. The roles are deliberately separated:
  224. | Role | Responsibility | What it cannot decide |
  225. |---|---|---|
  226. | Recon | Understand architecture and prioritize risk | Whether a bug is confirmed |
  227. | Hunter | Make a concrete bug claim | Its own final verdict |
  228. | Skeptic | Challenge the claim and expose missing context | The final verdict |
  229. | Referee | Judge the claim from evidence | Permission to edit unrelated code |
  230. | Fix planner | Turn confirmed verdicts into bounded remediation work | Permission outside approved bug IDs |
  231. | Fixer | Apply an approved plan | New scope, new findings, or commit permission |
  232. The calibration model favors evidence over volume. No role earns points for
  233. reporting more or for higher severities; each verdict rests on checked code:
  234. | Agent | Confirms when | Otherwise |
  235. |---|---|---|
  236. | Hunter | A concrete input reaches observable wrong behavior | Omits the claim, or reports a High/Critical hypothesis with its open precondition |
  237. | Skeptic | Counter-evidence at a cited file:line disproves the trigger | `MANUAL_REVIEW`, never a categorical dismissal |
  238. | Referee | A checked causal chain proves the bug | `MANUAL_REVIEW`; presentation and agreement are not evidence |
  239. The Skeptic keeps 9 settled false-positive classes for recurring non-bugs, such
  240. as rate-limiting suggestions, memory-safety claims in checked safe code, log
  241. injection, path-only SSRF, ReDoS, trusted environment variables, and secrets on
  242. disk. Each one is a hypothesis to check, not a categorical dismissal: a
  243. behavioral or security dismissal needs a checked precondition or defensive
  244. mechanism recorded as file:line counter-evidence. Findings only in tests, docs,
  245. assets, or config-only files are outside behavioral scope. Other claims require
  246. code tracing, caller and callee review, runtime-trigger reconstruction, and
  247. documentation verification when framework behavior matters.
  248. The Referee independently re-reads every finding when there are 20 or fewer.
  249. For larger sets it independently verifies all Critical findings and the top 15,
  250. then evaluates the remaining evidence with promotion rules for disputed or
  251. weakly supported decisions.
  252. ## Core code-analysis capabilities
  253. ### Deterministic risk triage
  254. Before the model reads source, `scripts/triage.cjs` inventories the target,
  255. filters non-source content, scores file risk, estimates scan size, and selects
  256. an execution strategy. This deterministic pre-pass spends no model tokens and
  257. keeps high-risk files ahead of lower-risk context.
  258. Risk signals are path and filename heuristics for authentication, security,
  259. API, data, service, utility, test, and low-value locations. Triage does not
  260. parse source behavior or claim to find bugs; it creates a review order and an
  261. explicit coverage budget.
  262. ### Runtime behavioral bug detection
  263. The Hunter reads production code for failures that can change real behavior:
  264. - wrong conditions, off-by-one errors, unreachable branches, and state errors
  265. - injection, authorization bypass, path traversal, SSRF, XSS, and unsafe input
  266. flow
  267. - race conditions, time-of-check/time-of-use bugs, and shared-state conflicts
  268. - swallowed exceptions, unhandled rejections, and partial-failure corruption
  269. - encoding, truncation, numeric, timezone, and serialization mistakes
  270. - mismatched API contracts between callers and callees
  271. - resource leaks involving files, sockets, connections, listeners, or workers
  272. - missing validation at external, service, persistence, and trust boundaries
  273. Each finding must identify a source location, concrete claim, evidence, runtime
  274. trigger, cross-references, confidence, and security classification when
  275. applicable. A theory without a reachable trigger should not become a finding.
  276. ### Cross-file and boundary analysis
  277. Many production bugs do not exist in one function. Bug Hunter checks where
  278. assumptions change:
  279. - a caller assumes a callee validated input, but neither did
  280. - a lower layer throws, an intermediate layer swallows the error, and an upper
  281. layer records success
  282. - one route enforces authorization while another route reaches the same service
  283. without it
  284. - a multi-step write leaves partial state when a later operation fails
  285. - two modules read and update shared state without coordination
  286. - string, number, boolean, date, or null semantics change across an API boundary
  287. Recon supplies the map, Hunter makes the claim, Skeptic follows the defensive
  288. path, and Referee decides what the full evidence supports.
  289. ### Documentation-verified framework analysis
  290. <p align="center">
  291. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/doc-verify-fix-plan.png" alt="Bug Hunter checks version-sensitive framework behavior against documentation before confirming findings, dismissals, or fixes" width="100%">
  292. </p>
  293. AI review often fails when it guesses what a library does. Bug Hunter can query
  294. Context Hub and use the bundled Context7 path as a fallback for a specific
  295. version-sensitive claim.
  296. Documentation checks are used at decision points:
  297. | Role | Example reason to check documentation |
  298. |---|---|
  299. | Hunter | Verify whether a framework actually escapes, validates, or parameterizes a value |
  300. | Skeptic | Confirm that middleware or a library guarantee really blocks the reported trigger |
  301. | Fixer | Verify the supported API and safe usage pattern before proposing a patch |
  302. Lookups are claim-driven rather than a broad search over every import. If no
  303. useful documentation is available, the agent must say that the claim could not
  304. be verified and continue from repository evidence without inventing a guarantee.
  305. Context Hub is optional:
  306. ```bash
  307. npm install -g @aisuite/chub
  308. ```
  309. ### False-positive reduction
  310. Bug Hunter reduces noise through several independent checks:
  311. 1. Scope rules exclude style and non-behavioral suggestions.
  312. 2. Hunter findings require code evidence and a runtime trigger.
  313. 3. Framework-dependent claims can be checked against documentation.
  314. 4. Skeptic re-reads code and tries to find defensive context.
  315. 5. Referee owns the only verdict that can authorize a confirmed result.
  316. 6. Missing review results remain visible as manual or unreviewed work.
  317. 7. A report join checks that the artifact counts and bug IDs agree.
  318. No review process can promise zero false positives or zero missed bugs. The
  319. goal is an auditable argument with enough evidence for a developer to review.
  320. ### Large-codebase coverage and resume
  321. For larger repositories, Bug Hunter can divide work by bounded file chunks or
  322. architectural domains while preserving a canonical queue. State records chunk
  323. attempts, file outcomes, findings, and the fix-plan reference. A sibling
  324. identity file stores the run ID, repository and base commit, scope hash, and
  325. options hash so resume can reject a different target.
  326. Coverage records `pending`, `in_progress`, `done`, or `failed` from per-file evidence. A parent chunk marked done cannot manufacture completion for a file whose evidence remains pending. Failed or incomplete coverage does not become a clean result. Cross-partition references can be sent through a reconciliation pass before the final join.
  327. ## Security vulnerability classification
  328. <p align="center">
  329. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/security-finding-card.png" alt="Security finding card with runtime evidence, STRIDE category, CWE identifier, CVSS 3.1 score, reachability, exploitability, and proof of concept" width="100%">
  330. </p>
  331. Security findings combine code-review evidence with common security taxonomies:
  332. - **STRIDE** describes the threat class and affected trust boundary.
  333. - **CWE** identifies the weakness family, such as CWE-89 for SQL injection or
  334. CWE-862 for missing authorization.
  335. - **CVSS 3.1** records a base vector and score for confirmed Critical or High
  336. security bugs.
  337. - **Reachability** distinguishes external, authenticated, internal, and
  338. unreachable paths.
  339. - **Exploitability** records whether the trigger is easy, conditional, or hard.
  340. - **Proof of concept** gives a minimal, benign way to understand the behavior.
  341. STRIDE and CWE are typed finding fields. Reachability, exploitability, CVSS,
  342. and proof-of-concept details are currently carried in the Referee's narrative
  343. fields.
  344. The six STRIDE categories are:
  345. | Category | Security question |
  346. |---|---|
  347. | Spoofing | Can an attacker pretend to be another user, service, or identity? |
  348. | Tampering | Can untrusted input change code, commands, queries, files, or records? |
  349. | Repudiation | Can an important action happen without reliable attribution? |
  350. | Information disclosure | Can protected data cross into an unauthorized response, log, or tenant? |
  351. | Denial of service | Can a demonstrated external path exhaust a bounded resource or stop service? |
  352. | Elevation of privilege | Can a user cross an authorization boundary or gain a stronger role? |
  353. Common mappings include SQL injection (`CWE-89`, Tampering), command injection
  354. (`CWE-78`, Tampering), XSS (`CWE-79`, Tampering), path traversal (`CWE-22`,
  355. Tampering), IDOR (`CWE-639`, Information disclosure), missing authentication
  356. (`CWE-306`, Spoofing), missing authorization (`CWE-862`, Elevation of
  357. privilege), SSRF (`CWE-918`, Tampering), CSRF (`CWE-352`, Tampering), and
  358. insecure deserialization (`CWE-502`, Tampering).
  359. Classification adds context; it does not replace proof. A severe label without
  360. a reachable trigger should not survive adversarial review.
  361. ## STRIDE threat modeling
  362. Run `/bug-hunter --threat-model` to generate or reuse
  363. `.bug-hunter/threat-model.md`. The threat-model workflow maps:
  364. - public, authenticated, internal, and administrative entry points
  365. - trust boundaries between clients, services, queues, storage, and third parties
  366. - sensitive data flows from input through processing, persistence, and output
  367. - important assets, attacker goals, and boundary-specific STRIDE threats
  368. - framework- and stack-specific vulnerable and defensive patterns
  369. Recon and Hunter use the threat model as scan context. An existing threat model
  370. modified within the last 90 days can be reused; an older one is regenerated
  371. with a warning. The bundled `threat-model-generation` skill owns the artifact,
  372. and `security-review` can request it when a full security review needs one.
  373. This is repository-level threat modeling, not a substitute for infrastructure,
  374. cloud-policy, runtime configuration, or penetration testing outside the checked
  375. source.
  376. ## Dependency CVE scanning
  377. Run `/bug-hunter --deps` to add lockfile-aware dependency vulnerability
  378. scanning for JavaScript and TypeScript projects.
  379. The implemented parser supports:
  380. | Lockfile | Package manager | Audit command |
  381. |---|---|---|
  382. | `package-lock.json` | npm | `npm audit --json` |
  383. | `pnpm-lock.yaml` | pnpm | `pnpm audit --json` |
  384. | `yarn.lock` | Yarn | `yarn npm audit --json` |
  385. | `bun.lock` or `bun.lockb` | Bun | `bun audit --json` |
  386. The scanner keeps High and Critical advisories and searches source for package
  387. imports. Imports in paths containing `.test.`, `.spec.`, or `__tests__` are
  388. treated as potentially reachable; other test naming patterns may still count as
  389. reachable. The result is `REACHABLE`, `POTENTIALLY_REACHABLE`,
  390. `NOT_REACHABLE`, or `UNKNOWN`. It is supporting evidence, not a complete
  391. call-graph proof.
  392. Python, Go, and Rust manifests may be detected, but their audit-output parsers
  393. and reachability fixtures are not implemented. They return
  394. `scanner-unsupported` and are never reported as clean by guesswork.
  395. Dependency results are written to `.bug-hunter/dep-findings.json` and can feed
  396. the Hunter when a vulnerable dependency appears reachable from application
  397. code.
  398. ## Pull-request and changed-code review
  399. <p align="center">
  400. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/2026-03-12-pr-review-flow.png" alt="Pull-request review flow for current PRs, recent PRs, staged changes, branch diffs, security context, and final reporting" width="100%">
  401. </p>
  402. Bug Hunter can narrow the audit to the code that is about to merge:
  403. ```text
  404. /bug-hunter --staged
  405. /bug-hunter --pr
  406. /bug-hunter --pr 123
  407. /bug-hunter --pr recent
  408. /bug-hunter -b feature/auth-refresh --base main
  409. /bug-hunter --pr-security
  410. ```
  411. PR security review routes through the bundled `commit-security-scan` skill and
  412. can combine changed-code scope with STRIDE context, dependency evidence, and
  413. vulnerability validation. GitHub metadata is used when available, with
  414. repository-local Git scope as the fallback.
  415. Changed-code review still follows the same Hunter, Skeptic, and Referee
  416. contract. A smaller diff changes scope; it does not weaken the evidence rules.
  417. ## Strategic fix planning and safe remediation
  418. <p align="center">
  419. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/2026-03-12-fix-plan-rollout.png" alt="Strategic bug-fix plan with confidence gating, canary rollout, scoped editing, verification, circuit breakers, and rollback reporting" width="100%">
  420. </p>
  421. Finding a bug and changing code are separate permissions. The default run
  422. stops after the report. `/bug-hunter --plan` writes a strategy and fix plan but
  423. does not edit source. `/bug-hunter --fix --approve` permits reviewed edits and
  424. requests the host agent's default permission mode; prompt behavior depends on
  425. that host.
  426. The remediation flow has these gates:
  427. ### Git and single-writer safety
  428. Fixing requires a Git repository. The current contract records the original
  429. branch and base commit, inspects dirty state, attempts to preserve tracked and
  430. indexed changes in a named stash, and creates a dedicated fix branch. Untracked
  431. files and pre-existing stashes need manual attention; automatic restoration is
  432. not guaranteed.
  433. A cooperative owner-token lock serializes compliant Bug Hunter Fixers after
  434. Git setup. It does not block a user or another tool from changing the
  435. repository. If status inspection, preservation, branch creation, or lock
  436. acquisition fails, fixing stops.
  437. Worktree isolation is used for supported subagent backends only when
  438. `--auto-commit` was also authorized. Worktree identity, harvest freshness, and
  439. cleanup are checked. If safe preservation or cleanup cannot be proven, the
  440. worktree is left in place for recovery rather than deleted.
  441. ### Baseline and flaky-test detection
  442. When a test command is available, the fix pipeline records two baseline runs.
  443. Failures seen in both are tracked as existing failures; failures seen in only
  444. one are tracked as flaky. New failures after a patch are evaluated against both
  445. sets. Missing verification commands are reported instead of treated as passes.
  446. ### Remediation classification
  447. Every confirmed finding is classified before patching:
  448. | Class | Meaning |
  449. |---|---|
  450. | `safe-autofix` | Localized enough for the guarded Fixer workflow |
  451. | `manual-review` | Evidence or patch confidence is too low |
  452. | `larger-refactor` | Needs coordinated changes beyond a small patch |
  453. | `architectural-remediation` | Requires a wider design or contract change |
  454. The Fixer queue comes only from Referee `REAL_BUG` verdicts. The planner marks
  455. low-confidence, conflicting, and non-autofix work as `manual-review`; the
  456. orchestrator is required to exclude those entries from Fixer batches.
  457. ### Canary-first rollout
  458. The agent-driven fix workflow can apply dependency ordering when an index is
  459. available, then severity ordering. The deterministic composition runner orders
  460. by severity, confidence, and stable key.
  461. The guided workflow describes a highest-risk 20 percent canary bounded to one
  462. through three findings:
  463. ```text
  464. 1–5 eligible bugs -> 1 canary
  465. 6–10 eligible bugs -> 2 canaries
  466. 11+ eligible bugs -> 3 canaries
  467. ```
  468. The deterministic composition runner instead uses its supplied
  469. `--canary-size`, with a default of three. The generated `fix-plan.json` is the
  470. authoritative canary set for a specific run.
  471. Canary changes run before the remaining rollout. Fixer batches are bounded,
  472. verification happens between batches, and a failure-rate circuit breaker stops
  473. the run when more than half of at least three attempted fixes fail. The overall
  474. fix phase also has a deadline.
  475. ### Scoped patches, verification, and rollback
  476. The validated Fixer scope binds the repository root, base commit, approved bug
  477. IDs, and approved file paths before dispatch. Claimed line ranges stay in the
  478. fix plan as review context. Current validation does not independently prove
  479. line-range, symlink, submodule, or Git-metadata compliance after a patch, so
  480. review the final diff before merging.
  481. Impacted checks run after checkpoints, followed by the available full tests,
  482. typecheck, and build. A targeted post-fix Hunter pass examines only changed
  483. hunks for newly introduced Medium-or-higher bugs.
  484. Final statuses explain the result:
  485. | Status | Meaning |
  486. |---|---|
  487. | `FIXED` | Patch landed and verification found no new failure |
  488. | `FIX_REVERTED` | Patch introduced a failure and its checkpoint was reverted |
  489. | `FIX_FAILED` | The patch or its rollback could not be verified safely |
  490. | `PARTIAL` | A bounded patch landed but wider work remains |
  491. | `SKIPPED` | The fix was not attempted or the guarded run stopped |
  492. | `FIXER_BUG` | Post-fix review found a new Medium-or-higher bug |
  493. | `MANUAL_REVIEW` | The finding was not authorized for automatic remediation |
  494. Automatic per-bug rollback requires commit-backed checkpoints. A run without
  495. commit permission records uncommitted changes and may need manual restoration.
  496. Rollback is a guarded operation, not a promise that every repository state can
  497. always be restored automatically. Failures remain visible in `fix-report.json`.
  498. ## Structured JSON for CI/CD
  499. <p align="center">
  500. <img src="https://raw.githubusercontent.com/codexstar69/bug-hunter/183e0a957bd22ea5df83741cd31e396f68b14ae5/docs/images/2026-03-12-machine-readable-artifacts.png" alt="Machine-readable Bug Hunter artifacts for findings, challenges, verdicts, coverage, fix planning, reports, and CI/CD integration" width="100%">
  501. </p>
  502. `.bug-hunter/scan-report.json` is the joined machine-readable result for CI/CD,
  503. security dashboards, pull-request gates, or ticket automation. It records run
  504. identity, target, execution mode, scanned-file count, dependency status, counts,
  505. and the confirmed, dismissed, manual-review, and unreviewed sets.
  506. A shortened example:
  507. ```json
  508. {
  509. "schemaVersion": 1,
  510. "runId": "scan-2026-08-04-083000",
  511. "generatedAt": "2026-08-04T08:30:00.000Z",
  512. "mode": "local-sequential",
  513. "target": "src/",
  514. "filesScanned": 47,
  515. "threatModelLoaded": false,
  516. "dependencies": {
  517. "status": "not-applicable"
  518. },
  519. "counts": {
  520. "findings": 2,
  521. "confirmed": 1,
  522. "dismissed": 1,
  523. "manualReview": 0,
  524. "unreviewed": 0
  525. },
  526. "confirmed": [
  527. {
  528. "id": "BUG-1",
  529. "finding": {
  530. "bugId": "BUG-1",
  531. "severity": "Critical",
  532. "file": "src/api/users.ts",
  533. "claim": "User input reaches a SQL query"
  534. },
  535. "verdict": {
  536. "bugId": "BUG-1",
  537. "verdict": "REAL_BUG",
  538. "trueSeverity": "Critical",
  539. "confidenceScore": 96
  540. }
  541. }
  542. ],
  543. "dismissed": [
  544. {
  545. "id": "BUG-2",
  546. "finding": {
  547. "bugId": "BUG-2",
  548. "severity": "Medium",
  549. "file": "src/api/profile.ts",
  550. "claim": "The response may expose a protected field"
  551. },
  552. "verdict": {
  553. "bugId": "BUG-2",
  554. "verdict": "NOT_A_BUG",
  555. "trueSeverity": "Low",
  556. "confidenceScore": 91
  557. }
  558. }
  559. ],
  560. "manualReview": [],
  561. "unreviewed": []
  562. }
  563. ```
  564. Consumers should distinguish result meanings:
  565. - `confirmed` means the Referee accepted the finding.
  566. - `dismissed` means the available evidence disproved it.
  567. - `manualReview` means a human decision is still needed.
  568. - `unreviewed` means adversarial review did not finish.
  569. - `scanner-unsupported` means the requested dependency parser is unavailable.
  570. Only a completed report with no confirmed, manual-review, unreviewed, failed-coverage, or required-verification items can support a clean result for the scanned scope.
  571. ## Output files
  572. Runs write artifacts under `.bug-hunter/`. Add that directory to the audited repository's `.gitignore`.
  573. The main files are:
  574. | File | Generated when | Purpose |
  575. |---|---|---|
  576. | `triage.json` | Every scan | File classification, risk map, scan order, and budget |
  577. | `recon.json` | Multi-file scan | Prioritized risk tiers and Recon notes |
  578. | `hunter-findings.json` | Every scan | Canonical Hunter claims before adversarial review |
  579. | `skeptic.json` | Findings exist | Challenges, decisions, and counter-evidence |
  580. | `referee.json` | Findings exist | Canonical final verdicts |
  581. | `scan-report.json` | Completed scan | Joined run metadata, counts, and verdicts |
  582. | `report.md` | Completed scan | Human-readable final report |
  583. | `coverage.json` | Coverage loop | Per-file evidence states; parent chunk status alone cannot mark a file done |
  584. | `fix-strategy.json` | Plan or fix run | Remediation class for confirmed bugs |
  585. | `fix-plan.json` | Plan or fix run | Authorized canary and rollout plan |
  586. | `fixer-scope.json` | Plan or fix run | Repository, base commit, bug ID, and file boundary |
  587. | `fix-report.json` | Fix run | Verification, rollback, and final-status results |
  588. | `threat-model.md` | Threat-model run | STRIDE boundaries, assets, flows, and threats |
  589. | `dep-findings.json` | Dependency run | Audit results, scanner status, and reachability |
  590. | `state.json` | Persisted scan | Queue, attempts, file outcomes, findings, and plan reference |
  591. | `adaptive-plan.json` | Adaptive run | Risk- and benchmark-derived context, review, verification, and early-stop policy |
  592. | `retrieval-plan.json` | Indexed/retrieval run | Hypothesis-ranked files and symbol slices under a hard context budget |
  593. | `verification-report.json` | Hybrid verification requested | Compiler, test, build, static, reproduction, or fuzz results tied to findings |
  594. | `benchmark-report.json` | Benchmark gate | Precision, recall, calibration, stability, cost, latency, and Pareto metrics |
  595. See [outputs](docs/how-it-works.md#output-contract) for the complete artifact contract.
  596. ## Supported languages and frameworks
  597. Source analysis supports JavaScript, TypeScript, Python, Go, Rust, Java,
  598. Kotlin, Ruby, PHP, C#, Swift, Scala, C, and C++ through agent reasoning and
  599. repository evidence.
  600. Dependency audit parsing and reachability currently support JavaScript and TypeScript projects using npm, pnpm, Yarn, or Bun lockfiles. Other ecosystems return `scanner-unsupported`; Bug Hunter does not report them as clean.
  601. Commonly recognized server and web stacks include Express, Fastify, Next.js,
  602. Django, Flask, FastAPI, Gin, Echo, Actix, Spring Boot, Rails, and Laravel.
  603. Framework support is not a separate parser allowlist: Recon identifies the
  604. repository stack, the agents reason from the checked source, and documentation
  605. lookup supplies library context when available.
  606. Language support means the agent can audit source behavior. It does not mean
  607. that every language has a dependency-audit parser, compiler integration,
  608. runtime sandbox, or framework-specific benchmark.
  609. ## Skill argument reference
  610. These are arguments sent to the installed skill through your coding agent:
  611. | Argument | Behavior |
  612. |---|---|
  613. | No arguments | Scan the current repository once without editing |
  614. | `src/` or `file.ts` | Scan a specific path |
  615. | `-b branch-name` | Scan a branch diff against the default base |
  616. | `-b branch --base dev` | Scan a branch diff against a chosen base |
  617. | `--staged` | Scan Git-staged changes |
  618. | `--pr` or `--pr current` | Review the current pull request |
  619. | `--pr recent` or `--last-pr` | Review the most recently updated open pull request |
  620. | `--pr 123` | Review a specific pull-request number |
  621. | `--review-pr` | Alias for `--pr current` |
  622. | `--pr-security` | Changed-code security review with threat and dependency context |
  623. | `--scan-only` or `--review` | Request report-only mode |
  624. | `--plan-only` or `--plan` | Write strategy and plan artifacts, then stop |
  625. | `--fix` | Permit reviewed fixes after confirmed verdicts |
  626. | `--approve` | Request the host agent's reviewed/default permission mode |
  627. | `--safe` | Alias for `--fix --approve` |
  628. | `--dry-run` or `--preview` | Build strategy and fix-plan output without editing files |
  629. | `--autonomous` | Permit unattended fixing |
  630. | `--auto-commit` | Grant commit permission for an authorized fix plan |
  631. | `--loop` | Continue until every queued file has a terminal recorded outcome |
  632. | `--no-loop` | Explicitly keep the default single-pass behavior |
  633. | `--deps` | Add supported dependency CVE scanning and reachability |
  634. | `--threat-model` | Generate or reuse a STRIDE threat model |
  635. | `--security-review` | Run the bundled repository security-review workflow |
  636. | `--validate-security` | Add focused exploitability validation |
  637. Arguments compose:
  638. ```text
  639. /bug-hunter --deps --threat-model src/
  640. /bug-hunter --pr-security --plan
  641. /bug-hunter --fix --approve src/auth
  642. ```
  643. Do not combine `--scan-only` or `--review` with `--fix`, `--approve`, `--safe`,
  644. or `--autonomous`. The current control plane treats contradictory read-only and mutation intent as invalid/safety-sensitive rather than silently broadening authority.
  645. The terminal `bug-hunter` CLI has a different job: install or upgrade, inspect
  646. metadata, and verify the skill. Removal is manual; see
  647. [agent installation](docs/agent-installation.md#remove).
  648. ## Safety model
  649. - No flags means scan-only and single-pass.
  650. - `--loop` changes coverage completion behavior; it does not grant edit authority.
  651. - Do not combine report-only and mutation intent; use one explicit authority model.
  652. - `--fix` permits reviewed edits after Referee/remediation gating.
  653. - `--approve` requests reviewed/default host permissions; prompt behavior is
  654. host-dependent.
  655. - `--plan` stops before edits.
  656. - `--preview` builds remediation strategy and plan output without source edits.
  657. - `--autonomous` permits unattended eligible edits.
  658. - `--auto-commit` separately grants commit permission for the approved plan;
  659. inspect harvested commit paths before merging.
  660. - Fix plans record bug IDs, files, and claimed line ranges. The validated
  661. scope independently enforces bug IDs and file paths before dispatch.
  662. - Required hybrid-verification failure blocks Fixer authorization.
  663. - Source mutation, deletion, unreadability, or repository escape fails the affected scan scope closed.
  664. - Worktree cleanup fails closed when preservation cannot be proven.
  665. - User-owned files are preserved during managed skill upgrades.
  666. Review [SECURITY.md](SECURITY.md) before using autonomous fixing in a sensitive repository.
  667. ## Project architecture
  668. ```text
  669. bug-hunter/
  670. ├── SKILL.md # Compact orchestration and permission control plane
  671. ├── bin/bug-hunter # Installer, updater, info, and doctor CLI
  672. ├── docs/ # Precision, measurable-protocol, installation, and usage guides
  673. ├── modes/ # Scan, scale, loop, dispatch, and fix workflows
  674. ├── skills/
  675. │ ├── recon/ # Architecture and attack-surface mapping
  676. │ ├── hunter/ # Behavioral code and security analysis
  677. │ ├── skeptic/ # Adversarial false-positive challenge
  678. │ ├── referee/ # Independent verdict and security enrichment
  679. │ ├── fixer/ # Authorized patch execution
  680. │ ├── doc-lookup/ # Context Hub and Context7 verification
  681. │ ├── commit-security-scan/ # Pull-request and changed-code security review
  682. │ ├── security-review/ # Full repository security workflow
  683. │ ├── threat-model-generation/
  684. │ └── vulnerability-validation/
  685. ├── schemas/ # Canonical JSON artifact contracts
  686. ├── scripts/ # Triage, state, benchmark, adaptive, retrieval, verification, cache, and safety tools
  687. ├── templates/ # Payload and report templates
  688. └── test-fixture/ # Source-only benchmark with planted bugs
  689. ```
  690. The role skills are canonical. Compatibility prompts are generated from them,
  691. and CI checks that generated files stay in sync.
  692. ## Documentation
  693. - [Getting started](docs/getting-started.md)
  694. - [Agent installation](docs/agent-installation.md)
  695. - [Usage guide](docs/usage-guide.md)
  696. - [CLI reference](docs/cli-reference.md)
  697. - [How it works](docs/how-it-works.md)
  698. - [Precision protocol](docs/precision-protocol.md)
  699. - [Measurable world-class protocol](docs/world-class-protocol.md)
  700. - [Troubleshooting](docs/troubleshooting.md)
  701. - [Security policy](SECURITY.md)
  702. - [Contributing](CONTRIBUTING.md)
  703. - [Changelog](CHANGELOG.md)
  704. - [Agent orchestration contract](SKILL.md)
  705. ## Development
  706. From a source checkout:
  707. ```bash
  708. pnpm install --frozen-lockfile
  709. pnpm quality:world-class
  710. ```
  711. `quality:world-class` checks generated runtime assets, the complete regression suite, the benchmark gate, runtime preflight, and package inventory. Use `pnpm test` for the current test count instead of relying on a copied number in documentation.
  712. The source repository also contains a deterministic hidden-label benchmark harness. Its bundled labels are a calibration fixture, not proof of universal superiority; production claims should use privately held historical bugs and clean repositories. See [the measurable protocol](docs/world-class-protocol.md).
  713. The planted-bug fixture exists only in the source repository and is useful for
  714. behavioral calibration:
  715. ```text
  716. Use the bug-hunter skill to scan test-fixture/. Do not edit files.
  717. ```
  718. See [CONTRIBUTING.md](CONTRIBUTING.md) before changing runtime contracts.
  719. ## License
  720. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.