Find, verify, and analyze leaked credentials
Go credentialsdevsecopsdynamic-analysisprecommitscanningsecretsecret-managementsecretssecuritysecurity-toolstrufflehogverification
Update Adding_Detectors_external.md (#1822)
Zachary Ricef2d0f809a840
diff --git a/hack/docs/Adding_Detectors_external.md b/hack/docs/Adding_Detectors_external.mdindex a40de07fb..c97369f71 100644--- a/hack/docs/Adding_Detectors_external.md+++ b/hack/docs/Adding_Detectors_external.md@@ -15,9 +15,9 @@ The purpose of Secret Detectors is to discover secrets with exceptionally high s+ [Sourcing Guidelines](#sourcing-guidelines)+ [Development Guidelines](#development-guidelines)+ [Development Dependencies](#development-dependencies)- + [Creating a new Secret Scanner](#creating-a-new-secret-scanner)+ + [Creating a new Secret Detector](#creating-a-new-secret-detector)+ + [Testing the Detector](#testing-the-detector)* [Addendum](#addendum)- + [Using a test secret file](#using-a-test-secret-file)+ [Adding Protos in Windows](#adding-protos-in-windows)## Getting Started@@ -52,7 +52,7 @@ Note: Be sure to update the tests to reference the new secret values in GSM, or3. Proceed from step 3 of [Creating a new Secret Scanner](#creating-a-new-secret-scanner)-### Creating a new Secret Scanner+### Creating a new Secret Detector1. Add a new Secret Detector enum to the [`DetectorType` list here](/proto/detectors.proto).@@ -69,40 +69,19 @@ Note: Be sure to update the tests to reference the new secret values in GSM, orAdd the secret scanner to the [`pkg/engine/defaults.go`](https://github.com/trufflesecurity/trufflehog/blob/main/pkg/engine/defaults.go) file like [`github.com/trufflesecurity/trufflehog/v3/pkg/detectors/<detector_name>`](https://github.com/trufflesecurity/trufflehog/blob/b71ea27a696bdf1c3141f637fda4ee4936c2f2d6/pkg/engine/defaults.go#L9) and[`<detector_name>.Scanner{}`](https://github.com/trufflesecurity/trufflehog/blob/b71ea27a696bdf1c3141f637fda4ee4936c2f2d6/pkg/engine/defaults.go#L1546)-5. Complete the secret detector.+5. Complete the Secret Detector.The previous step templated a boilerplate + some example code as a package in the `pkg/detectors` folder for you to work on.- The secret detector can be completed with these general steps:+ The Secret Detector can be completed with these general steps:- 1. Create a [test secrets file, and export the variable](#using-a-test-secret-file)- 2. Update the pattern regex and keywords. Try iterating with [regex101.com](http://regex101.com/).- 3. Update the verifier code to use a non-destructive API call that can determine whether the secret is valid or not.+ 1. Update the pattern regex and keywords. Try iterating with [regex101.com](http://regex101.com/).+ 2. Update the verifier code to use a non-destructive API call that can determine whether the secret is valid or not.* Make sure you understand [verification indeterminacy](#verification-indeterminacy).- 4. Update the tests with these test cases at minimum:- 1. Found and verified (using a credential loaded from GCP Secrets)- 2. Found and unverified (determinately, i.e. the secret is invalid)- 3. Found and unverified (indeterminately due to timeout)- 4. Found and unverified (indeterminately due to an unexpected API response)- 5. Not found- 6. Any false positive cases that you come across- 5. Create a pull request for review.+ 3. Create a [test for the detector](#testing-the-detector)+ 4. Create a pull request for review.-## Addendum--### Verification indeterminacy--There are two types of reasons that secret verification can fail:-* The candidate secret is not actually a valid secret.-* Something went wrong in the process unrelated to the candidate secret, such as a transient network error or an unexpected API response.--In Trufflehog parlance, the first type of verification response is called _determinate_ and the second type is called _indeterminate_. Verification code should distinguish between the two by returning an error object in the result struct **only** for indeterminate failures. In general, a verifier should return an error (indicating an indeterminate failure) in all cases that haven't been explicitly identified as determinate failure states.--For example, consider a hypothetical authentication endpoint that returns `200 OK` for valid credentials and `403 Forbidden` for invalid credentials. The verifier for this endpoint could make an HTTP request and use the response status code to decide what to return:-* A `200` response would indicate that verification succeeded. (Or maybe any `2xx` response.)-* A `403` response would indicate that verification failed **determinately** and no error object should be returned.-* Any other response would indicate that verification failed **indeterminately** and an error object should be returned.--### Using a test secret file+### Testing the Detector+To ensure the quality of your PR, make sure your tests are passing with verified credentials.1. Create a file called `.env` with this env file format:@@ -116,8 +95,49 @@ For example, consider a hypothetical authentication endpoint that returns `200 O```bashexport TEST_SECRET_FILE=".env"```+ The `.env` file should be in the new detector's directory like this:+ ```+ ├── tailscale+ │ ├── .env+ │ ├── tailscale.go+ │ └── tailscale_test.go+ ```+ Now that a `.env` file is present, the test file can load secrets locally.++3. Next, update the tests as necessary. A test file has already been generated by the `go run hack/generate/generate.go` command from earlier. There are 5 cases that have been generated:+ 1. Found and verified (using a credential loaded from the .env file)+ 2. Found and unverified (determinately, i.e. the secret is invalid)+ 3. Found and unverified (indeterminately due to timeout)+ 4. Found and unverified (indeterminately due to an unexpected API response)+ 5. Not found++ Make any necessary updates to the tests. Note there might not be any changes required as the tests generated by the `go run hack/generate/generate.go` command are pretty good.+ [Here is an exemplary test file for a detector which covers all 5 test cases](https://github.com/trufflesecurity/trufflehog/blob/6f9065b0aae981133a7fa3431c17a5c6213be226/pkg/detectors/browserstack/browserstack_test.go).++4. Now run the tests and check to make sure they are passing ✔️!+```bash+ go test ./pkg/detectors/<detector> -tags=detectors+ ```++If the tests are passing, feel free to open a PR!+++++## Addendum++### Verification indeterminacy++There are two types of reasons that secret verification can fail:+* The candidate secret is not actually a valid secret.+* Something went wrong in the process unrelated to the candidate secret, such as a transient network error or an unexpected API response.-Now, the detector test should attempt to load the given env key from that file.+In Trufflehog parlance, the first type of verification response is called _determinate_ and the second type is called _indeterminate_. Verification code should distinguish between the two by returning an error object in the result struct **only** for indeterminate failures. In general, a verifier should return an error (indicating an indeterminate failure) in all cases that haven't been explicitly identified as determinate failure states.++For example, consider a hypothetical authentication endpoint that returns `200 OK` for valid credentials and `403 Forbidden` for invalid credentials. The verifier for this endpoint could make an HTTP request and use the response status code to decide what to return:+* A `200` response would indicate that verification succeeded. (Or maybe any `2xx` response.)+* A `403` response would indicate that verification failed **determinately** and no error object should be returned.+* Any other response would indicate that verification failed **indeterminately** and an error object should be returned.### Adding Protos in Windows@@ -136,7 +156,3 @@ Now, the detector test should attempt to load the given env key from that file.make protos```-### Testing a detector-```bash- go test ./pkg/detectors/<detector> -tags=detectors- ```