Skip to main content

Want to Practice These Techniques?

Try Hackviser's interactive cyber security upskilling platform - Learn by doing!

Start Practicing Now

TruffleHog

What is the purpose of TruffleHog?​

TruffleHog is an open-source secret discovery, classification, validation, and analysis tool. It finds leaked credentials in Git repositories, GitHub and GitLab, filesystems, Docker images, S3, GCS, CI platforms, Postman, Jenkins, Elasticsearch, Hugging Face, and standard input.

TruffleHog is especially useful because it can verify many detected credentials against the relevant service API. This helps separate active credentials from unverified matches and makes triage more practical during security reviews, CI checks, and incident response.

Here are the primary uses of TruffleHog:

  • Verified Secret Discovery: TruffleHog detects credentials and, when supported, verifies whether they are still valid and active.

  • Git Repository Scanning: The tool scans remote Git repositories, local repositories, branches, commit ranges, and CI merge ranges for leaked credentials.

  • GitHub and GitLab Scanning: TruffleHog can scan repositories, organizations, issues, pull request comments, and GitLab projects when the required access is available.

  • Cloud Storage Scanning: The tool can scan S3 and GCS buckets for exposed credentials and supports AWS role-based workflows.

  • Container Secret Scanning: TruffleHog scans Docker images from registries, local Docker daemon images, and saved image tarballs.

  • Filesystem and Artifact Scanning: It can scan individual files, directories, binaries, documents, archives, and streamed data from standard input.

  • CI/CD Secret Blocking: TruffleHog can run in GitHub Actions, GitLab CI, CircleCI, and other pipelines, returning a failing exit code when selected findings are discovered.

  • Credential Analysis: For supported credential types, TruffleHog can analyze API keys for permission and resource information.

Core Features​

  • Secret Discovery
  • Secret Classification
  • Credential Verification
  • Verified, Unknown, and Unverified Result Types
  • Git Repository Scanning
  • Local Git Repository Scanning
  • GitHub Repository and Organization Scanning
  • GitHub Issue and Pull Request Comment Scanning
  • GitLab Scanning
  • Filesystem Scanning
  • Docker Image Scanning
  • S3 Bucket Scanning
  • GCS Bucket Scanning
  • CI Platform Scanning
  • Postman Workspace Scanning
  • Jenkins Scanning
  • Elasticsearch Scanning
  • Hugging Face Scanning
  • Standard Input Scanning
  • JSON Output
  • GitHub Actions Output
  • Pre-v3 JSON Output
  • Custom Detector Configuration
  • Include and Exclude Detector Controls
  • Custom Verification Endpoints
  • Archive Scanning
  • Binary and Document Scanning
  • Concurrency Controls
  • Failure Exit Code for CI
  • Pre-Commit Hook Support
  • GitHub Action Support
  • Docker Image Distribution

Data sources​

  • Remote Git Repositories
  • Local Git Repositories
  • Git Commit History
  • Git Branches
  • GitHub Repositories
  • GitHub Organizations
  • GitHub Issues
  • GitHub Pull Request Comments
  • GitLab Repositories
  • Files and Directories
  • Docker Images
  • Docker Image Tarballs
  • S3 Buckets
  • GCS Buckets
  • CircleCI
  • Travis CI
  • Postman Workspaces
  • Jenkins Servers
  • Elasticsearch Clusters
  • Hugging Face Models
  • Hugging Face Datasets
  • Hugging Face Spaces
  • Syslog Streams
  • Standard Input
  • Archives
  • Binaries
  • Documents
  • Custom Source Configuration Files
  • Custom Regex Detectors

Common TruffleHog Commands​

1. Install TruffleHog with Homebrew​

  • This command installs TruffleHog on macOS using Homebrew.
brew install trufflehog

2. Pull the Docker Image​

  • This command downloads the official TruffleHog Docker image.
docker pull trufflesecurity/trufflehog:latest

3. Install with the Official Script​

  • This command installs the TruffleHog binary using the official installation script.
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

4. Install a Specific Version​

  • This command installs a selected TruffleHog release tag with the official installation script.
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin <release_tag>

5. Show Help​

  • This command displays global help and available subcommands.
trufflehog --help

6. Show Version​

  • This command prints the installed TruffleHog version.
trufflehog --version

7. Show Git Source Help​

  • This command displays help for scanning Git repositories.
