RegexFilterProcessor

The RegexFilterProcessor uses regex pattern matching to filter, redact, or block content in agent messages. No LLM calls are made.

Supports built-in presets for common patterns (PII, secrets, URLs) and custom regex rules. Can be applied to input, output, or both phases.

Usage example

Block PII in input messages:

import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  presets: ['pii'],
  strategy: 'block',
  phase: 'input',
})

Redact secrets in output:

import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  presets: ['secrets'],
  strategy: 'redact',
  phase: 'output',
})

Custom rules:

import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  rules: [{ name: 'internal-id', pattern: /INTERNAL-\d{6}/g, replacement: '[INTERNAL_ID]' }],
  strategy: 'redact',
})

Raise the streaming carryover window for long custom matches (e.g. a fixed-length secret or a value that only matches once its closing delimiter arrives):

import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  rules: [
    {
      name: 'armored-key',
      pattern: /-----BEGIN KEY-----[A-Z]+-----END KEY-----/g,
      replacement: '[KEY]',
    },
  ],
  strategy: 'redact',
  streamCarryoverSize: 256,
})

Attach to an agent:

import { Agent } from '@mastra/core/agent'
import { RegexFilterProcessor } from '@mastra/core/processors'

const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  model: 'openai/gpt-5-nano',
  inputProcessors: [
    new RegexFilterProcessor({
      presets: ['pii', 'secrets'],
      strategy: 'block',
    }),
  ],
})

Constructor parameters

rules?:

RegexRule[]

Custom regex rules to apply. Each rule has a name, a regex pattern, and an optional replacement string.

RegexRule

name:

string

Display name for the rule (used in match reports and error messages).

pattern:

RegExp

The regex pattern to match against.

replacement?:

string

Replacement string for redact strategy. Defaults to '[REDACTED]'.

presets?:

('pii' | 'secrets' | 'urls')[]

Built-in preset categories. 'pii' matches emails, phone numbers, SSNs, credit cards. 'secrets' matches API keys, bearer tokens, AWS keys. 'urls' matches HTTP/HTTPS URLs.

strategy?:

'block' | 'redact' | 'warn'

= 'block'

Strategy when a pattern match is found. 'block' aborts with a TripWire error. 'redact' replaces matched content with replacement text. 'warn' logs a warning but passes content through unchanged.

phase?:

'input' | 'output' | 'all'

= 'all'

Phases to apply the filter. 'input' filters input messages. 'output' filters output stream and result. 'all' filters both.

includeRedactedValues?:

boolean

= false

Include the text that was redacted in each report entry. Off by default, because the values are the data the processor removes.

streamCarryoverSize?:

number

= 128

Trailing characters the streaming redact path holds back between chunks, so a match split across a chunk boundary is redacted whole. The default covers every built-in preset with a wide margin. Raise it for custom rules whose matches stay invisible to the rule until they complete, such as a fixed-length secret or a value with a closing delimiter, when such a match can be longer than the window.

Returns

id:

'regex-filter'

Processor identifier.

name:

'Regex Filter'

Processor display name.

processInput:

(args: ProcessInputArgs) => ProcessInputResult

Checks input messages against all configured rules. Blocks, redacts, or warns depending on strategy. Skipped when phase is output.

processOutputStream:

(args: ProcessOutputStreamArgs) => Promise<ChunkType | null | undefined>

Checks streaming text-delta chunks against all configured rules. Skipped when phase is input.

processOutputResult:

(args: ProcessOutputResultArgs) => ProcessorMessageResult

Checks output messages against all configured rules. Blocks, redacts, or warns depending on strategy. Skipped when phase is input.

Error behavior

When the block strategy is active (default), RegexFilterProcessor throws a TripWire error with retry: false when any pattern matches. The TripWire metadata includes:

• processorId: 'regex-filter'
• matches: Array of match objects with rule, match (redacted to '[REDACTED_MATCH]'), and index
• strategy: 'block'

Built-in presets

Preset	Patterns	Default replacement
pii	Emails, phone numbers, SSNs, credit card numbers	[EMAIL], [PHONE], [SSN], [CREDIT_CARD]
secrets	API keys, bearer tokens, AWS access keys	[API_KEY], [BEARER_TOKEN], [AWS_KEY]
urls	HTTP/HTTPS URLs	[URL]

Redaction behavior

Every rule is matched independently, which lets two rules claim overlapping text. For example, a card number without separators matches both phone and credit-card. Overlapping matches are combined into one region and replaced once with the replacement from the longest match.

const filter = new RegexFilterProcessor({
  presets: ['pii'],
  strategy: 'redact',
})

// "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"

A replacement string can use $1 or $& to reference capture groups for an independent single match. When matches form a combined region, the replacement string is inserted as written. The same applies when a rule relies on surrounding text through a lookbehind or lookahead. The region is redacted in either case.

Redaction reporting

Because the redact strategy rewrites text in place, downstream code can't determine what changed. Assign onViolation to record the change for each redacted message or message part and for each stream chunk, with offsets relative to that text. Async callbacks are awaited, while errors are caught so an unavailable audit sink can't fail the request.

import { RegexFilterProcessor, type RegexRedactionDetail } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  presets: ['pii'],
  strategy: 'redact',
})

filter.onViolation = async ({ detail }) => {
  const redaction = detail as RegexRedactionDetail

  for (const entry of redaction.redactions) {
    await auditLog.write({
      phase: redaction.phase,
      messageId: redaction.messageId,
      rule: entry.rule,
      offset: entry.index,
      length: entry.length,
    })
  }
}

The callback is awaited, including in processOutputStream, where it runs for every chunk that contains a match. Keep the callback fast, or hand the work to a queue, so a slow audit sink doesn't stall a streaming response. With no callback attached, the redact path stays synchronous.

The block strategy reports through the same callback. There the processor runner invokes it when it catches the TripWire, so detail holds the tripwire metadata described under Error behavior rather than the shape below.

detail for a redaction is a RegexRedactionDetail:

strategy:

'redact'

Distinguishes a redaction report from the block strategy payload.

phase:

'processInput' | 'processOutputStream' | 'processOutputResult'

Processor method that applied the redactions.

messageId?:

string

Id of the message the text came from. Absent for stream chunks.

partIndex?:

number

Index of the redacted part in the message's parts array, which also contains non-text parts. Absent for string content and stream chunks.

redactions:

RegexRedaction[]

Redactions in the order they appear in the text.

RegexRedaction

rule:

string

Name of the rule whose replacement was used.

index:

number

Start offset of the redacted span in the text.

length:

number

Length of the redacted span.

replacement:

string

Text that replaced the span.

overlappingRules?:

string[]

Names of all rules that matched this span, set only when more than one overlapped.

value?:

string

The text that was redacted. Set only when includeRedactedValues is enabled.

Values are left out by default. An audit trail that copies the data it protects widens the exposure it was added to narrow. Set includeRedactedValues only when the destination is as protected as the original, and note that the block strategy also withholds matched text from its TripWire metadata for the same reason.