Scanning Your Repo for Secrets With TruffleHog

Accidentally committed an API key to your repository? You’re not alone. Thousands of credentials leak through git every day—often sitting in commit history long after developers think they’ve deleted them. TruffleHog secret scanning offers a straightforward way to detect exposed API keys in repos before they become security incidents.

This article covers how TruffleHog works, how to scan git repositories for secrets locally and in CI, and how to interpret the results so you can prioritize remediation effectively.

Why Secrets End Up in Git

Developers move fast. A database password gets hardcoded during debugging. An AWS key lands in a config file. These mistakes happen constantly, and git’s immutable history means that even “deleted” secrets persist in older commits.

The risk is real: automated bots scan public repositories continuously, and exposed credentials can be exploited within minutes of being pushed. Even private repos aren’t safe—a single compromised developer account or misconfigured access control can expose everything.

How TruffleHog Detects Secrets

TruffleHog isn’t a simple grep tool. It uses detector-based scanning with hundreds of built-in patterns for specific credential types: AWS keys, GitHub tokens, Stripe API keys, database connection strings, and more.

The detection approach combines:

• Pattern matching: Regex detectors tuned for known secret formats
• Contextual analysis: Examining surrounding code to reduce noise
• Optional verification: Testing credentials against actual APIs to confirm they’re active

This layered approach means fewer false positives than entropy-only scanners. When TruffleHog flags something, it’s usually worth investigating.

Scanning a Local Repository

To scan git repositories for secrets locally, point TruffleHog at your repo:

trufflehog git file://.

This scans the entire git history—not just the current working tree. Secrets buried in old commits get surfaced alongside recent ones.

For faster feedback during development, you can limit the scan scope to recent commits or specific branches. This makes it practical to run before pushing changes.

Understanding Verified vs. Unverified Results

TruffleHog distinguishes between two finding types:

• Verified: The credential was tested against its API and confirmed active
• Unverified: The pattern matches a known secret format, but verification wasn’t possible or wasn’t attempted

Verified findings demand immediate action—these are live credentials that could be exploited right now. Unverified findings still warrant review, but you can prioritize them lower when triaging a large result set.

To filter output to only verified results:

trufflehog git file://. --only-verified

Integrating TruffleHog GitHub Action Into CI

Running scans manually catches problems, but automation prevents them. The TruffleHog GitHub Action integrates directly into your CI pipeline to scan every pull request and push.

A basic workflow configuration scans incoming changes and fails the build if secrets are detected. This creates a gate that stops credential leaks before they reach your main branch—or worse, production.

The action supports scanning just the diff (faster for PR checks) or the full repository history (useful for periodic audits). Most teams run lightweight diff scans on every PR and schedule comprehensive history scans weekly.

Beyond Git: Other Scan Targets

While this article focuses on git workflows, TruffleHog supports additional targets: filesystems, S3 buckets, and Docker images. For most developers, the git and filesystem scanners cover typical use cases. The broader capabilities become relevant as your infrastructure grows.

What to Do When Secrets Are Found

Finding a secret is only the first step. The response matters more:

1. Rotate the credential immediately—assume it’s compromised
2. Remove it from git history using tools like BFG Repo-Cleaner or git-filter-repo
3. Audit access logs for the affected service to check for unauthorized use
4. Update your workflow to prevent credential leaks in source control going forward

Simply deleting the file and committing again doesn’t help. The secret remains in history until you rewrite it.

Conclusion

TruffleHog works best as a preventative control, not just an audit tool. Run it early in CI, ideally on every pull request. The earlier you catch a leaked credential, the smaller the blast radius.

Pair automated scanning with good hygiene: use environment variables for secrets, add sensitive patterns to .gitignore, and consider pre-commit hooks for local enforcement.

Secret scanning won’t eliminate every risk, but it dramatically reduces the window between a mistake and its discovery. That’s often the difference between a near-miss and an incident.

FAQs

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.