TruffleHog: credential scanning that verifies whether a leaked secret still works

The problem: a leaked key is only urgent if it still works

Most secret scanners answer one question: does this file look like it contains a credential? That produces a list of matches, and a list of matches is not a risk assessment. A key committed in 2019 and rotated in 2020 is noise. A key committed this morning and still active is an incident. TruffleHog is built around that distinction. The README describes it as doing Discovery, Classification, Validation and Analysis, and the validation step is the one that changes how you triage.

According to the README, secret here means a credential a machine uses to authenticate itself to another machine: API keys, database passwords, private encryption keys. The tool is aimed at security engineers and platform teams who already know secrets end up in repositories and need to decide which ones to act on first. The README also states that for the roughly 20 most commonly leaked credential types, TruffleHog goes beyond a single login check and sends multiple requests to learn who created the secret, what resources it can reach and what permissions it holds. That is a different product category from a pattern matcher, and it is the reason the scan takes longer than a grep.

How validation works, and what the detector set implies

The repository layout shows the mechanism. There is a pkg/detectors directory, and the Makefile has a dedicated test-detectors target that runs go test -tags=detectors against pkg/detectors only. Detectors are therefore the unit of coverage: each one knows how to recognise a credential shape and, where possible, how to authenticate with it. The README puts the classification count at over 800 secret types, and states that for every secret TruffleHog can classify it can also log in to confirm whether the secret is live.

That sentence deserves a careful read. Classification coverage and validation coverage are not the same number. A detector that recognises a token format but cannot verify it will report the finding without a verified flag. This is why the --results=verified flag exists and why the README leads its Quick Start with it: it filters the output down to findings the tool actually confirmed. If you scan with the default settings you get everything the detectors matched, verified or not, and the volume can be large.

The scanning surface is broad. The README lists Git, chats, wikis, logs, API testing platforms, object stores and filesystems. The Dockerfile installs bash, git, openssh-client, ca-certificates, rpm2cpio, binutils and cpio into the runtime image, which tells you the container expects to unpack archives and RPM packages during a scan rather than only read plain text. The go.mod pulls in AWS SDK v2, Google Cloud Storage and Secret Manager, Elasticsearch and Couchbase clients among others, consistent with a tool that reaches into cloud storage and search backends as sources.

Installing TruffleHog and running a first verified scan

The README lists several installation paths. On macOS, Homebrew is the shortest. The formula installs the trufflehog binary, and you can confirm it is on your path by running the version command afterwards.

brew install trufflehog
trufflehog --version

On Linux, the README offers an installation script. The -b flag sets the destination directory, and the script pulls the latest release by default.

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

The README also documents a checksum-verification mode for that script, using the -v flag, which requires cosign to be installed first. If you are installing into a build pipeline rather than a laptop, that is the variant worth using, since the script otherwise fetches a binary over the network without verifying its signature. The README further documents manual verification: download the checksums file plus its .pem and .sig files from the releases page, run cosign verify-blob with the certificate identity regexp and the OIDC issuer set to https://token.actions.githubusercontent.com, then check the SHA256 sums with sha256sum --ignore-missing -c.

For a first real scan, the README's Quick Start uses a public test repository that contains deliberately exposed keys.

trufflehog git https://github.com/trufflesecurity/test_keys --results=verified

The expected output shown in the README begins with a banner, then a line reading Found verified result, followed by fields including Detector Type, Decoder Type, Raw result, Line, Commit, File, Email, Repository and Timestamp. Seeing that block means the scan reached a credential, classified it as an AWS key and confirmed it still authenticates. If you get no output at all, the flag did its job: nothing in that repository verified.

To scan an entire GitHub organisation rather than one repository, the README gives this.

trufflehog github --org=trufflesecurity --results=verified

There is also a flag to skip repositories that are no longer maintained, which matters because archived repositories are a common place for old credentials to sit.

trufflehog github --org=trufflesecurity --exclude-archived

If you would rather not install anything, the README's demo runs the published image directly and mounts the working directory into the container.

docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --org=trufflesecurity

On Windows the README gives separate Command Prompt and PowerShell forms of the volume mount, and on M1 and M2 Macs it adds --platform linux/arm64 to the same command. Those platform variants are in the README; the mount syntax differs enough between shells that copying the Unix line into PowerShell will not work.

