adding customizable successRanges and rotatedRanges to customDetector (#4892)

* adding customizable successRanges and rotatedRanges to customDetector

*setting definitive = true in the legacy 200 path so that an earlier ranged verifier's rangesInEffect = true can't trigger a spurious SetVerificationError after the legacy verifier already confirmed the secret as live.

* adressed review comments

Author: jordanTunstill

pkg/custom_detectors/CUSTOM_DETECTORS.md

@@ -36,6 +36,34 @@ This guide will walk you through setting up a custom detector in TruffleHog to i
    - **`regex`**: Defines the patterns to identify potential secrets. You can specify one or more named regular expressions. For a detection to be successful, each named regex must find a match. Capture groups `()` within these regular expressions are used to extract specific portions of the matched text, enabling the detector to process and report on particular segments of the identified patterns.
 
    - **`verify`**: An optional section to validate detected secrets. If you want to verify or unverify detected secrets, this section needs to be configured. If not configured, all detected secrets will be marked as unverified. Read [verification server examples](#verification-server-examples)
+     - **`successRanges`**: A list of HTTP status codes (or ranges) that indicate the secret is **live** (active). When the verification server responds with a matching status code, the secret is marked as verified. Each entry can be a single code (`"200"`) or an inclusive range (`"200-202"`). If omitted (along with `rotatedRanges`), only `200` is treated as verified (backward compatible).
+     - **`rotatedRanges`**: A list of HTTP status codes (or ranges) that indicate the secret has been **rotated** (no longer active). When the verification server responds with a matching status code, the secret is definitively marked as unverified.
+
+     When only one of the two fields is configured, non-matching responses are treated as the opposite state (e.g., if only `successRanges` is set, any response that doesn't match is treated as rotated; if only `rotatedRanges` is set, any non-matching response is treated as live). When both fields are configured and the response matches neither, the result is treated as unknown/inconclusive.
+
+   Here's an example with configurable verification ranges:
+
+   ```yaml
+   # config.yaml
+   detectors:
+     - name: HogTokenDetector
+       keywords:
+         - hog
+       regex:
+         token: '[^A-Za-z0-9+\/]{0,1}([A-Za-z0-9+\/]{40})[^A-Za-z0-9+\/]{0,1}'
+       verify:
+         - endpoint: http://localhost:8000/
+           unsafe: true
+           headers:
+             - "Authorization: super secret authorization header"
+           successRanges:
+             - "200"
+           rotatedRanges:
+             - "401"
+             - "403"
+   ```
+
+   In this example, a `200` response from the verification server means the secret is live and needs rotation. A `401` or `403` means the secret has been rotated and is no longer active. Any other response is treated as inconclusive.
 
    **Other allowed parameters:**
    - **`primary_regex_name`**: This parameter allows you designate the primary regex pattern when multiple regex patterns are defined in the regex section. If a match is found, the match for the designated primary regex will be used to determine the line number. The value must be one of the names specified in the regex section. If not provided, the first regex name in sorted order will be used as the primary regex by default.

pkg/custom_detectors/custom_detectors.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"io"
 	"maps"
 	"net/http"
@@ -64,6 +65,12 @@ func NewWebhookCustomRegex(pb *custom_detectorspb.CustomRegex) (*CustomRegexWebh
 		if err := ValidateVerifyHeaders(verify.Headers); err != nil {
 			return nil, err
 		}
+		if err := ValidateVerifyRanges(verify.SuccessRanges); err != nil {
+			return nil, err
+		}
+		if err := ValidateVerifyRanges(verify.RotatedRanges); err != nil {
+			return nil, err
+		}
 	}
 
 	// Ensure primary regex name is set.
@@ -275,10 +282,15 @@ func (c *CustomRegexWebhook) createResults(ctx context.Context, match map[string
 		// disrupt other verification.
 		return nil
 	}
-	// Try each config until we successfully verify.
+
+	var (
+		definitive     bool
+		rangesInEffect bool
+	)
+
+	// Try each config until we get a definitive answer.
 	for _, verifyConfig := range c.GetVerify() {
 		if common.IsDone(ctx) {
-			// TODO: Log we're possibly leaving out results.
 			return ctx.Err()
 		}
 		req, err := http.NewRequestWithContext(ctx, "POST", verifyConfig.GetEndpoint(), bytes.NewReader(jsonBody))
@@ -288,7 +300,6 @@ func (c *CustomRegexWebhook) createResults(ctx context.Context, match map[string
 		for _, header := range verifyConfig.GetHeaders() {
 			key, value, found := strings.Cut(header, ":")
 			if !found {
-				// Should be unreachable due to validation.
 				continue
 			}
 			req.Header.Add(key, strings.TrimLeft(value, "\t\n\v\f\r "))
@@ -305,27 +316,58 @@ func (c *CustomRegexWebhook) createResults(ctx context.Context, match map[string
 			_ = resp.Body.Close()
 		}()
 
-		if resp.StatusCode == http.StatusOK {
-			// mark the result as verified
-			result.Verified = true
+		successRanges := verifyConfig.GetSuccessRanges()
+		rotatedRanges := verifyConfig.GetRotatedRanges()
 
-			body, err := io.ReadAll(resp.Body)
-			if err != nil {
-				continue
+		if len(successRanges) == 0 && len(rotatedRanges) == 0 {
+			// Backward compat: no ranges configured, use legacy behavior.
+			if resp.StatusCode == http.StatusOK {
+				result.Verified = true
+				definitive = true
+				storeResponseBody(resp, result.ExtraData)
+				break
 			}
+			// Legacy non-200 is a meaningful response (verifier said "no");
+			// mark definitive so a prior ranged verifier with rangesInEffect
+			// does not cause a spurious verification error.
+			definitive = true
+			continue
+		}
 
-			// TODO: handle different content-type responses seperatly when implement custom detector configurations
-			responseStr := string(body)
-			// truncate to 200 characters if response length exceeds 200
-			if len(responseStr) > 200 {
-				responseStr = responseStr[:200]
-			}
+		rangesInEffect = true
+		bothConfigured := len(successRanges) > 0 && len(rotatedRanges) > 0
 
-			// store the processed response in ExtraData
-			result.ExtraData["response"] = responseStr
+		if StatusCodeMatchesRanges(resp.StatusCode, successRanges) {
+			result.Verified = true
+			definitive = true
+			storeResponseBody(resp, result.ExtraData)
+			break
+		}
 
+		if StatusCodeMatchesRanges(resp.StatusCode, rotatedRanges) {
+			definitive = true
 			break
 		}
+
+		// Status matched neither configured range.
+		if !bothConfigured {
+			// Only one side was configured: the non-matching response is
+			// treated as the opposite state.
+			//   successRanges only -> non-match means rotated
+			//   rotatedRanges only -> non-match means live
+			definitive = true
+			if len(rotatedRanges) > 0 {
+				result.Verified = true
+				storeResponseBody(resp, result.ExtraData)
+			}
+			break
+		}
+
+		// Both configured but neither matched -- try the next verifier.
+	}
+
+	if rangesInEffect && !definitive {
+		result.SetVerificationError(errors.New("verification response status code did not match any configured successRanges or rotatedRanges"))
 	}
 
 	select {
@@ -336,6 +378,20 @@ func (c *CustomRegexWebhook) createResults(ctx context.Context, match map[string
 	}
 }
 
+const maxResponseLen = 200
+
+func storeResponseBody(resp *http.Response, extraData map[string]string) {
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return
+	}
+	responseStr := string(body)
+	if len(responseStr) > maxResponseLen {
+		responseStr = responseStr[:maxResponseLen]
+	}
+	extraData["response"] = responseStr
+}
+
 func (c *CustomRegexWebhook) Keywords() []string {
 	return c.GetKeywords()
 }