TruffleHog

TruffleHog is the open-source secrets-detection tool the CDP (Certified DevSecOps Professional) curriculum names directly, and its headline feature is why: for a large share of the credential types it recognizes, TruffleHog doesn't stop at "this string looks like a secret." It takes the matched value and fires a live, read-only API call at the real provider that would have issued it — AWS, GitHub, Stripe, Slack, and hundreds more — and reports back whether that credential is actually still active right now. Every other scanner on this course's list, gitleaks included, stops at pattern and entropy. TruffleHog adds a fact-check on top, and that single design choice is what this whole page is about.

What TruffleHog is, and the problem it solves

☺ Like you're 10: Old secret-scanners could only guess. This one actually checks — and that turns a pile of maybes into a short, certain list.

TruffleHog started in 2016 as a much simpler tool: a Python script by Dylan Ayrey that walked git history looking for high-Shannon-entropy strings — the observation that a real API key or private key, being close to random, has a statistically higher "surprise per character" than ordinary source code or prose. That first version was useful and also noisy, because entropy alone can't distinguish a real secret from a hash, a UUID, a minified bundle, or any other high-randomness string that happens to live in a repository. TruffleHog v3 — a full rewrite in Go by Truffle Security Co., and the version actually in production use today — is a different tool wearing the same name. It replaced entropy-only guessing with several hundred purpose-built detectors, one per credential type or vendor format, and it added the feature this page is really about: live verification. Truffle Security's own detector count keeps climbing with every release, comfortably past 800 as of recent versions — treat any specific number here as a snapshot, and check the project's own repository for the current count rather than something fixed.

The problem this solves is specifically the one every regex- or entropy-based scanner leaves open. gitleaks, Semgrep's secret-shaped rules, and detect-secrets can all tell you a string looks like a live AWS access key. None of them can tell you whether that key still works — whether it was rotated eighteen months ago, whether it's a deliberately fake value sitting in a test fixture, or whether it's a real, currently-exploitable credential sitting in a commit from last week. Every hit from a pattern-only scanner is a "maybe," and a team that spends months triaging maybes eventually starts skimming past all of them — the same alert-fatigue failure this course keeps returning to for every gate that cries wolf too often. TruffleHog's verification step collapses that maybe into a fact: Verified means a real, currently-active credential is sitting in your repository right now; Unverified means the pattern matched but nothing confirmed it either way. See Static Analysis & Secrets Detection for where this fits next to SAST triage generally — that page treats TruffleHog's verified/unverified split as the central distinction of its own secrets-detection chapter.

The pipeline: sources, chunkers, decoders, detectors, verifiers

☺ Like you're 10: Every scan is the same five-step assembly line, no matter whether it's reading a git repo, a container image, or an S3 bucket.

TruffleHog v3's engine is a concurrent producer/consumer pipeline, and the vocabulary matters because each stage maps to a real CLI subcommand or config block. Understanding it is most of what makes an unfamiliar flag combination make sense on first read.

