TruffleHog Setup: Catch Leaked API Keys in 13 Steps [2026]

A leaked API key sitting in a public GitHub commit used to be a rare, embarrassing mistake. In 2026 it is a volume problem. GitGuardian’s 2026 State of Secrets Sprawl report counted 28.65 million hardcoded secrets added to public GitHub repositories during 2025, a 34% jump year over year. Internal, private repositories were six times more likely to contain a hardcoded secret than public ones, and a separate October 2026 scan found more than 10,000 Docker Hub images carrying live credentials from upwards of 100 organizations. Almost 75% of the leaked credentials that scanners find are still valid, because nobody rotated them after the leak.

This tutorial walks through setting up two of the most widely used open-source secret scanners, TruffleHog and Gitleaks, from a clean install to a full CI/CD pipeline that blocks a pull request the moment it contains a live AWS key, a Stripe token, or a database password. By the end you will have a working pre-commit hook, a GitHub Actions job, a GitLab CI job, a container-image scan, and an incident-response runbook for the day a scanner actually finds something. The whole setup takes about 90 minutes if you are following along with a test repository.

Neither tool requires a security background to run. If you can edit a YAML file and add a step to a CI pipeline, you can have both scanners enforcing checks on every commit by the end of this guide. What takes longer, and what most of the steps below are really about, is getting the configuration right so the scanner catches real leaks without burying your team in false positives they learn to click past.

·

Google · Preferred Sources

Don't miss new tech stories on Google

Add Tech Insider once in the Google app and our stories appear in your news suggestions.

Add Now

Why Secret Scanning Can’t Wait Until 2027

Every engineering team has told itself the same story: we use environment variables, we have a .gitignore, we’re careful. The data says otherwise. According to the GitGuardian 2026 report, specific service and provider detectors now identify 55.4% of leaked secrets, up from 46.3% in 2024, which means scanners are getting better at catching what people are still shipping. The report also found that 68% of 2025 incidents came from source-control-managed code, while 28% originated entirely outside repositories, in tools like Slack, Jira, and Confluence. Secrets found outside code were actually 13% more likely to be classified as critical than ones found in a repository, because they tend to sit unnoticed for longer.

None of this is abstract risk. A CI/CD pipeline that logs an environment variable, a terraform plan committed with a hardcoded database password, a .env file added by accident during a late-night deploy: these are the everyday events that TruffleHog and Gitleaks are built to catch before a commit ever reaches a remote branch. The goal of this guide is to make that catch automatic, not dependent on a reviewer happening to notice a 40-character string in a diff.

It also helps to be honest about why secrets keep leaking even at companies that know better. Deadlines compress review time. A developer testing against a real staging database pastes a connection string into a script “just for now” and forgets to remove it before committing. A CI job prints an environment variable to its log for debugging and nobody notices the log is public to anyone with repo read access. None of these are exotic attacks. They’re ordinary workflow friction, which is exactly why an automated scanner, not a policy document, is the fix that actually holds up under deadline pressure.

TruffleHog vs Gitleaks: How the Two Scanners Actually Work

TruffleHog and Gitleaks solve the same problem with different engines, and understanding the difference changes how you deploy them. Gitleaks is a pattern-driven scanner. It walks git history and file content, matches strings against a library of regular expressions tuned to specific providers (AWS, Slack, Stripe, GitHub tokens, and so on), and flags anything that scores above a configured entropy threshold. It is fast, it has no network dependency, and it is the tool most teams reach for first because a scan finishes in seconds even on a large repository.

TruffleHog takes an extra step: verification. Once it finds a string that looks like a credential, it can make a live, read-only API call to the relevant provider to confirm whether the key is still active. A result marked “verified” means TruffleHog actually confirmed the credential works right now; “unverified” means it matched the pattern but couldn’t check, often because the provider isn’t supported for verification or the network call failed. That distinction matters enormously for triage. A security team drowning in regex matches from Gitleaks has to manually check each one; a verified hit from TruffleHog is already a confirmed incident.

