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:

   hljs language-bash

   Copy

   python3 -m pip install semgrep
   

2. Validate the local runtime:

   hljs language-bash

   Copy

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

3. Scan the bundled vulnerable app and render an HTML report:

   hljs language-bash

   Copy

   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.

Stable Promise

See feature maturity for the full stability matrix.

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

Commands (15 total)

Feature Maturity

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