trufflehog Documentation

Find, verify, and analyze leaked credentials

27,416 stars Go Go 1 file · ~13,657 tokens #credentials#devsecops#dynamic-analysis#precommit#scanning#secret#secret-management#secrets
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy trufflehog on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name trufflehog --restart always trufflesecurity/trufflehog:latest

File: README.md

:mag_right: _Now Scanning_

:globe_with_meridians: TruffleHog Enterprise

Are you interested in continuously monitoring Git, Jira, Slack, Confluence, Microsoft Teams, Sharepoint (and more) for credentials? We have an enterprise product that can help! Learn more at https://trufflesecurity.com/trufflehog-enterprise.

We take the revenue from the enterprise product to fund more awesome open source projects that the whole community can benefit from.

What is TruffleHog 🐽

TruffleHog is the most powerful secrets Discovery, Classification, Validation, and Analysis tool. In this context, secret refers to a credential a machine uses to authenticate itself to another machine. This includes API keys, database passwords, private encryption keys, and more.

Discovery 🔍

TruffleHog can look for secrets in many places including Git, chats, wikis, logs, API testing platforms, object stores, filesystems and more.

Classification 📁

TruffleHog classifies over 800 secret types, mapping them back to the specific identity they belong to. Is it an AWS secret? Stripe secret? Cloudflare secret? Postgres password? SSL Private key? Sometimes it's hard to tell looking at it, so TruffleHog classifies everything it finds.

Validation ✅

For every secret TruffleHog can classify, it can also log in to confirm if that secret is live or not. This step is critical to know if there’s an active present danger or not.

Analysis 🔬

For the 20 some of the most commonly leaked out credential types, instead of sending one request to check if the secret can log in, TruffleHog can send many requests to learn everything there is to know about the secret. Who created it? What resources can it access? What permissions does it have on those resources?

:loudspeaker: Join Our Community

Have questions? Feedback? Jump into Slack or Discord and hang out with us.

Join our Slack Community

Join the Secret Scanning Discord

:tv: Demo

bash
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --org=trufflesecurity

:floppy_disk: Installation

Several options are available for you:

MacOS users

bash
brew install trufflehog

Docker:

Ensure Docker engine is running before executing the following commands:

    Unix

bash
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

    Windows Command Prompt

bash
docker run --rm -it -v "%cd:/=\%:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

    Windows PowerShell

bash
docker run --rm -it -v "${PWD}:/pwd" trufflesecurity/trufflehog github --repo https://github.com/trufflesecurity/test_keys

    M1 and M2 Mac

bash
docker run --platform linux/arm64 --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

Binary releases

bash
Download and unpack from https://github.com/trufflesecurity/trufflehog/releases

Compile from source

bash
git clone https://github.com/trufflesecurity/trufflehog.git
cd trufflehog; go install

Using installation script

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

Using installation script, verify checksum signature (requires cosign to be installed)

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

Using installation script to install a specific version

bash
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin <ReleaseTag like v3.56.0>

:closed_lock_with_key: Verifying the artifacts

Checksums are applied to all artifacts, and the resulting checksum file is signed using cosign.

You need the following tool to verify signature:

Verification steps are as follows:

  1. Download the artifact files you want, and the following files from the releases page.

    • trufflehog_{version}_checksums.txt
    • trufflehog_{version}_checksums.txt.pem
    • trufflehog_{version}_checksums.txt.sig

  2. Verify the signature:

    shell
    cosign verify-blob  \
--certificate  \
--signature  \
--certificate-identity-regexp 'https://github\.com/trufflesecurity/trufflehog/\.github/workflows/.+' \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"

  3. Once the signature is confirmed as valid, you can proceed to validate that the SHA256 sums align with the downloaded artifact:

    shell
    sha256sum --ignore-missing -c trufflehog_{version}_checksums.txt

Replace {version} with the downloaded files version

Alternatively, if you are using the installation script, pass -v option to perform signature verification.
This requires Cosign binary to be installed prior to running the installation script.

:rocket: Quick Start

1: Scan a repo for only verified secrets

Command:

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

Expected output:

text
🐷🔑🐷  TruffleHog. Unearth your secrets. 🐷🔑🐷

Found verified result 🐷🔑
Detector Type: AWS
Decoder Type: PLAIN
Raw result: AKIAYVP4CIPPERUVIFXG
Line: 4
Commit: fbc14303ffbf8fb1c2c1914e8dda7d0121633aca
File: keys
Email: counter <[email protected]>
Timestamp: 2022-06-16 10:17:40 -0700 PDT
...

2: Scan a GitHub Org for only verified secrets

bash
trufflehog github --org=trufflesecurity --results=verified

3: Scan a GitHub Org excluding archived repositories

bash
trufflehog github --org=trufflesecurity --exclude-archived

4: Scan a GitHub Repo for only verified secrets and get JSON output

Command:

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

Expected output:

text
{"SourceMetadata":{"Data":{"Git":{"commit":"fbc14303ffbf8fb1c2c1914e8dda7d0121633aca","file":"keys","email":"counter \[email protected]\u003e","repository":"https://github.com/trufflesecurity/test_keys","timestamp":"2022-06-16 10:17:40 -0700 PDT","line":4}}},"SourceID":0,"SourceType":16,"SourceName":"trufflehog - git","DetectorType":2,"DetectorName":"AWS","DecoderName":"PLAIN","Verified":true,"Raw":"AKIAYVP4CIPPERUVIFXG","Redacted":"AKIAYVP4CIPPERUVIFXG","ExtraData":{"account":"595918472158","arn":"arn:aws:iam::595918472158:user/canarytokens.com@@mirux23ppyky6hx3l6vclmhnj","user_id":"AIDAYVP4CIPPJ5M54LRCY"},"StructuredData":null}
...