Named individually: Sources are where TruffleHog reads bytes from — not just "a git repo." Dedicated source connectors exist for local and remote git repositories (full history, every branch, by default), whole GitHub or GitLab organizations, plain filesystem paths, S3 and GCS buckets, Docker images (scanned layer by layer, not just the final flattened filesystem), and CI build-log sources like CircleCI, Travis, and Jenkins, among others — each is its own subcommand. Chunkers split whatever a source returns into bounded, scannable pieces, since a source can be a single commit diff or a multi-gigabyte image layer. Decoders unwrap common encodings — Base64 chief among them — before detection runs, because a Base64-encoded key is invisible to a regex scanning raw bytes. Detectors are the roughly 800 purpose-built matchers, each combining a small set of trigger keywords (a cheap pre-filter — skip a chunk entirely if none of a detector's keywords appear, which is most of what keeps a full-history scan tractable) with a regex specific to that vendor's credential format. And verifiers, where a detector implements one, take a matched value and fire the live, read-only call that turns a match into a confirmed fact.

Detectors and what "Verified" actually means

☺ Like you're 10: The check is different for every kind of key, but the idea is always the same — ask the real service a harmless question only a working key could answer.

Each verifier is written specifically for its provider's API, and the pattern repeats: find the cheapest possible read-only endpoint that requires authentication and returns a clean success/failure signal. A few concrete examples make the shape obvious:

• AWS access keys — the detector needs to find an access key ID and a matching secret access key together in the same chunk (it pairs them by proximity), then verifies by calling sts:GetCallerIdentity: a response means the pair is live and resolves to a real IAM identity; an auth failure means it's dead. A lone access key ID with no adjacent secret nearby simply can't be verified this way — see the gotcha below.
• GitHub personal access tokens — a GET against the authenticated user endpoint with the token as a bearer credential. 200 means the token is live right now; 401 means it's revoked, expired, or never existed.
• Stripe secret keys — a call against a low-privilege, read-only endpoint (an account or balance lookup). A successful response confirms a live production key without touching a single charge or customer record.
• Slack tokens and incoming webhooks — an authenticated identity check against Slack's own API, the same "who am I" shape as the others.

Contrast that with what gitleaks does with the exact same matched string: nothing further. gitleaks is regex and entropy scoring over a diff or a full history, with zero network calls of any kind — which is precisely why it's fast, safe to run fully offline, and the right default for a pre-commit hook. It's also exactly why every one of its hits is unconfirmed. Truffle Security's own published benchmarks put the false-positive reduction from verification in the 90%-plus range for the detector types it covers — treat that figure as vendor-sourced marketing rather than an independently audited number, but the direction is not in dispute: in any repository old enough to have accumulated rotated credentials, revoked tokens, and obviously-fake test fixtures, the overwhelming majority of pattern-only hits turn out to be dead on inspection, and verification is what tells you which handful aren't without a human tracing each one down.

Custom detectors: teaching TruffleHog your own token format

☺ Like you're 10: The built-in detectors know every major vendor's key shape already — a config file is how you teach it your own company's shape too.

The ~800 built-in detectors ship compiled into the binary, so a default run needs no rule file at all — a real difference from gitleaks, which always needs a TOML ruleset (even if it's the bundled default one) to know what to look for. But most organizations eventually issue their own internal API tokens, and those obviously aren't in anyone's public detector catalog. TruffleHog supports a custom detectors config (--config) for exactly this: a keyword pre-filter, a regex for your token's shape, and — the part worth doing properly — a verification block that fires an HTTP request at your own internal service, so an internally-issued credential gets the same confirmed/unconfirmed treatment as an AWS or GitHub key.

# custom-detectors.yaml — teach TruffleHog about an internal token format
# The exact field names here have shifted across TruffleHog releases —
# treat this as the shape, and check the project's own examples/ folder
# for the current schema before committing one to a pipeline.
detectors:
  - name: acme-internal-api-token
    keywords:
      - "acme_key_"
    regex:
      token: 'acme_key_[A-Za-z0-9]{40}'
    verify:
      - endpoint: https://internal-api.acme.example/v1/whoami
        unsafe: false                      # never set true for a call with side effects
        headers:
          Authorization: "Bearer {token}"
        successRanges:
          - "200"

Notice the shape mirrors the built-in AWS and GitHub verifiers exactly: a cheap, read-only, authenticated endpoint, and a success signal that requires nothing more than a normal 200 response to confirm. That's the whole trick — you're not writing detection logic from scratch, you're describing your token's shape and pointing at the one endpoint that can honestly answer "is this still valid."

Day-to-day commands

☺ Like you're 10: One flag matters more than all the others — the one that says "only tell me about the keys that are actually still real."

# scan a local git repo — full history, every branch, by default
$ trufflehog git file://.

# the flag that matters most for a merge gate: only confirmed-live hits
$ trufflehog git file://. --only-verified

# CI diff-aware mode — only what's new on this branch since main
$ trufflehog git file://. --since-commit origin/main --branch feature/reporting-export

# scan an entire GitHub org in one pass (needs a token with read access)
$ trufflehog github --org=acme-corp --token=$GITHUB_TOKEN --only-verified

# scan a container image layer by layer, not just the flattened filesystem
$ trufflehog docker --image=ghcr.io/acme/checkout:1.4.3

# scan an S3 bucket — build artifacts, backups, log exports
$ trufflehog s3 --bucket=acme-build-artifacts

# scan a plain filesystem path, no git involved at all
$ trufflehog filesystem /path/to/extracted/artifact

# machine-readable output for a dashboard or a DefectDojo import
$ trufflehog git file://. --json --only-verified > results.json

# skip verification entirely — faster and works air-gapped, but back to "maybe"
$ trufflehog git file://. --no-verification

# fail the build on a verified hit — see the gotcha below before you skip this
$ trufflehog git file://. --only-verified --fail

Gotchas and failure modes

☺ Like you're 10: Most of the surprises trace back to one thing — verification needs to actually reach the real internet, and not every credential can be checked at all.

• The --fail gotcha above is the highest-impact one on this list — it's the difference between a gate that blocks a merge and one that only decorates a log nobody reads.
• Verification needs real network egress. Confirming a hit means reaching sts.amazonaws.com, api.github.com, api.stripe.com, and dozens of other providers' APIs directly from wherever the scan runs. A CI runner behind a restrictive egress allowlist, or an air-gapped scan environment, will silently fall back to Unverified or an error state for everything — quietly losing the tool's entire differentiator without necessarily throwing an obvious error.
• Not every detector implements verification. Roughly 800 detectors exist; a meaningful share of the less common or older vendor formats are pattern-only, with no safe verification path known or implemented. An "Unverified" result doesn't always mean "not yet confirmed" — sometimes it means "this credential type has no verification path at all," and treating every Unverified hit as equally uncertain is a mistake worth avoiding.
• Paired credentials need to actually be paired. AWS's detector (and others like it) needs both halves of a credential found close together to attempt verification. An access key ID sitting in one file with its matching secret key committed somewhere entirely different in the repository won't verify, even though both pieces genuinely exist and genuinely work together.
• Verification is live traffic against a real account. A read-only sts:GetCallerIdentity call is safe by design, but it's still a real API call that can show up in the provider's own logs — a CloudTrail entry, for instance. That's a fine trade for confirming an active leak, but worth knowing if you're scanning in a context where every API call needs to be independently explainable to an auditor.
• Rate limits. Scanning a large GitHub org with many candidate matches can trip the verifying provider's own API rate limits, producing a wave of ambiguous "couldn't verify" results rather than a clean verified/unverified split — rerun narrower or throttled rather than trusting a rate-limited pass as a clean bill of health.
• Full history by default is slow, and noisy on first run. A repository scanned for the very first time can surface years of accumulated historical findings in one pass, the same "wall of pre-existing debt" problem SAST baselining solves for static analysis. Run an initial full-history onboarding scan separately from a fast, diff-aware CI gate scoped with --since-commit.
• Detector coverage isn't pinned. New detectors ship in new releases the same way a SAST registry gains rules over time — a scan that was clean last month can surface a newly added detector's finding today with no code change at all. Pin a specific TruffleHog version for a reproducible gate, the same discipline this course recommends for Semgrep's Registry.

TruffleHog versus gitleaks and detect-secrets

☺ Like you're 10: All three look for the same kind of thing — the difference is speed versus certainty, and most real pipelines use more than one.

None of these tools is strictly "better" — they trade speed and network dependence for certainty in opposite directions, and a mature pipeline typically layers more than one.

The practical pairing this course keeps coming back to: run gitleaks (or detect-secrets) as the fast, zero-network layer at pre-commit and on every pull-request diff, and run TruffleHog with --only-verified --fail as the slower, higher-confidence layer — either a second CI stage on every push, or a scheduled deep scan across full history. gitleaks tells you something needs a look in milliseconds; TruffleHog tells you, with certainty, which of those somethings actually needs a rotation right now. See Static Analysis & Secrets Detection for the full worked example of a verified TruffleHog hit moving through triage, and the leaked credential triage drill for a timed, hands-on run of exactly that scenario.