Claude Code plugin for whitebox security review with deterministic quick scans, evidence-backed verification, and portable reports.
VulnScout's stable promise is an offline quick scan, shared findings.json with stable keys and hotspot-aware findings, SARIF/Markdown/HTML/PR-comment/bundle reports, suppressions, and a CI fail-on gate. It writes audit-plan.md and review-ledger.json for reviewer-driven workflows and exposes structured Claude Code and Kuzushi surfaces.
For MCP hosts, VulnScout also ships a local stdio MCP server with scanner, report, artifact, and Joern CPG tools. See docs/mcp.md.
- Python 3.9 or newer
- Semgrep for the stable
quickscan profile - Claude Code for slash-command workflows
- Optional deep analyzers: Joern, CodeQL, Slither, Trivy, Checkov
python3 -m pip install semgrep-
Install the runtime prerequisite:
python3 -m pip install semgrep
-
Validate the local runtime:
python3 vuln-scout/scripts/doctor.py --strict
-
Scan the bundled vulnerable app and render an HTML report:
python3 vuln-scout/scripts/scan_orchestrator.py demo/vulnerable-app --profile quick --output /tmp/vuln-scout-demo.json python3 vuln-scout/scripts/report.py /tmp/vuln-scout-demo.json --format html --output report.html
Expected quick-profile result: four findings from bundled local rules.
| Severity | Finding |
|---|---|
| high | Python SQL injection |
| high | Python command injection |
| medium | Browser XSS |
| medium | Express open redirect |
See feature maturity for the full stability matrix.
| Capability | Status |
|---|---|
| Offline quick scan with bundled rules | Stable |
Shared findings.json schema and stable keys |
Stable |
| SARIF, Markdown, HTML, and bundle reports | Stable |
Suppressions and CI --fail-on gate |
Stable |
| Kuzushi structured tool surface | Stable |
| Joern, CodeQL, Slither, Trivy, Checkov deep analyzers | Beta when installed |
| Auto-fix, PoC, and mutation workflows | Experimental |
Primary paths are documented in docs/install.md. The quickest product check is the demo above; after that, use the Claude Code plugin command path.
claude plugin install vuln-scout
claude --plugin-dir ./vuln-scout
npm install @kuzushi/vuln-scout| Workflow | Command | Guide |
|---|---|---|
| Full audit | /vuln-scout:full-audit |
First run |
| Verify finding | /vuln-scout:verify |
PR review |
| Report | /vuln-scout:report |
CI |
| Scope repo | /vuln-scout:scope |
First run |
| Diff review | /vuln-scout:diff |
PR review |
Advanced commands
| Command | Maturity | Purpose |
|---|---|---|
/vuln-scout:scan |
beta | Run quick, deep, or audit scan profiles |
/vuln-scout:threats |
beta | Build STRIDE threat models |
/vuln-scout:sinks |
beta | Find dangerous functions and output sinks |
/vuln-scout:trace |
beta | Trace source-to-sink data flow |
/vuln-scout:propagate |
beta | Find related instances of a confirmed pattern |
/vuln-scout:create-rule |
experimental | Generate custom Semgrep rules |
/vuln-scout:org-memory-compile |
experimental | Compile human-reviewed org memory |
/vuln-scout:mutate |
experimental | Mutation-test security controls |
/vuln-scout:auto-fix |
experimental | Generate patches for verified findings |
| Surface | Stable | Beta | Experimental |
|---|---|---|---|
| Profiles | quick | deep, audit | custom-rules |
| Reports | SARIF, Markdown, HTML, PR comment, bundle | generated PoCs | generated exploit harnesses |
| Workflows | full-audit, verify, report, scope, diff | scan, threats, sinks, trace, propagate | create-rule, mutate, auto-fix |
The npm package exports Kuzushi tools that return structured results:
{ ok, output, artifacts, maturity, toolName }Kuzushi exposes the same 14 command names as the Claude plugin. Its structured schemas cover the common flags; advanced reviewer workflows still live in the Claude Code command prompts.
The report tool supports sarif, md, json, html, pr-comment, and bundle.
Use the bundled MCP server when an MCP host should call VulnScout directly:
python3 vuln-scout/scripts/mcp_server.pyThe server exposes vulnscout_scan, vulnscout_report, vulnscout_create_cpg, vulnscout_joern_query, vulnscout_joern_discover, vulnscout_verify_findings, vulnscout_read_artifact, and vulnscout_doctor. Joern tools return structured unavailable states when Joern is not installed.
vuln-scout/
.claude-plugin/plugin.json
agents/
commands/
hooks/
skills/
references/
scripts/
The plugin ships 27 knowledge skills plus 5 task skills under vuln-scout/skills/tasks/.
.claude/audit-plan.mdcaptures scope, module priority, attack surfaces, and verification strategy..claude/review-ledger.jsonrecords adversarial review rounds and approvals..claude/findings.jsonfollowsvuln-scout/references/findings.schema.json.
Users upgrading from 3.x should read docs/migration-3.x-to-3.2.md. /whitebox-pentest:* aliases remain as deprecated shim files for one release and are shipped as a legacy plugin root.
MIT