Trufflehog

trufflehog

Secrets scanner with live credential verification — finds + validates real active secrets.

Quick Start

# Scan local git repo
trufflehog git file://. --only-verified

# Scan GitHub repo
trufflehog git https://github.com/org/repo --only-verified

# Scan filesystem
trufflehog filesystem /path/to/project --only-verified

# JSON output
trufflehog git file://. --only-verified --json

Subcommands (Scan Sources)

Core Flags

Verification: The Key Differentiator

trufflehog actually tests if secrets work by calling the issuing service API:

No data is altered during verification. Only read-only auth checks.

# CI/CD gate: only verified = real, active secrets
trufflehog git file://. --only-verified --fail
echo $?  # non-zero = live secrets found

# Show verified + unknown (be thorough)
trufflehog git file://. --results=verified,unknown --json

# Skip verification (fast pattern scan only)
trufflehog git file://. --no-verification --json

Common Workflows

# Scan repo since last CI commit (delta scan)
trufflehog git file://. \
    --since-commit "$CI_COMMIT_BEFORE_SHA" \
    --only-verified --fail

# Scan specific branch
trufflehog git file://. --branch main --only-verified

# Limit to recent 500 commits
trufflehog git file://. --max-depth=500 --only-verified

# Full organization scan (GitHub)
trufflehog github --org=MyOrg \
    --token=$GITHUB_TOKEN \
    --include-members \
    --include-wikis \
    --issue-comments --pr-comments \
    --only-verified --json

# Docker image scan
trufflehog docker --image myapp:latest --only-verified

# S3 bucket scan
trufflehog s3 --bucket my-bucket --only-verified

# Decode base64 / encoded secrets
trufflehog filesystem . --max-decode-depth=3 --only-verified

# Exclude paths
trufflehog git file://. \
    --exclude-paths=exclude.txt \
    --exclude-globs="*.log,*.lock,vendor/*" \
    --only-verified

GitHub Actions

name: TruffleHog Secrets Scan
on: [push, pull_request]
jobs:
  trufflehog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: TruffleHog OSS
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: ${{ github.event.repository.default_branch }}
          head: HEAD
          extra_args: --only-verified

Output Parsing (JSON)

trufflehog git file://. --only-verified --json > findings.json

# Key fields in each finding:
# .DetectorName    - type of secret (aws, github, slack, etc.)
# .Verified        - true/false
# .Raw             - redacted secret value
# .SourceMetadata.Data.Git.File   - file path
# .SourceMetadata.Data.Git.Commit - commit SHA
# .SourceMetadata.Data.Git.Email  - author email

# Extract finding summary
cat findings.json | jq '{detector: .DetectorName, file: .SourceMetadata.Data.Git.File, commit: .SourceMetadata.Data.Git.Commit, verified: .Verified}'

# List unique secret types found
cat findings.json | jq -r '.DetectorName' | sort -u

# Only show verified with file+commit context
cat findings.json | jq 'select(.Verified == true) | {type: .DetectorName, file: .SourceMetadata.Data.Git.File, commit: .SourceMetadata.Data.Git.Commit}'

Resources