/scan

name: scan
description: "[beta] Run quick, deep, or audit scan profiles and emit a shared findings artifact"
argument-hint: "[path] [--profile quick|deep|audit] [--tools api-spec,semgrep,codeql,joern] [--rules ruleset] [--workspace name] [--since-commit sha] [--diff-base ref] [--exclude patterns] [--suppressions path] [--format json|sarif|md|html|pr-comment|badge] [--fail-on severity] [--output file] [--json] [--secrets] [--require-tools] [--custom-rules] [--extended-detectors] [--incremental] [--generate-pocs] [--no-filter] [--no-semantic-analysis]"
allowed-tools:
  - Bash
  - Glob
  - Read
  - Write
  - TodoWrite

Security Scan

Run automated static analysis and write the results to `.claude/findings.json`.

Flags

| Flag | Effect | |------|--------| | `--profile` | Use `quick` (local deterministic rules), `deep` (installed analyzers), or `audit` (deterministic baseline for Claude-driven review) | | `--tools` | Run `api-spec`, `semgrep`, `codeql`, `joern`, or a comma-separated combination | | `--rules` | Semgrep ruleset override | | `--workspace` | Resolve a monorepo workspace before scanning | | `--since-commit` | Scan files changed since a commit SHA | | `--diff-base` | Backward-compatible alias for diff scans against a git ref | | `--exclude` | Extra exclusions | | `--suppressions` | Apply `.vuln-scout-ignore` after aggregation | | `--format` | Emit `json`, `sarif`, `md`, `html`, `pr-comment`, or `badge` at the end | | `--fail-on` | Exit `2` when unsuppressed `finding` entries exist at or above the severity | | `--output` | Save the final emitted artifact to a file. In Claude plugin workflows, resolve relative output paths under the target workspace when the scan target is not the current directory. | | `--json` | Shortcut for `--format json` | | `--secrets` | Run secret scanning (gitleaks/truffleHog) alongside static analysis | | `--require-tools` | Fail if any requested tool is unavailable | | `--custom-rules` | Generate target-specific Semgrep rules in addition to profile rules | | `--extended-detectors` | Run regex-based VulnScout detectors in addition to scanner tools | | `--incremental` | Use file-hash cache to skip unchanged files | | `--generate-pocs` | Generate proof-of-concept scripts for verified findings | | `--no-filter` | Keep low-confidence Semgrep audit results as hotspots instead of dropping them | | `--no-semantic-analysis` | Compatibility flag for callers that share `/full-audit` options; the standalone CLI does not run a Claude semantic analysis phase |

The `audit` profile does not invoke Claude during the scan phase; semantic review is performed afterward by `/vuln-scout:verify` or `/vuln-scout:full-audit`.

Shared artifact contract

All tool branches must write the same artifact shape to `.claude/findings.json`.

Source of truth:

• `vuln-scout/references/findings.schema.json`

Required top-level fields:

• `schema_version`
• `scan_id`
• `project_path`
• `completed_at`
• `source_tool`
• `summary`
• `findings`

Required finding fields:

• `id`
• `stable_key`
• `kind`
• `severity`
• `type`
• `title`
• `file`
• `line`
• `verdict`
• `confidence`
• `source_tool`
• `message`
• `evidence`

`kind` rules

• `finding`: reportable issue; contributes to severity totals
• `hotspot`: risky sink or framework pivot; does **not** contribute to severity totals

If a scan branch only proves that a dangerous pattern exists, record a `hotspot`.

Step 1: Resolve scope

Default target is the current directory.

Static scans always run against a **source directory**. Saved `.claude/scope-*.md` snapshots are useful context for Claude-side review and threat modeling, but they are not direct input to Semgrep, Joern, or CodeQL.

When invoking `scripts/scan_orchestrator.py` from this command and the user supplies a scan target other than `.`, convert relative `--output` paths to live under that target. For example:

python3 /path/to/vuln-scout/scripts/scan_orchestrator.py /tmp/app \
  --profile quick \
  --output /tmp/app/.claude/plugin-findings.json

Do not write relative output artifacts into the plugin repository unless the plugin repository is the explicit scan target.

If `--since-commit <sha>` is passed:

CHANGED_FILES=$(git diff --name-only <sha>...HEAD -- [path])
printf '%s\n' "$CHANGED_FILES" > /tmp/vuln-scout-targets.txt

If `--diff-base <ref>` is passed:

• treat it as an alias for `--since-commit <ref>`

Step 2: Apply baseline exclusions

Always exclude:

node_modules
vendor
dist
build
coverage
__pycache__
*.min.js
*.map

Step 3: Run selected tool branches

Semgrep branch

semgrep --config "${RULESET:-vuln-scout/rules/vuln-scout-local.yml}" --json [targets...]

Classify:

• direct Semgrep matches with actionable evidence -> `finding`
• framework pivots and sink-only matches -> `hotspot`

CodeQL branch

Create a database for each detected language, then analyze it explicitly.

codeql database create .codeql-db --language=<language> --source-root [path]
codeql database analyze .codeql-db \
  <language>-security-and-quality.qls \
  --format=sarif-latest \
  --output /tmp/codeql-results.sarif

Map CodeQL results into the shared findings artifact:

• taint or data-flow backed results -> `finding`
• broad query matches without exploit proof -> `hotspot`

Joern branch

Joern is verification-oriented, so its standalone scan branch should be conservative.

1. Generate or reuse a cached CPG keyed by target hash plus detected language. 2. Run language-aware hotspot queries or batch verification.

TARGET_HASH=$(git ls-files -z [path] | xargs -0 shasum | shasum | awk '{print $1}')
LANGUAGE=<detected-language>
CPG_FILE=".joern/${TARGET_HASH}-${LANGUAGE}.cpg"

if [ ! -f "$CPG_FILE" ]; then
  joern-parse [path] --output "$CPG_FILE"
fi

joern --script "${CLAUDE_PLUGIN_ROOT}/scripts/joern/batch-verify.sc" \
  --params cpgFile="$CPG_FILE",findingsFile=".claude/findings.json"

Classification