Skip to content

Find, verify, and analyze leaked credentials

docs: add generic config-secret custom detector example (#5195)

Patience Mpofue12da3c72f1f
diff --git a/README.md b/README.md
index aa681b49a..5d7b000a2 100644
--- a/README.md
+++ b/README.md
@@ -798,6 +798,8 @@ Custom Detectors support a few different filtering mechanisms: entropy, regex ta
and excluded word lists checked against the secret (captured group if present, entire match if capture group is not present). Note that if
your custom detector has multiple `regex` set (in this example `hogID`, and `hogToken`), then the filters get applied to each regex. [Here](examples/generic_with_filters.yml) is an example of a custom detector using these filters.
+The `verify` section is optional — if you omit it, matches are still reported as unverified, no webhook required. This makes Custom Detectors useful for flagging generic hardcoded secrets (e.g. `*.password=`, `*.secret=`) in config files like `.properties`, `.env`, or `.yaml` that TruffleHog's built-in, verified detectors won't otherwise catch. [Here](examples/generic_config_secrets.yml) is an example tuned for that use case.
+
**NB:** This feature is alpha and subject to change.
### Regex Detector Example
diff --git a/examples/generic_config_secrets.yml b/examples/generic_config_secrets.yml
new file mode 100644
index 000000000..06a814c4c
--- /dev/null
+++ b/examples/generic_config_secrets.yml
@@ -0,0 +1,47 @@
+detectors:
+- name: generic-config-secret
+ keywords:
+ - secret
+ - password
+ - passwd
+ - pwd
+ - apikey
+ - api_key
+ - api-key
+ - token
+ - credential
+ - cred
+ - auth
+ regex:
+ secret: |-
+ (?i)[\w.-]{0,50}?(?:secret|passw(?:or)?d|pwd|api[_-]?key|token|credentials?|creds?|auth)[\w.-]{0,20}\s*[=:]\s*["'`]?([^\s"'`,;]{6,150})["'`]?\s*(?:$|[\r\n#;])
+ entropy: 2.5
+ # Applied to the captured value only (not the key), so a key path like
+ # `env.password` or `app.env.secret` doesn't cause a real hardcoded
+ # secret to be excluded just because "env" appears in the key.
+ exclude_regexes_capture:
+ - '(?i)^\$\{[^}]*\}$'
+ - '(?i)^\{\{[^}]*\}\}$'
+ - '(?i)^%[A-Z_]+%$'
+ - '(?i)^\$[A-Z_][A-Z0-9_]*$'
+ - '(?i)^(?:process\.env\.|os\.environ|getenv\(|System\.getenv\()'
+ - '(?i)^(?:vault|kms|secretsmanager|parameterstore)://'
+ exclude_words:
+ - "changeme"
+ - "change_me"
+ - "change-me"
+ - "changethis"
+ - "xxxxxx"
+ - "example"
+ - "placeholder"
+ - "dummy"
+ - "redacted"
+ - "your_api_key"
+ - "your-api-key"
+ - "yourapikey"
+ - "insert_secret_here"
+ - "todo"
+ - "fixme"
+ - "null"
+ - "none"
+ - "false"
diff --git a/pkg/custom_detectors/CUSTOM_DETECTORS.md b/pkg/custom_detectors/CUSTOM_DETECTORS.md
index d7887109e..f149f81f0 100644
--- a/pkg/custom_detectors/CUSTOM_DETECTORS.md
+++ b/pkg/custom_detectors/CUSTOM_DETECTORS.md
@@ -41,6 +41,8 @@ This guide will walk you through setting up a custom detector in TruffleHog to i
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.
+ Since `verify` is optional, Custom Detectors can also be used without a webhook to flag generic hardcoded secrets (e.g. `*.password=`, `*.secret=`) in config files such as `.properties`, `.env`, or `.yaml`. [Here](/examples/generic_config_secrets.yml) is an example config tuned for that use case.
+
Here's an example with configurable verification ranges:
```yaml