TruffleHog can also output SARIF with --sarif instead of --json. GitHub code scanning understands SARIF natively, so uploading it surfaces findings inline on pull request diffs and in the repository's Security tab, and tracks findings as new/fixed across scans instead of reporting the same one every run — see the TruffleHog Github Action section below for how to upload it. Note that, unlike the other output formats, SARIF results are buffered in memory for the full scan and written out at the end, since SARIF requires a single JSON document rather than a stream — fine for typical scans, but scans producing a very large number of results will use proportionally more memory.

5: Scan a GitHub Repo + its Issues and Pull Requests

bash
trufflehog github --repo=https://github.com/trufflesecurity/test_keys --issue-comments --pr-comments

6: Scan an S3 bucket for high-confidence results (verified + unknown)

bash
trufflehog s3 --bucket= --results=verified,unknown

7: Scan S3 buckets using IAM Roles

bash
trufflehog s3 --role-arn=

8: Scan a Github Repo using SSH authentication in Docker

bash
docker run --rm -v "$HOME/.ssh:/root/.ssh:ro" trufflesecurity/trufflehog:latest git ssh://github.com/trufflesecurity/test_keys

9: Scan individual files or directories

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

10: Scan a local git repo

Clone the git repo. For example test keys repo.

bash
git clone [email protected]:trufflesecurity/test_keys.git

Run trufflehog from the parent directory (outside the git repo).

bash
trufflehog git file://test_keys --results=verified,unknown

To guard against malicious git configs in local scanning (see CVE-2025-41390), TruffleHog clones local git repositories to a temporary directory prior to scanning. This follows Git's security best practices. If you want to specify a custom path to clone the repository to (instead of tmp), you can use the --clone-path flag. If you'd like to skip the local cloning process and scan the repository directly (only do this for trusted repos), you can use the --trust-local-git-config flag.

11: Scan GCS buckets for only verified secrets

bash
trufflehog gcs --project-id= --cloud-environment --results=verified

12: Scan a Docker image for only verified secrets

Use the --image flag multiple times to scan multiple images.

bash
# to scan from a remote registry
trufflehog docker --image trufflesecurity/secrets --results=verified

# to scan from the local docker daemon
trufflehog docker --image docker://new_image:tag --results=verified

# to scan from an image saved as a tarball
trufflehog docker --image file://path_to_image.tar --results=verified

13: Scan in CI

Set the --since-commit flag to your default branch that people merge into (ex: "main"). Set the --branch flag to your PR's branch name (ex: "feature-1"). Depending on the CI/CD platform you use, this value can be pulled in dynamically (ex: CIRCLE_BRANCH in Circle CI and TRAVIS_PULL_REQUEST_BRANCH in Travis CI). If the repo is cloned and the target branch is already checked out during the CI/CD workflow, then --branch HEAD should be sufficient. The --fail flag will return an 183 error code if valid credentials are found.

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

14: Scan a Postman workspace

Use the --workspace-id, --collection-id, --environment flags multiple times to scan multiple targets.

bash
trufflehog postman --token= --workspace-id=<workspace id>

15: Scan a Jenkins server

bash
trufflehog jenkins --url https://jenkins.example.com --username admin --password admin

16: Scan an Elasticsearch server

Scan a Local Cluster

There are two ways to authenticate to a local cluster with TruffleHog: (1) username and password, (2) service token.

Connect to a local cluster with username and password

bash
trufflehog elasticsearch --nodes 192.168.14.3 192.168.14.4 --username truffle --password hog

Connect to a local cluster with a service token

bash
trufflehog elasticsearch --nodes 192.168.14.3 192.168.14.4 --service-token ‘AAEWVaWM...Rva2VuaSDZ’

Scan an Elastic Cloud Cluster

To scan a cluster on Elastic Cloud, you’ll need a Cloud ID and API key.

bash
trufflehog elasticsearch \
  --cloud-id 'search-prod:dXMtY2Vx...YjM1ODNlOWFiZGRlNjI0NA==' \
  --api-key 'MlVtVjBZ...ZSYlduYnF1djh3NG5FQQ=='

17. Scan a GitHub Repository for Cross Fork Object References and Deleted Commits

The following command will enumerate deleted and hidden commits on a GitHub repository and then scan them for secrets. This is an alpha release feature.

bash
trufflehog github-experimental --repo https://github.com//<REPO>.git --object-discovery

In addition to the normal TruffleHog output, the --object-discovery flag creates two files in a new $HOME/.trufflehog directory: valid_hidden.txt and invalid.txt. These are used to track state during commit enumeration, as well as to provide users with a complete list of all hidden and deleted commits (valid_hidden.txt). If you'd like to automatically remove these files after scanning, please add the flag --delete-cached-data.

Note: Enumerating all valid commits on a repository using this method takes between 20 minutes and a few hours, depending on the size of your repository. We added a progress bar to keep you updated on how long the enumeration will take. The actual secret scanning runs extremely fast.

For more information on Cross Fork Object References, please read our blog post.