trufflehog git --help

8. Scan a Remote Git Repository​

  • This command scans a remote Git repository and reports verified secrets only.
trufflehog git https://github.com/example/repo.git --results=verified

9. Scan a Remote Git Repository with JSON Output​

  • This command scans a Git repository and writes JSON lines to standard output.
trufflehog git https://github.com/example/repo.git --results=verified --json

10. Scan a Local Git Repository​

  • This command scans a local Git repository by using a file:// URI.
trufflehog git file://. --results=verified,unknown

11. Scan a Local Git Repository with a Clone Path​

  • This command uses a selected clone path for TruffleHog's local repository scanning workflow.
trufflehog git file://repo --clone-path /tmp/trufflehog-clones --results=verified,unknown

12. Scan a Trusted Local Git Repository Directly​

  • This command skips the safer local clone process and scans a trusted local repository directly.
trufflehog git file://repo --trust-local-git-config --results=verified,unknown

13. Scan a Git Repository over SSH with Docker​

  • This command mounts local SSH keys read-only and scans an SSH Git URL from Docker.
docker run --rm -v "$HOME/.ssh:/root/.ssh:ro" trufflesecurity/trufflehog:latest git ssh://github.com/example/repo.git --results=verified

14. Scan a GitHub Repository​

  • This command scans a GitHub repository through the GitHub source.
trufflehog github --repo=https://github.com/example/repo --results=verified

15. Scan a GitHub Organization​

  • This command scans repositories in a GitHub organization.
trufflehog github --org=example-org --results=verified

16. Scan GitHub with an Access Token​

  • This command uses a GitHub token to improve access and rate limits for GitHub scanning.
trufflehog github --org=example-org --token <github_token> --results=verified

17. Scan GitHub Issues and Pull Request Comments​

  • This command includes GitHub issue comments and pull request comments in the scan.
trufflehog github --repo=https://github.com/example/repo --issue-comments --pr-comments --results=verified,unknown

18. Scan GitHub Hidden and Deleted Commits​

  • This command uses the experimental GitHub object discovery workflow for hidden and deleted commits.
trufflehog github-experimental --repo https://github.com/example/repo.git --object-discovery

19. Delete Cached Object Discovery Data​

  • This command removes cached object discovery data after the experimental scan completes.
trufflehog github-experimental --repo https://github.com/example/repo.git --object-discovery --delete-cached-data

20. Scan Individual Files and Directories​

  • This command scans selected files and directories without requiring Git history.
trufflehog filesystem path/to/file.txt path/to/dir

21. Scan Standard Input​

  • This command streams data into TruffleHog from standard input.
cat config.txt | trufflehog stdin

22. Scan Compressed Data from Standard Input​

  • This command streams decompressed cloud data into TruffleHog.
aws s3 cp s3://example-bucket/data.gz - | gunzip -c | trufflehog stdin

23. Scan an S3 Bucket​

  • This command scans a selected S3 bucket for high-confidence results.
trufflehog s3 --bucket <bucket_name> --results=verified,unknown

24. Scan S3 with an IAM Role​

  • This command assumes an IAM role for S3 scanning.
trufflehog s3 --bucket <bucket_name> --role-arn <iam_role_arn> --results=verified

25. Scan All Accessible Buckets for Multiple Roles​

  • This command attempts to scan buckets accessible to each supplied role.
trufflehog s3 --role-arn <iam_role_arn_1> --role-arn <iam_role_arn_2> --results=verified

26. Scan GCS Buckets​

  • This command scans Google Cloud Storage buckets for verified secrets.
trufflehog gcs --project-id <project_id> --cloud-environment --results=verified

27. Scan a Remote Docker Image​

  • This command scans a Docker image from a remote registry.
trufflehog docker --image trufflesecurity/secrets --results=verified

28. Scan a Local Docker Daemon Image​

  • This command scans an image available through the local Docker daemon.
trufflehog docker --image docker://new_image:tag --results=verified

29. Scan a Docker Image Tarball​

  • This command scans a Docker image saved as a tarball.
trufflehog docker --image file://path_to_image.tar --results=verified

30. Scan Multiple Docker Images​

  • This command scans multiple Docker images in one run.
trufflehog docker --image image-one:latest --image image-two:latest --results=verified

31. Run a CI Merge Range Scan​

  • This command scans changes between a default branch and a feature branch and fails when selected results are found.
