Get the free coreGet core

TruffleHog: how to scan your repos for leaked secrets

Updated 5 min readSection 05 / Threats
SHORT ANSWER

TruffleHog is a command line tool that finds leaked secrets in repositories and files. On a Mac, install it with brew install trufflehog. Then, from the folder of a Git repository, scan it with trufflehog git file://. --results=verified. A result is verified when the credential was confirmed valid and active by API testing. It is unverified when it was detected but not confirmed, and unknown when the check failed due to errors. Start with the verified ones and revoke those keys first.

This page gives the commands and explains each part of the output. A scan does not replace revoking a key that has leaked. For that, go to what to do when a key leaked.

01What the tool does

TruffleHog is a secrets discovery, classification, validation and analysis tool. In plain words: it reads code, history and files, recognizes strings that look like credentials, and works out which service each one belongs to. It classifies over 800 secret types, mapping them back to the specific identity they belong to. Then, for every secret it can classify, it can log in to confirm whether that secret is still live.

It has a sub-command for each source of data you may want to scan. This page uses two: git for repositories and filesystem for files and folders.

Attackers use scanners too. The Shai-Hulud npm payload used TruffleHog to find secrets on the machines it reached; the story is on the Shai-Hulud page. A key in a file on your disk is as findable for them as for you.

02Install it on a Mac

With Homebrew, the macOS package manager:

brew install trufflehog

That is the whole setup for the commands below. Use the same terminal for each of them. Run them in a terminal, in the folder you want to check.

03Scan a local repository

Open a terminal in the folder of a Git repository. Then run this command.

trufflehog git file://. --results=verified

git tells it to scan Git history, and file://. points at the current folder. --results=verified limits the output to verified results. Leave the flag off to see everything: by default the output includes verified, unverified and unknown results. Start with the flag on, so the list is short. Once the verified keys are dead, run the scan again without it and read the rest.

04Scan a GitHub repository

To scan a repository on GitHub and show only verified secrets, this command targets a public test repository.

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

Swap the address for your own public repository. For a private repository, clone it to your Mac first and scan the clone with the local command above. The clone is an ordinary local repository, so the command from the previous section applies to it unchanged.

05Scan files and folders

For loose files and directories, such as a project folder that is not a Git repository, use the filesystem source. Here is the form.

trufflehog filesystem path/to/file1.txt path/to/file2.txt path/to/dir

List as many files and folders as you need on the same line. This is the way to check a folder of notes or exports, where a key can sit without ever touching Git. It is also the way to check a project folder you downloaded or unzipped, which has no Git history to scan.

06What verified, unverified and unknown mean

Every result has one of three statuses.

StatusWhat it meansWhat to do
verifiedThe credential was confirmed as valid and active by API testingRevoke it now with its provider
unverifiedDetected but not confirmed valid. It may be invalid or expired, or verification may be disabledLook at it by hand. If it is a real key, revoke it anyway
unknownVerification was attempted but failed due to errorsRun the scan again, then treat it as unverified

A verified hit is a key that worked at the moment of the scan. That is why verified results go first: they are the ones an attacker could use today. Do not read unverified as safe: verification may have been off, or the key may be one the scanner cannot test. Treat an unverified hit that looks like a real key as live until the provider tells you otherwise. The provider is always the most reliable source for whether a secret is still valid.

07Use it before the push, not after

TruffleHog is available as a GitHub Action and a pre-commit hook. A pre-commit hook is a script that Git runs before it records a commit. Use one to reject commits that contain keys detected by your secret scanner. CI is the automatic build system that runs when you push. There, the --fail option makes the scan exit with code 183 when results are found, which can stop a pipeline. GitHub's push protection does a similar job on the server side; see GitHub secret scanning.

08When it finds something

Consider any leaked secret immediately compromised. Revoking the key with its provider is the most important step. That usually means logging into the provider's portal and finding where the secret is managed. If the repository is public, speed matters: automated scanners can locate publicly exposed secrets in minutes. The order of steps is on the page about a leaked key. The repository side is on a key exposed on GitHub. After the key is dead, remove it from Git history if you still want a clean log. Then move the keys out of the project: where to store API keys compares the options on a Mac.

Other scanners exist. Secret scanning compares local and hosted ones, and the GitGuardian alternatives page puts ggshield, git-secrets and others in a table.

09The short version

Install with Homebrew, scan the repository you are in, a GitHub address or a folder with the commands above, and start with the verified results. Verified means confirmed valid and active, so revoke those keys first.

FAQ

What is TruffleHog used for?

Finding leaked credentials. It is a secrets discovery, classification, validation and analysis tool. You point it at a repository, a folder or another data source and it reports what it finds.

Is TruffleHog good?

It classifies over 800 secret types, and for each type it can classify it can also log in to confirm whether the secret is live. That second step cuts noise. The table on the secret scanning page lines it up with other tools.

How do I install TruffleHog on a Mac?

With Homebrew: brew install trufflehog.

What does verified mean in TruffleHog?

The credential was confirmed as valid and active by API testing. Unverified means it was detected but not confirmed valid, and unknown means a verification attempt failed due to errors.

How do I scan a folder with TruffleHog?

Use the filesystem source and list the files or folders: trufflehog filesystem path/to/file1.txt path/to/file2.txt path/to/dir.

Can I use TruffleHog in CI?

Yes. It is available as a GitHub Action and a pre-commit hook. The --fail option makes it exit with code 183 when results are found.

Sources

  1. TruffleHog README
  2. Wiz, Shai-Hulud npm supply chain attack
  3. GitHub docs, remediating a leaked secret
A scan finds keys in files. Artificial Immunity watches program starts on the Mac where your agents work and reports what it finds.Get the free core