The practical answer is not to pick one. Gitleaks is the right tool for a sub-second pre-commit hook on every developer’s laptop. TruffleHog is the right tool for a scheduled, deeper scan across full git history, data sources, and container images where verification against live providers is worth the extra time. Most of the teams running a mature setup in 2026 run both, at different points in the pipeline.

Tool	Latest version (Oct 2026)	Detection method	Live credential verification	GitHub stars (approx.)	License
TruffleHog	v3.99.2	Regex + entropy + provider verification	Yes, 800+ detectors	~27,500	AGPL-3.0 (OSS CLI)
Gitleaks	v8.30.1	Regex + entropy rules (gitleaks.toml)	No	~28,900	MIT
GitGuardian ggshield	Commercial CLI, free tier available	Managed detector library + ML scoring	Platform-dependent	N/A (hosted platform)	Proprietary / free tier
detect-secrets (Yelp)	Actively maintained	Plugin-based regex + entropy	No	Lower than above two	Apache-2.0

Prerequisites: What You Need Before You Start

You don’t need a security team or a budget to follow this guide. Everything here runs on free, open-source tooling. Confirm you have the following before Step 1:

• Git 2.40 or newer installed and a test repository you’re allowed to scan (never run your first scan against a production repo you don’t control)
• TruffleHog v3.99.2 or later, the latest open-source CLI release as of October 2026
• Gitleaks v8.30.1 or later
• Docker 24.x or newer if you plan to follow the container-image scanning step
• A GitHub or GitLab account with permission to add workflow files and branch protection rules to at least one repository
• Go 1.22+ only if you intend to build either tool from source instead of using a prebuilt binary
• pre-commit (Python package) if you want the local git-hook integration covered in Step 9

Step 1-2: Installing TruffleHog and Gitleaks

Start with TruffleHog. The project ships prebuilt binaries, a Homebrew formula, and an official install script. On macOS or Linux, the fastest path is Homebrew:

brew install trufflehog
trufflehog --version
# trufflehog 3.99.2

If you’d rather not use Homebrew, the maintainers publish a shell installer that drops a pinned binary into your path:

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

Now install Gitleaks the same way. Homebrew again covers macOS and Linux cleanly:

brew install gitleaks
gitleaks version
# 8.30.1

On Windows, both tools publish standalone .exe binaries on their GitHub Releases pages that you can drop into a directory on your PATH. If you’re containerizing your scanning pipeline instead of installing locally, both projects also publish official Docker images, which becomes useful later when you wire this into CI.

Step 3-4: Running Your First Scan and Reading the Output

Pick a repository you control, ideally one with some git history, and point TruffleHog at it. The git subcommand scans commit history, not just the current working tree, which is where most leaked secrets actually hide, since deleting a file doesn’t remove it from history.

trufflehog git file://./my-test-repo --only-verified --json > trufflehog-results.json

The --only-verified flag is worth using on your first run. It filters the output down to credentials TruffleHog actually confirmed are live against the provider’s API, which turns a potentially noisy first scan into a short, actionable list. Each result in the JSON output includes the detector name, the file and commit where the secret was found, and a Verified: true or Verified: false field.

Now run Gitleaks against the same repository:

gitleaks detect --source . --report-format json --report-path gitleaks-report.json -v

Gitleaks will almost certainly return more raw matches than TruffleHog’s verified-only scan, because it has no way to confirm a key is live, only that a string matches a known pattern or crosses an entropy threshold. That’s expected. The two tools are meant to be read together: Gitleaks for breadth and speed, TruffleHog’s verified results for the “this is definitely a live incident” shortlist.

Step 5-6: Comparing Detection Engines and Building an Allowlist

Your first full-history scan on a repository that’s more than a year old will almost always surface false positives: test fixtures with fake-looking but pattern-matching strings, example .env files from documentation, UUIDs that happen to trip an entropy check. Before you wire either tool into CI, build an allowlist so you’re not training your team to ignore the scanner.

