RegexFilterProcessor

RegexFilterProcessor applique une correspondance sans coût de motifs d'expressions régulières afin de filtrer, masquer ou bloquer le contenu des messages d'un Agent. Aucun appel de LLM n'est effectué. Toute la détection repose sur des expressions régulières.

Il prend en charge des préréglages intégrés pour les motifs courants (PII, secrets et URL) ainsi que des règles d'expressions régulières personnalisées. Il peut être appliqué à l'entrée, à la sortie ou aux deux phases.

Exemple d'utilisation

Bloquez les PII dans les messages d'entrée :

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

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

Masquez les secrets dans la sortie :

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

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

Règles personnalisées :

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

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

Augmentez la fenêtre de report du streaming pour les longues correspondances personnalisées (par exemple, un secret de longueur fixe ou une valeur qui correspond uniquement lorsque son délimiteur de fermeture arrive) :

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,
})

Associez-le à un 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',
    }),
  ],
})

Paramètres du constructeur

rules?:

RegexRule[]

Règles d'expressions régulières personnalisées à appliquer. Chaque règle possède un nom, un motif d'expression régulière et une chaîne de remplacement facultative.

RegexRule

name:

string

Nom d'affichage de la règle (utilisé dans les rapports de correspondance et les messages d'erreur).

pattern:

RegExp

Motif d'expression régulière à rechercher.

replacement?:

string

Chaîne de remplacement de la stratégie redact. Utilise par défaut '[REDACTED]'.

presets?:

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

Catégories de préréglages intégrées. 'pii' correspond aux e-mails, numéros de téléphone, SSN et cartes de crédit. 'secrets' correspond aux clés d'API, tokens bearer et clés AWS. 'urls' correspond aux URL HTTP/HTTPS.

strategy?:

'block' | 'redact' | 'warn'

= 'block'

Stratégie appliquée lors de la détection d'une correspondance. 'block' interrompt l'opération avec une erreur TripWire. 'redact' remplace le contenu correspondant par le texte de remplacement. 'warn' journalise un avertissement, mais transmet le contenu sans le modifier.

phase?:

'input' | 'output' | 'all'

= 'all'

Phases auxquelles appliquer le filtre. 'input' filtre les messages d'entrée. 'output' filtre le flux et le résultat de sortie. 'all' filtre les deux.

includeRedactedValues?:

boolean

= false

Inclut le texte masqué dans chaque entrée du rapport. Désactivé par défaut, car ces valeurs sont précisément les données supprimées par le Processor.

streamCarryoverSize?:

number

= 128

Nombre de caractères de fin conservés entre les chunks par le chemin redact du streaming, afin qu'une correspondance répartie sur une limite de chunk soit entièrement masquée. La valeur par défaut couvre largement tous les préréglages intégrés. Augmentez-la pour les règles personnalisées dont les correspondances restent invisibles jusqu'à leur achèvement, telles qu'un secret de longueur fixe ou une valeur dotée d'un délimiteur de fermeture, lorsque la correspondance peut dépasser la taille de la fenêtre.

Valeur renvoyée

id:

'regex-filter'

Identifiant du Processor.

name:

'Regex Filter'

Nom d'affichage du Processor.

processInput:

(args: ProcessInputArgs) => ProcessInputResult

Vérifie les messages d'entrée par rapport à toutes les règles configurées. Bloque, masque ou avertit selon la stratégie. Ignoré lorsque la phase est output.

processOutputStream:

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

Vérifie les chunks text-delta du streaming par rapport à toutes les règles configurées. Ignoré lorsque la phase est input.

processOutputResult:

(args: ProcessOutputResultArgs) => ProcessorMessageResult

Vérifie les messages de sortie par rapport à toutes les règles configurées. Bloque, masque ou avertit selon la stratégie. Ignoré lorsque la phase est input.

Comportement en cas d'erreur

Lorsque la stratégie block est active (par défaut), RegexFilterProcessor lève une erreur TripWire avec retry: false dès qu'un motif correspond. Les métadonnées TripWire comprennent :