18. Scan Hugging Face

Scan a Hugging Face Model, Dataset, Space or Bucket

bash
trufflehog huggingface \
    --model <model_id> \
    --dataset <dataset_id> \
    --space <space_id> \
    --bucket

Scan all Models, Datasets, Spaces and Buckets belonging to a Hugging Face Organization or User

bash
trufflehog huggingface --org <orgname> --user

(Optionally) When scanning an organization or user, you can skip an entire class of resources with --skip-all-models, --skip-all-datasets, --skip-all-spaces, --skip-all-buckets OR a particular resource with --ignore-models <model_id>, --ignore-datasets <dataset_id>, --ignore-spaces <space_id>, --ignore-buckets .

Scan Discussion and PR Comments

bash
trufflehog huggingface --model <model_id> --include-discussions --include-prs

19. Scan stdin Input

bash
aws s3 cp s3://example/gzipped/data.gz - | gunzip -c | trufflehog stdin

:question: FAQ

  • All I see is 🐷🔑🐷 TruffleHog. Unearth your secrets. 🐷🔑🐷 and the program exits, what gives?
    • That means no secrets were detected
  • Why is the scan taking a long time when I scan a GitHub org
    • Unauthenticated GitHub scans have rate limits. To improve your rate limits, include the --token flag with a personal access token
  • It says a private key was verified, what does that mean?
    • A verified result means TruffleHog confirmed the credential is valid by testing it against the service's API. For private keys, we've confirmed the key can be used live for SSH or SSL authentication. Check out our Driftwood blog post to learn more Blog post
  • Is there an easy way to ignore specific secrets?
    • If the scanned source supports line numbers, then you can add a trufflehog:ignore comment on the line containing the secret to ignore that secrets.

:newspaper: What's new in v3?

TruffleHog v3 is a complete rewrite in Go with many new powerful features.

  • We've added over 700 credential detectors that support active verification against their respective APIs.
  • We've also added native support for scanning GitHub, GitLab, Docker, filesystems, S3, GCS, Circle CI and Travis CI.
  • Instantly verify private keys against millions of github users and billions of TLS certificates using our Driftwood technology.
  • Scan binaries, documents, and other file formats
  • Available as a GitHub Action and a pre-commit hook

What is credential verification?

For every potential credential that is detected, we've painstakingly implemented programmatic verification against the API that we think it belongs to. Verification eliminates false positives and provides three result statuses:

  • verified: Credential confirmed as valid and active by API testing
  • unverified: Credential detected but not confirmed valid (may be invalid, expired, or verification disabled)
  • unknown: Verification attempted but failed due to errors, such as a network or API failure

For example, the AWS credential detector performs a GetCallerIdentity API call against the AWS API to verify if an AWS credential is active.

:memo: Usage

TruffleHog has a sub-command for each source of data that you may want to scan:

  • git
  • github
  • gitlab
  • huggingface
  • docker
  • s3
  • filesystem (files and directories)
  • syslog
  • circleci
  • travisci
  • gcs (Google Cloud Storage)
  • postman
  • jenkins
  • elasticsearch
  • stdin
  • multi-scan

Each subcommand can have options that you can see with the --help flag provided to the sub command:

text
/* Detailed source-code truncated for AI context efficiency. */

For example, to scan a git repository, start with

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

Configuration

TruffleHog supports defining custom regex detectors
and multiple sources in a configuration file provided via the --config flag.
The regex detectors can be used with any subcommand, while the sources defined
in configuration are only for the multi-scan subcommand.

The configuration format for sources can be found on Truffle Security's
source configuration documentation page.

Example GitHub source configuration and options reference:

yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.GitHub
    repositories:
    - https://github.com/trufflesecurity/test_keys.git
    unauthenticated: {}
  name: example config scan
  type: SOURCE_TYPE_GITHUB
  verify: true

You may define multiple connections under the sources key (see above), and
TruffleHog will scan all of the sources concurrently.

S3

The S3 source supports assuming IAM roles for scanning in addition to IAM users. This makes it easier for users to scan multiple AWS accounts without needing to rely on hardcoded credentials for each account.

The IAM identity that TruffleHog uses initially will need to have AssumeRole privileges as a principal in the trust policy of each IAM role to assume.

To scan a specific bucket using locally set credentials or instance metadata if on an EC2 instance:

bash
trufflehog s3 --bucket=

To scan a specific bucket using an assumed role:

bash
trufflehog s3 --bucket= --role-arn=

Multiple roles can be passed as separate arguments. The following command will attempt to scan every bucket each role has permissions to list in the S3 API:

bash
trufflehog s3 --role-arn= --role-arn=

Exit Codes:

  • 0: No errors and no results were found.
  • 1: An error was encountered. Sources may not have completed scans.
  • 183: No errors were encountered, but results were found. Will only be returned if --fail flag is used.

:octocat: TruffleHog Github Action

General Usage

text
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

In the example config above, we're scanning for live secrets in all PRs and Pushes to main. Only code changes in the referenced commits are scanned. If you'd like to scan an entire branch, please see the "Advanced Usage" section below.

Shallow Cloning

If you're incorporating TruffleHog into a standalone workflow and aren't running any other CI/CD tooling alongside TruffleHog, then we recommend using Shallow Cloning to speed up your workflow. Here's an example of how to do it:

text
...
      - shell: bash
        run: |
          if [ "${{ github.event_name }}" == "push" ]; then
            echo "depth=$(($(jq length <<< '${{ toJson(github.event.commits) }}') + 2))" >> $GITHUB_ENV
            echo "branch=${{ github.ref_name }}" >> $GITHUB_ENV
          fi
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "depth=$((${{ github.event.pull_request.commits }}+2))" >> $GITHUB_ENV
            echo "branch=${{ github.event.pull_request.head.ref }}" >> $GITHUB_ENV
          fi
      - uses: actions/checkout@v3
        with:
          ref: ${{env.branch}}
          fetch-depth: ${{env.depth}}
      - uses: trufflesecurity/trufflehog@main
        with:
          extra_args: --results=verified,unknown
...

Depending on the event type (push or PR), we calculate the number of commits present. Then we add 2, so that we can reference a base commit before our code changes. We pass that integer value to the fetch-depth flag in the checkout action in addition to the relevant branch. Now our checkout process should be much shorter.

Canary detection

TruffleHog statically detects https://canarytokens.org/.

Advanced Usage

yaml
- name: TruffleHog
  uses: trufflesecurity/trufflehog@main
  with:
    # Repository path
    path:
    # Start scanning from here (usually main branch).
    base:
    # Scan commits until here (usually dev branch).
    head: # optional
    # Extra args to be passed to the trufflehog cli.
    extra_args: --log-level=2 --results=verified,unknown
    # Scan with a specific TruffleHog version (default: latest).
    version:
    # Docker image to pull. Override to use a registry mirror (default: ghcr.io/trufflesecurity/trufflehog).
    image:

If you'd like to specify specific base and head refs, you can use the base argument (--since-commit flag in TruffleHog CLI) and the head argument (--branch flag in the TruffleHog CLI). We only recommend using these arguments for very specific use cases, where the default behavior does not work.

To upload results to GitHub code scanning instead, run TruffleHog directly with --sarif and pass the output to github/codeql-action/upload-sarif:

yaml
- name: TruffleHog
  run: trufflehog filesystem . --sarif --no-verification > results.sarif
- name: Upload SARIF results
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Advanced Usage: Scan entire branch

text
- name: scan-push
        uses: trufflesecurity/trufflehog@main
        with:
          base: ""
          head: ${{ github.ref_name }}
          extra_args: --results=verified,unknown

TruffleHog GitLab CI

Example Usage

yaml
stages:
  - security

security-secrets:
  stage: security
  allow_failure: false
  image: alpine:latest
  variables:
    SCAN_PATH: "." # Set the relative path in the repo to scan
  before_script:
    - apk add --no-cache git curl jq
    - curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin
  script:
    - trufflehog filesystem "$SCAN_PATH" --results=verified,unknown --fail --json | jq
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

In the example pipeline above, we're scanning for live secrets in all repository directories and files. This job runs only when the pipeline source is a merge request event, meaning it's triggered when a new merge request is created.

Pre-commit Hook

TruffleHog can be used in a pre-commit hook to prevent credentials from leaking before they ever leave your computer.

See the pre-commit hook documentation for more information.

Custom Regex Detector (alpha)

TruffleHog supports detection and verification of custom regular expressions.
For detection, at least one regular expression and keyword is required.
A keyword is a fixed literal string identifier that appears in or around
the regex to be detected. To allow maximum flexibility for verification, a
webhook is used containing the regular expression matches.

TruffleHog will send a JSON POST request containing the regex matches to a
configured webhook endpoint. If the endpoint responds with a 200 OK response
status code, the secret is considered verified. If verification fails due to network/API errors, the result is marked as unknown.

Custom Detectors support a few different filtering mechanisms: entropy, regex targeting the entire match, regex targeting the captured secret,
and excluded word lists checked against the secret (captured group if present, entire match if capture group is not present). Note that if
your custom detector has multiple regex set (in this example hogID, and hogToken), then the filters get applied to each regex. Here is an example of a custom detector using these filters.

The verify section is optional — if you omit it, matches are still reported as unverified, no webhook required. This makes Custom Detectors useful for flagging generic hardcoded secrets (e.g. *.password=, *.secret=) in config files like .properties, .env, or .yaml that TruffleHog's built-in, verified detectors won't otherwise catch. Here is an example tuned for that use case.

NB: This feature is alpha and subject to change.

Regex Detector Example

Here is how to setup a custom regex detector with verification server.

Generic JWT Detection

TruffleHog supports detection and verification of a subset of generic JWTs it finds.
Specifically, if a JWT uses public-key cryptography rather than HMAC and the public key can be obtained, TruffleHog can determine whether the JWT is live or not.

:mag: Analyze

TruffleHog supports running a deeper analysis of a credential to view its permissions and the resources it has access to.

bash
trufflehog analyze

:heart: Contributors

This project exists thanks to all the people who contribute. [Contribute].

:computer: Contributing

Contributions are very welcome! Please see our contribution guidelines first.

We no longer accept contributions to TruffleHog v2, but that code is available in the v2 branch.

Adding new secret detectors

We have published some documentation and tooling to get started on adding new secret detectors. Let's improve detection together!

Use as a library

Currently, trufflehog is in heavy development and no guarantees can be made on
the stability of the public APIs at this time.

License Change