Gitleaks reads its allowlist from a .gitleaks.toml file in the repository root. A minimal allowlist that ignores a known test-fixtures directory and a specific commit looks like this:

[allowlist]
description = "Known false positives"
paths = [
  '''test/fixtures/.*''',
  '''\.gitleaksignore'''
]
commits = ["a1b2c3d4e5f6"]
regexTarget = "match"

TruffleHog uses a different mechanism: an exclusion file passed with --exclude-paths, pointing at a plain-text list of path globs to skip entirely. Keep this file in version control, next to the scanner configuration, and require a short justification in the pull request whenever someone adds a new entry. An allowlist that grows silently over time is how a real leaked credential ends up hidden next to twenty ignored test fixtures.

Step 7-8: Writing Custom Detection Rules and Enabling Provider Verification

Out of the box, both tools ship detectors for the obvious providers: AWS, GCP, Azure, Stripe, Slack, GitHub, Twilio, and dozens more. If your company issues its own internally formatted API keys, say a prefix like acme_live_ followed by 40 hex characters, neither tool will catch it until you teach it the pattern. Gitleaks custom rules go in the same .gitleaks.toml file:

[[rules]]
id = "acme-internal-api-key"
description = "Acme internal service API key"
regex = '''acme_live_[a-f0-9]{40}'''
entropy = 3.5
tags = ["key", "acme", "internal"]

TruffleHog’s verification step relies on provider-specific detectors that know how to call that provider’s API to check validity. For an internal key format with no public API to verify against, TruffleHog will still flag it by pattern but can’t mark it “verified,” which is fine: pattern-matched internal keys should route straight into your incident runbook rather than waiting on a verification call that will never succeed.

Step 9: Adding a Pre-Commit Hook So Secrets Never Leave the Laptop

The cheapest place to catch a leaked secret is before it’s committed, not after it’s pushed. The pre-commit framework makes this a five-line config file. Add a .pre-commit-config.yaml to your repository root:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks

Then install the hook once per developer machine:

pip install pre-commit
pre-commit install

From this point on, every git commit runs Gitleaks against the staged diff first. Use Gitleaks here rather than TruffleHog: a pre-commit hook needs to return in well under a second to not annoy developers, and Gitleaks’ pattern-only approach is fast enough for that. Save TruffleHog’s heavier, verification-backed scan for CI, where a few extra seconds don’t matter.

Step 10: Automating Scans in GitHub Actions

A pre-commit hook only protects developers who installed it. CI is what protects you against the developer who didn’t, or who committed with --no-verify. Add a workflow file at .github/workflows/secret-scan.yml that runs both tools on every pull request:

name: Secret Scan
on: [pull_request]
jobs:
  trufflehog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: TruffleHog scan
        uses: trufflesecurity/[email protected]
        with:
          extra_args: --only-verified --fail
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Gitleaks scan
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The fetch-depth: 0 setting matters: without it, GitHub Actions checks out a shallow clone with only the latest commit, and both scanners will silently miss anything buried deeper in history. Set branch protection to require this check before merge, and a pull request carrying a verified secret simply can’t land.

Step 11: Automating Scans in GitLab CI

If your team runs GitLab instead, the same two-scanner approach fits into a .gitlab-ci.yml stage. GitLab Ultimate has a built-in secret detection feature, but the open-source jobs below work on any tier, including the free one:

secret-scan:
  stage: test
  image: ghcr.io/gitleaks/gitleaks:v8.30.1
  script:
    - gitleaks detect --source . --report-format json --report-path gitleaks-report.json --exit-code 1
  artifacts:
    paths:
      - gitleaks-report.json
    when: always

trufflehog-scan:
  stage: test
  image: ghcr.io/trufflesecurity/trufflehog:v3.99.2
  script:
    - trufflehog git file://. --only-verified --fail
  artifacts:
    paths:
      - trufflehog-results.json
    when: always