trufflehog git file://. --since-commit main --branch feature-1 --results=verified,unknown --fail

32. Run a CI Scan Against HEAD​

  • This command scans from the default branch to the already checked-out branch.
trufflehog git file://. --since-commit main --branch HEAD --results=verified,unknown --fail

33. Disable Update Checks​

  • This command disables update checks, which is useful in deterministic CI jobs.
trufflehog git file://. --results=verified,unknown --no-update

34. Output in GitHub Actions Format​

  • This command formats findings for GitHub Actions annotations.
trufflehog git file://. --results=verified,unknown --github-actions

35. Scan Without Verification​

  • This command disables credential verification and reports detection results only.
trufflehog filesystem path/to/dir --no-verification --results=verified,unknown,unverified

36. Include Selected Detectors​

  • This command runs only selected detector types.
trufflehog git file://. --include-detectors AWS,GitHub --results=verified,unknown

37. Exclude Selected Detectors​

  • This command excludes selected detector types from the scan.
trufflehog git file://. --exclude-detectors Slack --results=verified,unknown

38. Filter Unverified Results by Entropy​

  • This command filters unverified findings with a Shannon entropy threshold.
trufflehog filesystem path/to/dir --filter-entropy 3.0 --results=unverified

39. Set Concurrency​

  • This command adjusts the number of concurrent workers.
trufflehog git file://. --concurrency 8 --results=verified,unknown

40. Limit Archive Scanning​

  • This command sets archive scan depth and maximum archive size.
trufflehog filesystem path/to/dir --archive-max-depth 2 --archive-max-size 10MB --results=verified,unknown

41. Skip Binaries​

  • This command skips binary files during scanning.
trufflehog filesystem path/to/dir --force-skip-binaries --results=verified,unknown

42. Skip Archives​

  • This command skips archive extraction during scanning.
trufflehog filesystem path/to/dir --force-skip-archives --results=verified,unknown

43. Use a Configuration File​

  • This command loads custom detectors or source definitions from a configuration file.
trufflehog filesystem path/to/dir --config trufflehog.yaml --results=verified,unknown

44. Run a Multi-Source Scan​

  • This command scans multiple sources defined in a configuration file.
trufflehog multi-scan --config trufflehog.yaml --results=verified,unknown

45. Use Custom Verification Endpoints​

  • This command uses a selected verifier endpoint for credential verification workflows.
trufflehog git file://. --verifier https://verifier.example.com --results=verified,unknown

46. Use Only Custom Verifiers​

  • This command disables built-in verifiers and uses only custom verification endpoints.
trufflehog git file://. --verifier https://verifier.example.com --custom-verifiers-only --results=verified,unknown

47. Scan a Postman Workspace​

  • This command scans a Postman workspace with a Postman API token.
trufflehog postman --token <postman_api_token> --workspace-id <workspace_id> --results=verified

48. Scan a Jenkins Server​

  • This command scans a Jenkins server when valid Jenkins credentials are available.
trufflehog jenkins --url https://jenkins.example.com --username <username> --password <password> --results=verified

49. Scan an Elasticsearch Cluster​

  • This command scans an Elasticsearch cluster using username and password authentication.
trufflehog elasticsearch --nodes 192.0.2.10 192.0.2.11 --username <username> --password <password> --results=verified

50. Scan Hugging Face Resources​

  • This command scans Hugging Face models, datasets, or spaces.
trufflehog huggingface --model <model_id> --dataset <dataset_id> --space <space_id> --results=verified

51. Analyze a Credential​

  • This command starts TruffleHog's credential analysis workflow for supported key types.
trufflehog analyze

Output Examples of TruffleHog Commands​

