TruffleHog

TruffleHog finds and classifies machine credentials such as API keys, database passwords and private keys across Git, Docker, filesystems, cloud storage and other supported sources.

Install the official Kali package with sudo apt install trufflehog, then verify the executable with trufflehog --version.

TruffleHog can test supported credentials against their real APIs; accepted credentials are verified, detected but unconfirmed candidates are unverified, and failed verification attempts are unknown.

Use the Git source on the official demo repository or a repository you own or are authorized to scan, and select the required result states with --results.

Exit code 183 means --fail was enabled and results were found without a scan error; it should be handled as a secret-detection outcome in CI.

TruffleHog offers broader source coverage and live verification, while Gitleaks is a lighter Git-focused option often suited to pre-commit checks.

TruffleHog is a secrets discovery, classification, verification and analysis tool. It searches authorized Git history, GitHub organizations and repositories, filesystems, Docker images, cloud storage and other supported systems for machine credentials such as API keys, database passwords and private keys. It classifies more than 800 secret types and uses more than 700 detectors that can verify many findings against their real APIs. Its main security use is finding exposed credentials early enough to revoke, rotate and remove them.

On Kali Linux, install the official package with `sudo apt install trufflehog`, then confirm the executable with `trufflehog --version`. Homebrew, Docker, the official installation script, GitHub release binaries and a Go source installation are also documented options. Use one managed route where possible so the binary found on PATH is predictable. Before the first internal scan, test the setup against the official `trufflesecurity/test_keys` demo repository.

For a classified secret, TruffleHog can contact the associated service and attempt authentication to determine whether the credential is live. A successful check produces a verified result. If a candidate is detected but not confirmed, it is unverified; if verification was attempted but failed because of a network or API problem, it is unknown. Live verification sends credential material to the relevant verifier, so only scan assets and credentials you are authorized to test.

Verified means the relevant API or authentication mechanism accepted the credential. Unverified means a detector classified a candidate but TruffleHog did not confirm that it was usable. Unknown means verification was attempted but could not be completed, commonly because of a network or API failure. The default result selection includes all three statuses, while a command such as `--results=verified` requests only confirmed findings.

Use the `git` source on a repository you own or are authorized to assess. The official safe example is `trufflehog git https://github.com/trufflesecurity/test_keys --results=verified`. For an authorized change range in CI, `trufflehog git file://. --since-commit main --branch feature-1 --results=verified,unknown --fail` compares the feature branch with main. Local repositories are cloned to a temporary directory first for safety unless the documented trusted-local configuration behavior is deliberately selected.

GitHub permits unauthenticated access, but broader scans can hit API rate limits. Supply a valid personal access token with the documented `--token` option when scanning an authorized GitHub scope that needs authenticated API access. Keep the token out of command logs, screenshots and CI output, and grant only the access required by the approved scan. An invalid token must be replaced before authenticated collection can continue.

If TruffleHog displays its banner and then exits, the documented explanation is that no secrets were detected. Confirm that the intended source and path were supplied, and verify that a Docker run mounted the host directory into the container when scanning local files. Do not interpret an empty result as proof that a repository is safe, because detector coverage and source selection still matter. Test the installation against the official authorized demo repository before troubleshooting an internal scan.

Exit code 183 is expected only when `--fail` is enabled and the scan finds one or more results without otherwise failing. It lets CI distinguish a detected secret from both a clean scan and an execution error. Exit code 0 means there were no errors and no results, while exit code 1 means an error occurred. Configure the pipeline to treat 183 as a secret-detection condition rather than mislabeling it as a scanner crash.

Gitleaks is the closest alternative secret scanner. TruffleHog verifies secrets live against APIs and covers more sources, including cloud services, Docker images and service integrations, while Gitleaks is lighter and often faster for pre-commit or Git-only scanning. Choose TruffleHog when live verification and broad source coverage matter, and consider Gitleaks when a compact Git-focused check is the priority. Some teams use both at different stages, but either tool still requires authorization and a credential-response process.

Use the `docker` source to inspect an authorized image from a registry, local daemon or tarball. The official demonstration command is `trufflehog docker --image trufflesecurity/secrets --results=verified`; local-daemon and tarball forms use `docker://new_image:tag` and `file://path_to_image.tar`. This source scans image content rather than merely running TruffleHog inside a container. When the scanner itself runs in Docker, mount the host directory correctly or local files will not be visible inside the container.

In CI, scan the authorized checkout with `trufflehog git file://. --since-commit main --branch feature-1 --results=verified,unknown --fail`. A GitHub Actions checkout needs `fetch-depth: 0` so the relevant history is present, and the official action accepts `extra_args: --results=verified,unknown`. For code-scanning ingestion, generate SARIF with `trufflehog filesystem . --sarif --no-verification > results.sarif` and upload it through the platform's SARIF workflow. Protect output artifacts and teach the job that exit code 183 means findings were detected.

A `trufflehog:ignore` comment on the same line tells TruffleHog to ignore that secret. This can be useful for a reviewed test fixture, but it should not be used to conceal a real credential. The `--no-ignore-tag` flag reports findings even when that comment is present, which is useful for an authorized audit of suppression usage. Document every accepted suppression and periodically confirm that the ignored value cannot authenticate.

For private keys, verified means the key was confirmed usable for SSH or SSL authentication. TruffleHog uses Driftwood technology to verify private keys against GitHub users and TLS certificates. That status is stronger than merely recognizing PEM-like text, but it does not establish who intentionally placed the key in the source. Treat a verified private key as an urgent credential exposure and follow the owner's approved revocation or replacement process.

TruffleHog is a legitimate defensive security tool, but a scan can read sensitive history and may send candidate credentials to real services for verification. Use it only on repositories, cloud accounts, images and services you own or have explicit authorization to assess. Define whether live verification is permitted before scanning; use `--no-verification` when policy forbids those checks. Minimize access, protect findings and rotate confirmed credentials instead of attempting any activity beyond the approved validation.