RegexFilterProcessor
RegexFilterProcessor は、コストゼロの正規表現パターンマッチングを適用し、Agent メッセージ内のコンテンツをフィルタリング、墨消し、またはブロックします。LLM 呼び出しは行われません。すべての検出は正規表現に基づきます。
一般的なパターン（PII、シークレット、URL）に対応する組み込みプリセットと、カスタム正規表現ルールをサポートします。入力、出力、または両方のフェーズに適用できます。
使用例使用例への直接リンク
入力メッセージ内の PII をブロックします。
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
presets: ['pii'],
strategy: 'block',
phase: 'input',
})
出力内のシークレットを墨消しします。
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
presets: ['secrets'],
strategy: 'redact',
phase: 'output',
})
カスタムルール：
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
rules: [{ name: 'internal-id', pattern: /INTERNAL-\d{6}/g, replacement: '[INTERNAL_ID]' }],
strategy: 'redact',
})
長いカスタム一致（固定長のシークレットや、終了区切り文字が届いた時点で初めて一致する値など）には、ストリーミングの持ち越しウィンドウを広げます。
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,
})
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',
}),
],
})
コンストラクターパラメーターコンストラクターパラメーターへの直接リンク
rules?:
name:
pattern:
replacement?:
presets?:
strategy?:
phase?:
includeRedactedValues?:
streamCarryoverSize?:
戻り値戻り値への直接リンク
id:
name:
processInput:
processOutputStream:
processOutputResult:
エラー動作エラー動作への直接リンク
block 方法が有効な場合（デフォルト）、RegexFilterProcessor はいずれかのパターンが一致すると、retry: false の TripWire エラーをスローします。TripWire のメタデータには次が含まれます。
processorId：'regex-filter'matches：rule、match（'[REDACTED_MATCH]'に墨消し）、indexを持つ一致オブジェクトの配列strategy：'block'
組み込みプリセット組み込みプリセットへの直接リンク
| プリセット | パターン | デフォルトの置換 |
|---|---|---|
pii | メールアドレス、電話番号、SSN、クレジットカード番号 | [EMAIL]、[PHONE]、[SSN]、[CREDIT_CARD] |
secrets | API キー、Bearer トークン、AWS アクセスキー | [API_KEY]、[BEARER_TOKEN]、[AWS_KEY] |
urls | HTTP/HTTPS URL | [URL] |
墨消しの動作墨消しの動作への直接リンク
各ルールは個別に照合されるため、2つのルールが重複するテキストに一致する場合があります。たとえば、区切り文字なしで記述されたカード番号は phone と credit-card の両方に一致します。重複する一致は1つの領域にまとめられ、最長の一致の置換値を使用して一度だけ置き換えられます。
const filter = new RegexFilterProcessor({
presets: ['pii'],
strategy: 'redact',
})
// "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"
置換文字列では、$1 または $& でキャプチャグループを参照できます。これらの参照が解決されるのは、パターンが一致したテキスト単体にも一致する、単一の一致の場合です。結合された領域の場合や、後読みまたは先読みで周囲に固定されたルールの場合、置換文字列はそのまま挿入されます。どちらの場合も領域は墨消しされます。
墨消しのレポート墨消しのレポートへの直接リンク
redact 方法はテキストをその場で書き換えるため、後続処理からは変更内容を判別できません。記録するには onViolation を設定します。Processor は、墨消しされたメッセージ、メッセージ part、またはストリームチャンクごとに1回呼び出します。オフセットはそのテキスト片を基準とします。非同期コールバックは完了まで待機されます。監査先が利用できない場合でもリクエストが失敗しないよう、エラーは捕捉されます。
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,
})
}
}
一致を含む各チャンクで実行される processOutputStream 内も含め、コールバックの完了を待機します。低速な監査先がストリーミングレスポンスを停止させないよう、コールバックは高速に保つか、処理をキューへ渡してください。コールバックを設定しない場合、redact 処理は同期のままです。
block 方法も同じコールバックを通じてレポートします。この場合、Processor runner が TripWire を捕捉したときにコールバックを呼び出すため、detail には以下の形式ではなく、エラー動作で説明した Tripwire メタデータが入ります。
墨消しの detail は RegexRedactionDetail です。
strategy:
phase:
messageId?:
partIndex?:
redactions:
rule:
index:
length:
replacement:
overlappingRules?:
value?:
デフォルトでは値を含めません。保護対象データを監査証跡へコピーすると、縮小するために導入した露出範囲を逆に広げることになります。includeRedactedValues は、保存先が元のデータと同等に保護されている場合に限り設定してください。同じ理由から、block 方法も一致したテキストを TripWire メタデータに含めません。