VulnScout

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.

VulnScout runs scanner binaries and Joern CPGQL locally against the workspace you provide. The stable quick path uses bundled rules and does not require a remote service.

Prerequisites

• Python 3.9 or newer
• Semgrep for the stable quick scan profile
• Claude Code for slash-command workflows
• Optional deep analyzers: Joern, CodeQL, Slither, Trivy, Checkov
• Optional code-intelligence sidecar: CodeGraph for symbol search, context, and affected-file analysis

python3 -m pip install semgrep

5-Minute Demo

1. Install the runtime prerequisite:

   python3 -m pip install semgrep

2. Validate the local runtime:

   python3 vuln-scout/scripts/doctor.py --strict

3. 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

Stable Promise

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

Install

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

Canonical Workflows

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

Commands (15 total)

Advanced commands

Command	Maturity	Purpose
/vuln-scout:scan	beta	Run quick, deep, or audit scan profiles
/vuln-scout:mobile-audit	beta	Audit decompiled Android targets (jadx_out + apktool_out merged)
/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

Feature Maturity

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

Kuzushi Integration

The npm package exports Kuzushi tools that return structured results:

{ ok, output, artifacts, maturity, toolName }

Kuzushi exposes the same 15 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.

MCP Server

Use the bundled MCP server when an MCP host should call VulnScout directly:

python3 vuln-scout/scripts/mcp_server.py

The server exposes vulnscout_scan, vulnscout_report, vulnscout_create_cpg, vulnscout_joern_query, vulnscout_joern_discover, vulnscout_verify_findings, CodeGraph sidecar tools, vulnscout_read_artifact, and vulnscout_doctor. Joern and CodeGraph tools return structured unavailable states when their binaries or indexes are not installed, and report content is opt-in to keep MCP responses compact.

Project Structure

vuln-scout/
  .claude-plugin/plugin.json
  agents/
  commands/
  hooks/
  skills/
  references/
  scripts/

35 Auto-Activated Skills

The plugin ships 27 knowledge skills plus 5 task skills under vuln-scout/skills/tasks/.

Audit Artifacts

• .claude/audit-plan.md captures scope, module priority, attack surfaces, and verification strategy.
• .claude/review-ledger.json records adversarial review rounds and approvals.
• .claude/findings.json follows vuln-scout/references/findings.schema.json.

Migration

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.

License

MIT