Both jobs run in the test stage so a merge request can’t advance to deploy until the scan passes. The --exit-code 1 and --fail flags are what actually break the pipeline on a hit; without them, both tools will happily log a finding and let the job pass green, which defeats the point.

Step 12: Scanning Docker Images for Secrets Baked Into Layers

Git history isn’t the only place secrets hide. A COPY .env . line in a Dockerfile, or a build argument passed with --build-arg API_KEY=... instead of a build secret, bakes the credential directly into an image layer, where it survives even if the final container never prints it. The October 2026 report that found secrets in more than 10,000 Docker Hub images is exactly this failure mode at scale. TruffleHog can scan an image directly:

trufflehog docker --image your-registry/your-app:latest --only-verified

Run this as a step after your image build and before you push to a registry, not after. Once an image with a baked-in secret is pushed and pulled even once, you have to treat the credential as compromised and rotate it, regardless of whether you later delete the tag. Add this scan to the same CI job that builds and tags your production images.

Step 13: Building an Incident Response Runbook for When a Scanner Finds Something

Installing scanners without a response plan just converts “unknown leaked secret” into “known leaked secret nobody acted on.” Write down, before you need it, exactly what happens when CI reports a verified hit. At minimum, the runbook should cover:

• Immediate revocation: rotate or revoke the credential at the provider first, before investigating how it leaked. A valid key sitting in a scan report is still a live risk every minute it isn’t revoked.
• History cleanup: removing the secret from the latest commit doesn’t remove it from git history. Use git filter-repo or BFG Repo-Cleaner, then force-push and have every contributor re-clone.
• Scope the blast radius: check provider access logs for any usage of the credential between when it was committed and when it was revoked.
• Root cause: was this a missing pre-commit hook, a bypassed check, a secret pasted into a config file that should have used a vault reference instead?
• Prevent recurrence: if the same pattern of leak happens twice, that’s a process gap, not a one-off mistake.

Given that nearly 75% of credentials found by scanners are still valid when discovered, according to GitGuardian’s 2026 figures, the revocation step is the one your runbook cannot skip or delay, even for a key that “probably isn’t that sensitive.”

Common Pitfalls When Deploying Secret Scanners

Teams tend to make the same handful of mistakes when they first roll these tools out. Watch for these five in particular.

• Scanning only the working tree, not history. A shallow clone or a scan that skips git log will miss a secret that was committed and later deleted. It’s still in history, and TruffleHog’s git mode or a full-depth checkout in CI is required to catch it.
• Treating every Gitleaks match as a confirmed incident. Gitleaks has no verification step. A pattern match is a lead to investigate, not proof of an active credential. Escalating every raw match as a P1 burns out a security team fast.
• Letting the allowlist grow without review. Every allowlist entry is a blind spot. If adding an exclusion doesn’t require the same review as adding a dependency, the allowlist eventually hides a real leak.
• Skipping the –fail flag in CI. Both tools can run, log output, and still exit 0 unless configured to fail the job on a finding. A scanner that can’t block a merge is a dashboard, not a control.
• Forgetting Docker images and CI logs. A pipeline can be clean of secrets in git and still leak one through an echoed environment variable in a build log or a secret baked into an image layer, as the Docker Hub statistics above show happening at scale.

Troubleshooting Guide: Fixing the Most Common Errors

Here are the issues that come up most often once teams move past the first clean scan.

