tl;dr Scan for secrets using TruffleHog inside Burp Suite.
Quickstart Steps:
Install TruffleHog on your local machine (instructions here).
Install the TruffleHog Burp Suite extension from the Burp Suite Extensions Store.
Verify secret detection works by visiting this test credential.
For the past year, we've been quietly working on connecting two of your favorite security tools: Burp Suite and TruffleHog. Today, we're excited to announce that you can now officially install TruffleHog directly from the Burp Suite extension (BApp) store.
We've integrated TruffleHog's secret scanning into Burp Suite to efficiently surface verified, live credentials - those that are both active and exploitable.
Why build secret scanning into Burp Suite? Great question! Secret scanning is often associated with Git repositories, while Burp Suite focuses on HTTP traffic. Surely, developers aren’t hardcoding root AWS keys into front-end HTML forms…
Eh…unfortunately, this happens more often than you’d think.
We recently found ~12,000 live secrets in public web traffic data. This discovery, in part, was thanks to TruffleHog’s Burp Suite Extension and drove our team to open-source this tool.
How do I use TruffleHog’s Burp Suite extension?
Let’s walk through installation, configuration, and usage.
Installation
Step 1: Install TruffleHog on your local machine (instructions here).
Step 2: Install the TruffleHog Burp Suite extension. There are two options:
(Harder) Clone the TruffleHog Burp Suite extension repo, and then load the extension in Burp Suite:
Extensions -> Add -> Extension Type: Python > Extension File: trufflehog.py.
Note: We built this extension using Python. If you don't already have another Burp Suite extension using Python, you'll need to download and configure a Jython JAR file. Jython is a Java implementation of Python needed to run Python-based Burp extensions. Here are the instructions:
Download Jython Standalone.
Go to
Extensions -> Extension Settings -> Python environment.Select the path to the
jython-standalone-2.7.4.jarfile for the "Location of Jython standalone JAR file" field.
Configuration
Users can configure settings related to TruffleHog’s execution and the traffic being scanned from Burp Suite.
Note: Configuration changes take effect automatically (there is no save button).
TruffleHog Options
Secret Verification: Enabled by default. This means that the extension will attempt to verify each secret it finds via an HTTP request. This requires internet access. If you’re operating in an environment without internet access, turn off “Verify Secrets” and manually review the unverified secrets. Read more about the verification process here.
⚠️ Important: The Burp Suite extension executes the TruffleHog binary every 10 seconds. Secret verification information is not cached across executions. As a result, the same secret may be re-verified repeatedly if it appears in new HTTP request/response data. Read more about it here.
Overlapping Secret Verification: Disabled by default. This means that the extension will not allow overlapping secret checks. Read more about this here.
TruffleHog Path location. If we can't automatically find the TruffleHog binary in your PATH, you'll need to specify the path to TruffleHog in the TruffleHog Burp Suite tab. This is typical on OSX. You'll only need to do this once.
Burp Suite Options
By default, the extension will only scan proxy traffic. You can modify the configuration in the TruffleHog tab to scan other Burp Suite traffic (e.g., repeater, intruder, etc.).
Scanning for Secrets
Once the extension loads, TruffleHog will automatically scan all configured Burp Suite traffic. There’s no need to click any other buttons.
You might notice a ~10 second lag between when a secret displays in your proxying browser and TruffleHog reports it. That’s expected and by design. For more information, read our Extension Architecture section below.
Interpreting Results
When TruffleHog discovers a secret, it will be displayed in the TruffleHog Burp Suite tab.
Click the relevant row on the top-left table to learn about a secret.
Clicking a secret will open up all the URLs where TruffleHog identified that secret.
Users can then click a specific URL to see detailed information about the secret and identify its exact location in the request or response data.
Note: If TruffleHog finds the secret in the request data, the response tab will be empty.
How does TruffleHog in Burp Suite work?
Loading the TruffleHog Burp Suite extension creates a child process that scans for secrets using the TruffleHog binary installed on your local machine. When TruffleHog identifies a secret, the results are reported in the “TruffleHog” tab. We go into more detail in the next few sections.
Extension Architecture
The TruffleHog Burp Suite extension works as follows:
All configured HTTP traffic (proxy, intruder, etc) is written to temporary files (tempfile).
A child process loops every 10 seconds, running TruffleHog to search for secrets in the temporary files.
The child process deletes the scanned files.
The child process passes discovered secrets to the parent process by writing to standard out.
The parent process parses the data and updates the Burp Suite UI in two ways:
Creates an issue.
Adds the secret to the TruffleHog tab.
The parent process registers a shutdown hook with Burp Suite to ensure exiting Burp Suite will clean up all temporary files.
Why not embed TruffleHog into the extension?
The only requirement to run TruffleHog in Burp Suite is to install TruffleHog locally on the user’s machine. We considered bundling the TruffleHog binary with the extension but decided against it for two reasons:
Extension size bloat: TruffleHog is ~170Mb.
TruffleHog updates: We update TruffleHog frequently with new detectors and other functionality. By using a local version of TruffleHog, users can automatically upgrade to the latest version and benefit from new features. If we bundled the TruffleHog binary into the extension, we’d be reliant on the Burp Suite team to update our extension. This would be time-consuming for everyone involved and suboptimal for the user.
Custom TruffleHog Implementations: It's easy to add your own secret detectors to TruffleHog. You can point the extension to your personal version of TruffleHog and check for non-standard secrets.
How is this different from TruffleHog?
Short answer: This is the TruffleHog command line tool, plus a presentation layer explicitly designed for Burp Suite.
Long answer: Without this extension, if you'd like to scan Burp Suite traffic for secrets, you'd need to write a custom hook to write all HTTP traffic to disk, manually run TruffleHog, and then parse the results to understand which request contained which exposed secret. Most security practitioners do not scan their Burp data for secrets because that process is a bit pain.
UX Design
We put a lot of thought into this extension’s design to ensure it fits seamlessly into Burp Suite users’ existing workflow. Here are a few highlights:
It just works. After loading and a one-time quick configuration, you don’t need to do anything. If your HTTP traffic contains a secret, TruffleHog will report it.
Automatic reloads. If you change a setting related to TruffleHog (e.g. turning Secret Verification off), TruffleHog will automatically reload and scan with your new settings.
Configuration Persistence. When you make a configuration change, we store that data and automatically load those settings the next time you open Burp Suite.
Minimal Configuration Options. TruffleHog has a lot of settings. We extracted only the most critical settings and used an optimized command, so you don’t have to worry about memorizing a long list of CLI flags.
TruffleHog Binary Auto-Location. The extension attempts to automatically locate the absolute file path of the TruffleHog binary. If it can’t find it, users have to manually set it.
Issue Creation. This extension will report secrets in two places: the TruffleHog tab and Burp Suite's built-in issue tracking feature. We did this in case some users don't want to have to look inside the TruffleHog tab.
Secret Persistence. If you reload the TruffleHog extension using Burp Suite Pro or Enterprise, all existing secrets are loaded into the TruffleHob tag. This isn’t available in Burp Suite Community due to the limitations of that version.
New Secret Notifications. When a new secret is identified, the TruffleHog Burp Suite tab will turn orange for 3 seconds, and the number of new secrets will be added to the tab name.
Additionally, the secrets table will bold the row(s) containing the yet-to-be-reviewed secrets(s).
Once you click into a secret for the first time, the bold font will be removed and the secret count in the tab name will be decremented by 1.
Limitations
The primary limitation of the Burp Suite extension (and a great project for anyone interested) is support for Web Socket traffic scanning.
Thank you, Port Swigger
A big thank you to the Port Swigger team, especially Hannah L, for promptly reviewing our extension and adding it to the BApp store. We love using Burp Suite and are grateful to be partnering on this.
Parting Thoughts
The architecture we used to add TruffleHog to Burp Suite is rather straightforward: a looping child process invoking an OS command every 10 seconds and then reporting the results to a Burp Suite tab. Other command-line tools could likely be seamlessly integrated into Burp Suite by copying the scaffolding of this project. In fact, if you provided this project as context to an LLM and asked for modifications to fit another tool, it might not be that taxing.