CommandExample UsageFunctionOutput Example
Show Helptrufflehog --helpDisplays global help.Commands: git, github, gitlab, docker, s3, filesystem, stdin
Show Versiontrufflehog --versionPrints the installed version.trufflehog version 3.x.x
Git Helptrufflehog git --helpShows Git source options.Find credentials in git repositories
Remote Git Scantrufflehog git https://github.com/example/repo.git --results=verifiedScans a remote Git repository.Found verified result
JSON Git Scantrufflehog git https://github.com/example/repo.git --results=verified --jsonOutputs JSON findings.{"DetectorName":"AWS","Verified":true}
Local Git Scantrufflehog git file://. --results=verified,unknownScans a local Git repository.scanning repo
Clone Pathtrufflehog git file://repo --clone-path /tmp/trufflehog-clonesUses a selected local clone path.temporary clone path configured
Trusted Local Scantrufflehog git file://repo --trust-local-git-configScans trusted local Git config directly.trust local git config enabled
GitHub Repotrufflehog github --repo=https://github.com/example/repo --results=verifiedScans a GitHub repository.Repository: https://github.com/example/repo
GitHub Orgtrufflehog github --org=example-org --results=verifiedScans repositories in an organization.Scanning GitHub organization example-org
GitHub Tokentrufflehog github --org=example-org --token <github_token>Authenticates GitHub scans.Using authenticated GitHub client
GitHub Commentstrufflehog github --repo=https://github.com/example/repo --issue-comments --pr-commentsIncludes issue and PR comments.Scanning issue comments
Object Discoverytrufflehog github-experimental --repo https://github.com/example/repo.git --object-discoveryScans hidden and deleted commits.valid_hidden.txt created
Filesystemtrufflehog filesystem path/to/file.txt path/to/dirScans files and directories.File: path/to/file.txt
STDINcat config.txt | trufflehog stdinScans streamed input.Found unverified result
S3 Buckettrufflehog s3 --bucket example-bucket --results=verified,unknownScans one S3 bucket.SourceName: trufflehog - s3
S3 Roletrufflehog s3 --bucket example-bucket --role-arn <iam_role_arn>Scans using an assumed role.Assuming role
GCStrufflehog gcs --project-id example-project --cloud-environment --results=verifiedScans GCS buckets.SourceName: trufflehog - gcs
Docker Remotetrufflehog docker --image trufflesecurity/secrets --results=verifiedScans a remote image.Scanning Docker image
Docker Localtrufflehog docker --image docker://new_image:tag --results=verifiedScans local Docker daemon image.SourceName: trufflehog - docker
Docker Tarballtrufflehog docker --image file://path_to_image.tar --results=verifiedScans saved Docker image tar.Archive extracted
CI Rangetrufflehog git file://. --since-commit main --branch feature-1 --results=verified,unknown --failScans a merge range and fails on findings.exit code 183
GitHub Actions Outputtrufflehog git file://. --github-actionsEmits GitHub Actions annotations.::warning file=...
No Verificationtrufflehog filesystem path/to/dir --no-verificationDisables live validation.Verified: false
Include Detectorstrufflehog git file://. --include-detectors AWS,GitHubRuns selected detectors.Included detectors: AWS, GitHub
Exclude Detectorstrufflehog git file://. --exclude-detectors SlackSkips selected detectors.Excluded detector: Slack
Entropy Filtertrufflehog filesystem path/to/dir --filter-entropy 3.0Filters unverified results by entropy.Filtered unverified results
Concurrencytrufflehog git file://. --concurrency 8Sets concurrent workers.concurrency=8
Archive Limitstrufflehog filesystem path/to/dir --archive-max-depth 2 --archive-max-size 10MBControls archive scanning.Archive depth: 2
Skip Binariestrufflehog filesystem path/to/dir --force-skip-binariesSkips binary files.Skipping binary file
Skip Archivestrufflehog filesystem path/to/dir --force-skip-archivesSkips archive extraction.Skipping archive
Config Filetrufflehog filesystem path/to/dir --config trufflehog.yamlLoads custom configuration.Loaded config trufflehog.yaml
Multi-Scantrufflehog multi-scan --config trufflehog.yamlScans configured sources.Scanning multiple sources
Custom Verifiertrufflehog git file://. --verifier https://verifier.example.comUses a verifier endpoint.Custom verifier configured
Postmantrufflehog postman --token <postman_api_token> --workspace-id <workspace_id>Scans a Postman workspace.Scanning Postman workspace
Jenkinstrufflehog jenkins --url https://jenkins.example.com --username <username> --password <password>Scans Jenkins.Scanning Jenkins server
Elasticsearchtrufflehog elasticsearch --nodes 192.0.2.10 --username <username> --password <password>Scans Elasticsearch.Scanning Elasticsearch nodes
Hugging Facetrufflehog huggingface --model <model_id> --results=verifiedScans Hugging Face resources.Scanning Hugging Face model
Analyzetrufflehog analyzeStarts credential analysis.Analyze API keys for permissions information