Symptom	Likely cause	Fix
GitHub Actions scan finds nothing on a repo you know has secrets	Shallow clone, missing fetch-depth: 0	Set fetch-depth: 0 on the checkout step so full history is available
TruffleHog reports zero verified secrets but Gitleaks finds dozens	Working as intended: Gitleaks has no verification step	Review Gitleaks’ unverified matches manually; don’t expect parity between the two
Pre-commit hook times out or feels slow	Running TruffleHog, not Gitleaks, as the pre-commit hook	Use Gitleaks for pre-commit; reserve TruffleHog for CI and scheduled scans
CI job passes even though the console shows a finding	Missing --fail (TruffleHog) or --exit-code 1 (Gitleaks)	Add the explicit fail/exit flag to the scan command
Gitleaks custom rule never matches	Regex escaping issue in TOML, or entropy threshold set too high	Test the regex in isolation with gitleaks detect --config and lower entropy incrementally
Known test fixtures keep triggering alerts	No allowlist configured	Add a scoped [allowlist] entry for the fixtures path, reviewed in PR
TruffleHog verification calls are slow in CI	Scanning full history with verification against many providers on every run	Run verified full-history scans on a schedule, not on every PR; use pattern-only mode for PR checks
Docker image scan can’t find the image	Image not yet pushed to a registry accessible from the CI runner	Scan the locally built image by tag before the push step, not after
GitLab CI job reports “command not found: gitleaks”	Wrong or missing container image in the job definition	Pin the job to ghcr.io/gitleaks/gitleaks:v8.30.1 rather than a generic Linux image

Advanced Tips: Tuning Entropy, Scheduling Deep Scans, and Alerting

Once the basic pipeline is running cleanly, a few refinements separate a working setup from a mature one. First, tune entropy thresholds per rule rather than globally. A high-entropy JWT and a high-entropy UUID look similar to a generic threshold; a per-rule entropy value in your .gitleaks.toml cuts false positives without losing real detections.

Second, split your scanning cadence. Run Gitleaks on every commit (pre-commit) and every pull request (CI), but run a TruffleHog full-history verified scan against your entire organization on a schedule, say nightly or weekly, rather than per-PR. Full-history verification against live providers takes real time on a large monorepo, and it catches a different problem: secrets that were committed long before this pipeline existed.

Third, pipe verified findings somewhere a human will actually see them immediately, not just into a CI log nobody reads until Monday. A simple pattern is a small script step after the scan job that posts to a Slack or Teams webhook only when the JSON output contains a Verified: true entry, so routine unverified noise doesn’t page anyone, but a live credential does.

#!/usr/bin/env bash
# Alert only on verified TruffleHog hits
if jq -e '.[] | select(.Verified == true)' trufflehog-results.json > /dev/null; then
  curl -X POST -H 'Content-type: application/json' \
    --data '{"text":"Verified secret detected in CI scan. Rotate immediately."}' \
    "$SLACK_WEBHOOK_URL"
  exit 1
fi

Finally, treat the scanner configuration itself as code worth reviewing. Changes to .gitleaks.toml, exclusion paths, and entropy thresholds should go through a pull request like any other change, with a required reviewer who isn’t the person who wrote the rule. This is the same discipline Gartner’s research found in mature programs: 55% of respondent organizations formally include vulnerability-assessment tooling in their broader security program, and 52% include patch-management tooling as a managed, reviewed part of the stack, not a one-off script someone ran once, according to Gartner’s peer community research.

The Complete Working Pipeline: Putting It All Together

Here’s the full project structure you should have after completing all 13 steps, ready to drop into any Git repository:

your-repo/
├── .gitleaks.toml              # custom rules + allowlist (Steps 5-7)
├── .pre-commit-config.yaml     # local Gitleaks hook (Step 9)
├── .github/
│   └── workflows/
│       └── secret-scan.yml     # TruffleHog + Gitleaks on every PR (Step 10)
├── .gitlab-ci.yml              # same checks for GitLab (Step 11)
├── scripts/
│   └── alert-on-verified.sh    # Slack webhook on verified hits (Advanced Tips)
└── docs/
    └── secret-incident-runbook.md  # revocation + history cleanup steps (Step 13)

This layout gives you defense in depth without depending on any single check. A developer who skips the pre-commit hook still gets caught in CI. A secret that slips past both still gets caught by the nightly scheduled full-history scan. A secret baked into a container image gets caught before it’s pushed. And when something does get through, the runbook tells the team exactly what to do in the first five minutes, which is the difference between a contained incident and a live credential sitting unrotated for weeks.

TruffleHog and Gitleaks vs the Managed Alternatives

