SystemPromptScrubber

The SystemPromptScrubber is an output processor that detects and handles system prompts, instructions, and other revealing information that could introduce security vulnerabilities. This processor helps maintain security by identifying types of system prompts and providing flexible strategies for handling them, including multiple redaction methods to ensure sensitive information is properly sanitized.

Usage example

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

const processor = new SystemPromptScrubber({
  model: 'openrouter/openai/gpt-oss-safeguard-20b',
  strategy: 'redact',
  redactionMethod: 'mask',
  includeDetections: true,
  lastMessageOnly: true,
})

Constructor parameters

options:

Options

Configuration options for system prompt detection and handling

Options

model:

MastraModelConfig

Model configuration for the detection agent

errorStrategy?:

'warn' | 'strict'

How to handle failures from the internal model call. 'warn' is fail-open: it logs the failure and allows the content through unchanged. 'strict' is fail-closed: it stops processing with a tripwire.

strategy?:

'block' | 'warn' | 'filter' | 'redact'

Strategy when system prompts are detected: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages, 'redact' replaces with redacted versions

customPatterns?:

string[]

Custom patterns to detect system prompts (regex strings)

includeDetections?:

boolean

Whether to include detection details in warnings. Useful for debugging and monitoring

lastMessageOnly?:

boolean

Whether to inspect only the most recent output message in the batch instead of checking every message. Use this to limit LLM-based scrubbing to the latest response.

instructions?:

string

Custom instructions for the detection agent. If not provided, uses default instructions

redactionMethod?:

'mask' | 'placeholder' | 'remove'

Redaction method for system prompts: 'mask' replaces with asterisks, 'placeholder' replaces with placeholder text, 'remove' removes entirely

placeholderText?:

string

Custom placeholder text for redaction when redactionMethod is 'placeholder'

bufferSize?:

number

Opt-in buffering for streamed text. When greater than 0, streamed text is held back and checked in one LLM call when it ends a sentence, reaches this many characters, or a non-text part arrives. This makes far fewer LLM calls and catches content split across chunks. Recommended for production streaming, for example bufferSize: 200. With 0, every text chunk gets its own LLM call.

Returns

id:

string

Processor identifier set to 'system-prompt-scrubber'

name:

string

Processor display name, always 'System Prompt Scrubber'

processOutputStream:

(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; requestContext?: RequestContext; tracingContext?: TracingContext }) => Promise<ChunkType | null>

Processes streaming output parts to detect and handle system prompts during streaming

processOutputResult:

(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; requestContext?: RequestContext; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>

Processes final output results to detect and handle system prompts in non-streaming scenarios

Extended usage example

For production streaming, set bufferSize (for example bufferSize: 200) so SystemPromptScrubber makes one detection call per sentence instead of one per chunk. Buffering also catches content that is split across chunks. Text then reaches the client in sentence-sized pieces.

When using SystemPromptScrubber as an output processor, it's recommended to combine it with BatchPartsProcessor to optimize performance. The BatchPartsProcessor batches stream chunks together before passing them to the scrubber, reducing the number of LLM calls required for detection.

src/mastra/agents/scrubbed-agent.ts

import { Agent } from '@mastra/core/agent'
import { BatchPartsProcessor, SystemPromptScrubber } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'scrubbed-agent',
  name: 'scrubbed-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  outputProcessors: [
    // Batch stream parts first to reduce LLM calls
    new BatchPartsProcessor({
      batchSize: 10,
    }),
    // Then apply system prompt detection on batched content
    new SystemPromptScrubber({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      strategy: 'redact',
      customPatterns: ['system prompt', 'internal instructions'],
      includeDetections: true,
      redactionMethod: 'placeholder',
      placeholderText: '[REDACTED]',
    }),
  ],
})

Related

• Guardrails