Since v3.0, TruffleHog is released under a AGPL 3 license, included in LICENSE. TruffleHog v3.0 uses none of the previous codebase, but care was taken to preserve backwards compatibility on the command line interface. The work previous to this release is still available licensed under GPL 2.0 in the history of this repository and the previous package releases and tags. A completed CLA is required for us to accept contributions going forward.

File: docs/concurrency.md

Concurrency

text
/* Detailed source-code truncated for AI context efficiency. */

File: docs/process_flow.md

TruffleHog Process Flows

Scans

Data Flow

mermaid
flowchart LR
    SourceDecomposition["`**Source Decomposition**

Breaking up the locations that we are looking _for_ secrets into small chunks`"]

    DetectorMatching{ChunktoDetectorMatching}
    
    SecretDetection["`**Secret Detection**

Finding secrets in these chunks and (optionally) verifying whether they are live`"]

    ResultNotification["`**Result Notification**

Enriching results with metadata and (usually) printing to console`"]
    
    SourceDecomposition -- chunks --> DetectorMatching
    DetectorMatching -- matched chunks --> SecretDetection
    SecretDetection -- results --> ResultNotification

Source Decomposition

mermaid
flowchart TD
    subgraph Source
        direction TB
        SourceDescription("`**(1)** Sources are top level places we find data/files/text to _scan_`")
        GitSource["git Source"]
        GitHubSource["GitHub Source"]
        FilesystemSource["File System Source"]
        PostmanSource["Postman Source"]
    end

    subgraph Unit
        direction TB
        UnitDescription("`**(2)** Units are natural subdivisions of Sources, but still quite large`")
        FilesystemUnit[Directory]
        GitUnit[Git Repository]
    end

    subgraph Chunk
        direction TB
        ChunkDescription("`**(3)** Chunks are the smallest units that we decompose our chunks into, and are subsequent passed on to detection`")
        FilesystemChunk[file contents]
        GitRepositoryChunk["`git log diff hunks`"]
        PostmanChunk[data chunk]
    end


    SourceDescription -- decomposed into --> UnitDescription
    UnitDescription -- further decomposed into --> ChunkDescription


    GitSource -- cloned locallyif not already local --> GitUnit
    GitHubSource -- cloned locally --> GitUnit
    PostmanSource -- Most sources\ndon't use units --> PostmanChunk
    FilesystemSource --> FilesystemUnit

    GitUnit -- git log -p --> GitRepositoryChunk
    FilesystemUnit --> FilesystemChunk

    style SourceDescription fill:#89553e
    style UnitDescription fill:#89553e
    style ChunkDescription fill:#89553e

Chunk to Detector Matching

mermaid
flowchart LR


    KeywordMatching["`**Keyword Matching**
_(Aho-Corasick)_

Match chunks to detectors based on the presence of specific keywords in the chunk`"]
    
    chunks --> KeywordMatching --> detectors

Secret Detection

mermaid
flowchart LR

subgraph Detector
    direction RL
    subgraph DetectorDescription["  "]
        DetectorDescriptionText["`Detectors are the bits that actually check for the existence of a secret in a chunk, and (optionally) verify it`"]
        ExampleDetectors["`Example Detectors:
                    * AWS
                    * Azure
                    * Twilio`"]
    end
    
    subgraph DetectorResponsibility[" "]
        direction LR

        De-Dupe-Detectors["`**De-Dupe-Detectors**

If multiple detectors keyword-match on the same chunk, we have some logic that chooses which detector will verify found secret (so we don't duplicate verification requests to external APIs)`"]

        CollectMatches["`**Collect Matches**

Detector specific regexes are run against the matched chunks, resulting in unverified secrets`"]
        VerifyMatches["`**Verify Matches**

Optionally, observed unverified secrets are verified by attempting to use them against live services`"]
        
        De-Dupe-Detectors -- deduped detectors --> CollectMatches
        CollectMatches -- regex matched chunks --> VerifyMatches
    end
    
    style DetectorDescription fill:#89553e
    style DetectorDescriptionText fill:#89553e
end

Result Notification

mermaid
flowchart LR

    Dispatcher["`**Dispatcher**

Results, verified or otherwise, are sent to a dispatcher to be sent to whichever place we're updating about the 
results -- usually the command line.`"]
    
    results --> Dispatcher --> output

File: examples/README.md

Examples

This folder contains various examples like custom detectors, scripts, etc. Feel free to contribute!

Generic Detector

An often requested feature for TruffleHog is a generic detector. By default, we do not support generic detection as it would result in lots of false positives. However, if you want to attempt detect generic secrets you can use a custom detector.

Try it out:

text
wget https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/examples/generic.yml
trufflehog filesystem --config=$PWD/generic.yml $PWD

# to filter so that _only_ generic credentials are logged:
trufflehog filesystem --config=$PWD/generic.yml --json --no-verification $PWD | awk '/generic-api-key/{print $0}'

File: hack/docs/Adding_Detectors_external.md

Secret Detectors

Secret Detectors have these two major functions:

  1. Given some bytes, extract possible secrets, typically using a regex.
  2. Validate the secrets against the target API, typically using a HTTP client.

The purpose of Secret Detectors is to discover secrets with exceptionally high signal. High rates of false positives are not accepted.

Table of Contents

Getting Started

Sourcing Guidelines

We are interested in detectors for services that meet at least one of these criteria

  • host data (they store any sort of data provided)
  • have paid services (having a free or trial tier is okay though)

If you think that something should be included outside of these guidelines, please let us know.

Development Guidelines

  • When reasonable, favor using the net/http library to make requests instead of bringing in another library.
  • Use the common.SaneHttpClient for the http.Client whenever possible.

Development Dependencies

  • Go 1.17+
  • Make

Adding New Token Formats to an Existing Scanner

In some instances, services will update their token format, requiring a new regex to properly detect secrets in addition to supporting the previous token format. Accommodating this can be done without adding a net-new detector. We provide a Versioner interface that can be implemented.

  1. Create two new directories v1 and v2. Move the existing detector and tests into v1, and add new files to v2.
    Ex: /<old_files> -> /v1/<old_files>, /v2/<new_files>

Note: Be sure to update the tests to reference the new secret values in GSM, or the tests will fail.

  1. Implement the Versioner interface. GitHub example implementation.)

  2. Add a 'version' field in ExtraData for both existing and new detector versions.

  3. Update the existing detector in DefaultDetectors in /pkg/engine/defaults/defaults.go

  4. Proceed from step 3 of Creating a new Secret Scanner

Creating a new Secret Detector

  1. Add a new Secret Detector enum to the DetectorType list here.

  2. Run make protos to update the .pb files.

  3. Generate the Secret Detector

    bash
    go run hack/generate/generate.go detector <DetectorType enum name>
example: go run hack/generate/generate.go detector SampleAPI

  4. Add the Secret Detector to TruffleHog's Default Detectors

    Add the secret scanner to the pkg/engine/defaults/defaults.go file like github.com/trufflesecurity/trufflehog/v3/pkg/detectors/<detector_name> and
    <detector_name>.Scanner{}

  5. Complete the Secret Detector.

    The previous step templated a boilerplate + some example code as a package in the pkg/detectors folder for you to work on.
    The Secret Detector can be completed with these general steps:

    1. Update the pattern regex and keywords. Try iterating with regex101.com.
    2. Update the verifier code to use a non-destructive API call that can determine whether the secret is valid or not.
    3. Populate SecretParts on every Result your detector emits. See Populating SecretParts.
    4. Create a test for the detector.
    5. Add your new detector to DefaultDetectors in /pkg/engine/defaults/defaults.go.
    6. Create a pull request for review.

Testing the Detector

To ensure the quality of your PR, make sure your tests are passing with verified credentials.

  1. Create a file called .env with this env file format:

    bash
    SECRET_TYPE_ONE=value
SECRET_TYPE_ONE_INACTIVE=v@lue

  2. Export the TEST_SECRET_FILE variable, pointing to the env file:

    bash
    export TEST_SECRET_FILE=".env"

    The .env file should be in the new detector's directory like this:

    text
    ├── tailscale
│   ├── .env
│   ├── tailscale.go
│   └── tailscale_test.go

    Now that a .env file is present, the test file can load secrets locally.

  3. Next, update the tests as necessary. A test file has already been generated by the go run hack/generate/generate.go command from earlier. There are 5 cases that have been generated:

    1. Found and verified (using a credential loaded from the .env file)
    2. Found and unverified (determinately, i.e. the secret is invalid)
    3. Found and unverified (indeterminately due to timeout)
    4. Found and unverified (indeterminately due to an unexpected API response)
    5. Not found

    Make any necessary updates to the tests. Note there might not be any changes required as the tests generated by the go run hack/generate/generate.go command are pretty good.
    Here is an exemplary test file for a detector which covers all 5 test cases.

  4. Now run the tests and check to make sure they are passing ✔️!

bash
go test ./pkg/detectors/<detector> -tags=detectors

If the tests are passing, feel free to open a PR!

Populating SecretParts

SecretParts is the structured source of truth for the credential components a detector found. It is a map[string]string on detectors.Result that stores each part of the credential under a descriptive key. Downstream consumers (analyzers, Secret Storage, and — in future work — the Raw/RawV2 mapping layer and dedup hashing) rely on it.

Every Result your detector emits must populate SecretParts. Populate it whether or not the secret is verified.

Single-part credentials

Most detectors find a single opaque token. Use one entry keyed by "key" — this is the established convention in the codebase:

go
s1 := detectors.Result{
    DetectorType: detector_typepb.DetectorType_Example,
    Raw:          []byte(match),
    SecretParts:  map[string]string{"key": match},
}

Multi-part credentials

When the credential has more than one component (e.g. AWS access-key + secret-access-key, OAuth client-id + client-secret, or a token bound to an endpoint/host), use one entry per part with descriptive keys:

go
s1 := detectors.Result{
    DetectorType: detector_typepb.DetectorType_Example,
    Raw:          []byte(accessKeyID),
    RawV2:        []byte(accessKeyID + secretAccessKey),
    SecretParts: map[string]string{
        "access_key_id":     accessKeyID,
        "secret_access_key": secretAccessKey,
    },
}

Key-naming guidance

  • Single-part: use "key". This matches the bulk of existing detectors in pkg/detectors/.
  • Multi-part: pick descriptive, lowercase, snake_case keys that name each part (e.g. client_id, client_secret, access_key_id, secret_access_key, username, password, domain, host, endpoint). If the detector also has a corresponding analyzer in pkg/analyzer/analyzers/, the keys must match what the analyzer expects, since analyzers read directly from this map.
  • Only secret parts that uniquely identify the credential belong in SecretParts. Unrelated metadata belongs in ExtraData.
  • This field is the source of truth for uniquely identifying a credential.

Addendum

Verification indeterminacy

There are two types of reasons that secret verification can fail:

  • The candidate secret is not actually a valid secret.
  • Something went wrong in the process unrelated to the candidate secret, such as a transient network error or an unexpected API response.

In TruffleHog parlance, the first type of verification response is called determinate and the second type is called indeterminate. Verification code should distinguish between the two by returning an error object in the result struct only for indeterminate failures. In general, a verifier should return an error (indicating an indeterminate failure) in all cases that haven't been explicitly identified as determinate failure states.

For example, consider a hypothetical authentication endpoint that returns 200 OK for valid credentials and 403 Forbidden for invalid credentials. The verifier for this endpoint could make an HTTP request and use the response status code to decide what to return:

  • A 200 response would indicate that verification succeeded. (Or maybe any 2xx response.)
  • A 403 response would indicate that verification failed determinately and no error object should be returned.
  • Any other response would indicate that verification failed indeterminately and an error object should be returned.

Adding Protos in Windows

  1. Install Ubuntu App in Microsoft Store https://www.microsoft.com/en-us/p/ubuntu/9nblggh4msv6.
  2. Install Docker Desktop https://www.docker.com/products/docker-desktop. Enable WSL integration to Ubuntu. In Docker app, go to Settings->Resources->WSL INTEGRATION->enable Ubuntu.
  3. Open Ubuntu cli and install dos2unix.
    bash
    sudo apt install dos2unix
  4. Identify the trufflehog local directory and convert scripts/gen_proto.sh file in Unix format.
    bash
    dos2unix ./scripts/gen_proto.sh
  5. Open /proto/detector_type.proto file and add new detectors then save it. Make sure Docker is running and run this in Ubuntu command line.
    bash
    make protos

File: hack/docs/Adding_Detectors_Internal.md

Secret Detectors

Secret Detectors have these two major functions:

  1. Given some bytes, extract possible secrets, typically using a regex.
  2. Validate the secrets against the target API, typically using a HTTP client.

The purpose of Secret Detectors is to discover secrets with exceptionally high signal. High rates of false positives are not accepted.

Table of Contents

Getting Started

Sourcing Guidelines

We are interested in detectors for services that meet at least one of these criteria

  • host data (they store any sort of data provided)
  • have paid services (having a free or trial tier is okay though)

If you think that something should be included outside of these guidelines, please let us know.

Development Guidelines

  • When reasonable, favor using the net/http library to make requests instead of bringing in another library.
  • Use the common.SaneHttpClient for the http.Client whenever possible.
  • We recommend an editor with gopls integration (such as Vscode with Go plugin) for benefits like easily running tests, autocompletion, linting, type checking, etc.

Development Dependencies

Adding New Token Formats to an Existing Scanner

In some instances, services will update their token format, requiring a new regex to properly detect secrets in addition to supporting the previous token format. Accommodating this can be done without adding a net-new detector. We provide a Versioner interface that can be implemented.

  1. Create two new directories v1 and v2. Move the existing detector and tests into v1, and add new files to v2.
    Ex: /<old_files> -> /v1/<old_files>, /v2/<new_files>

Note: Be sure to update the tests to reference the new secret values in GSM, or the tests will fail.

  1. Implement the Versioner interface. GitHub example implementation.

  2. Add a 'version' field in ExtraData for both existing and new detector versions.

  3. Update the existing detector in DefaultDetectors in /pkg/engine/defaults/defaults.go

  4. Proceed from step 3 of Creating a new Secret Scanner

Creating a new Secret Scanner

  1. Identify the Secret Detector name from the /proto/detector_type.proto DetectorType enum.

  2. Generate the Secret Detector

    bash
    go run hack/generate/generate.go detector <DetectorType enum name>

  3. Complete the secret detector.

    The previous step templated a boilerplate + some example code as a package in the pkg/detectors folder for you to work on.
    The secret detector can be completed with these general steps:

    1. Add the test secret to GCP Secrets. See managing test secrets
    2. Update the pattern regex and keywords. Try iterating with regex101.com.
    3. Update the verifier code to use a non-destructive API call that can determine whether the secret is valid or not.
    4. Populate SecretParts on every Result your detector emits. See Populating SecretParts.
    5. Update the tests with these test cases at minimum:
      1. Found and verified (using a credential loaded from GCP Secrets)
      2. Found and unverified (determinately, i.e. the secret is invalid)
      3. Found and unverified (indeterminately due to timeout)
      4. Found and unverified (indeterminately due to an unexpected API response)
      5. Not found
      6. Any false positive cases that you come across
    6. Add your new detector to DefaultDetectors in /pkg/engine/defaults/defaults.go
    7. Create a merge request for review. CI tests must be passing.

Populating SecretParts

SecretParts is the structured source of truth for the credential components a detector found. It is a map[string]string on detectors.Result that stores each part of the credential under a descriptive key. Downstream consumers (analyzers and enterprise TruffleHog) rely on it.

Every Result your detector emits must populate SecretParts. Populate it whether or not the secret is verified.

Single-part credentials

Most detectors find a single opaque token. Use one entry keyed by "key" — this is the established convention in the codebase:

go
s1 := detectors.Result{
    DetectorType: detector_typepb.DetectorType_Example,
    Raw:          []byte(match),
    SecretParts:  map[string]string{"key": match},
}

Multi-part credentials

When the credential has more than one component (e.g. AWS access-key + secret-access-key, OAuth client-id + client-secret, or a token bound to an endpoint/host), use one entry per part with descriptive keys:

go
s1 := detectors.Result{
    DetectorType: detector_typepb.DetectorType_Example,
    Raw:          []byte(accessKeyID),
    RawV2:        []byte(accessKeyID + secretAccessKey),
    SecretParts: map[string]string{
        "access_key_id":     accessKeyID,
        "secret_access_key": secretAccessKey,
    },
}

Key-naming guidance

  • Single-part: use "key". This matches the bulk of existing detectors in pkg/detectors/.
  • Multi-part: pick descriptive, lowercase, snake_case keys that name each part (e.g. client_id, client_secret, access_key_id, secret_access_key, username, password, domain, host, endpoint). If the detector also has a corresponding analyzer in pkg/analyzer/analyzers/, the keys must match what the analyzer expects, since analyzers read directly from this map.
  • Only secret parts that uniquely identify the credential belong in SecretParts. Unrelated metadata belongs in ExtraData.
  • This field is the source of truth for uniquely identifying a credential.

Addendum

Verification indeterminacy

There are two types of reasons that secret verification can fail:

  • The candidate secret is not actually a valid secret.
  • Something went wrong in the process unrelated to the candidate secret, such as a transient network error or an unexpected API response.

In TruffleHog parlance, the first type of verification response is called determinate and the second type is called indeterminate. Verification code should distinguish between the two by returning an error object in the result struct only for indeterminate failures. In general, a verifier should return an error (indicating an indeterminate failure) in all cases that haven't been explicitly identified as determinate failure states.

For example, consider a hypothetical authentication endpoint that returns 200 OK for valid credentials and 403 Forbidden for invalid credentials. The verifier for this endpoint could make an HTTP request and use the response status code to decide what to return:

  • A 200 response would indicate that verification succeeded. (Or maybe any 2xx response.)
  • A 403 response would indicate that verification failed determinately and no error object should be returned.
  • Any other response would indicate that verification failed indeterminately and an error object should be returned.

Managing Test Secrets

Do not embed test credentials in the test code. Instead, use GCP Secrets Manager.

  1. Access the latest secret version for modification.

    Note: /tmp/s is a valid path on Linux. You will need to change that for Windows or OSX, otherwise you will see an error. On Windows you will also need to install WSL.

    bash
    gcloud secrets versions access --project trufflehog-testing --secret detectors5 latest > /tmp/s

  2. Add the secret that you need for testing.

    The command above saved it to /tmp/s.

    The format is standard env file format,

    bash
    SECRET_TYPE_ONE=value
SECRET_TYPE_ONE_INACTIVE=v@lue

  3. Update the secret version with your modification.

    bash
    gcloud secrets versions add --project trufflehog-testing detectors5 --data-file /tmp/s

    Note: We increment the detectors file name detectors(n+1) once the previous one exceeds the max size allowed by GSM (65kb).

  4. Access the secret value as shown in the example code.

Setting up Google Cloud SDK

  1. Install the Google Cloud SDK: https://cloud.google.com/sdk/docs/install
  2. Authenticate with gcloud auth login --update-adc using your Google account

Adding Protos in Windows

  1. Install Ubuntu App in Microsoft Store https://www.microsoft.com/en-us/p/ubuntu/9nblggh4msv6.
  2. Install Docker Desktop https://www.docker.com/products/docker-desktop. Enable WSL integration to Ubuntu. In Docker app, go to Settings->Resources->WSL INTEGRATION->enable Ubuntu.
  3. Open Ubuntu cli and install dos2unix.
    bash
    sudo apt install dos2unix
  4. Identify the trufflehog local directory and convert scripts/gen_proto.sh file in Unix format.
    bash
    dos2unix ./scripts/gen_proto.sh
  5. Open /proto/detector_type.proto file and add new detectors then save it. Make sure Docker is running and run this in Ubuntu command line.
    bash
    make protos

Testing a detector

bash
go test ./pkg/detectors/<detector> -tags=detectors

File: hack/snifftest/README.md

snifftest

See the help pages with this command, or look further below to get started quickly.

text
go run hack/snifftest/main.go

Show available secret scanners

text
go run hack/snifftest/main.go show-scanners

Scan

All scanners

text
go run snifftest/main.go scan --db ~/sdb --scanner all --print

Particular scanner

text
go run snifftest/main.go scan --db ~/sdb --scanner github --print --print-chunk --fail-threshold 5

File: pkg/analyzer/README.md

Implementing Analyzers

Defining the Permissions

Permissions can be defined in:

  • lower snake case as permission_name:access_level
  • kebab case as permission-name:read
  • dot notation as permission.name:read

The Permissions are initially defined as a yaml file.

At the top of the analyzer implementation you specify the go generate command.

You can install the generator with go install github.com/trufflesecurity/trufflehog/v3/pkg/analyzer/generate_permissions.

Then you can run go generate ./... to generate the Permission types for the analyzer.

The generated Permission types are to be used in the AnalyzerResult struct when defining the Permissions and in your code.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#credentials Browse credentials catalog → #devsecops Browse devsecops catalog → #dynamic-analysis Browse dynamic-analysis catalog → #precommit Browse precommit catalog → #scanning Browse scanning catalog → #secret Browse secret catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →