trufflehog-scanning

Overview

Per github.com/trufflesecurity/trufflehog:

TruffleHog v3's distinguishing feature is live verification - discovered secrets are tested against the provider API to confirm they're actual valid credentials. This dramatically reduces false-positive rate vs entropy-only scanners.

The verification works for many cloud providers, SaaS APIs, and custom-detector definitions. Filter to --results=verified to skip unverified hits in CI gating.

When to use

• Team needs low-FP-rate secret scanning (verification > entropy alone).
• Scanning beyond git: GitHub orgs, GitLab repos, S3 buckets, Docker images, Postman workspaces.
• Verified-only output for CI gating (block only confirmed-real secrets; track unverified separately).
• Layered with gitleaks-scanning for cross-tool consensus.

Step 1 - Install

Per th-gh:

# Homebrew
brew install trufflehog

# Docker
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest \
  github --repo https://github.com/trufflesecurity/test_keys

# Install script (Linux/macOS)
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh \
  | sh -s -- -b /usr/local/bin

# From source
git clone https://github.com/trufflesecurity/trufflehog.git
cd trufflehog && go install

Step 2 - Per-source subcommands

Per th-gh TruffleHog uses subcommands per data source:

Examples per th-gh:

# Scan git repository, verified only
trufflehog git https://github.com/trufflesecurity/test_keys --results=verified

# Scan GitHub organization with JSON output
trufflehog github --org=trufflesecurity --results=verified --json

# Scan local filesystem
trufflehog filesystem path/to/file1.txt path/to/dir

Step 3 - Verification: the killer feature

Per th-gh:

"--results=verified - Show only credentials confirmed valid through API testing"

The verification flow per detector:

1. Regex match a candidate secret in source
2. Construct a provider-specific API call (e.g., AWS GetCallerIdentity)
3. If the call succeeds with the candidate as the credential, mark as verified
4. Filter the output by verification status

This is the difference between "high entropy string that LOOKS like an AWS key" (probably a false positive) and "valid AWS key that will let an attacker into your account" (definitely real).

Trade-off: verification calls can be detected by the provider

• may generate audit-log entries. For compliance-sensitive scans, disable via --no-verification.

Step 4 - Output formats

Per th-gh:

For secrets-rotation-runner integration, use --json --results=verified:

trufflehog git . --json --results=verified > verified-secrets.json

Step 5 - False-positive triage (MANDATORY)

TruffleHog has fewer false positives than entropy-only scanners (thanks to verification), but unverified findings still need triage:

trufflehog.yaml example:

detectors:
  - name: "AWS"
    enabled: true
  - name: "PrivateKey"
    enabled: true
  - name: "GenericAPIKey"
    enabled: false   # too noisy in this codebase

verification: true
exclude_paths:
  - "tests/fixtures/**"
  - "vendor/**"

Justification template (mandatory in trufflehog.yaml comments or sibling REASONS.md):

# Reason: GenericAPIKey detector produces 50+ FPs per scan in our codebase
#         (matches our own fingerprint hashes that look like keys but aren't).
# Approved-by: alice@example.com
# Re-review-date: 2026-09-15 (re-evaluate after fingerprint format migration)
detectors:
  - name: "GenericAPIKey"
    enabled: false

Cadence: every quarter, audit trufflehog.yaml disabled detectors

• exclude_paths; expired entries removed.

Step 6 - Failure semantics

Per th-gh:

"--fail - Exit with code 183 if secrets found"

Exit codes:

• 0 - no secrets found
• 183 - secrets found (with --fail)
• (other) - runtime errors

CI usage:

trufflehog git . --results=verified --fail
# Exit 183 if verified secrets found; exit 0 otherwise
# CI workflow fails the job on non-zero exit

Step 7 - Pre-commit + CI integration

Pre-commit hook (community-supported, not first-party):

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/trufflesecurity/trufflehog
    rev: v3.81.0
    hooks:
      - id: trufflehog
        args: ['--results=verified', '--fail']

GitHub Action:

jobs:
  trufflehog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with: { fetch-depth: 0 }
      - uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: ${{ github.event.pull_request.base.sha }}
          head: HEAD
          extra_args: --results=verified --fail

base + head enable diff-only scanning on PRs (faster).

Step 8 - Cross-tool layering

Pair with gitleaks-scanning:

• gitleaks: faster, regex-based, runs in pre-commit
• trufflehog: slower (verification calls), high-precision, runs in CI

Run both in CI; gitleaks catches what didn't make it past pre-commit; trufflehog catches what gitleaks missed (e.g., novel formats not yet in gitleaks' rule library).

Anti-patterns

Limitations

• Verification API calls may trigger provider audit-log alerts (false positives in the security team's incident queue).
• Rate-limited APIs may slow scans or fail verification on large secret pools.
• Verification doesn't prove the secret hasn't been already rotated - a "valid" key per TruffleHog might be a recently-rotated legacy key still active for grace period.
• TruffleHog Enterprise (paid) has more detectors + features; the OSS version covers ~200 detectors.

References

• th-gh - repository, install, commands, exit codes
• trufflesecurity.com - company site
• gitleaks-scanning, kingfisher-scanning - sister scanners
• secrets-rotation-runner - rotation workflow after detection