Open-source scanners aren’t the only option, and it’s worth knowing when a managed platform earns its cost. GitGuardian’s own ggshield CLI wraps a hosted detector library and dashboard around similar scanning logic, with a free tier for individual developers and paid plans for organization-wide monitoring, including the ability to scan Slack, Jira, and Confluence, the non-code sources that accounted for 28% of 2025 incidents in the firm’s own data. Yelp’s detect-secrets takes a plugin-based approach similar to Gitleaks but with a smaller detector library and community than either TruffleHog or Gitleaks.

For most teams starting out, the open-source combination of Gitleaks and TruffleHog covers git-based risk completely at zero licensing cost. The case for a managed platform shows up once you need to scan non-code systems at scale, centralize findings across dozens of repositories and teams, or hand a compliance auditor a dashboard instead of a folder of JSON reports. There is no wrong starting point here: every team benefits from running the open-source scanners first, even if a managed platform joins the stack later.

How Automation Changes the Math on Vulnerability and Secret Management

Secret scanning is one piece of a larger shift toward automated security tooling, and the industry data on that shift backs up why teams keep adding these checks rather than relying on manual review. The Ponemon Institute found that 56% of surveyed organizations now use automation to assist with vulnerability management broadly, and among that group, 59% automate patching itself, 47% automate prioritization of what to fix first, and 41% automate reporting, according to the Ponemon and Rezilion State of Vulnerability Management in DevSecOps report. The same research found that 52% of organizations rate their prioritization of critical vulnerabilities as very effective, while 43% rate timely patching as highly effective, numbers that track closely with how secret-scanning programs mature: the ones that automate detection and prioritize verified findings over raw matches get better outcomes than the ones relying on a human to eyeball every diff.

That pattern extends to how responsibility gets assigned once automation is in place. Gartner’s peer research on vulnerability patching found that 51% of respondents say IT holds primary responsibility for patching security vulnerabilities, while 29% say the responsibility is shared equally between IT and information security teams. Secret scanning tends to follow the same split: a platform or DevOps team owns the CI integration, while security owns the response runbook and the decision on which findings are urgent.

Scaling This Setup Across a Whole Organization

Rolling secret scanning out to one repository is a weekend project. Rolling it out across fifty repositories owned by a dozen different teams is a different challenge entirely, and it’s worth planning for before you start. Use a shared, central configuration repository that holds a baseline .gitleaks.toml and reusable GitHub Actions workflow, referenced by every other repo rather than copy-pasted into each one. When you update entropy thresholds or add a detector for a new internal key format, every repository that references the shared config picks up the change on its next run instead of waiting for fifty separate pull requests.

Track rollout with a simple dashboard: which repositories have the pre-commit hook installed, which have the CI check enabled and required on the default branch, and which are still unprotected. Repositories without the check enabled are exactly where a leaked secret is most likely to slip through unnoticed, since they’re usually the ones nobody’s actively maintaining. Make enabling the check part of onboarding any new repository, not an afterthought bolted on once something goes wrong.

Assign an owner for the shared configuration itself, the same way you’d assign an owner to a shared Terraform module or a common CI template. Without a named owner, the baseline rule set drifts: one team adds an exclusion for their own convenience, another team forks the config instead of contributing back, and within a year the fifty repositories you rolled this out to are running fifty slightly different versions of the same scanner. A quarterly review of the shared config, with changes proposed through the same pull request process as everything else, keeps the baseline actually shared instead of shared in name only.

Secret Scanning and Compliance: Why Auditors Ask for This Now

If your organization has been through a SOC 2 audit, a PCI DSS assessment, or a vendor security questionnaire in the last year or two, you’ve probably already seen a question about secret detection in source code. Auditors ask because the failure mode is so well understood: a hardcoded credential in a repository is a single point of failure that bypasses every access control built around the system it unlocks. A database protected by network segmentation, IAM roles, and VPN access is still fully exposed if its password sits in plaintext in a config file three commits back.

