---
title: Custom detectors
slug: docs/custom-detectors
docTags: 
createdAt: 2024-05-13T22:06:45.238Z
---

## Adding a Detector configuration

Locally-configured detectors are configured in your
`config.yaml` file under the `detectors` field.

## Example config

```yaml
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
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.

```yaml
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"
```

**Explanation**:

- `name`: A unique identifier for your custom detector.
- `keywords`: An array of strings that, when found, trigger the regex search. If multiple keywords are specified, the presence of any one of them will initiate the regex search.
- `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](https://github.com/trufflesecurity/trufflehog/blob/main/pkg/custom_detectors/CUSTOM_DETECTORS.md#verification-server-examples)

**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.
- `exclude_regexes_capture`: This parameter allows you to define regex patterns to exclude specific parts of a detected secret. If a match is found within the detected secret, the portion matching this regex is excluded from the result.
- `exclude_regexes_match`: This parameter enables you to define regex patterns to exclude entire matches from being reported as secrets.
- `entropy`: This parameter is used to assess the randomness of detected strings. High entropy often indicates that a string is a potential secret, such as an API key or password, due to its complexity and unpredictability. It helps in filtering false-positives. While an entropy threshold of `3` can be a starting point, it's essential to adjust this value based on your project's specific requirements and the nature of the data you have.
- `exclude_words`: This parameter allows you to specify a list of words that, if present in a detected string, will cause TruffleHog to ignore that string.
- `successRanges` : This parameter allows you to specify a list of HTTP status codes (or ranges) that indicate the secret is live.
- `rotatedRanges` : This parameter allows you to specify a list of HTTP status codes (or ranges) that indicate the secret is rotated.

Here is [an example of a 'generic' secret detector](https://raw.githubusercontent.com/trufflesecurity/trufflehog/refs/heads/main/examples/generic_with_filters.yml) that exercises many of these options.

### Testing Regex Patterns

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.

Here’s an example of how to test your regex pattern with Regex101:

![](https://api.archbee.com/api/optimize/S23bFlGfp3a-8_a9YY_cE/sl23AposO_DItMagShOpk_image.png)

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.

![](https://api.archbee.com/api/optimize/S23bFlGfp3a-8_a9YY_cE/_6R4cEPBt6cCh8o9nA0ZM_image.png)

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.

```json
{
    "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).

By default response status code of `200 OK` will mark the secret
as **verified**. Any other response status code will mark the secret as
**unverified**. This can be modified with the use of successRanges and/or rotatedRanges

**successRanges**: A list of HTTP status codes (or ranges) that indicate the secret is live. 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. 

**rotatedRanges**: A list of HTTP status codes (or ranges) that indicate the secret has been rotated. 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 is an example with configurable verification ranges:

```json
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.

An example verification server in Python can be found [here](https://github.com/trufflesecurity/trufflehog#verification-server-example-python).