PII Redaction Configuration

Use this page when you want to configure the built-in PII redaction plugin component. The component kind is pii_redaction.

The CLI and primary language bindings register this component. Direct Rust applications must call nemo_relay_pii_redaction::component::register_pii_redaction_component() before they validate or initialize a pii_redaction component.

For plugin file discovery, precedence, merge behavior, editor controls, and gateway conflict rules, refer to Plugin Configuration Files.

NeMo Relay plugin configuration uses the generic plugin document shape, so field names stay snake_case in every binding and in plugins.toml.

Relation to Raw Middleware

This plugin uses the same sanitize-guardrail middleware family documented in Middleware.

The difference between raw middleware and pii_redaction is the layer of abstraction:

Raw middleware asks you to register sanitize callbacks directly in code.
pii_redaction gives you a first-party, config-driven privacy contract on top of those same runtime hooks.

Choose pii_redaction when you want a reusable built-in policy surface. Choose raw middleware when you need bespoke callback logic that does not fit the plugin contract.

Plugin Versus Middleware

Use this matrix when deciding whether to use the built-in pii_redaction plugin or raw sanitize-guardrail middleware directly.

Area	`pii_redaction` Plugin	Raw Middleware
Primary UX	Declarative config through `plugins.toml`, bindings helpers, and the CLI editor	Callback registration in application code
Best fit	Reusable privacy policy shared across apps or teams	App-specific logic tied to runtime state or custom heuristics
Built-in actions	`remove`, `redact`, `regex_replace`, `hash`, `mask`	You implement the behavior yourself
Built-in detectors	Supported	You implement the matcher yourself
Codec-aware LLM handling	Supported for the documented codecs	You handle normalization and provider shapes yourself
Validation and editor support	Supported	Not provided
Cross-runtime consistency	First-party contract across Relay surfaces	Depends on each app’s callback code
Flexibility	Limited to the plugin contract	Full control over sanitize behavior
When to choose it	You want the fastest path to a supported privacy surface	You need behavior the plugin contract does not express

Component Shape

The top-level PII redaction object contains:

Field	Purpose
`version`	PII redaction config schema version. Defaults to `1`.
`mode`	Backend mode. Current values are `builtin` and `local_model`. Defaults to `builtin`.
`input`	Enables managed LLM request sanitization and non-tool, non-LLM scope-start field sanitization. Defaults to `true`.
`output`	Enables managed LLM response sanitization and non-tool, non-LLM scope-end field sanitization. Defaults to `true`.
`mark`	Enables mark `data`, `category_profile`, and `metadata` sanitization. Defaults to `true`.
`tool_input`	Enables sanitization of emitted tool-request observability payloads. Defaults to `true`.
`tool_output`	Enables sanitization of emitted tool-response observability payloads. Defaults to `true`.
`priority`	Guardrail priority. Lower values run earlier. Defaults to `100`.
`codec`	Managed LLM provider codec. Required when `input` or `output` is enabled.
`profiles`	Ordered redaction profiles. Each profile selects `builtin` or `local_model`; enabled profiles cover every supported sanitization surface.
`builtin`	Built-in backend settings used when `mode = "builtin"`.
`local`	Local-backend settings used when `mode = "local_model"`.
`policy`	Component-local handling for unknown fields and unsupported values.

At least one managed redaction surface must be enabled.

Use either the legacy single-policy fields (mode, surface flags, priority, builtin, and local) or profiles, but not both. The component-wide codec, version, and policy fields remain valid with profiles.

In profile-array mode, profiles execute by ascending priority and use array order to break ties. Relay assigns internal names such as profile_0, so profiles do not require IDs. Disabled profiles are validated but do not register callbacks. The complete array is replaced as one value during config layering.

Backend Support

The following table compares the available PII redaction backends:

Area	`builtin`	`local_model`
Built-in component kind and config validation	Supported	Supported
Managed LLM `input`	Supported	Not implemented
Managed LLM `output`	Supported	Not implemented
Mark and generic scope event fields	Supported	Not implemented
Managed `tool_input`	Supported	Not implemented
Managed `tool_output`	Supported	Not implemented
Built-in actions	`remove`, `redact`, `regex_replace`, `hash`, `mask`	N/A
Codec support	`openai_chat`, `openai_responses`, `anthropic_messages`	Runtime-specific future implementation
Runtime availability	Any runtime that includes the `nemo-relay-pii-redaction` plugin crate	Runtimes that install a local backend provider

