Skip to content
Back to search

VulnHunter

Agentic AI security scanner that hunts exploitable vulnerabilities like an adversary, proves them with executable PoCs, and fixes them test-first. A maintained fork of Capital One's VulnHunter, rebuilt for any agent harness.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nealbridges--vulnhunter/badge.svg)](/listings/nealbridges--vulnhunter)

HTML

<a href="/listings/nealbridges--vulnhunter"><img src="/api/listings/nealbridges--vulnhunter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Clone the repository
git clone https://github.com/nealbridges/VulnHunter.git
cd VulnHunter

# Skills and agents directories are required. This script does not guess.
# If GROK_HOME is set, use that home. Do not use ~/.grok when GROK_HOME
# points somewhere else, and do not use ~/.claude/skills unless this
# process is Claude Code.
#   VULNHUNT_SKILLS_DIR="$GROK_HOME/skills" \
#   VULNHUNT_AGENTS_DIR="$GROK_HOME/agents" \
#   ./install.sh
./install.sh

On Windows, use the `.cmd` equivalents from a `cmd.exe` or PowerShell prompt:

git clone https://github.com/nealbridges/VulnHunter.git
cd VulnHunter

REM Set VULNHUNT_SKILLS_DIR to this harness's skills directory first.
.\install.cmd

REM (Optional) To clean up or remove installed skills
REM .\uninstall.cmd

> [!NOTE] > `install.sh`/`install.cmd` copy files directly (rather than symlinking) because symlinks can break `find`/`glob` functionality inside subagents. Re-run the install script after pulling updates to refresh your local environment. > > **Any harness:** the skills are plain prompt files. `install.sh` copies them > into `VULNHUNT_SKILLS_DIR`, copies `agents/vulnhunter.md` into > `VULNHUNT_AGENTS_DIR` when that is set, and writes a `vh` launcher to > `VULNHUNT_BIN_DIR` or `~/.local/bin`. `~/.local/bin` has to be on `PATH`. > A model installing into the harness it is running uses `$GROK_HOME/skills` > and `$GROK_HOME/agents` when `GROK_HOME` is set.

---

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.

