vulnhunter-security-scanner
Agentic AI security tool that applies attacker-first analysis to source code, using falsification-based reasoning to minimize false positives
How do I install this agent skill?
npx skills add https://github.com/reason-machines/security-skills --skill vulnhunter-security-scannerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The VulnHunter Security Scanner is a specialized developer tool for performing 'attacker-first' source code analysis. It originates from Capital One, a well-known organization, and adheres to standard development practices for security research tools, including local installation and configuration. The primary security consideration is the risk of indirect prompt injection, which is inherent in tools designed to process and analyze untrusted source code.
- Socketwarn
1 alert: gptSecurity
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
VulnHunter Security Scanner
Skill by ara.so — Security Skills collection.
VulnHunter is an agentic AI security tool that applies proactive, attacker-first analysis directly to source code. Unlike traditional SAST scanners that flag patterns and generate false positives, VulnHunter reasons like an adversary: it identifies which defects are actually exploitable, maps attack paths, and proposes evidence-backed fixes.
Core Concepts
Attacker-First Forward Analysis: Starts at attacker-accessible entry points (APIs, file uploads, network messages) and reasons forward to evaluate whether an attacker can truly break through, rather than working backward from dangerous sinks.
Falsification Engine: After finding a potential vulnerability, VulnHunter runs a structured workflow to disprove its own argument, searching for flawed assumptions, logic gaps, or security controls that would block the attack.
Three-Skill Loop:
/vulnhunt- Hunt for vulnerabilities/vulnhunter-fix- Fix verified issues with test-driven remediation/vulnhunt-fix-verify- Independently verify fixes
Prerequisites
- Claude Code CLI authenticated with access to Claude Opus (required)
- Python 3.12+ (for agent runtime and harness tooling)
- Git and GitHub CLI (
gh) authenticated (for fix workflow) - Anthropic Cyber Verification Program enrollment recommended to avoid cyber safeguard blocks
Installation
# Clone the repository
git clone https://github.com/capitalone/vulnhunter.git
cd vulnhunter
# Install skills to ~/.claude/skills/
./install.sh
# Optional: Uninstall
# ./uninstall.sh
Note: install.sh copies files (not symlinks) because symlinks can break subagent functionality. Re-run after pulling updates.
Core Usage
1. Running the Scanner (/vulnhunt)
# Launch Claude Code with the vulnhunt skill
claude --model opus \
--add-dir ~/.claude/skills/vulnhunt \
--add-dir ~/.claude/skills/vulnhunt/phases
# Inside Claude Code session:
/vulnhunt
The scanner will:
- Recon Phase: Map entry points and dangerous sinks
- Parallel Hunt: Trace paths from entries to sinks
- Adversarial Disprove: Apply falsification to eliminate false positives
- Capability Filter: Verify actual exploitability
- Output: Emit only verified issues with exploit paths and proposed fixes
2. Running the Fixer (/vulnhunter-fix)
First install Python dependencies:
cd vulnhunter-fix
pip install -e ".[dev]"
Launch with the fix skill:
claude --model opus --add-dir ~/.claude/skills/vulnhunter-fix
# Inside Claude Code session:
/vulnhunter-fix
The fixer implements RED-GREEN-REFACTOR workflow:
- Write exploit demonstration
- Create failing security test (RED)
- Implement code fix (GREEN)
- Verify exploit blocked without regressions
- Cut reviewable PR
3. Running the Verifier (/vulnhunt-fix-verify)
The verifier runs read-only validation on fixes. Pre-create the output directory:
mkdir -p /tmp/verify-output
claude --model opus \
--add-dir ~/.claude/skills/vulnhunt-fix-verify \
--add-dir ~/.claude/skills/vulnhunt-fix-verify/phases
# Inside Claude Code session:
/vulnhunt-fix-verify \
repo=/absolute/path/to/repo \
report=/absolute/path/to/vulnhunt_report.md \
fixed=VULN-001,VULN-003 \
out=/tmp/verify-output \
comments=/absolute/path/to/pr_comments.json \
additional_repos=/path/to/lib1,/path/to/lib2
Parameters:
repo- Absolute path to repository rootreport- Absolute path to VulnHunt findings reportfixed- Comma-separated list of vulnerability IDs to verifyout- Absolute path to output directory (must exist)comments- (Optional) Path to PR review comments JSONadditional_repos- (Optional) Comma-separated paths to dependency repos
Headless Runtime Agent
For CI/CD or non-interactive pipelines:
cd vulnhunter-agent
pip install -e ".[dev]"
# Configure via config.yaml
cp config.example.yaml config.yaml
# Edit config.yaml with your settings
Example config.yaml:
anthropic_api_key: ${ANTHROPIC_API_KEY}
model: claude-opus-4-20250514
github_token: ${GITHUB_TOKEN}
targets:
- url: https://github.com/org/repo
branch: main
language: python
create_issues: true
output_dir: ./scan-results
max_concurrent: 3
Run headless scan:
python -m vulnhunter_agent.main --config config.yaml
The agent will:
- Clone target repositories
- Execute
/vulnhuntskill - Parse findings
- Create GitHub issues for verified vulnerabilities
Batch Scanning with Harness
For workstation-scale batch operations:
cd harness
pip install -e ".[dev]"
# Configure target list
echo "https://github.com/org/repo1" >> local_harness/batch/REPO_LIST.txt
echo "https://github.com/org/repo2" >> local_harness/batch/REPO_LIST.txt
# Lines starting with # are ignored
# Run batch scan
python -m local_harness.batch.run scan
# Resume interrupted scan
python -m local_harness.batch.run scan --resume
# Check progress
python -m local_harness.batch.run status
# Collect all findings
python -m local_harness.batch.run collect
Results are stored in harness/local_harness/batch/workdir/.
Benchmarking Mode
Evaluate scanner accuracy against known vulnerabilities:
cd harness
pip install -e ".[dev]"
# Run full benchmark
python -m local_harness.benchmark.run
# Benchmark specific repository
python -m local_harness.benchmark.run --repos "OWASP/NodeGoat"
# Regenerate metrics only
python -m local_harness.benchmark.run --tally-only
Creating Ground Truth
Define known vulnerabilities in harness/local_harness/benchmark/ground_truth/<repo>.json:
{
"repo_name": "my-vulnerable-app",
"repo_url": "https://github.com/org/my-vulnerable-app",
"vulnerabilities": [
{
"id": "SQL-001",
"type": "SQL Injection",
"file": "src/db/user.py",
"line": 42,
"severity": "critical",
"description": "Unsanitized user input in SQL query",
"exploit_vector": "username parameter in /api/login"
}
]
}
Configure benchmark engines in harness/local_harness/config.py:
BENCHMARK_CONFIG = {
"scanner_model": "claude-opus-4-20250514",
"judge_model": "claude-opus-4-20250514",
"max_workers": 4
}
Configuration
VulnHunt Scanner Configuration
The scanner is prompt-driven. Customize behavior by editing vulnhunt/SKILL.md and phase files in vulnhunt/phases/:
vulnhunt/phases/recon.md- Entry point discoveryvulnhunt/phases/hunt.md- Path tracing logicvulnhunt/phases/disprove.md- Falsification rulesvulnhunt/phases/capability.md- Exploitability verification
VulnHunter-Fix Configuration
Edit vulnhunter-fix/vulnhunter_fix/config.py:
DEFAULT_CONFIG = {
"test_framework": "pytest", # or "unittest", "jest", etc.
"create_pr": True,
"pr_base_branch": "main",
"require_tests": True,
"max_fix_attempts": 3
}
Or override at runtime by creating .vulnhunter-fix.yaml in project root:
test_framework: pytest
create_pr: true
pr_base_branch: develop
require_tests: true
max_fix_attempts: 5
Common Patterns
Pattern 1: Quick Security Audit
# One-shot vulnerability scan
claude --model opus \
--add-dir ~/.claude/skills/vulnhunt \
--add-dir ~/.claude/skills/vulnhunt/phases \
<< 'EOF'
/vulnhunt
EOF
Pattern 2: Full Remediation Workflow
#!/usr/bin/env python3
"""Complete hunt-fix-verify workflow"""
import subprocess
import json
from pathlib import Path
def run_workflow(repo_path: Path):
# Step 1: Scan
print("[1/3] Scanning for vulnerabilities...")
subprocess.run([
"claude", "--model", "opus",
"--add-dir", "~/.claude/skills/vulnhunt",
"--add-dir", "~/.claude/skills/vulnhunt/phases",
"-c", "/vulnhunt"
], cwd=repo_path)
# Step 2: Fix
print("[2/3] Applying fixes...")
subprocess.run([
"claude", "--model", "opus",
"--add-dir", "~/.claude/skills/vulnhunter-fix",
"-c", "/vulnhunter-fix"
], cwd=repo_path)
# Step 3: Verify
print("[3/3] Verifying fixes...")
out_dir = Path("/tmp/verify-out")
out_dir.mkdir(exist_ok=True)
subprocess.run([
"claude", "--model", "opus",
"--add-dir", "~/.claude/skills/vulnhunt-fix-verify",
"--add-dir", "~/.claude/skills/vulnhunt-fix-verify/phases",
"-c", f"/vulnhunt-fix-verify repo={repo_path} report={repo_path}/vulnhunt_report.md out={out_dir}"
])
if __name__ == "__main__":
run_workflow(Path.cwd())
Pattern 3: CI/CD Integration
# .github/workflows/vulnhunt.yml
name: VulnHunter Security Scan
on:
schedule:
- cron: '0 2 * * 1' # Weekly Monday 2 AM
workflow_dispatch:
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install VulnHunter Agent
run: |
git clone https://github.com/capitalone/vulnhunter.git
cd vulnhunter/vulnhunter-agent
pip install -e ".[dev]"
- name: Run Security Scan
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
cd vulnhunter/vulnhunter-agent
cat > config.yaml << EOF
anthropic_api_key: ${ANTHROPIC_API_KEY}
github_token: ${GITHUB_TOKEN}
model: claude-opus-4-20250514
targets:
- url: ${{ github.server_url }}/${{ github.repository }}
branch: ${{ github.ref_name }}
create_issues: true
output_dir: ./results
EOF
python -m vulnhunter_agent.main --config config.yaml
- name: Upload Results
uses: actions/upload-artifact@v4
with:
name: vulnhunt-results
path: vulnhunter/vulnhunter-agent/results/
Pattern 4: Custom Falsification Rules
Extend the falsification engine by adding constraints to vulnhunt/phases/disprove.md:
## Custom Falsification Rules
### Framework-Specific Protections
**Django ORM**: If the code uses Django ORM methods like `.filter()`,
`.get()`, `.exclude()` with keyword arguments (not raw SQL), the ORM
provides automatic parameterization. Flag this as NOT exploitable.
**Express.js Helmet**: If `helmet()` middleware is configured and the
vulnerability is XSS-related, verify CSP headers block inline script
execution.
### Language-Specific Checks
**Python Type Hints**: If function signatures use strict type hints
with runtime validation (e.g., Pydantic), trace whether malicious input
can bypass type coercion.
**Rust Ownership**: For memory safety issues, verify whether Rust's
borrow checker already prevents the exploit at compile time.
Testing
Each component has isolated test suites:
# Test harness
cd harness
pip install -e ".[dev]"
python -m pytest tests/ --cov=local_harness
# Test fixer
cd vulnhunter-fix
pip install -e ".[dev]"
python -m pytest -q
# Test agent
cd vulnhunter-agent
pip install -e ".[dev]"
python -m pytest -q
Troubleshooting
Issue: Cyber Safeguard Blocks
Symptom: Requests blocked with cyber abuse warnings
Solution: Enroll in Anthropic Cyber Verification Program
# Verify enrollment status
curl https://api.anthropic.com/v1/cyber/status \
-H "x-api-key: $ANTHROPIC_API_KEY"
Issue: High False Positive Rate
Symptom: Many reported vulnerabilities are not exploitable
Solution: Strengthen falsification phase:
- Review
vulnhunt/phases/disprove.md - Add domain-specific sanitization patterns
- Increase falsification iterations in
SKILL.md:
## Falsification Configuration
Run **3 independent falsification passes** (up from default 1):
- Pass 1: Check input validation
- Pass 2: Verify sanitization/encoding
- Pass 3: Confirm no bypass via edge cases
Issue: Scanner Misses Known Vulnerabilities
Symptom: Benchmark shows low recall
Solution: Expand reconnaissance phase:
- Edit
vulnhunt/phases/recon.mdto include more entry point types - Add framework-specific entry points:
## Additional Entry Points
**FastAPI**: `@app.post()`, `@app.get()` decorated async functions
**Spring Boot**: `@RestController`, `@RequestMapping` methods
**GraphQL**: `resolve_*` functions in schema definitions
Issue: Verifier Rejects Valid Fixes
Symptom: /vulnhunt-fix-verify marks fixes as unsuccessful
Solution: Check verification logs for specific failure reason:
cat /path/to/verify-output/VULN-001-verification.log
Common causes:
- Test not exercising exact exploit path
- Fix incomplete (e.g., sanitizes one parameter but not all)
- Regression introduced (unrelated functionality broken)
Issue: Headless Agent Crashes
Symptom: vulnhunter-agent exits with errors
Solution: Enable debug logging:
# config.yaml
log_level: DEBUG
log_file: ./agent-debug.log
Check common issues:
- Invalid GitHub token:
gh auth status - API rate limits:
curl -H "x-api-key: $ANTHROPIC_API_KEY" https://api.anthropic.com/v1/usage - Disk space:
df -h
Issue: Skill Not Found
Symptom: /vulnhunt command not recognized
Solution: Verify installation:
ls -la ~/.claude/skills/vulnhunt
ls -la ~/.claude/skills/vulnhunt/phases
# Reinstall if missing
cd /path/to/vulnhunter
./install.sh
Environment Variables
# Required for Anthropic API access
export ANTHROPIC_API_KEY="your-api-key"
# Required for GitHub integration
export GITHUB_TOKEN="your-github-token"
# Optional: Custom skill directory
export CLAUDE_SKILLS_DIR="$HOME/custom-skills"
# Optional: Control batch concurrency
export VULNHUNT_MAX_WORKERS=4
# Optional: Verification timeout (seconds)
export VULNHUNT_VERIFY_TIMEOUT=1800
Additional Resources
- Official Docs: VulnHunter GitHub
- Claude Code Docs: docs.claude.com/claude-code
- Cyber Verification: Anthropic CVP Portal
- Contributing: See
CONTRIBUTING.mdin repository - Security: Report issues per
SECURITY.mdguidelines
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/security-skills/vulnhunter-security-scanner">View vulnhunter-security-scanner on skillZs</a>