Built-in Mode

Use builtin mode when NeMo Relay should sanitize emitted observability payloads with a deterministic first-party backend.

This is the recommended mode when the privacy behavior is common enough to be described declaratively with built-in actions, detector presets, exact target paths, and supported codecs.

Requirements

To use mode = "builtin":

builtin settings are required.
codec is required when input or output is enabled.
builtin.action must be remove, redact, regex_replace, hash, or mask.
builtin.pattern or builtin.detector is required when builtin.action = "regex_replace" or builtin.action = "redact".

Composed `plugins.toml` Example

You can write this config directly in plugins.toml, or create and edit it through the CLI with nemo-relay plugins edit. For plugin file discovery, precedence, merge behavior, and editor controls, refer to Plugin Configuration Files.

1 version = 1
2 
3 [[components]]
4 kind = "pii_redaction"
5 enabled = true
6 
7 [components.config]
8 version = 1
9 codec = "openai_chat"
10 
11 [[components.config.profiles]]
12 mode = "builtin"
13 priority = 80
14 
15 [components.config.profiles.builtin]
16 action = "redact"
17 detector = "email"
18 
19 [[components.config.profiles]]
20 mode = "builtin"
21 priority = 90
22 
23 [components.config.profiles.builtin]
24 action = "redact"
25 detector = "api_key"
26 
27 [components.config.policy]
28 unknown_component = "warn"
29 unknown_field = "warn"
30 unsupported_value = "error"

This example applies email redaction before API-key redaction to marks, LLM and tool observability payloads, and scope metadata. [REDACTED] is already the default replacement for redact, so no replacement field is needed.

Legacy single-policy configurations may still use mark and the other surface flags. Profile-array configurations intentionally do not expose those flags: every enabled profile owns the complete pre-subscriber sanitization boundary.

CLI Editor Support

The NeMo Relay CLI plugin editor now exposes pii_redaction directly through nemo-relay plugins edit.

Use the editor when you want to:

Toggle the component on or off
Choose builtin or local_model
Add and order multiple redaction profiles
Enable or disable individual profiles
Set the LLM codec
Edit builtin action settings such as action, target_paths, pattern, detector, replacement, and masking fields
Edit local.backend for a runtime-provided future local-model backend

The editor preserves unknown fields when it rewrites an existing pii_redaction component, so future or runtime-specific settings are not discarded by the interactive edit flow.

If your policy needs callback code instead of editor or configuration fields, use raw middleware.

Built-in Settings

The builtin section contains:

Field	Purpose
`action`	Sanitization action. Current values are `remove`, `redact`, `regex_replace`, `hash`, and `mask`.
`target_paths`	Exact JSON-pointer paths to sanitize. Empty means every matching string leaf.
`pattern`	Regex pattern used when `action = "regex_replace"` or `action = "redact"`.
`detector`	Optional built-in matcher preset. Current values are `email`, `phone`, `api_key`, `ip_address`, `ipv6`, `url`, `uuid`, `bearer_token`, `jwt`, `credit_card`, `aws_access_key_id`, `aws_secret_access_key`, `gcp_api_key`, and `azure_storage_account_key`.
`replacement`	Replacement text used when `action = "regex_replace"` or `action = "redact"`. Defaults to `[REDACTED]`.
`mask_char`	Masking token used when `action = "mask"`. Defaults to `*`.
`unmasked_prefix`	Leading character count to keep when `action = "mask"`. Defaults to `0`, unless a detector-specific masking preset is active.
`unmasked_suffix`	Trailing character count to keep when `action = "mask"`. Defaults to `0`, unless a detector-specific masking preset is active.

Action Semantics

`remove`

remove is structural.

When a target matches:

Object fields are removed.
Array elements become null.
Targeted scalar or root values become null.

`regex_replace`

regex_replace applies the configured regex to matching string leaves and replaces matches with the configured replacement.

If you set detector instead of pattern, the built-in backend uses the detector’s stock matcher regex.

`redact`

redact is the deterministic whole-match replacement lane.