• processorId: 'regex-filter'
• matches : tableau d'objets de correspondance contenant rule, match (masqué sous la forme '[REDACTED_MATCH]') et index
• strategy: 'block'

Préréglages intégrés

Préréglage	Motifs	Remplacement par défaut
pii	E-mails, numéros de téléphone, SSN, numéros de carte de crédit	[EMAIL], [PHONE], [SSN], [CREDIT_CARD]
secrets	Clés d'API, tokens bearer, clés d'accès AWS	[API_KEY], [BEARER_TOKEN], [AWS_KEY]
urls	URL HTTP/HTTPS	[URL]

Comportement du masquage

Chaque règle est recherchée indépendamment ; deux règles peuvent donc correspondre à des portions de texte qui se chevauchent. Par exemple, un numéro de carte écrit sans séparateurs correspond à la fois à phone et à credit-card. Les correspondances qui se chevauchent sont regroupées en une seule région et remplacées une seule fois au moyen du remplacement de la correspondance la plus longue.

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

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

Une chaîne de remplacement peut référencer des groupes de capture au moyen de $1 ou $&. Ces références sont résolues pour une correspondance unique dont le motif correspond également seul au texte détecté. Dans une région combinée, ou pour une règle ancrée sur son contexte avec un lookbehind ou un lookahead, la chaîne de remplacement est insérée telle quelle. Dans les deux cas, la région est masquée.

Rapports de masquage

La stratégie redact réécrit le texte sur place ; les étapes suivantes ne peuvent donc pas déterminer ce qui a changé. Affectez onViolation afin de l'enregistrer. Le Processor l'appelle une fois par message, partie de message ou chunk de flux masqué, et les offsets sont relatifs à cette portion de texte. Les callbacks asynchrones sont attendus et les erreurs interceptées, afin qu'une destination d'audit indisponible ne fasse pas échouer la requête.

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,
    })
  }
}

Le callback est attendu, y compris dans processOutputStream, où il s'exécute pour chaque chunk contenant une correspondance. Veillez à ce qu'il soit rapide, ou confiez le travail à une file d'attente, afin qu'une destination d'audit lente ne bloque pas une réponse en streaming. Si aucun callback n'est associé, le chemin redact reste synchrone.

La stratégie block produit un rapport au moyen du même callback. Le Runner du Processor l'invoque lorsqu'il intercepte le TripWire ; detail contient donc les métadonnées TripWire décrites dans Comportement en cas d'erreur, et non la structure ci-dessous.

Pour un masquage, detail est un RegexRedactionDetail :

strategy:

'redact'

Distingue un rapport de masquage du payload de la stratégie block.

phase:

'processInput' | 'processOutputStream' | 'processOutputResult'

Méthode du Processor qui a appliqué les masquages.

messageId?:

string

Identifiant du message d'où provient le texte. Absent pour les chunks de flux.

partIndex?:

number

Index de la partie masquée dans le tableau de parties du message, qui contient également des parties non textuelles. Absent pour le contenu sous forme de chaîne et les chunks de flux.

redactions:

RegexRedaction[]

Masquages dans leur ordre d'apparition dans le texte.

RegexRedaction

rule:

string

Nom de la règle dont le remplacement a été utilisé.

index:

number

Offset de début de la portion masquée dans le texte.

length:

number

Longueur de la portion masquée.

replacement:

string

Texte qui a remplacé la portion.

overlappingRules?:

string[]

Noms de toutes les règles ayant correspondu à cette portion. Défini uniquement lorsque plusieurs correspondances se chevauchent.

value?:

string

Texte masqué. Défini uniquement lorsque includeRedactedValues est activé.

Les valeurs sont omises par défaut. Une piste d'audit qui copie les données qu'elle protège élargit l'exposition qu'elle devait réduire. Définissez includeRedactedValues uniquement lorsque la destination est aussi protégée que l'original, et notez que la stratégie block masque également le texte correspondant dans ses métadonnées TripWire pour la même raison.