TruffleHog: Find, Verify, and Analyze Leaked Secrets

What TruffleHog is

TruffleHog is a secrets scanner maintained by Truffle Security. Its README tagline is simply "Find leaked credentials." In this context a secret is a credential a machine uses to authenticate to another machine: API keys, database passwords, private encryption keys, and similar material. TruffleHog looks for these across source code history and a long list of other places they tend to end up, then goes a step further than pattern matching by checking whether what it found actually works.

The README frames the tool around four capabilities: discovery, classification, validation, and analysis. That combination is the reason teams use it. A scanner that only matches regexes produces a pile of candidates; TruffleHog tries to tell you which of those candidates are live credentials that represent a present danger.

It is aimed at security engineers running audits, DevOps and platform teams wiring secret detection into CI, and developers who want a pre-commit hook that stops credentials from leaving their machine.

How it works

Discovery

TruffleHog has a subcommand per data source. The README lists git, github, gitlab, huggingface, docker, s3, gcs, filesystem, syslog, circleci, travisci, postman, jenkins, elasticsearch, stdin, and multi-scan, which reads several sources from a configuration file and scans them concurrently. It can also scan binaries, documents, and other file formats, and archives up to configurable size, depth, and time limits.

Classification

According to the README, TruffleHog classifies over 800 secret types and maps each back to the identity it belongs to, so a finding is labeled as an AWS key, a Stripe secret, a Postgres password, an SSL private key, and so on.

Verification

For each classified secret, TruffleHog can attempt to authenticate against the corresponding service. The AWS detector, for example, calls GetCallerIdentity. Each result gets one of three statuses: verified (confirmed valid by API testing), unverified (detected but not confirmed), or unknown (verification attempted but failed due to a network or API error). Private keys are checked using what Truffle Security calls Driftwood, which the README says verifies keys against millions of GitHub users and billions of TLS certificates.

Analysis

For around 20 of the most commonly leaked credential types, trufflehog analyze sends many requests instead of one to work out who created the credential, which resources it can reach, and what permissions it holds.

Key features

• Verified-only output: --results=verified filters results down to confirmed live credentials, cutting triage noise.
• GitHub depth: scan whole organizations, exclude archived repositories, and include issue and pull request comments.
• Deleted and hidden commit discovery: the alpha github-experimental --object-discovery mode enumerates cross-fork object references and deleted commits and scans them. The README warns this can take from 20 minutes to a few hours on large repositories.
• Cloud storage scanning: S3 with IAM role assumption across accounts, prefix and extension filters, plus GCS.
• Container images: scan images from a registry, the local Docker daemon, or a saved tarball.
• CI-friendly output: JSON, GitHub Actions annotations, and SARIF for upload to GitHub code scanning, plus --fail to exit with code 183 when results are found.
• GitHub Action and GitLab CI examples, and a pre-commit hook.
• Custom regex detectors (alpha): define your own patterns and keywords, optionally verified via a webhook that returns 200 for valid secrets.
• Ignore comments: a trufflehog:ignore comment suppresses a line, and --no-ignore-tag re-surfaces those findings for review.
• Canary token detection: statically detects canarytokens.org tokens.
• Signed releases: checksums are signed with cosign, and the install script can verify them.

Getting started

On macOS:

brew install trufflehog

Or with Docker, scanning Truffle Security's test repository:

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

Or the install script, optionally verifying the signature with -v (requires cosign):

curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

Common scans from the README:

trufflehog git https://github.com/trufflesecurity/test_keys --results=verified
trufflehog github --org=trufflesecurity --results=verified
trufflehog filesystem path/to/file1.txt path/to/file2.txt path/to/dir
trufflehog s3 --bucket=<bucket name> --results=verified,unknown
trufflehog docker --image trufflesecurity/secrets --results=verified

For a pull request in CI, scan only the commits since the default branch and fail if anything is found:

trufflehog git file://. --since-commit main --branch feature-1 --results=verified,unknown --fail

Exit codes are 0 for no errors and no results, 1 for an error, and 183 for results found when --fail is set.

Use cases

• Blocking secrets in pull requests: the GitHub Action scans only the commits in a push or PR and reports verified and unknown results.
• Incident response: after a suspected leak, scan an organization with --results=verified to find which exposed credentials still work, then use analyze to scope what they can access.
• Cloud estate audits: pass several --role-arn values to scan every S3 bucket each role can list across AWS accounts.
• Container supply chain checks: scan built images before pushing them to a registry.
• Checking collaboration tools: scan Postman workspaces, Jenkins servers, Elasticsearch clusters, and Hugging Face models, datasets, and spaces.
• Ad-hoc pipelines: pipe arbitrary data into trufflehog stdin, for example a gzipped object streamed from S3.

How it compares

The README does not benchmark TruffleHog against other scanners. Within the secret-scanning category, its most visible differences are the breadth of source integrations and the emphasis on active verification, which turns a list of regex hits into a list of credentials known to be live. Tools that only pattern-match can be faster to run and never contact third-party APIs, which some environments require; TruffleHog supports that mode too via --no-verification. Truffle Security also sells TruffleHog Enterprise for continuous monitoring of Git, Jira, Slack, Confluence, Microsoft Teams, SharePoint, and more; the open-source CLI is the self-run part of that offering.

Things to know before adopting

• AGPL-3.0 license: since v3.0 TruffleHog is licensed under AGPL-3.0. Running the CLI internally is straightforward, but if you modify it and offer it to users over a network, the AGPL's network clause requires making your modified source available. Embedding it in a commercial product deserves a legal review. Pre-v3 code remains available under GPL-2.0, and contributions require a signed CLA.
• Verification makes outbound requests: verifying a credential means calling the service it belongs to. Disable with --no-verification or point at custom verifiers if that is not acceptable.
• Library use is unstable: the README says the public Go APIs carry no stability guarantees.
• Update checks: the CLI checks for updates unless you pass --no-update.
• Rate limits: unauthenticated GitHub scans are rate limited; pass --token for large organizations.
• Local repo safety: to guard against malicious Git configs (the README cites CVE-2025-41390), local repositories are cloned to a temporary directory before scanning.

Project activity

As of October 2026 the repository has roughly 28,200 stars. It was created on December 31, 2016, and the current v3 line is a complete rewrite in Go. It is licensed under AGPL-3.0. The source is at github.com/trufflesecurity/trufflehog, and the company site is trufflesecurity.com. The project runs a community Slack and a Secret Scanning Discord, accepts new detector contributions with published tooling, and no longer accepts changes to the v2 branch.