dobbe

dobbe vuln scan

Scan repositories for Dependabot vulnerabilities and triage with AI.

Synopsis

dobbe vuln scan [OPTIONS]

Description

vuln scan fetches Dependabot vulnerability alerts from one or more GitHub repositories and uses Claude AI to triage each alert. The AI analyzes whether the vulnerable code path is actually used in your codebase, assigns adjusted risk levels, and provides evidence-backed recommendations.

Flowchart

┌─────────────────────────────────────────────┐
│         dobbe vuln scan [OPTIONS]            │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  --repo given?                               │
│  yes -> use provided repo slug               │
│  no  -> auto-detect from CWD git remote      │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Parse CLI args + merge config defaults      │
│  - severity from --severity or config        │
│  - format from --format or config            │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Validate severity values                    │
│  (critical, high, medium, low only)          │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Discover MCP servers                        │
│  (~/.claude/settings.json)                   │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Resolve repo location                       │
│  configured paths -> common dirs ->          │
│  CWD remote match -> clone to tempdir        │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Parallel scan (semaphore = 5)               │
│  For each repo:                              │
│    - Build scan prompt                       │
│    - Ask Claude async                        │
│    - Tools: [Bash, Read, Grep, Glob] + MCP   │
│    - Timeout: 600s per repo                  │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Parse responses                             │
│  - Extract JSON from Claude output           │
│  - Build AlertGroup / TriageResult models    │
│  - Handle parse errors gracefully            │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Build ScanReport                            │
│  - Aggregate stats by severity               │
│  - Count affected vs safe-to-ignore          │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Render output                               │
│  --format table (default) / json / markdown  │
│  --output file (optional)                    │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Optional: Notify                            │
│  --notify slack -> post to --channel         │
│  --notify jira  -> create tickets            │
└─────────────────────────────────────────────┘

Options

Option	Type	Default	Description
`--repo` / `-r`	`str`	auto-detect	Single repo to scan (`org/repo`). Auto-detected from current directory if omitted.
`--severity` / `-s`	`str`	`critical,high,medium,low`	Comma-separated severity filter
`--format` / `-f`	`str`	`table`	Output format: `table`, `json`, `markdown`
`--verbose` / `-V`	`bool`	`False`	Show evidence, CVEs, and upgrade paths
`--quiet` / `-q`	`bool`	`False`	Suppress progress output, only show final result
`--output`	`str`	-	Write output to file instead of stdout
`--no-cache`	`bool`	`False`	Skip response cache, force fresh analysis
`--notify`	`str`	-	Send report to platform (`slack`, `jira`)
`--channel`	`str`	-	Notification channel (e.g., `#security-alerts`)

When run from inside a git repository with no --repo flag, auto-detects the repo from the current directory’s git remote URL.

Examples

Auto-detect from current directory

dobbe vuln scan

Scan a single repository

dobbe vuln scan --repo acme/web-app

Filter by severity and output verbose details

dobbe vuln scan --repo acme/web-app --severity critical --verbose

JSON output to file

dobbe vuln scan --repo acme/web-app --format json --output scan-report.json

Send report to Slack

dobbe vuln scan --repo acme/web-app --notify slack --channel "#security-alerts"

Saving Results for Later Use

Save scan results as JSON for use with dobbe vuln resolve --from-scan:

dobbe vuln scan --repo acme/web-app --format json --output scan.json
dobbe vuln resolve --repo acme/web-app --from-scan scan.json

Or pipe directly to avoid writing a file:

dobbe vuln scan --repo acme/web-app --format json | dobbe vuln resolve --repo acme/web-app --from-scan -

This avoids running the scan agent twice when scanning and resolving the same repository.

Internal Architecture

Prompt Construction

The scan prompt is built by build_scan_prompt() with:

Fetch instructions: Uses GitHub MCP tools if available (mcp__github__*), otherwise instructs Claude to use gh api via Bash
Code instructions: If the repo is resolved locally, instructs Claude to read source files directly. For remote repos, instructs analysis based on alert metadata only
Severity clause: Filters alerts to the requested severity levels

Async Scanning

Repos are scanned in parallel using asyncio with a semaphore limiting concurrency to 5 simultaneous scans. Each scan has a 600-second timeout. Errors for individual repos are captured in the RepoResult.error field without failing the entire batch.

Response Parsing

Claude’s JSON response is parsed into structured models:

AlertGroup: Related alerts grouped by package (package name, current/target versions)
TriageResult: Per-alert triage (severity, affected flag, evidence, risk level, recommendation)
RepoResult: Per-repo aggregate (groups, total alerts, affected count)
ScanReport: Cross-repo aggregate with severity statistics

Output Models

The ScanReport provides computed properties:

total_alerts - sum across all repos
total_affected - alerts where the code path is actually used
total_safe_to_ignore - alerts where the code path is not used
stats_by_severity - breakdown by severity level