Customizing TruffleHog
Custom detectors
6min
adding a detector configuration locally configured detectors are configured in your config yaml file under the detectors field example config concurrency "8" detectors \ keywords \ keyword1 \ keyword2 name custom regex detector regex id id \[a za z0 9]{16} secret '\[a za z0 9]{32}' verify \ endpoint http //localhost 8000 headers \ 'authorization bearer token' unsafe true filterunverified true loglevel info numworkers 16 trufflehogaddress https //gnarly flying pancake c1 prod trufflehog org trufflehogscannergroup account 1 us west 2 trufflehogscannertoken thog agent xxxxxxxxxxxxxxxxxxxxxxxxxx custom regex beta detector the custom regex detector allows you to define your own detector using regular expressions with optional verification using a webhook detectors \ name hogtokendetector keywords \ hog regex hogid '\b(hog\[0 9a z]{17})\b' hogtoken '\[^a za z0 9+\\/]{0,1}(\[a za z0 9+\\/]{40})\[^a za z0 9+\\/]{0,1}' verify \ endpoint http //localhost 8000/ \# unsafe must be set if the endpoint is http unsafe true headers \ "authorization super secret authorization header" keywords are fixed string literals that appear around or in the regular expression you would like to use they are required and allow us to apply the regular expression to only relevant chunks of data, speeding up scan time if any one of the provided keywords are found in a chunk of data, the detector will search for the regular expressions the regex section is where you'll define one or more named regular expression a match is one of each of the named regular expressions the total number of matches is the cartesian product of the regular expressions up to a maximum of 100 for example, if regexa has 2 matches a, b and regexb has 3 matches 1, 2, 3 , the total number of matches will be 6 (a, 1), (a, 2\), (a, 3), (b, 1), (b, 2), (b, 3) in the above example, the regex section defines regex pattern for id as a string prepended with id then followed by a 16 characters comprising of lowercase and uppercase letters a z and digits 0 9 we highly recommend that you test your regex pattern with a site like https //regex101 com/ https //regex101 com/ to ensure that your custom detector works as intended testing regex patterns here’s an example of how to test your regex pattern with regex101 make sure to select golang (the regex flavor utilized by the trufflehog scanning engine) and confirm the gm on the right of the text field if not, click into it and adjust the regex flag to g lobal m ultiline enter in the regex pattern you’d like to detect confirm in regex101 that the regex pattern matches with the desired type of strings you’d like to detect the explanation panel on upper right will translate what the regex pattern specifically looks for and the quick reference panel on the bottom can help you find the regex token to define your desired regex pattern verification verification is done via a webhook post request to the provided endpoint unsafe must be set to true if the endpoint is http provided headers will be sent as is to the verification server verification webhook payload and response an example payload is provided for the above configuration { "hogtokendetector" { "hogid" \["hogasdijklkeijkxnezw"], "hogtoken" \["asdjklielknckejd212498ssjnidjklasdm23459"] } the first index in the array is the full match and subsequent indices are any sub matches (delineated by surrounding parentheses in the regular expression) a response status code of 200 ok will mark the secret as verified any other response status code will mark the secret as unverified an example verification server in python can be found here https //github com/trufflesecurity/trufflehog#verification server example python