Configure the policy
Open Policies → Library → Regex Replace.Target
Target chooses the leg, and it is required — there is no default.
One policy rewrites one leg. To rewrite both, create two policies.
Rules
Add Rule appends a rule. Rules run in the order listed, and each rule sees the previous rule’s output.
An invalid pattern is rejected when you save, not at request time, so a policy
that saved has patterns that compile.
A worked example: two rules that chain
Say your users write the same thing three ways —email, e-mail, E Mail —
and you want the address after it replaced with a placeholder.
Rule 1 normalises the word:
Rule 2 matches the normalised form and redacts what follows:
My E-Mail is ana@example.com becomes My email is [REDACTED]. Rule 2 matches
only because rule 1 ran first — on its own it would miss every spelling but one.
Reorder the two and the rewrite stops working, with nothing to say why.
$ in a replacement is a capture-group reference, not a literal. $5 is
group 5, not five dollars, and a group that does not exist expands to nothing.
Write $$ for a literal dollar sign, and ${1} rather than $1 when the group
number is followed by more characters — $1x is read as a group named 1x.Mode and scope
Enforce is the only mode in which this policy does anything. In Observe a rule that matches is recorded asobserved and the original text is forwarded
unchanged — which for a rewriting policy means it is a no-op with an event.
That is still worth a first pass: it tells you how often your patterns fire
before they start changing traffic.
How the decision is made
1
The leg matching Target is decoded
The other leg passes through without the rules being applied at all. A policy
with Target
request does nothing on the response, and vice versa.2
Every rule is applied in order, to every field
On the request leg that is the system prompt and each message’s content,
separately — a rule cannot match across a message boundary. On the response leg
it is the assistant’s content.
3
If nothing changed, the body is forwarded untouched
The event records that nothing matched. A rule whose replacement is identical to
what it matched counts as no change.
4
If something changed, the rewritten body is forwarded
In Enforce, the re-encoded body goes upstream on the request leg, or back to
the caller on the response leg with the upstream’s own status code. The event
records
rewritten.403.
Modes and failures
Limits
- It can never block. There is no threshold, no action, no refusal. If the requirement is “this must not reach the model at all”, this is the wrong policy.
- It forwards unredacted when it cannot rewrite. See the warning above.
- Streaming responses pass through untouched, silently.
- One leg per policy. Target is a single choice; use two policies for both legs.
- Message content only. On the request leg, tool call arguments, tool definitions and attachments are not rewritten — only the system prompt and message content. On the response leg, only the assistant’s text: not tool call arguments, not reasoning.
- A rule cannot match across messages. Each message is rewritten on its own, so a pattern spanning a turn boundary never fires.
- A rewrite re-encodes the whole body, and anything the gateway does not model is lost. When a rule fires, the request is rebuilt from the gateway’s own neutral representation rather than patched in place, and that representation carries only the model, the system prompt, the messages, the tools and a handful of sampling settings. Everything else the client sent is dropped: the provider-specific options, the sampling controls the gateway does not carry, and, on the response leg, a few identifiers the provider stamps on its answer. A body no rule matched is forwarded byte for byte, so only the requests this policy actually rewrites are affected.
- A rewritten multimodal message keeps only its text. Content sent as an array of parts — text beside an image, an audio clip or a document — is flattened to the joined text of its text parts before the rules see it, and written back as a plain string. If a rule fires on such a message the image never reaches the model, and no event records the loss.
- RE2 only: no backreferences, no lookahead, no lookbehind. RE2 gives them up in exchange for patterns that cannot be made to run away on hostile input. See below for what to write instead.
- LLM traffic only. The policy does not apply to MCP (Model Context Protocol) tool calls.
Writing patterns without lookaround
RE2 rejects(?=…), (?!…), (?<=…), (?<!…) and \1. The pattern will not
compile and the policy will not save. Three substitutions cover almost every real
case:
The capture-and-restore trick is the whole answer: RE2 cannot assert around a
match, so consume the context and re-emit it.
Verify the policy
Open the Playground, pick an application the policy applies to, and send these in this order.1
Control — the path works at all
2
A rule fires — the rewrite happens
Send text your first rule should match.Expect the decision
rewritten. Read the model’s reply, not just the
status: with Target request, the reply must behave as though it had been
asked the rewritten question. That is what proves the model received the rewrite
and not the original.3
The chain holds — later rules see earlier output
Send text that only your last rule can match once the earlier rules have run —
the
E-Mail spelling from the worked example above, if you built it.Still rewritten, and the reply must show the final form. If it shows the
intermediate one, a later rule is not matching what the earlier rule produced;
check the order.Troubleshooting
Related
- Guardrails — the other guardrail policies, and how to choose between them
- TrustGuard — detector-driven masking that refuses rather than forwards when it cannot mask
- Policies overview — scope, modes and policy chains
- Event schema — the fields each decision records