It uses the same pattern or detector matcher flow as regex_replace, but defaults the replacement token to [REDACTED] and is intended for cases where you do not want to preserve any matched secret characters.

Use redact when you want:

credential-style secrets fully replaced
a consistent redaction token across detectors
clearer policy intent than a custom regex_replace

`hash`

hash replaces matching string leaves with their SHA-256 hex digest.

When pattern or detector is set, hash only replaces the matching substring instead of hashing the entire string leaf.

`mask`

mask replaces the middle portion of each matching string leaf with the configured mask_char.

Use unmasked_prefix and unmasked_suffix when you want to preserve a small leading or trailing segment for correlation or debugging, such as the last four characters of a token.

When pattern or detector is set, mask only masks matching substrings inside the string leaf.

When detector is set and you do not specify unmasked_prefix or unmasked_suffix, the built-in backend applies detector-aware defaults:

email: Preserves the domain and the first local-part character
phone: Preserves the last four digits while keeping separators intact
api_key: Preserves the vendor-style prefix such as sk- and the last four characters
ip_address: Preserves the last octet
ipv6: Preserves the last segment
url: Preserves the scheme and host, then collapses the path/query tail
uuid: Preserves the last four characters
bearer_token: Preserves the auth scheme and the last four characters
jwt: Preserves the header segment and the tail of the signature
credit_card: Preserves the last four digits while keeping separators intact
aws_access_key_id: Preserves the provider prefix and the last four characters
aws_secret_access_key: Preserves the last four characters
gcp_api_key: Preserves the AIza-style prefix and the last four characters
azure_storage_account_key: Preserves the last four characters

Path Semantics

target_paths are exact JSON-pointer matches.

The plugin uses different payload boundaries for tools and LLMs:

Tools use JSON-native payloads. Paths point into the emitted tool args or tool result shape directly.
LLMs use the selected built-in codec. Prefer normalized Relay paths such as:
- /messages/0/content for request message content
- /message for the normalized assistant response text
Marks and non-tool, non-LLM scopes sanitize data, category_profile, and metadata as separate JSON values. A target path is evaluated independently inside each value; it does not start with /data, /category_profile, or /metadata.

The current implementation also preserves provider-shaped response-path compatibility for the supported codecs, but normalized LLM paths are the recommended contract for new configuration.

Decision Rule

Use pii_redaction for reusable, config-driven privacy behavior. Use raw middleware when the policy depends on application-specific runtime state or custom callback logic. Refer to Plugin Versus Middleware for the full comparison.

Detector Presets

The built-in detector presets are grouped into three deterministic families:

Common PII

email
phone
ip_address
ipv6
url

Structured Secrets

api_key
uuid
bearer_token
jwt
credit_card

bearer_token is heuristic rather than vendor-specific. It can still match benign bearer-style values, so prefer a narrower detector when you know the credential family.

Cloud Credentials

aws_access_key_id
aws_secret_access_key
gcp_api_key
azure_storage_account_key

They are deterministic regex-backed helpers, not model inference.

If target_paths is empty, the built-in backend sanitizes every matching string leaf in the selected payload boundary.

Observability Semantics

The built-in plugin uses sanitize guardrails and event sanitizers.

That means:

The real provider request and response values are unchanged.
The emitted NeMo Relay start, end, or mark event observability fields are sanitized.
annotated_response is regenerated from the sanitized end-event payload when the configured response codec can decode that payload.
Subscribers and exporters consume only the sanitized canonical event stream. Each exporter can omit or transform fields as part of its normal projection, but raw values removed by the plugin do not bypass the sanitizer.

For tool and LLM scope events, the PII redaction scope sanitizer leaves data, category_profile, and metadata unchanged because the specialized tool or LLM sanitizer already owns that lifecycle boundary. This prevents repeated hashing or masking. Other scope categories use input for starts and output for ends.

Local Model Mode

local_model is reserved for a future in-process local-model backend.

Current Status

The current local-model status is:

The plugin contract accepts mode = "local_model".
The local section supports:
- backend
- model_id
- detector_profile
- allow_network
- max_latency_ms
Actual behavior depends on a runtime-installed local backend provider.

Without a provider, runtimes report the local backend as unavailable during plugin initialization.