dobbe

dobbe scan secrets

Scan repositories for secrets using gitleaks/truffleHog with AI assessment.

Synopsis

dobbe scan secrets [PATH] [OPTIONS]

Description

scan secrets runs a secret detection scan against a local repository using gitleaks or truffleHog. Each finding is optionally assessed by Claude AI to determine real severity and identify false positives. The AI evaluates whether a detected string is an actual secret, a test fixture, a placeholder, or a known-safe pattern, and provides an evidence-backed assessment for each finding.

Flowchart

┌─────────────────────────────────────────────┐
│      dobbe scan secrets ./my-repo            │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Parse CLI args + load config                │
│  - path from positional arg (default ".")    │
│  - format from --format or config            │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Discover MCP servers + extra tools          │
│  (~/.claude/settings.json)                   │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Run secret scanner                          │
│  - Detect gitleaks or truffleHog             │
│  - Scan repo at PATH                         │
│  - Collect raw findings                      │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  AI severity assessment (unless --no-ai)     │
│  For each finding:                           │
│    - Classify severity (critical/high/med/   │
│      low)                                    │
│    - Detect false positives                  │
│    - Provide evidence-backed assessment      │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Render output                               │
│  --format table (default) / json             │
│  --output file (optional)                    │
└──────────────────────┬──────────────────────┘
                       │
                       v
┌─────────────────────────────────────────────┐
│  Shallow clone warning                       │
│  If .git/shallow exists and no secrets found │
│  -> warn that history may contain secrets    │
└─────────────────────────────────────────────┘

Options

Option	Type	Default	Description
`PATH`	`str` (positional)	`.`	Repository path to scan
`--no-ai`	`bool`	`False`	Skip AI severity assessment; report raw scanner output only
`--format` / `-f`	`str`	`table`	Output format: `table`, `json`. Env: `DOBBE_FORMAT`
`--output`	`str`	-	Write output to file instead of stdout
`--quiet` / `-q`	`bool`	`False`	Suppress progress output, only show final result

AI Severity Assessment

By default, each finding from gitleaks/truffleHog is sent through Claude AI for triage. The AI:

Classifies severity as critical, high, medium, or low based on the type of secret and its exposure risk
Detects false positives – test fixtures, placeholder values (e.g., CHANGEME, xxx), example keys from documentation, and known-safe patterns are flagged
Provides an assessment string explaining why the finding is or is not a real secret

Use --no-ai to skip this step and get raw scanner output only. This is faster but produces no false-positive filtering or severity adjustment.

Shallow Clone Warning

When scanning a repository that was cloned with --depth (a shallow clone), secrets present in older git history may not be detected. If the scan finds no secrets and the repository has a .git/shallow file, the command prints a warning:

Note: This is a shallow clone. Secrets in git history may be missed.
For deeper analysis, use a full clone or `dobbe audit report`.

This warning is suppressed in --quiet mode.

Examples

Scan the current directory

dobbe scan secrets

Scan a specific repository path

dobbe scan secrets ~/projects/api

Skip AI assessment for faster raw results

dobbe scan secrets --no-ai

JSON output to file

dobbe scan secrets --format json --output secrets-report.json

Quiet mode for CI pipelines

dobbe scan secrets . --quiet --format json --output secrets.json

Internal Architecture

Scanner Detection

The scan_secrets function detects which scanner is available on the system (gitleaks or truffleHog) and runs it against the specified path. The scanner name is included in the output so consumers know which tool produced the findings.

Finding Model

Each finding includes:

rule_id – the scanner rule that triggered (e.g., generic-api-key, aws-access-key)
file – the file path where the secret was found
line – the line number
severity – AI-adjusted severity (or raw scanner severity with --no-ai)
is_false_positive – whether the AI determined this is not a real secret
ai_assessment – free-text explanation from the AI

Output Formats

Table (default): Renders a Rich table with columns for severity, rule, file, line, and AI assessment. False positives are excluded from table output.
JSON: Includes all findings (including false positives) with full metadata. Written to stdout or to the file specified by --output.