The pipeline built in this guide happens to produce exactly the artifacts an audit wants to see: a documented scanning policy (your .gitleaks.toml and CI configuration), evidence that the control runs on every change (the CI job logs and branch protection rules), and a written incident response procedure (the runbook from Step 13). Keep the CI scan results as build artifacts for at least as long as your audit retention window requires, since “we have a scanner” is a weaker answer than “here are twelve months of passing scan logs across every production repository.”

This also changes how you should think about the allowlist discussed in Step 5-6. An auditor who sees a growing, unreviewed allowlist will ask the same question a security engineer would: what’s actually being excluded, and who approved it? Treat the allowlist file as part of your control evidence, not as a junk drawer for silencing alerts you don’t have time to investigate properly.

Frequently Asked Questions

Do I need both TruffleHog and Gitleaks, or is one enough?
Running both covers more ground than either alone. Gitleaks gives you a fast, zero-dependency pre-commit check, while TruffleHog’s provider verification turns a pattern match into a confirmed incident. Many teams run Gitleaks locally and in every CI job, then schedule a deeper TruffleHog full-history, verified scan on a recurring basis.

Will scanning my full git history slow down every pull request?
It can, if you run a full verified TruffleHog scan on every single PR. The pattern used in this guide avoids that: fast pattern-only checks (Gitleaks) run on every commit and PR, while the slower, verification-heavy full-history TruffleHog scan runs on a schedule instead of blocking every merge.

What happens if a scanner flags something that’s actually a false positive?
Add a scoped entry to your allowlist (.gitleaks.toml for Gitleaks, an exclude-paths file for TruffleHog) and require the same PR review process for that change as for any code change. Don’t disable the scanner or widen the exclusion beyond the specific file or pattern causing the false positive.

Is deleting a leaked secret from the latest commit enough to fix the problem?
No. The secret remains in git history and can be recovered by anyone with repository access until you rewrite history with a tool like BFG Repo-Cleaner or git filter-repo and force-push. More importantly, treat the credential itself as compromised and rotate it at the provider regardless of whether you clean the history, since nearly 75% of leaked credentials found by scanners are reported as still valid when discovered.

Can these tools scan private npm, PyPI, or internal package registries, not just git?
TruffleHog supports scanning beyond git repositories, including filesystems, S3 buckets, and other data sources depending on the detector configuration. Gitleaks is primarily focused on git repositories and local file content. For registry-specific or Slack/Jira/Confluence scanning at scale, a managed platform like GitGuardian’s ggshield is generally a better fit than stretching either open-source tool outside its core use case.

Do these scanners work with monorepos that have years of history?
Yes, but expect the first full-history scan to take noticeably longer than scanning a small, recently created repository. Run the first deep scan outside of a blocking CI job, review the baseline results, build your allowlist from that baseline, and only then turn on blocking checks for new commits going forward.

Does a pre-commit hook replace the need for a CI check?
No. A pre-commit hook only protects commits made on a machine where the hook is installed and not bypassed with a flag like --no-verify. CI is the control that applies to everyone, every time, regardless of local setup, which is why the pipeline in this guide treats CI as the required gate and the pre-commit hook as an earlier, optional convenience layer.

How often should the custom detection rules get updated?
Review custom rules whenever your organization adopts a new internal key format, a new third-party provider, or a new credential type, and revisit the full rule set on a quarterly basis at minimum. Treat an outdated rule set the same way you’d treat outdated dependency versions: a known gap that gets more expensive to leave unaddressed over time.

Will an auditor accept TruffleHog and Gitleaks instead of a paid platform?
In most frameworks, auditors care about whether a documented, consistently enforced control exists, not which specific vendor provides it. Open-source scanners with a written policy, CI enforcement, retained scan logs, and a tested incident runbook generally satisfy the same control objective as a commercial platform. The exception is when a framework or customer contract explicitly names a required vendor or centralized monitoring capability that an open-source CLI doesn’t provide on its own.