trufflehog

Scan a Git repository for verified secrets

$ trufflehog git [https://github.com/trufflesecurity/test_keys] --only-verified

$ trufflehog github --org [trufflesecurity] --only-verified

$ trufflehog git [https://github.com/trufflesecurity/test_keys] --only-verified --json

$ trufflehog github --repo [https://github.com/trufflesecurity/test_keys] --issue-comments --pr-comments

$ trufflehog s3 --bucket [bucket name] --only-verified

$ trufflehog s3 --role-arn [iam-role-arn]

$ trufflehog filesystem [path/to/file_or_directory1 path/to/file_or_directory2 ...]

$ trufflehog docker --image [trufflesecurity/secrets] --only-verified

trufflehog <command> [options] <arguments>
The primary command is scan, used as:
trufflehog scan <target_type> [scan_options] <target_identifier>
Examples:
trufflehog scan git --repo https://github.com/owner/repo.git --full-history --json
trufflehog scan filesystem --path /var/www/my-app --max-depth 3

--json
    Outputs findings in a structured JSON format, useful for programmatic processing and integration with other tools.

--no-verify
    Disables SSL certificate verification for network requests, useful in certain environments but potentially insecure.

--entropy
    Enables or disables the high-entropy secret detection engine. By default, both entropy and regex are enabled.

--regex
    Enables or disables the regular expression-based secret detection engine. By default, both entropy and regex are enabled.

--allow-list
    Specifies a path to a YAML or JSON file containing a list of secrets or patterns to ignore, reducing false positives.

--output
    Redirects scan results to the specified file instead of standard output (stdout).

--config
    Loads scan configurations from a specified YAML or JSON file, allowing for predefined scan settings.

--full-history
    For Git repository scans, processes the entire commit history, not just recent commits, ensuring comprehensive coverage.

--repo
    (Used with scan git) Specifies the URL of the Git repository to scan.

--path
    (Used with scan filesystem) Specifies the local filesystem path to scan.

--log-level
    Sets the logging verbosity level (e.g., debug, info, warn, error) for more detailed output.

Trufflehog is an open-source secret scanning tool designed to find sensitive information such as API keys, passwords, and credentials across various data sources. It employs two primary detection methods:
1. Entropy Checks: It identifies strings with high entropy, which are often indicative of randomly generated secrets.
2. Regular Expressions (Regex): It uses a comprehensive set of predefined regex patterns to match known secret formats (e.g., AWS access keys, private RSA keys, database connection strings).

Trufflehog can scan a wide range of targets, including Git repositories (local or remote, full history or specific commits), local file systems, Amazon S3 buckets, Docker images, and popular Git hosting platforms like GitHub, GitLab, and Bitbucket. Its versatile nature makes it an invaluable tool for security engineers, DevOps teams, and developers to proactively identify and mitigate secret exposures in codebases and infrastructure, helping to prevent data breaches and maintain a strong security posture. It is frequently integrated into CI/CD pipelines to ensure secrets are not accidentally committed.

Trufflehog can produce false positives, especially when using entropy detection on highly random but non-secret data. Running on very large Git repositories with extensive history can be resource-intensive and time-consuming. When scanning private repositories or cloud services, appropriate authentication tokens or credentials must be provided, which introduces its own security considerations. The effectiveness of regex-based detection depends on the comprehensiveness of its rule set, which may need customization for proprietary secret formats. It's crucial to review results manually or integrate with other security tools for verification.

Trufflehog organizes its functionality into subcommands. The most common is scan, used for initiating scans against various targets (e.g., trufflehog scan git, trufflehog scan filesystem, trufflehog scan s3, trufflehog scan docker). Other subcommands like verify (for validating findings against external services) or configure (for managing configurations) also exist, providing modularity to its operations.

Trufflehog was originally created by Dylan Ayrey in 2015 as a Python-based tool focused on scanning Git repositories. Over the years, it evolved significantly. In 2021, the project was rewritten in Go by Truffle Security to improve performance, broaden its scanning capabilities to include various data sources beyond Git, and enhance its integration into modern DevSecOps workflows. This rewrite marked a major milestone, making Trufflehog a more robust and versatile secret scanning solution widely adopted in the cybersecurity community.

git-secrets(1), gitleaks(1), grep(1), find(1)