TruffleHog - A Deep Dive on Secret Management and How to Fix Exposed Secrets

We’ve historically posted about a nifty new open source tool in the Jit stack, TruffleHog, because it does stand apart when it comes to secret detection. It provides out of the box support that is extremely vast and tracks hundreds of patterns and strings for a wide range of tooling. 

This includes everything from clouds like AWS, GCP and Azure, through integrated tool chains like Slack, Stripe, GitHub and more in TruffleHog Enterprise. 

Developers love this tool. This love is well-deserved, as they have invested a lot of effort in understanding the developer psyche, workflows and patterns, and have optimized capabilities to provide as much value as possible in development. 

This post will provide an overview of Trufflehog and highlight some of the best features and core components. Then, we'll review a short guide on how to fix an exposed secret being deployed to your code or public repository.

What is Trufflehog?

Trufflehog is an application security tool that focuses on detected hardcoded secrets.

By continuously maintaining a dictionary of regular expressions of  specific patterns and strings in common source code, it lets developers know if there is a secret exposed before pushing code to production. Additionally, it can flag hard coded secrets that already made their way to production.

This means that if TruffleHog will see a 16-character string in your code that starts with AKIA or ASIA, it will use one of its 800+ detectors to determine that you have an AWS secret exposed. 

But the cool part is that it doesn’t stop there.  This tool will then go on to verify whether this is an actual secret by making an API call to verify the secret’s authenticity.

With developers today using thousands of secrets in their stacks and code regularly, it’s essential to be able to verify which are the real secrets to prioritize, and which are just dummy or testing secrets that can be ignored. 

The open source community

TruffleHog has gained such widespread popularity that organizations using its detectors will contribute code, and update their detectors if they change or are updated from version to version. 

Check out this joint blog by Truffle Security and Tailscale on how outside organizations contribute back to the project. This organization hosts events like their Hacktoberfest Detector Competition which encourages community members to contribute to the project.

In this way, the community itself helps keep the open source project up to date with the latest developments across applications.

Five Essential Trufflehog Features

Below is just a roundup of some of the tool's open-source capabilities that improve developer efficiency and productivity.  

1. Automation

Developers love tools they can automate – as automation ensures things get done.  TruffleHog has both pre-commit hooks, and a GitHub Action, making it really simple to automate secret management and security in your stack.  

2. Remote Scanning

With a diversity of authentication methods (leveraging login through common developer tooling), another great feature is the ability to scan remote files and folders as well, not requiring the code to be on your local machine.  You can use a remote repository’s URL––whether GitHub or Gitlab, or point to a Docker image and TruffleHog will scan the remote source.  If the first layer of code doesn't have secrets, but you know developers have accidentally pushed secrets in the past (even if they deleted it in another commit), it will still detect these deleted secrets in the git history.

3. Commands, Flags, Modes

With a wide range of out of the box commands, flags, and modes, it’s also possible to define the depth of a scan and how many layers deep you want to go.

This also comes back to the previous point.  Where, you can ensure that TruffleHog scans layers deep to also find previously committed and deleted secrets.

In the example below, we demonstrate the ability to scan remote git repositories without even cloning them locally. In this case, we scanned and detected a (fake) GitHub Personal Access Token pushed by a specific commit.



4. Customer Rules and Verifiers

If you have your own service API that generates tokens, it is possible to define custom detectors.  You can specify specific patterns and strings so that it will know how to catch your own custom tokens and secrets as your developers are writing code.

In the example below from Trufflehog’s readme, see how to define a file ‘config.yaml’ with a regular expression that matches the pattern you want to detect.



5. Secret Verification

TruffleHog distinguishes itself through its capability to authenticate secrets. To do this, it initiates an API request to the respective service, determining whether the identified secret is a verified and authentic secret, or merely resembles one.

You can find more about this example in our previous post, and see how it works in action.  Even if a secret is unverified, it provides you with good practices for how to verify or mitigate the risk.

These features are great for identifying secrets before production.  But what can we do if a secret has already been exposed?

Remediating a Leaked Secret

Let’s be honest, who of us hasn’t accidentally committed a secret to a repository at some point in our engineering career?  This is why TruffleHog has the capability of scanning layers deep in your commit history.

When this happens, you may need to work rapidly to mitigate the exposure. Below is a quick guide for some best practices to mitigate risk when a secret is pushed to the code repository and is found in your commit history - even if the commit was reversed or the token deleted.

Remediating a leaked secret (like API keys, passwords, or private keys) in GitHub or other public-facing repositories involves several steps to minimize potential damage and prevent unauthorized access.

Below are generally good practices to mitigate risk once a secret has accidentally been committed to a repository.

Rotate or Revoke the Leaked Secret

If the secret is active in your systems, it is recommended to immediately change or revoke the leaked credentials no matter how sensitive because can be a gateway to other more sensitive systems and data.

This could mean generating a new API key, changing passwords, or creating new private keys. The goal is to invalidate the old credentials so they cannot be used for unauthorized access.

Truffle Security has open sourced a collection of  API Key Rotation tutorials that provide step-by-step instructions on how to remediate a leaked API key security vulnerability

Remove the Secret from the Repository

For GitHub or similar platforms, use the Git command line tools to remove the sensitive data.

This might involve rewriting the repository's history using commands like `git filter-branch`, `git rebase`, or using the BFG Repo-Cleaner or git-secret tool.

Remember, simply deleting the file or editing it in a new commit does not remove the data from the repository's history. To remove the secret from the repository history, another step needs to be taken.

A common method for purging the secret from your repository and its version history is using the `git reset --hard` to a commit before the point in time when we pushed the secret.  Then the `git push --force` command is used to "revert" back to this commit, and these consecutive steps will erase the secret from the repository's history

After cleaning the history, force-push the changes to the remote repository. Be cautious as this can affect others who have forked or cloned the repository.

Check Forks and Clones

If the repository is public and there was sufficient time for the secret to have been forked with the code, you need to inform the owners of the forks about the leak so they can also remove the sensitive data from their copies.

Even if the secret has already been revoked, ensure they’re aware of the hard-coding, and to take measures in their own code to clean the repository and its history.

Audit for Unauthorized Access

Review logs and monitor the services to check whether leaked secrets provided access to unauthorized actors conducting suspicious activity. This can help you understand if the leaked credentials were used maliciously.

Secret Management Made Easy

TruffleHog is gaining widespread adoption and use because it is natively integrated with developer workflows. 

This is a great example of when security is done right, not only will developers use it, they will also contribute back, and ensure the project is well-maintained and continues to provide value to all of its users.  

By providing automation, flags, customization, and verification that reduces developer friction, the tool is fast and easy to adopt. This streamlines engineering, as developers aren’t held back by common mistakes like committing secrets to production or public-facing code repositories. 

Guardrails enable engineers to develop fast, with added safety, increasing the speed of software delivery without sacrificing quality.