> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/ox-code/ox-scan-engines/managing-secret-and-pii-detection/managing-secret-and-pii-detection.md).
# Defining Custom Secret and PII Patterns
> **Note:** This capability is currently in Early Access (EA) and is not generally available. To request access, please contact OX technical support.
You can define custom patterns to detect proprietary secrets, internal credentials, or organization-specific PII formats that are not recognized by OX by default.
After a custom pattern is added, it becomes active in subsequent scans across supported OX scanning engines.
1. Go to **Settings** > **Scan settings** > **Secrets**.
2. Enable **Custom Secret/PII Pattern Detection**.
3. In the **Custom patterns** section, select **Add**.
4. In the **Basics** tab, configure the pattern settings.
| Field | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Secret / PII | Defines whether the pattern detects secrets or PII |
| Name | Display name for the custom pattern |
| Severity | Severity assigned to matching findings |
| Pattern (regex) | Regex expression used for matching, see [Requirements for custom regex patterns](#requirements-for-custom-regex-patterns) |
| Notes | Internal notes for the pattern |
| Custom Issue Description | Custom description displayed in related findings |
5. Optional: In the **Validation** tab, test the Regex pattern against example values before saving the rule.
| Field | Description |
| -------------- | ------------------------------------------------ |
| Example Secret | Example value used to validate the Regex pattern |
6. Optional: In the **Advanced** tab, configure additional matching controls.
| Field | Description |
| ------------ | -------------------------------------------------------- |
| Entropy | Additional validation used to improve detection accuracy |
| Secret group | Group identifier used during matching |
7. Select **Add**.
The pattern becomes active in subsequent scans after it is saved.
## Requirements for custom regex patterns
When you add or edit a custom Secret or PII pattern, OX automatically checks that the regex meets a set of requirements before it can be saved.
These requirements help ensure that custom patterns:
* Use valid regular expression syntax.
* Do not negatively affect scan performance.
* Are specific enough to detect meaningful secrets or PII without producing excessive matches.
If a regex does not meet one or more of these requirements, OX displays an error message explaining why the pattern was rejected.
> **Note**
>
> The **Validation** tab lets you test a regex against sample values. The requirements described in this section are separate checks that OX performs automatically whenever you add a custom regex.
### Syntax requirements
The regex must use valid regular expression syntax. Invalid regex patterns cannot be saved.
For example, the following regex is invalid because the character class is not closed:
```
[abc
```
### Performance requirements
The regex must not contain patterns that may cause excessive backtracking, also known as **Regular Expression Denial of Service (ReDoS)**.
Unsafe regexes can significantly increase scan time and affect scan performance.
Examples of patterns that may be rejected include:
```
(a+)+
```
```
(.*)*
```
```
(\w+)+
```
### Specificity requirements
The regex must be specific enough to detect meaningful secrets or PII without matching excessive amounts of unrelated content.
To measure specificity, OX assigns a score to each regex. A regex must achieve a minimum specificity score of **3** to be accepted.
The following regex elements contribute to the specificity score.
| Regex element | Contribution |
| ------------------------------------------------------- | --------------------------------- |
| Literal character (for example `a`, `B`, `-`, `_`) | +1 |
| Meta character (`.`, `\d`, `\w`, `\s`) | 0 |
| Character class (`[a-z]`, `[\s\S]`)\* | Confirm with your OX version |
| Sequence | Sum of all elements |
| Alternation (`foo\|bar`) | Lowest scoring branch |
| Group (`(...)`) | Same score as its contents |
| Quantifier with a required minimum (`+`, `{3}`, `{5,}`) | Minimum occurrences × inner score |
| Optional quantifier (`*`, `?`) | 0 |
| Anchors and assertions (`^`, `$`, `\b`) | 0 |
### Examples
| Regex | Result | Explanation |
| ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `morrigan-pk_[A-F0-9]{16}` | Accepted | The literal prefix `morrigan-pk_` makes the pattern highly specific. |
| `sync://cred_[a-z0-9]{10}@ox` | Accepted | Contains multiple literal components with a variable section, resulting in a highly specific pattern. |
| `AKIA[0-9A-Z]{16}` | Accepted | The literal prefix `AKIA` identifies a specific secret format. |
| `\w{24}` | Rejected | Uses only a meta character and does not include any literal characters. |
| `.*` | Rejected | Matches arbitrary content and is too broad for secret or PII detection. |
| `foo\|.*` | Rejected | One branch is overly broad, so the lowest-scoring branch determines the result. |
| `ab` | Rejected | Contains only two literal characters and does not meet the minimum specificity requirement. |
### Common validation errors
| Error | Cause | Resolution |
| ------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Invalid regex | The regex contains a syntax error. | Correct the regex syntax. |
| Regex may be vulnerable to ReDoS | The regex contains an unsafe pattern that may affect scan performance. | Simplify the regex and remove nested quantifiers. |
| Use at least three literal characters | The regex is too broad and does not meet the minimum specificity requirement. | Add more literal characters or make the pattern more specific. |
## Limits and permissions
| Configuration | Value |
| ---------------------------------------- | ----------------------- |
| Maximum custom patterns per organization | 20 |
| Default state | Disabled |
| Required permissions | Admin or Policy Manager |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.ox.security/ox-code/ox-scan-engines/managing-secret-and-pii-detection/managing-secret-and-pii-detection.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
.png?alt=media)
.png?alt=media)
.png?alt=media)