TruffleHog — Find and Verify Leaked Credentials

Introduction

TruffleHog goes beyond pattern matching — it actually verifies that detected credentials are live and active. Found an AWS key? TruffleHog calls the AWS STS API to confirm it works. Found a GitHub token? It checks if the token has valid permissions. This verification step eliminates the false positive noise that plagues other secret scanners.

With over 26,000 GitHub stars, TruffleHog is developed by Truffle Security, a company focused on credential leak detection. It scans Git repos, GitHub/GitLab orgs, S3 buckets, filesystems, Docker images, and CI/CD logs.

What TruffleHog Does

TruffleHog scans data sources for credentials using 800+ detectors. When it finds a potential secret, it performs verification — making a safe API call to check if the credential is active. Results are categorized as verified (confirmed active), unverified (pattern match but not confirmed), or false positive.

Architecture Overview

[Data Sources]
Git repos, GitHub orgs,
GitLab, S3 buckets,
filesystems, Docker images
        |
   [TruffleHog Scanner (Go)]
        |
   [800+ Detectors]
   AWS, GCP, Azure, GitHub,
   Slack, Stripe, Twilio,
   databases, private keys...
        |
   [Verification Engine]
   Makes safe API calls to
   check if credential is
   actually active/valid
        |
   [Results]
   Verified: confirmed active
   Unverified: pattern match
   + source location, commit

Self-Hosting & Configuration

# Scan different sources

# GitHub organization (all repos)
trufflehog github --org=mycompany --token=ghp_xxx

# GitLab group
trufflehog gitlab --group=mygroup --token=glpat_xxx

# S3 bucket
trufflehog s3 --bucket=my-bucket

# Docker image
trufflehog docker --image=myapp:latest

# CI/CD integration
trufflehog git file://./ --since-commit HEAD~1 --fail --only-verified
# Exits with code 183 if verified secrets found

# JSON output for processing
trufflehog git file://./ --json | jq 'select(.Verified == true)'

Key Features

• Credential Verification — checks if found secrets are actually active
• 800+ Detectors — covers most cloud providers, SaaS tools, and databases
• Multi-Source — Git, GitHub, GitLab, S3, filesystem, Docker, CircleCI
• Git History — scans complete commit history for buried secrets
• Low False Positives — verification dramatically reduces noise
• CI/CD Integration — exit codes and JSON output for pipeline use
• Org-Wide Scanning — scan entire GitHub/GitLab organizations at once
• Docker Scanning — detect secrets baked into container images

Comparison with Similar Tools

FAQ

Q: How does verification work? A: TruffleHog makes safe, read-only API calls using detected credentials. For AWS keys, it calls STS GetCallerIdentity. For GitHub tokens, it checks /user. These calls confirm the key is active without making any changes.

Q: Is it safe to verify credentials? A: Yes. Verification calls are read-only and minimal. They do not modify any data or trigger alerts in most monitoring systems. The calls are designed to be the safest possible validation.

Q: TruffleHog v2 vs v3 — what changed? A: v3 is a complete rewrite in Go (v2 was Python). v3 is much faster, has 800+ detectors (vs regex-only in v2), and adds verification. Always use v3.

Q: How do I scan before every commit? A: Use pre-commit hook: trufflehog git file://./ --since-commit HEAD --fail. Or integrate with the pre-commit framework.

Sources

• GitHub: https://github.com/trufflesecurity/trufflehog
• Documentation: https://trufflesecurity.com/trufflehog
• Created by Truffle Security
• License: AGPL-3.0