Skip to main content

​
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 with action: "block" is attached to the agent, it is refused with HTTP 400:
Detection is on by default; blocking is not. The built-in heuristics run on every request whether or not a policy is attached, but with no policy attached the outcome is capped at warn — the match is recorded, the request still reaches the provider, and you get no 400. The gateway never blocks on an action you did not configure.Nor does an agent created through /v1 or the dashboard start out unprotected and unblocking by accident: it is given the tenant’s Default policy, whose action is also warn. That is deliberate — a policy every future agent inherits must not be able to start refusing their traffic on its own.So blocking is opt-in on every path. Either change the Default policy’s action to block, or create your own with action: "block" and set the agent’s firewall_policy_id. Until you do, treat the firewall as an alerting control, not a blocking one.

​
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.
A policy carries one 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 to block is a promise, so the gateway refuses rather than serve a request under a policy it knows is incomplete:

​
Canary tokens

Enable canary_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:
  1. Emits an ai_gateway.canary_leak audit entry at critical severity.
  2. Sets firewall_outcome = "warn" on the usage record.
  3. Fires any compliance-pack alert rules listening for ai_gateway.canary_leak.
The canary is stripped from the response before it reaches your app, so it’s invisible in normal operation.

​
Outcomes in telemetry

The firewall outcome is recorded on every call and exported on the OpenTelemetry span as knoxcall.ai_gateway.firewall_outcome (pass / warn / block / tag), so you can alert and dashboard on it in your own backend.