Prompt Firewall
The prompt firewall screens every request before it reaches the provider. Built-in heuristics always run — they cannot be disabled — and you can layer your own rules on top.Built-in heuristics
The firewall ships with heuristics for common prompt-injection and jailbreak patterns (for example, instruction-override attempts and known jailbreak templates). When a request matches and a policy withaction: "block" is attached to the agent, it is refused with HTTP 400:
Your own rules
A firewall policy attached to an agent can add:- Regex rules — validated with a safe-regex guard so a pathological pattern can’t cause catastrophic backtracking.
- Keyword rules — literal terms to block or flag.
action, which decides what a match does:
With no policy attached, the outcome is
warn.
Test a policy against sample input from the Firewall tab on the gateway detail
page, or programmatically with
POST /v1/ai-gateway/firewall-policies/test,
before you attach it. The tester compiles rules through the same validator the
writer uses, so it refuses exactly what a create would refuse — a pattern that
passes the tester can actually run.
When a blocking policy cannot be fully applied
A policy set toblock is a promise, so the gateway refuses rather than serve a
request under a policy it knows is incomplete:
Canary tokens
Enablecanary_enabled on a policy and the gateway injects a unique kc_canary_<16hex> token into every system prompt before forwarding upstream. If the model ever echoes that token back in its response — a strong signal that a prompt-injection attack extracted the system prompt — the gateway:
- Emits an
ai_gateway.canary_leakaudit entry at critical severity. - Records the policy’s own action as
firewall_outcomeon the usage record —blockwhen the policy’s action isblock, otherwisewarn. - Under a
blockpolicy, refuses the response:400 canary_leakwhen buffered, or — when streamed — stops the stream at the leak and ends it with anevent: errorframe carryingcanary_leak. Anything already sent before the leak contained no canary and stays delivered. - Fires any compliance-pack alert rules listening for
ai_gateway.canary_leak.
monitor streaming mode, which passes the response through unredacted and only inspects it at the end. An agent in monitor mode delivers a leaked canary before any refusal can fire, so do not pair it with a block policy you are relying on.
Where the canary is placed
The canary goes into the system prompt of the request you send, in the form that request’s API uses. Your own system prompt is always forwarded unchanged; the canary is added alongside it.Outcomes in telemetry
The firewall outcome is recorded on every call and exported on the OpenTelemetry span asknoxcall.ai_gateway.firewall_outcome (pass / warn / block / tag), so you can alert and dashboard on it in your own backend.