README.md · README · 292 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # VulnHunter
  2. > [!NOTE]
  3. > **A maintained fork** of [Capital One's
  4. > VulnHunter](https://github.com/capitalone/VulnHunter) (Apache-2.0) — built to
  5. > run on **any agent harness**, not just Claude Code. This fork's focus:
  6. > **harness portability**, **sandboxed (containerized) exploit validation**,
  7. > and **measured-impact PoCs**. See
  8. > [Why the changes](#why-the-changes) ·
  9. > [What this fork changes](#what-this-fork-changes) ·
  10. > [The numbers](#the-numbers-behind-the-fork).
  11. > **From pattern-matching to provability.**
  12. VulnHunter is an open-source, **agentic AI security tool** that applies proactive, attacker-first analysis directly to source code.
  13. Unlike traditional, passive SAST scanners that flag suspicious patterns and often cause false positives, VulnHunter reasons like an adversary. It **identifies** which defects are actually exploitable, maps prospective attack paths, and proposes targeted, evidence-backed fixes.
  14. Modern software supply chains are deeply interconnected. A single vulnerability in a widely-used open-source component can ripple across thousands of enterprises simultaneously.
  15. VulnHunter was developed internally at Capital One and open-sourced for the community. This fork carries that work forward — same methodology, reworked to run on **any agent harness**, with **sandboxed (containerized) exploit validation** and **measured-impact PoCs** as the roadmap. See [What this fork changes](#what-this-fork-changes).
  16. ----
  17. > **Dual-use caution**
  18. > VulnHunter performs dual-use cybersecurity work (vulnerability discovery and
  19. > exploitation). Expect guardrails: most commercially available models apply
  20. > dual-use cyber safeguards, and aggressive exploitation behavior can trip
  21. > rate limits or usage flags. VulnHunter's development and testing ran on
  22. > open-weight, community-provided models — de-risked, abliterated, and
  23. > uncensored — which are the models likely to matter for organizational use
  24. > going forward. Audit only code you own or are otherwise authorized to
  25. > audit.
  26. ---
  27. > [!IMPORTANT]
  28. > **Prerequisites & Model Requirements**
  29. > VulnHunter's methodology is built to run on **open-weight, community-provided
  30. > models** — the de-risked, abliterated, uncensored ones organizations can
  31. > actually deploy. A capable reasoning model is required; the strongest model
  32. > your harness offers gives the best results, but the methodology does not
  33. > depend on a specific vendor's frontier model. **You supply your own model
  34. > access.**
  35. ---
  36. ## What this fork changes
  37. | Capability | Upstream (Capital One) | This fork | Status |
  38. | :--- | :--- | :--- | :--- |
  39. | **Harness portability** | Skills invoke Claude Code specifically; installer targets `~/.claude/skills`; model gates hardcode Opus; harness pins `claude-opus-4-8` | Skills are harness-portable prompt files (any harness with a skills directory + subagents); `VULNHUNT_SKILLS_DIR` / `VULNHUNT_AGENTS_DIR` / `VULNHUNT_BIN_DIR` / `VULNHUNT_HOST_CMD` / `VULNHUNT_MODEL` environment contract; model gates rephrased to "your harness's most capable reasoning model" | **Shipped** |
  40. | **No-guess installer** | `install.sh` assumes `~/.claude/skills` | Explicit directories, honors `GROK_HOME` semantics, writes the `vh` launcher to `VULNHUNT_BIN_DIR`/`~/.local/bin`, installs the `vulnhunter-run` skill + agent definition; Windows `.cmd` equivalents updated | **Shipped** |
  41. | **`vulnhunter-run` operator skill** | — (absent) | Unattended operator: clone → hunt → find-results → write/validate the scan manifest, with explicit stop rules and no improvisation | **Shipped** |
  42. | **Benchmark/judge hardening** | Fixed model + basic retry | Model via environment, retry/backoff configuration, `analyze_misses` pipeline loss-point tracing, per-finding history tracking | **Shipped** |
  43. | **Harness-neutral report language** | Claude-specific prose throughout the skills | Harness-neutral tool language (Agent → subagent, Claude CLI → harness session) | **Shipped** |
  44. | **Sandbox-first exploit validation** | Exploit tests may be static traces; runtime choice ad hoc | Docker-first runtime provisioning; the runtime recorded per finding; Medium+ severity must execute | **In progress** |
  45. | **Measured-impact PoCs** | PoCs are documents; impact asserted | Executable PoC + impact number in the finding (rows exposed, requests amplified, key-hours stranded) | **In progress** |
  46. ## Why the changes
  47. VulnHunter's methodology is host-agnostic by nature: it is prompt procedure, not tool binding. The upstream project grew up inside Claude Code — a coherent choice, and the right first home. But the agent-harness landscape has broadened, and a security methodology that installs into only one of them stops being an audit capability and starts being a vendor feature. This fork makes four changes, each with a reason.
  48. ### 1. Harness portability — your team's harness is not our harness
  49. Every skill here is a portable prompt file with an explicit environment contract (`VULNHUNT_SKILLS_DIR`, `VULNHUNT_AGENTS_DIR`, `VULNHUNT_MODEL`, `VULNHUNT_HOST_CMD`), and the model gates now ask for *your harness's most capable reasoning model* instead of a specific product. **Better means:** the same methodology installs into whatever harness your team already runs — and becomes comparable *across* harnesses in benchmark runs, which is how this fork is developed.
  50. ### 2. A no-guess installer — "where do skills go" is a per-harness answer
  51. The upstream installer copied skills into `~/.claude/skills` unconditionally. On a machine running two harnesses — or a harness with a relocated home — that guess installs into the wrong place, silently. The fork's installer asks, or takes environment variables, and fails loudly with the exact instruction when the answer is missing. **Better means:** safe on multi-harness machines, correct under relocated homes, loud instead of silent when misconfigured.
  52. ### 3. Execution depth as a recorded decision — "provability" should not depend on model instinct
  53. The original design already demands falsification and exploit tests. What it left open was *how hard* to work to actually execute them: static trace, mocked test, or a real containerized server. In one six-run benchmark against a single commit, that discretion produced anywhere from 3 to 42 findings — and opposite verdicts on the same sink, one proven against a mock, one closed by a test against a real server. This fork adds a runtime-provisioning procedure (Docker-first, recorded per finding) and a PoC discipline where impact is **measured** — rows leaked, ×-amplification, key-hours stranded — not narrated. **Better means:** a finding's validity no longer depends on which model had the instinct to stand up a container. *(In progress — the build plan is on the public roadmap; ask in issues or watch the repo's Discussions.)*
  54. ### 4. Operator ergonomics — a remediation loop compounds when it runs nightly
  55. New in this fork: `vulnhunter-run`, an unattended operator that clones, hunts, locates results, and writes and validates the scan manifest with explicit stop rules. The benchmark tooling gains model configuration via environment, retry/backoff knobs, and loss-point analysis for missed findings. **Better means:** the difference between a tool you demo and a tool you schedule.
  56. ## The numbers behind the fork
  57. We benchmark VulnHunter against itself: six full scans of one real production Go service — same commit, five harness/model stacks. The numbers below are from those runs, and they're why this fork exists.
  58. | | |
  59. |---|---|
  60. | **14×** | spread in confirmed findings across runs of the same commit. The process measuring itself was the first vulnerability — closing that gap is this fork's build plan. |
  61. | **42/42** | confirmed findings carried executable exploit tests — every one PASS, every one with its own PoC. No finding ships on a hunch. |
  62. | **55%** | of candidate findings eliminated or downgraded by the adversarial verification pass before reaching you. Others scan. VulnHunter litigates. |
  63. | **315** | attacker-controlled inputs inventoried in a single scan — every one traced, every disposition written. Completeness is a discipline, not an aspiration. |
  64. | **20/20** | adversarial payloads executed against a live server in one run — outcome-measured, not asserted. |
  65. <details>
  66. <summary><strong>Where these numbers come from</strong></summary>
  67. Six complete VulnHunter scans were run against one commit of the same
  68. production Go service, across five harness/model stacks, over roughly three
  69. weeks. Every figure above traces to retained scan artifacts — per-input
  70. disposition tables, adversarial verdict tables, PoCs, and executed exploit
  71. tests. Raw outputs are retained by the maintainer; ask, or re-run it
  72. yourself.
  73. </details>
  74. ---
  75. ## Why VulnHunter is Different
  76. * **Attacker-First Forward Analysis:** Conventional tools often leverage "sink-first" analysis, looking at potentially dangerous code patterns to search backward for a hypothetical attacker, flooding teams with false positives. VulnHunter flips this model to simulate a bad actor's exact journey. It begins at potential attacker-accessible entry points (APIs, network messages, file uploads) and reasons *forward* to evaluate whether an attacker can truly break through.
  77. * **Falsification Engine:** After finding a potential vulnerability, VulnHunter runs a structured reasoning workflow specifically designed to *disprove* its own argument. It searches for flawed assumptions, logic gaps, or security controls that would block the attack. It is designed to immediately discard findings that rely on unsupported assumptions. What reaches you is a high-priority, actionable defect. On the roadmap: an **independent adversarial verifier** — a separate agent whose only job is to disprove the finding, rather than asking the hunter to grade its own homework (see the build plan).
  78. * **Evidence-Backed Remediation:** When a defect survives the falsification engine, VulnHunter maps the exact exploit path, explains the structural flaw, details the specific capabilities or access an attacker would gain, and generates focused, targeted code changes for review.
  79. * **PoC or It Didn't Happen:** A vulnerability isn't a vulnerability until it's *proven*. Every confirmed finding carries a proof-of-concept — ideally executed, with the impact **measured** (rows exposed, requests amplified, credentials stranded) rather than narrated. Findings without working PoCs are labeled as such, so you always know what you're looking at.
  80. ---
  81. ## The Closed Loop: Hunt → Fix → Verify
  82. VulnHunter ships as three composable agent skills that form a complete, automated remediation loop:
  83. | Skill | Phase | Core Responsibility |
  84. | :--- | :--- | :--- |
  85. | **`/vulnhunt`** | **Hunt** | Maps entry points to dangerous sinks. Filters findings through a multi-stage falsification pipeline (Recon → Parallel Hunt → Adversarial Disprove → Capability Filter). Emits only verified issues with an executable exploit and a proposed fix. |
  86. | **`/vulnhunter-fix`** | **Fix** | Developer-led, test-driven remediation. It writes an exploit demo, creates a failing security test (**RED**), implements the code fix (**GREEN**), verifies the exploit is blocked without regressions, and cuts a reviewable PR. |
  87. | **`/vulnhunt-fix-verify`** | **Verify** | A completely separate, read-only agent that independently validates whether a finding was successfully remediated. It emits a per-finding verdict so fixes are proven, not taken on faith. |
  88. > **Note:** For running this loop unattended at scale, `vulnhunter-agent/` wraps the scanner in a headless runtime, while `harness/` drives it across multiple repositories in batch.
  89. > **On the naming:** the suite is **VulnHunter**, but the core scanner command is `/vulnhunt` (and the verifier `/vulnhunt-fix-verify`) — the shorter form is intentional, not a typo. The `/vulnhunter-fix` remediation skill and the `vulnhunter-agent/` runtime keep the full spelling.
  90. ---
  91. ## Repository Layout
  92. Each component is organized into a self-contained subtree:
  93. | Path | Description |
  94. | :--- | :--- |
  95. | `vulnhunt/` | The core `/vulnhunt` scanner skill (Prompt-only: `SKILL.md` + phases). See [`vulnhunt/README.md`](vulnhunt/README.md). |
  96. | `vulnhunter-fix/` | The `/vulnhunter-fix` skill, its companion Python helper package, and tests. See [`vulnhunter-fix/README.md`](vulnhunter-fix/README.md). |
  97. | `vulnhunt-fix-verify/` | The `/vulnhunt-fix-verify` standalone verification skill (Prompt-only). See [`vulnhunt-fix-verify/README.md`](vulnhunt-fix-verify/README.md). |
  98. | `vulnhunter-agent/` | Config-driven headless runtime wrapper that runs scans and files GitHub issues. See [`vulnhunter-agent/README.md`](vulnhunter-agent/README.md). |
  99. | `harness/` | Developer tooling for running large batch-scans and benchmarking detection accuracy. See [`harness/README.md`](harness/README.md). |
  100. | `vh/` | Deterministic operator CLI for a single scan: clone, find the results directory, write and validate the scan manifest, and launch the host's headless command. No model SDK. |
  101. ---
  102. ## Requirements & Setup
  103. ### Prerequisites
  104. * An agent harness (e.g. Claude Code, omp, Codex, or similar) with access to a capable reasoning model — open-weight, community-provided models are the primary development target. **You supply your own model access.**
  105. * Python 3.12+ (Required only for the runtime agent and the benchmarking harness).
  106. * *Responsibility Check:* Ensure you are only scanning code bases you are explicitly authorized to analyze.
  107. ### Installation
  108. ```bash
  109. # Clone the repository
  110. git clone https://github.com/nealbridges/VulnHunter.git
  111. cd VulnHunter
  112. # Skills and agents directories are required. This script does not guess.
  113. # If GROK_HOME is set, use that home. Do not use ~/.grok when GROK_HOME
  114. # points somewhere else, and do not use ~/.claude/skills unless this
  115. # process is Claude Code.
  116. # VULNHUNT_SKILLS_DIR="$GROK_HOME/skills" \
  117. # VULNHUNT_AGENTS_DIR="$GROK_HOME/agents" \
  118. # ./install.sh
  119. ./install.sh
  120. ```
  121. On Windows, use the `.cmd` equivalents from a `cmd.exe` or PowerShell prompt:
  122. ```bat
  123. git clone https://github.com/nealbridges/VulnHunter.git
  124. cd VulnHunter
  125. REM Set VULNHUNT_SKILLS_DIR to this harness's skills directory first.
  126. .\install.cmd
  127. REM (Optional) To clean up or remove installed skills
  128. REM .\uninstall.cmd
  129. ```
  130. > [!NOTE]
  131. > `install.sh`/`install.cmd` copy files directly (rather than symlinking) because symlinks can break `find`/`glob` functionality inside subagents. Re-run the install script after pulling updates to refresh your local environment.
  132. >
  133. > **Any harness:** the skills are plain prompt files. `install.sh` copies them
  134. > into `VULNHUNT_SKILLS_DIR`, copies `agents/vulnhunter.md` into
  135. > `VULNHUNT_AGENTS_DIR` when that is set, and writes a `vh` launcher to
  136. > `VULNHUNT_BIN_DIR` or `~/.local/bin`. `~/.local/bin` has to be on `PATH`.
  137. > A model installing into the harness it is running uses `$GROK_HOME/skills`
  138. > and `$GROK_HOME/agents` when `GROK_HOME` is set.
  139. ---
  140. ## Usage Guide
  141. ### 1. Run the Scanner
  142. Install the `vulnhunt` skill into your harness (see above), open a session on the host's most capable reasoning model, and invoke:
  143. ```text
  144. /vulnhunt
  145. ```
  146. The skill also loads `vulnhunt/phases/`. If your harness does not follow a skill's subdirectories on its own, add that `phases/` directory to the session the same way you add any other path.
  147. ### 2. Run the Fixer
  148. The fixer requires `git`, the GitHub CLI (`gh`) authenticated to your target repositories, and its Python helpers installed (`pip install -e ".[dev]"` inside the `vulnhunter-fix/` directory).
  149. Install the `vulnhunter-fix` skill and invoke:
  150. ```text
  151. /vulnhunter-fix
  152. ```
  153. *See [`vulnhunter-fix/README.md`](vulnhunter-fix/README.md) for advanced operational modes and configuration settings.*
  154. ### 3. Run the Fix Verifier
  155. The verifier runs strictly read-only over trusted roots under a tight tool envelope (Read/Write/Edit/Glob/Grep/subagent — **no shell execution, no network access**). The caller must pre-create the output (`out`) directory.
  156. Install the `vulnhunt-fix-verify` skill (it reads `vulnhunt-fix-verify/phases/`) and invoke:
  157. ```text
  158. /vulnhunt-fix-verify repo=<abs_path> report=<abs_path> fixed=VULN-001,... out=<abs_path> [comments=<abs_path>] [additional_repos=<path1>,<path2>]
  159. ```
  160. ---
  161. ## Automation & Scale
  162. ### Headless Runtime Agent (`vulnhunter-agent/`)
  163. For non-interactive or CI/CD pipelines, `vulnhunter-agent/` wraps the scanner into a headless workflow. It clones targets, executes `/vulnhunt`, publishes results, and opens GitHub issues for confirmed bugs. Model and credential wiring for that runtime live in its own README; the skills above do not depend on it.
  164. Review the [`vulnhunter-agent/README.md`](vulnhunter-agent/README.md) for deployment blueprints.
  165. ### Local Harness (`harness/`)
  166. The `harness/` directory provides workstation-scale developer tooling. To initialize, run `cd harness && pip install -e ".[dev]"`.
  167. #### Batch Scanning
  168. Manage your target list in `harness/local_harness/batch/REPO_LIST.txt` (one GitHub URL per line, lines starting with `#` are ignored):
  169. ```bash
  170. cd harness
  171. python -m local_harness.batch.run scan # Clone and scan every repo in the list
  172. python -m local_harness.batch.run scan --resume # Skip repositories already processed
  173. python -m local_harness.batch.run status # Monitor progress across your batch
  174. python -m local_harness.batch.run collect # Gather all findings for centralized review
  175. ```
  176. #### Benchmarking Mode
  177. Evaluate scanner accuracy against a known-vulnerable vulnerability corpus (Clone → Scan → LLM-Judge → Tally Metrics):
  178. ```bash
  179. python -m local_harness.benchmark.run # Execute full benchmark run
  180. python -m local_harness.benchmark.run --repos "name" # Benchmark a single target repository
  181. python -m local_harness.benchmark.run --tally-only # Re-generate the analytical report only
  182. ```
  183. > **Starter corpus:** `harness/local_harness/benchmark/ground_truth/` ships six findings across OWASP Juice Shop, WebGoat, and NodeGoat, each pinned to a public commit. Add more files as `ground_truth/<repo>.json`. `finding_id` values must be unique across the whole corpus. Schema samples live in `EXAMPLE.json.template` and are not loaded. The runner validates every file before cloning.
  184. ### Operator CLI (`vh/`)
  185. `vh` is a deterministic, model-free companion for a single scan run. It sequences the mechanical steps around a hunt and validates the output shape:
  186. ```bash
  187. vh clone <url> --dest <dir> # shallow-clone the target
  188. vh find-results <checkout> # print *_VULNHUNT_RESULTS_* directories
  189. vh write-manifest <results-dir> --exit-code 4 # write scan_manifest.json; record the agent exit code
  190. vh validate-manifest <results-dir> # check the manifest against the schema rules
  191. VULNHUNT_HOST_CMD="<one-shot>" vh host <prompt-file> # run the harness's headless one-shot
  192. ```
  193. `--exit-code` records the exit code the hunt actually produced (0-4; an invalid value is recorded as 1). When the flag is omitted, the exit code is derived from the results directory: a non-empty `README.md` scan report means 0, anything else means 1. `vh write-manifest` writes a schema-shaped stub manifest — it never populates `findings`; the headless runtime agent (`vulnhunter-agent/`) is the writer that extracts real findings from the scan report.
  194. ---
  195. ## Running Tests
  196. Each Python component maintains its own isolated testing suite. Run them using `pytest`:
  197. ```bash
  198. cd harness && pip install -e ".[dev]" && python -m pytest tests/ --cov=local_harness
  199. cd vulnhunter-fix && pip install -e ".[dev]" && python -m pytest -q
  200. cd vulnhunter-agent && pip install -e ".[dev]" && python -m pytest -q
  201. python -m pytest vh/tests -q # from the repository root; vh is a plain package
  202. ```
  203. ---
  204. ## Contributing, Security & License
  205. * **A Note on Models:** VulnHunter's methodology is developed against open-weight, community-provided models — de-risked, abliterated, and uncensored — the deployment reality most organizations are heading toward. The skills are harness-portable prompt files that work with any agent harness; only the headless runtime (`vulnhunter-agent/`) and `harness/` remain Claude-Code-based.
  206. * **Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md) to propose core framework improvements, prompt updates, or wider model support configurations.
  207. * **Security:** Review [SECURITY.md](SECURITY.md) for instructions on how to safely report security vulnerabilities found within VulnHunter itself.
  208. * **License:** Distributed under the terms of the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

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