(Part II Coming Soon!)
TruffleHog, our open-source secrets scanner, detects over 900 unique types of secrets and we’re constantly adding to that list. But that doesn’t mean TruffleHog can identify every type of secret your organization is looking for. What should you do if we don’t detect a secret type you’re interested in? We recommend adding a new detector.
TruffleHog, our open-source secrets scanner, detects over 900 unique types of secrets and we’re constantly adding to that list. But that doesn’t mean TruffleHog can identify every type of secret your organization is looking for. What should you do if we don’t detect a secret type you’re interested in? We recommend adding a new detector.
Adding a New Secret Detector
Adding a new detector should only take about 10 minutes. We’ve thoroughly documented the process here in our GitHub repository and created a video narrating the process (see below). There is no obligation to contribute a new detector to the community – you could create one on a local copy of TruffleHog; however, the community would greatly appreciate any new detector PRs you submit.
Creating the Detector
First, fork and clone the TruffleHog repo then navigate to the root of the repo and open an editor of your choosing.
Next add a new Secret Detector enum to the DetectorType list. If the last item in the list before adding yours is AcmeCo: 990 then you would add MyDetectorType: 991.
After adding the enum to the detectors.proto file, run make protos to update the .pb files.
Generate the new Secret Detector by running:
This command generates a new package in the pkg/detectors folder containing boilerplate code for your detector.
Next, update the generated boilerplate code:
Update the secret detection pattern regex and keywords. (Pro Tip: try iterating with regex101.com)
Update the verifier code to use a non-destructive API call that can determine whether the secret is valid.
Create a test for the detector (This is important!)
Testing the Detector
To ensure the quality of your PR, make sure your tests pass with verified credentials.
1. Create a file called .env with this env file format:
2. Export an environment variable named TEST_SECRET_FILE and point it to the .env file’s path. For example:
Now that a .env file is present, the test file can load secrets locally.
3. Update the boilerplate tests as necessary. A test file has already been generated by the
command and placed in the new detectors pkg folder. The auto-generated tests are often sufficient, so you might not need to change anything. Here is an exemplary test file for a detector which covers all 5 test cases.
4. Run the tests and ensure they pass !
Open your Pull Request
The last step is to contribute your change back to the community! Submit a pull request and someone from the team will review it and your detector will start helping everyone find the new secret type: https://github.com/trufflesecurity/trufflehog/compare
If you stumble into any roadblocks, please reach out to us on Slack!
