nealbridges/VulnHunter

What it is

This fork of Capital One's VulnHunter adds four concrete changes to the upstream agentic SAST tool: environment-variable-driven install paths, a containerized exploit-validation discipline, measured-impact PoCs, and an unattended operator (vulnhunter-run/vh). It ships three composable skills — /vulnhunt (scanner), /vulnhunter-fix (remediation), /vulnhunt-fix-verify (read-only verifier) — plus vulnhunter-agent/ for headless CI use and harness/ for batch scanning and benchmarking.

How it works

The core pipeline: forward attacker-path analysis → falsification engine (tries to disprove its own finding) → evidence-backed remediation → PoC requirement. The verifier (/vulnhunt-fix-verify) runs under a restricted tool envelope — Read/Write/Edit/Glob/Grep/subagent only, no shell execution, no network access — and requires the caller to pre-create the output directory. The vh CLI is a deterministic, model-free companion that clones targets, locates results directories, and writes/validates a scan_manifest.json; it records the hunt's exit code (0–4, invalid values normalize to 1) but never populates findings itself — that's left to vulnhunter-agent/.

Preconditions / Affected

Requires an agent harness with a capable reasoning model (tested against Claude Code, Codex, Grok-style harnesses) and Python 3.12+ for the runtime agent and benchmarking harness. The fixer additionally needs git, an authenticated GitHub CLI (gh), and pip install -e ".[dev]" inside vulnhunter-fix/. Install directories (VULNHUNT_SKILLS_DIR, VULNHUNT_AGENTS_DIR) must be set explicitly — the installer refuses to guess and fails loudly if unset, specifically to avoid silently installing into the wrong harness's directory on multi-harness machines.

What to do

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

Set VULNHUNT_SKILLS_DIR/VULNHUNT_AGENTS_DIR to the target harness's own directories first (e.g. $GROK_HOME/skills). Then run /vulnhunt in a session on the harness's most capable model. For CI/batch use:

cd harness && pip install -e ".[dev]"
python -m local_harness.batch.run scan
python -m local_harness.benchmark.run

Re-run install.sh after any update — the installer copies files rather than symlinking, since symlinks break glob/find inside subagents.

Caveats

The page reports an internal six-run benchmark (same commit, five harness/model stacks) where unvalidated exploit discretion produced a 3-to-42 finding spread and opposite verdicts on the same sink depending on whether validation used a mock or a real server — the containerized-validation fix for this is explicitly still in progress (on the roadmap, not shipped). The independent adversarial verifier (separate from the hunter grading its own findings) is also roadmap-only. The project's stated design target is open-weight/abliterated models, not frontier vendor models, because the latter apply dual-use cyber safeguards that can trip rate limits during aggressive exploitation steps.