Where TruffleHog is the wrong tool

Validation is a network operation. Every verified finding means TruffleHog contacted the service that issued the credential and attempted to authenticate. That has three consequences. It is slower than a pure pattern scan, because the tool waits on remote APIs. It generates authentication attempts against third-party services, which some providers log and rate-limit, and which you should be prepared to explain if a security team at the other end asks. And it requires outbound network access from wherever the scan runs, so an air-gapped build environment will only ever produce unverified results.

The README does not document a rollback or undo path, and it does not describe a dry-run mode for validation. If you need to know exactly what requests leave your network before you run this against production credentials, that information is not in the README.

There is also a scale problem. The README states that classification covers over 800 secret types, but the deeper analysis that maps an identity to its permissions is described as covering the 20 some most commonly leaked credential types. If your environment leans on an obscure internal token format, expect classification and possibly validation, not the full analysis treatment. And if your goal is a sub-second pre-commit hook that blocks a commit, a tool that performs network logins is the wrong shape: you want a local pattern check that fails fast, with TruffleHog running separately on a schedule where latency does not matter.

TruffleHog compared with gitleaks

The most common comparison is against gitleaks, and the difference is architectural rather than a matter of detector counts. Gitleaks is a pattern and entropy scanner: it reads content, applies rules, and reports matches. It does not authenticate to the services behind the credentials it finds. TruffleHog's distinguishing behaviour is precisely that authentication step, which is why its output includes a verified or unverified distinction and why the README's Quick Start uses --results=verified to cut the noise.

That trade-off cuts both ways. Because gitleaks does not make outbound requests, it is cheaper to run on every commit and simpler to reason about in a restricted network. Because TruffleHog does, it can tell you that a finding from three years ago is still an active credential, which a pattern scanner cannot. The honest framing is that they answer different questions, and a team that only runs one of them is accepting a gap: run the fast scanner for enforcement and the validating scanner for triage. TruffleHog's own README points readers to an enterprise product for continuous monitoring of Git, Jira, Slack, Confluence, Microsoft Teams and Sharepoint, which is the vendor's answer for teams that want the validating behaviour as a hosted service rather than a command they schedule themselves.

Licence and the cost of keeping it current

TruffleHog is licensed under AGPL-3.0, and the repository ships a LICENSE file alongside a SECURITY.md and a CODE_OF_CONDUCT.md. AGPL-3.0 is a strong copyleft licence with a network clause: if you modify the software and let users interact with it over a network, the licence's terms reach that deployment. Running the unmodified binary as an internal scanner is a different situation from embedding it in a product you offer to customers. That distinction is worth raising with whoever owns licensing decisions in your organisation before it becomes part of a shipped pipeline; this is a description of the licence, not legal advice.

The upgrade cost is mostly detector drift. The last push to the repository was on 2026-08-24, and the most recent release listed is v3.97.1 on the same date, following v3.97.0 on 2026-08-14 and v3.96.0 on 2026-07-24. That cadence means new credential formats get detectors regularly, and it also means the tool you installed six months ago is missing coverage for whatever launched since. If you pin a version in CI, plan for periodic bumps. The Makefile shows the project's own dogfooding target, dogfood, which runs the scanner against its own repository with JSON output and a raised log level, so the maintainers scan TruffleHog with TruffleHog.

One build detail worth knowing if you compile from source: the Makefile sets CGO_ENABLED=0 for install, run and test, and the Dockerfile does the same in its builder stage. The repository's go.mod declares go 1.25.0 with toolchain go1.25.10, so a source build needs a recent Go toolchain. It also contains two replace directives, one redirecting jpillora/overseer to a Truffle Security fork and one redirecting the archived coinbase/waas-client-library-go to a fork, with a comment noting the original has vulnerable dependencies. Those replacements are part of the build graph you inherit, not optional patches.

Editorial conclusion

Adopt TruffleHog if you need to know which leaked credentials are still live, not just which files match a pattern: the validation step is the reason to pay its runtime cost in CI or on a schedule. Skip it if you only want a fast pre-commit regex check on every keystroke, where a lighter scanner fits better. Before rolling it out, verify two things yourself: which detectors run under --results=verified for the credential types you actually use, and whether your organisation treats AGPL-3.0 as acceptable for the way you deploy it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes