Custom Regex

Overview

Custom Regex is a Bifrost Enterprise guardrail provider that evaluates request and response text against regex patterns you define. It is useful when you need a simple, local policy check without calling an external guardrail provider. Common uses include blocking organization-specific IDs, internal project names, environment-specific secrets, and PII-like text patterns.

Custom Regex runs in-process and uses Go’s RE2-compatible regexp engine. It does not support lookaheads, lookbehinds, or backreferences. Server-side RE2 validation is authoritative.

How It Works

You create a guardrail provider with provider_name: "regex".
You add one or more regex patterns.
You attach that provider to a guardrail rule.
The rule decides when to run the provider and whether to scan input, output, or both.
If a pattern matches, Bifrost applies that pattern’s action: detect only, block, or redact.

Custom Regex currently evaluates text content. It does not inspect image pixels or binary file contents.

Streaming output: Delivery depends on whether the matched patterns detect, redact, or can block. See Streaming Output Guardrails for details.

Pattern Fields

Field	Required	Description
`pattern`	Yes	RE2-compatible regex pattern
`description`	No	Human-readable label used in the intervention reason
`entity_type`	No	Redaction token to use for matches. Defaults to `description` when set, otherwise `REGEX_MATCH`.
`flags`	No	Optional flag or flag combination. Leave empty for no flag.
`action`	No	`detect_only`, `block`, or `redact`. Defaults to `block`.
`redaction_strategy`	No	`replace`, `mask`, or `hash`. Defaults to `replace`. Used when `action` is `redact`.
`redaction_mode`	No	`runtime`, `logs_only`, or `runtime_reversible`. Defaults to `runtime`. Used when `action` is `redact`.
`allowed_values`	No	List of exact values this pattern ignores. A match equal to one of them is neither detected, blocked, nor redacted. See Allowed Values.

The Web UI exposes these flag choices:

Flag	Meaning
None	No regex flag
`i`	Case-insensitive matching
`m`	Multiline mode
`s`	Dot matches newline
`im`	Case-insensitive + multiline
`is`	Case-insensitive + dot matches newline
`ms`	Multiline + dot matches newline
`ims`	Case-insensitive + multiline + dot matches newline

PII Detection Template

The Web UI includes a PII Detection template under Add Pattern. It pre-fills a Custom Regex configuration with common PII-like patterns:

Description	Flags
Email address	`i`
US phone number	-
US Social Security Number	-
Credit-card-like number	-
IPv4 address	-

The exact template patterns are shown in the config.json and Helm examples below.

The PII Detection template is pattern-based. It is fast and transparent, but it is not semantic PII classification. Expect some false positives and false negatives, especially for international phone numbers and unformatted values. For national IDs outside the US, add your own Custom Regex patterns for the exact country and format you need to enforce.

Allowed Values

Use Allowed values when a pattern is right in general but should skip specific known-safe strings, such as your company’s support email in an email-redaction pattern.

A match is skipped only when the entire matched text equals one of the allowed values, ignoring case. Substrings do not count: an allowed value of support@acme.com skips a match of exactly support@acme.com or Support@Acme.com, but not nosupport@acme.com.
A pattern that captures surrounding context (for example email: x@y.com) is compared as a whole, so the bare value does not exempt it. Write patterns so they match only the value you want to allow.
Allowed values apply to every action: detect_only, block, and redact. Other matches from the same pattern are still handled normally.
In the Web UI, enter one value per line. Values are trimmed, lowercased, and de-duplicated on save. Commas are kept as part of a value.
Allowed values belong to a single pattern. Other patterns in the same configuration are unaffected.

Redaction

Set a pattern’s action to redact when matching text should be rewritten instead of blocked. Custom Regex supports all Bifrost-managed redaction modes:

runtime redacts the live request or response and stores the redacted value in logs.
logs_only leaves runtime content raw but redacts Bifrost logs and trace-export connector content.
runtime_reversible redacts runtime content and logs with reversible placeholders.

For the full behavior matrix, including reveal permissions and connector export behavior, see Guardrail Redaction.

Configuration

Web UI
API
config.json
Helm

Go to Guardrails > Providers.
Select Custom Regex.
Click Add Configuration.
Set a descriptive Name, for example pii-detection.
Click Add Pattern.
Choose either Custom regexp or PII Detection.
Optionally, under Allowed values, list values the pattern should ignore, one per line.
Enable the configuration and save it.
Attach the configuration to a guardrail rule under Guardrails > Configuration.

Create the Custom Regex provider configuration directly with the management API. The current Enterprise backend registers guardrail provider APIs at /api/guardrails/{provider}; the provider type is the path segment (regex), and the API assigns the configuration ID after creation.

curl -X POST http://localhost:8080/api/guardrails/regex \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pii-detection",
    "enabled": true,
    "config": {
      "timeout": 5,
      "patterns": [
        {
          "pattern": "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b",
          "description": "Email address",
          "entity_type": "EMAIL",
          "flags": "i",
          "action": "redact",
          "redaction_strategy": "replace",
          "redaction_mode": "runtime_reversible",
          "allowed_values": ["support@example.com"]
        },
        {
          "pattern": "\\b(?:\\+?1[-.\\s]?)?(?:\\(?\\d{3}\\)?[-.\\s]?)\\d{3}[-.\\s]?\\d{4}\\b",
          "description": "US phone number",
          "entity_type": "PHONE_NUMBER",
          "action": "redact",
          "redaction_strategy": "replace",
          "redaction_mode": "runtime_reversible"
        },
        {
          "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b",
          "description": "US Social Security Number",
          "entity_type": "US_SSN",
          "action": "redact",
          "redaction_strategy": "replace",
          "redaction_mode": "runtime_reversible"
        },
        {
          "pattern": "\\b(?:\\d[ -]?){13,19}\\b",
          "description": "Credit card-like number",
          "entity_type": "CREDIT_CARD",
          "action": "redact",
          "redaction_strategy": "replace",
          "redaction_mode": "runtime_reversible"
        },
        {
          "pattern": "\\b(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}\\b",
          "description": "IPv4 address",
          "entity_type": "IP_ADDRESS",
          "action": "redact",
          "redaction_strategy": "replace",
          "redaction_mode": "runtime_reversible"
        }
      ]
    }
  }'

To attach it through the API, fetch the generated ID with GET /api/guardrails/regex, then reference it in selectedGuardrailProfiles on POST /api/guardrails/rules.

{
  "guardrails_config": {
    "guardrail_providers": [
      {
        "id": 20,
        "provider_name": "regex",
        "policy_name": "pii-detection",
        "enabled": true,
        "timeout": 5,
        "config": {
          "patterns": [
            {
              "pattern": "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b",
              "description": "Email address",
              "entity_type": "EMAIL",
              "flags": "i",
              "action": "redact",
              "redaction_strategy": "replace",
              "redaction_mode": "runtime_reversible",
              "allowed_values": ["support@example.com"]
            },
            {
              "pattern": "\\b(?:\\+?1[-.\\s]?)?(?:\\(?\\d{3}\\)?[-.\\s]?)\\d{3}[-.\\s]?\\d{4}\\b",
              "description": "US phone number",
              "entity_type": "PHONE_NUMBER",
              "action": "redact",
              "redaction_strategy": "replace",
              "redaction_mode": "runtime_reversible"
            },
            {
              "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b",
              "description": "US Social Security Number",
              "entity_type": "US_SSN",
              "action": "redact",
              "redaction_strategy": "replace",
              "redaction_mode": "runtime_reversible"
            },
            {
              "pattern": "\\b(?:\\d[ -]?){13,19}\\b",
              "description": "Credit card-like number",
              "entity_type": "CREDIT_CARD",
              "action": "redact",
              "redaction_strategy": "replace",
              "redaction_mode": "runtime_reversible"
            },
            {
              "pattern": "\\b(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}\\b",
              "description": "IPv4 address",
              "entity_type": "IP_ADDRESS",
              "action": "redact",
              "redaction_strategy": "replace",
              "redaction_mode": "runtime_reversible"
            }
          ]
        }
      }
    ],
    "guardrail_rules": [
      {
        "id": 201,
        "name": "block-pii-in-prompts",
        "description": "Block prompts containing common PII-like values",
        "enabled": true,
        "cel_expression": "headers[\"x-bf-tenant\"] == \"external\"",
        "query": {
          "combinator": "and",
          "rules": [
            {
              "field": "headers",
              "operator": "=",
              "value": "x-bf-tenant:external",
              "valueSource": "value"
            }
          ]
        },
        "apply_to": "input",
        "sampling_rate": 100,
        "timeout": 10,
        "provider_config_ids": [20]
      }
    ]
  }
}

bifrost:
  guardrails:
    providers:
      - id: 20
        provider_name: "regex"
        policy_name: "pii-detection"
        enabled: true
        timeout: 5
        config:
          patterns:
            - pattern: "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b"
              description: "Email address"
              entity_type: "EMAIL"
              flags: "i"
              action: "redact"
              redaction_strategy: "replace"
              redaction_mode: "runtime_reversible"
            - pattern: "\\b(?:\\+?1[-.\\s]?)?(?:\\(?\\d{3}\\)?[-.\\s]?)\\d{3}[-.\\s]?\\d{4}\\b"
              description: "US phone number"
              entity_type: "PHONE_NUMBER"
              action: "redact"
              redaction_strategy: "replace"
              redaction_mode: "runtime_reversible"
            - pattern: "\\b\\d{3}-\\d{2}-\\d{4}\\b"
              description: "US Social Security Number"
              entity_type: "US_SSN"
              action: "redact"
              redaction_strategy: "replace"
              redaction_mode: "runtime_reversible"
            - pattern: "\\b(?:\\d[ -]?){13,19}\\b"
              description: "Credit card-like number"
              entity_type: "CREDIT_CARD"
              action: "redact"
              redaction_strategy: "replace"
              redaction_mode: "runtime_reversible"
            - pattern: "\\b(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}\\b"
              description: "IPv4 address"
              entity_type: "IP_ADDRESS"
              action: "redact"
              redaction_strategy: "replace"
              redaction_mode: "runtime_reversible"

    rules:
      - id: 201
        name: "block-pii-in-prompts"
        description: "Block prompts containing common PII-like values"
        enabled: true
        cel_expression: 'headers["x-bf-tenant"] == "external"'
        query:
          combinator: "and"
          rules:
            - field: "headers"
              operator: "="
              value: "x-bf-tenant:external"
              valueSource: "value"
        apply_to: "input"
        sampling_rate: 100
        timeout: 10
        provider_config_ids: [20]

When To Use Custom Regex

Use Custom Regex when:

You need transparent, deterministic matching.
You want to block a known organization-specific identifier or data format.
You want the built-in PII Detection template.
You need a local guardrail with no external service dependency.

Use Secrets Detection instead when you want broad credential and API key coverage from the built-in Gitleaks rules.

Getting Started

Moving from OSS

Release Cadence

Migration Guides

Features

Security

Overview

How It Works

Pattern Fields

PII Detection Template

Allowed Values

Redaction

Configuration

When To Use Custom Regex

​Overview

​How It Works

​Pattern Fields

​PII Detection Template

​Allowed Values

​Redaction

​Configuration

​When To Use Custom Regex

Overview

How It Works

Pattern Fields

PII Detection Template

Allowed Values

Redaction

Configuration

When To Use Custom Regex