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
-
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 |
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)
| 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
