TruffleHog tutorial: install, scan, and verify live secrets

TruffleHog is a free, open-source secret scanner whose standout feature is live verification: after finding a candidate credential, it calls the provider’s API to confirm whether the key is still active. Install it with brew, Docker, the install script, or go install, then scan a git repo, GitHub org, filesystem, or Docker image, and add --results=verified to surface only confirmed live leaks. This tutorial walks the real commands from the TruffleHog repo.

TL;DR:

• Install: brew install trufflehog, a Docker image, the official install script, or go install from source.
• Scan: trufflehog git, trufflehog github, trufflehog filesystem, and trufflehog docker cover most needs; more subcommands reach S3, GCS, Postman, and CI systems.
• Verify: --results=verified outputs only credentials TruffleHog confirmed are still live, cutting false positives.
• Automate: add a pre-commit hook and a GitHub Action so leaks are caught before and after they reach the remote.
• New to the tradeoffs? Read gitleaks vs TruffleHog first, then browse the tools directory.

How do you install TruffleHog?

There are four common routes. Pick whichever suits your environment:

1. Homebrew (macOS) is the simplest: brew install trufflehog.
2. Docker avoids a local install entirely. Mount your working directory and run the image, for example docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys.
3. Install script drops a binary into a path of your choice: curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin. Pre-built binaries are also on the releases page.
4. Go install builds from source: git clone https://github.com/trufflesecurity/trufflehog.git, then cd trufflehog; go install.

Confirm the install with trufflehog --help, which lists every available subcommand.

How do you scan different sources?

TruffleHog uses one subcommand per source type. Here are the four you will reach for most, exactly as documented.

Scanning a git repository

Point it at a remote or local repo and it walks the full history across commits:

trufflehog git https://github.com/trufflesecurity/test_keys

For a local checkout, use the file:// form. You can scope the scan to recent work with --since-commit and --branch, and fail the run on findings with --fail:

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

Scanning GitHub

The github subcommand scans across an organisation or a single repository:

trufflehog github --org=trufflesecurity

Scanning a filesystem

Use filesystem to scan local files and directories, which is handy for build artefacts, config folders, and unpacked archives:

trufflehog filesystem path/to/file1.txt

Scanning a Docker image

The docker subcommand inspects image layers for baked-in credentials, a frequent leak source:

trufflehog docker --image trufflesecurity/secrets

Beyond these, the scanner ships gitlab, s3, gcs, postman, jenkins, elasticsearch, and stdin subcommands, so secrets that escaped the repo into cloud buckets or SaaS tools are still in reach.

What does live verification do?

This is the feature that sets TruffleHog apart. When it detects a candidate secret, it can attempt to authenticate against the matching provider to prove the key still works. Per the TruffleHog documentation, the --results flag controls what you see: verified means confirmed valid by the provider API, unknown means verification failed due to an error, and unverified means detected but not checked.

To surface only confirmed live leaks, add --results=verified:

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

A verified hit looks like this in the output:

Found verified result 🐷🔑
Detector Type: AWS
Raw result: AKIAYVP4CIPPERUVIFXG
Verified: true

The Detector Type tells you which provider matched, and Verified: true confirms the credential authenticated successfully. That single line is the difference between a pattern that looks like a key and a key an attacker could use right now, so treat any verified result as an active incident. If you want detections plus failed-verification cases, use --results=verified,unknown.

How do you add a pre-commit hook?

Stopping a secret before it ever leaves your machine is far cheaper than scrubbing history later. Using the pre-commit.com framework, add this to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: trufflehog
        name: TruffleHog
        description: Detect secrets in your data.
        entry: bash -c 'trufflehog git file://.'
        language: system
        stages: ["pre-commit", "pre-push"]

Per the documentation, TruffleHog auto-detects when it runs under the pre-commit.com framework and applies optimal settings, so no extra configuration is needed. If you prefer a plain git hook, a minimal script works too:

#!/bin/sh
export TRUFFLEHOG_PRE_COMMIT=1
trufflehog git file://.

For a wider look at where these hooks fit, see secret scanning in pre-commit hooks.

How do you run TruffleHog in CI?

A pre-commit hook is opt-in, so back it with a server-side gate. The official GitHub Action scans on push and pull request:

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: Secret Scanning
      uses: trufflesecurity/trufflehog@main
      with:
        extra_args: --results=verified,unknown

The fetch-depth: 0 line is important: it fetches full history so the scan covers every commit in the pull request, not just the tip. Pass scanner flags through extra_args. To fail the build only on confirmed live leaks, narrow it to --results=verified.

Where to go next

TruffleHog’s open-source release is under the AGPL-3.0 licence, worth checking against your distribution model before embedding it. Scanning is detection, not remediation: a found key must be rotated, because git history means a committed secret is effectively public. If a scan flags something, follow the response steps in committed a secret to GitHub, then compare scanners in gitleaks vs TruffleHog and browse more write-ups in the guides library.