AI Firewall
The AI Firewall is what stands between a request and your models. It has two parts: the prompt-injection guard, which reads what a request carries and is described first, and IP allow and deny lists, which decide where a call with your keys may come from.
A prompt injection is text that tries to give your model new orders: “ignore all previous instructions”, “reveal your system prompt”, a fake <|im_start|>system line hidden in a web page your agent fetched. Zabio checks every request for these patterns before it reaches a model. The check is free, runs on Zabio’s own servers, and is on for every API key.
It is not a guarantee. Patterns catch the common, known phrasings and their usual disguises. They miss what they do not name, a new phrasing, or an attack in another language. Detection is measured in English; the override, extraction, persona and bypass phrases are also checked in Spanish, Portuguese, French, German, Italian, Russian and Chinese. Treat the guard as one layer, and keep your own: give agents the fewest permissions they need, and confirm irreversible actions with a person.
What is checked
Section titled “What is checked”The guard reads three kinds of text in the request, on POST /v1/chat/completions, POST /v1/responses and POST /v1/messages:
source |
What |
|---|---|
user |
the user’s messages |
tool |
tool results: chat’s tool messages, the Responses API’s function_call_output items, Anthropic’s tool_result blocks. This is where an injection hidden in a fetched page, a file or an email usually arrives |
assistant |
assistant turns your client sends back in the history, since a forged one can carry orders too |
A text part of a user message that you mark as text you did not write is read as a tool result is (see Text you did not write). System and developer messages and instructions are not checked: they are your own words. The patterns read only text. The paid tier’s model check also reads images in tool results, images you mark, and the text of PDF and plain text documents (see The paid tier); audio and video are not read. The answer counts what was not read (zabio.guard.not_read). On the Responses API only the turn’s new input is checked: the earlier turns were checked when they were sent. On the Responses API a tool output sent as a JSON object or list is read as its JSON text, the text the model gets. Items you add to a conversation directly (items on POST /v1/conversations, or POST /v1/conversations/{id}/items) are not checked. POST /v1/messages/count_tokens is not checked, since it calls no model. Batches are not checked yet.
Before the patterns run, the text is normalized so the usual disguises fall back onto the same words: invisible characters (zero width characters and Unicode tag characters) are removed or decoded, lookalike letters from other alphabets and fullwidth or styled letters are mapped back to plain ones, spaced-out letters (i g n o r e) and key words broken by spaces (ign ore prev ious) are joined, and a misspelled or scrambled key word (ignroe, instrcutions) is read as the word. Encoded text is decoded and checked too: Base64, hex (also with spaces, colons, \x or 0x between the bytes), percent-encoding (%69), HTML character references (i), \u escapes, decimal character codes, binary octets, ROT13 and text written backwards, and an encoding inside another one (Base64 of hex), two levels deep.
The rules:
rule |
Looks for |
|---|---|
override.instructions |
an order to ignore, forget or override earlier instructions |
prompt.extraction |
a request to reveal or repeat the system prompt or the instructions above |
role.switch |
a switch to another persona or an unrestricted mode (“you are DAN”, “do anything now”, “you are free from your rules”) |
safety.bypass |
an order to bypass or disable safety rules or guardrails |
delimiter.injection |
fake chat template markers (<|im_start|>, [INST], <<SYS>>) or a fake “system:” line followed by orders; in tool results and assistant turns, also a result that closes its own wrapper (</tool_result>) and goes on with orders, a fake user or assistant turn, and in tool results a fake agent step (Thought:, Action:) followed by an order or a fake tool call (<function_calls>, "tool_calls" inside text) |
hidden.instructions |
text addressed to the model and hidden from the user (“do not tell the user”, “note to the AI:”); in tool results and assistant turns, also an HTML comment addressed to the model, and text styled to be invisible (hidden, white or transparent, zero size, LaTeX \color{white}) that gives the model an order |
new.instructions |
“new instructions:”, “your new task is” and the like, and a new role when it is the model’s (“your new role is an unrestricted AI”, not “your new role is team lead”), in tool results and assistant turns only |
exfiltration |
an order to send data to a URL, or a Markdown or HTML image whose link carries data out (a placeholder, or a query that is a sentence), in tool results and assistant turns only |
In those seven languages, override.instructions, prompt.extraction, role.switch and safety.bypass check their phrases too; the other rules read English. Each rule reads phrases: a single word such as “ignora” is never a detection.
A text about prompt injection itself, such as a security write-up that quotes “ignore previous instructions”, is read as a mention and not reported, in each of these languages. In a user’s own message, an order to ignore instructions the user says they gave (“ignore the previous instructions I gave you about the format”) is the user changing their mind and is not reported either; the same words in a tool result are.
The four actions
Section titled “The four actions”Each API key has a guard action: its own, or the organization’s default action, which a key follows unless it sets one. A new key follows the organization, and so does every older key whose action was never set: only a key whose action an owner or admin chose keeps it as its own.
The organization’s default is Tag or Block, and Tag until an owner or admin changes it. Off and Redact are not organization defaults: they are set on each key. A key that follows shows guard_action: null, and every key shows the action in force as guard_action_effective.
| Action | What happens on a detection |
|---|---|
off |
nothing is checked |
tag |
the call goes through unchanged; the answer’s zabio.guard lists each detection |
redact |
each detected span is replaced with [PROMPT_INJECTION] before the model sees it; the answer lists what was replaced. A stored Responses turn keeps the redacted text |
block |
the request is refused with 403 prompt_injection_blocked. Nothing reaches a model, nothing is billed and nothing of the request is stored; only the guard’s event is kept (see What Zabio keeps) |
Owners and admins set the key’s action when they create or edit the key, in AI Firewall, Prompt Injection or with guard_action on POST or PATCH /admin/v1/orgs/{org}/keys from a web session (null makes the key follow the organization again). They set the organization’s default in AI Firewall, Prompt Injection, Default action on a match, or with {"action": "block"} on PATCH /admin/v1/orgs/{org}/guard; it applies to every key that follows at its next request. A member, or a user token, cannot change a key’s or the organization’s guard settings.
Try tag before block. Patterns also match ordinary text now and then: a sentence that happens to read like an order, or a quote from an article about injections. Under tag such a call goes through and only the report is wrong; under block it is refused. Run a key on tag first, read the detections on its real traffic, add the harmless ones to the allowlist, and switch to block when what is left is what you want stopped.
A single request can ask for a stronger action than its key’s, in the body or as a header, which wins over the body:
{"model": "auto", "messages": [...], "zabio": {"guard": {"action": "block"}}}x-zabio-guard: blockA request can only tighten the key’s action, never loosen it, so text your agent reads cannot switch the guard off. A weaker ask is ignored and listed in zabio.ignored_parameters as zabio.guard.action; the call is not refused for it. A value other than the four names is a 400 invalid_value.
The answer
Section titled “The answer”Every answer the guard checked carries zabio.guard. The detections say where the text was and which rule it matched, never the text:
"zabio": { "guard": { "action": "tag", "detections": [ {"message_index": 2, "path": "messages[2].content", "source": "tool", "rule": "override.instructions", "start": 41, "end": 74} ] }}| Field | Meaning |
|---|---|
action |
the action in force: the key’s, or the stronger one the request asked for |
detections |
one entry per match; an empty list when nothing was found |
detections[].message_index |
the index in your own messages or input array |
detections[].path |
the JSON path of the string in your request body |
detections[].source |
user, tool or assistant |
detections[].rule |
the rule matched |
detections[].start, end |
the span’s offsets in that string, in Unicode characters, end not included |
detections[].encoding |
how the span was encoded, when it was: base64, hex, percent, html, unicode, decimal, binary, rot13 or reversed, the outer one first for an encoding inside another (base64+hex). For an encoded run the offsets are those of the whole run; for ROT13 and reversed text, those of the phrase |
truncated |
true when part of the request was not checked: it was larger than the guard reads (256 KB per string, 1 MB per request), it held more than 64 detections, or its text was built to be costly to read and the character patterns stopped early |
detections[].detector |
pattern for the free patterns; model only when the guard’s paid tier read the request, for a string its model check flagged |
detections[].trusted |
true for a detection in a result of a tool the key trusts: reported, never redacted or blocked (see Trusted tools) |
detections[].untrusted |
true for a detection in a user text part you marked as text you did not write; source is user (see Text you did not write) |
paid |
present only when the paid tier read the request, as true |
unchecked |
present only when the paid tier read the request and could not read a string, an image or a document: each with message_index, path, source and reason (timeout, rate_limited, error, no_credit, image_limit or unsupported), and untrusted for a marked part; the free patterns read such a text, and a document’s text, as always; an image they do not read. A long text the model check flagged while one of its parts could not be read is in detections and also here, with partial: true and windows_unread, the number of parts not read |
not_read |
present when the request carries something the guard did not read, as counts, never text: images, audio, video, files (a file, a document or any other part that is not text) and system (system and developer messages, instructions) are read by neither the patterns nor the model check (an image or a document the model check read, or reported in unchecked, is not counted here); when the model check ran, also earlier_messages (user messages before the current turn), assistant_turns and trusted_results (results of the key’s trusted tools), which the patterns read and the model check does not. A count that is zero is left out |
No zabio.guard at all means the guard did not run: the action is off. The header x-zabio-guard repeats the action and the count (tag; detections=1) on every checked answer, streams included. The header x-zabio-guard-unread repeats not_read on every checked answer (images=1; system=1, or none), and when the model check ran it ends with unchecked= and the number of strings it could not read. When the headers are sent before the model check has finished (a stream, or an answer whose headers go out as soon as the provider accepts the call), it says unchecked=pending: read zabio.guard.unchecked in the body. A stream on /v1/messages has no zabio object, so there pending cannot be resolved. A stream carries zabio.guard where it carries the zabio object: in the final chunk on chat completions and in the final response on the Responses API. A stream on /v1/messages carries the header only. A background response carries zabio.guard from the moment it is queued.
A blocked request answers in the endpoint’s own error envelope, with zabio.guard beside the error, so your code can show where the text was:
{ "error": {"type": "permission_error", "code": "prompt_injection_blocked", "message": "This request was blocked: the prompt-injection guard found text that tries to override the model's instructions. zabio.guard names where. If it is not an injection, add it to your organization's guard allowlist."}, "zabio": {"guard": {"action": "block", "detections": [...]}}}On /v1/messages the error is Anthropic’s, with zabio.code and zabio.guard (see Errors).
Trusted tools
Section titled “Trusted tools”A key can trust some of its tools by name, with guard_trusted_tools on POST or PATCH /admin/v1/orgs/{org}/keys, or in AI Firewall, Prompt Injection; owners and admins set them, as they set the key’s action. What the patterns find in those tools’ results is reported with trusted: true and is never redacted or blocked, whatever the key’s action. A result is matched to its tool through its call in the same request (chat’s tool_calls, the Responses API’s function_call, Anthropic’s tool_use); a result whose call is not in the request is not trusted. Trust a tool only when you control what it returns: an injection in a trusted tool’s result reaches your model.
The paid tier: a model check
Section titled “The paid tier: a model check”To check a text, an image or a PDF on its own, without a call to a model, use the AI Firewall check.
Besides the free patterns, an organization can turn on a model check. A model built to judge text reads each tool result together with the user’s request it answers, and your users’ new messages, and flags what looks like an injection. It finds injected tasks that use no known phrase, such as an email that asks the assistant to unlock a door or forward the inbox, which patterns miss. Like the patterns it is not a guarantee, and it does not block: a flagged call goes through unchanged and the answer reports it.
What it reads:
- Tool results, from the same sources as above, each with the user’s message that led to it (its first 2,000 characters).
- Your users’ new messages: those after the last assistant turn and the last tool result. Earlier messages were read when they were new.
- Text you marked as not yours in those new messages, read as a tool result (see Text you did not write).
- Images in tool results on
/v1/messages, and images you marked in your users’ new messages on any API, PNG or JPEG: the model looks at the image itself, beside the user’s request, and reads it as a tool result. An image larger than 1568 pixels on a side is scaled down first, and one smaller than 280 is padded with white. At most 8 images are read per request, the newest first; an image already read in the conversation is not read again for 24 hours and does not count. The others are unchecked withimage_limit, and so is an image over 12 megapixels. An image given by URL, a GIF or a WebP is not read: Zabio does not fetch your URLs during the check. In a tool result it is counted innot_read; marked, it is unchecked withunsupported. Text drawn a few shades from a flat background (white on white, a banner’s own colour) is made readable before the image is read; faint text over a photograph or a texture is often missed. A JPEG that carries an EXIF orientation is turned the way models turn it. - Documents on
/v1/messages, in a tool result or in your users’ new messages: the text of a PDFdocumentblock (each page’s text, hidden text included, and its title, subject, keywords and author) and a plain text document, read as a tool result. A document block’stitleandcontextare read too, each as a text of its own, also when the document is given by URL or file id. A scanned PDF, whose pages hold no text, is read by its pages’ images when they are stored as JPEG: each is read as an image is, the first 8 of a document, within the 8 images of the request, and billed as an image. Further pages are unchecked withimage_limit, and pages stored in another encoding withunsupported. A scan none of whose pages can be read is counted innot_readas a file. In a PDF whose pages hold text the images are not read, and text that is only drawn as shapes is not read either. A PDF that cannot be read (protected by a password, damaged, or too large) is unchecked witherror. Reading the PDFs of a request takes at most a quarter of a second; one not read by then is unchecked withtimeout.
System and developer messages, assistant turns, audio, video, your users’ own images and other files are not read by the model check (zabio.guard.not_read counts them), and neither are the results of your key’s trusted tools or a text your organization reported as not an injection. A tool result already checked in the conversation is not checked again for 24 hours, so an agent that sends its history on every turn has each result read once. A text longer than about 100,000 characters is read in overlapping parts, and is flagged when any part is.
The answer: a model detection has detector model and rule model.injection, and its start and end cover the whole string, or the part of a long text that was flagged. In an image, path names the image block and start and end are 0; in a document, path names the document block and start and end count in the text read from it; for a document’s title or context, path ends in .title or .context; for a scanned page, path names the document block and start and end are 0. zabio.guard.paid is true when the model check read the request. zabio.guard.unchecked lists what it could not read, each with reason: timeout, rate_limited, error, no_credit when your balance is at zero, image_limit for an image over the limits above, or unsupported for a marked image it cannot read or a scan’s pages stored in an encoding it does not read. Nothing unchecked is reported as clean. The free patterns read an unchecked text as always, also on a key whose guard action is off, and they read the text of an unchecked document whatever the action, as tags only; an unchecked image is read by neither.
Latency: the model check reads the request while your model answers it, so it adds nothing to a call that takes longer than it does. It waits at most 2 seconds; what is not read by then is unchecked. The header x-zabio-guard is sent before the answer and counts the patterns’ detections only; zabio.guard in the body has both.
Price: 0.50 USD per million tokens checked, its own line on your bill and usage page (“AI firewall”), also on calls that use your own vendor keys. Tokens checked are Zabio’s count of each text the model check read this time, and for an image the tokens the model counts for reading it with its request (about 3,000 for a 1280 by 800 screenshot): a text or an image already checked, allowed or trusted counts nothing. The model check needs a positive balance: at zero it stops, its items are unchecked with no_credit, and nothing is charged.
Turning it on: owners and admins turn it on in AI Firewall, Prompt Injection, or set {"paid": true} on PATCH /admin/v1/orgs/{org}/guard; they can also choose for one key with guard_paid (true, false, or null to follow the organization). An organization on the Free plan can turn it on, for itself or for a key, after its first top-up.
Text you did not write
Section titled “Text you did not write”Text from someone else that your application puts in front of the model, such as a forum post, an email, a web page or a document, is where an injection usually hides. Send it in a way that tells Zabio it is not your user’s own words:
- As a tool result, when your application fetched it through a tool call: chat’s
toolmessage, the Responses API’sfunction_call_output, Anthropic’stool_result. - Or mark it, when you paste it into a user message: put it in a text part of its own with
"zabio": {"untrusted": true}. A screenshot or a photo you did not take can be marked the same way on its image part: a chatimage_urlor a Responsesinput_imageholding a data URL, or a/v1/messagesimageblock with a base64 source.
Chat completions:
{"model": "auto", "messages": [{"role": "user", "content": [ {"type": "text", "text": "Write a polite reply to this forum post."}, {"type": "text", "text": "<the post>", "zabio": {"untrusted": true}}]}]}The Responses API, with input_text parts:
{"model": "auto", "input": [{"role": "user", "content": [ {"type": "input_text", "text": "Summarize this email."}, {"type": "input_text", "text": "<the email>", "zabio": {"untrusted": true}}]}]}/v1/messages, with text blocks:
{"model": "claude-sonnet-5", "max_tokens": 1024, "messages": [{"role": "user", "content": [ {"type": "text", "text": "Summarize this page."}, {"type": "text", "text": "<the page>", "zabio": {"untrusted": true}}]}]}With the OpenAI Python SDK the part is a plain dictionary and is sent as written:
client.chat.completions.create(model="auto", messages=[{"role": "user", "content": [ {"type": "text", "text": "Write a polite reply to this forum post."}, {"type": "text", "text": post, "zabio": {"untrusted": True}},]}])The official OpenAI SDKs for Python and Node and Anthropic’s Python SDK send the key unchanged. In TypeScript the SDK’s types do not name it, so the part needs a cast.
What the mark changes:
- The model check reads a marked part as it reads a tool result, with your user’s own words in the same message, or else the user’s words before it, beside it as the request it answers. A tool result is read against a stricter bar than a user’s own message, and a marked part is read against that bar. A marked part is read while its message is new, as the user’s own words are.
- The patterns read it with the rules for tool results (see What is checked). Under
redactorblocka marked part can be redacted or refused where the same text in your user’s own words would pass. - The answer reports a detection in a marked part with
sourceuseranduntrusted: true. - Nothing else. The model receives the text as an ordinary text part, without the mark, and the price is the same as for any text the model check reads.
The mark is read only on a text or image part of a user message. On any other part, message or block (an assistant or system message, a tool result, a document, audio), or in any shape other than an object with untrusted set to true or false, the request is refused with 400 invalid_value rather than served with the mark ignored. Where the guard does not read the request at all (a key whose guard action is off without the paid tier, batch lines, items added to a conversation directly), a mark in the right place is accepted and changes nothing. A message whose content is a single string cannot carry the mark: send it as parts.
When it is not an injection
Section titled “When it is not an injection”A detection your organization knows is harmless can be allowed. An allowlist entry names the rule and a hash of the detected text, never the text, and applies to the whole organization: the same phrase is then neither reported, redacted nor blocked on any of its keys, also when it is written with the disguises above. An entry can carry a note of up to 200 characters, for your team. Owners and admins add an entry from a guard event, or by typing the text before any call is flagged, through the dashboard API:
| Method, path | What |
|---|---|
GET /admin/v1/orgs/{org}/guard |
the organization’s guard settings and its allowlist |
GET /admin/v1/orgs/{org}/guard/events |
the requests with a detection, newest first, kept 90 days |
POST /admin/v1/orgs/{org}/guard/allowlist |
{"event_id": "...", "detection_index": 0} adds that detection to the allowlist |
POST /admin/v1/orgs/{org}/guard/allowlist/text |
{"text": "...", "rule": "all", "note": "Our test prompts"} allows a text you type: rule is one rule or all. The patterns read the text and one entry is added per match, each the rule and a hash; the text is not kept. If the patterns find nothing in it, nothing is added and the answer is 400 guard_text_not_flagged |
DELETE /admin/v1/orgs/{org}/guard/allowlist/{id} |
removes an entry |
POST /admin/v1/orgs/{org}/guard/reports |
{"event_id": "...", "detection_index": 0, "kind": "not_injection"} reports a false alarm and allows that exact text at once; "kind": "confirmed" reports a real attack and changes nothing. Add "text" to share the flagged text: only that exact text is accepted, kept encrypted for 90 days to improve the guard |
The same reports are on Usage, Logs: open a call the guard flagged (the Guard filter shows only those) and choose Not an injection or Confirm attack. AI Firewall, Prompt Injection lists the allowed texts, with a button to remove each, and Add text to allow one by typing or pasting it, such as your own test prompts or a product’s fixed instructions. A typed text covers the patterns only: the model check’s findings are allowed from the flagged call. Allowing a text needs a web session of an owner or admin; a user token, an API key and an MCP app cannot do it, so an agent can never allow a text. A report sent through the MCP feedback tool (its injection field) is recorded and changes nothing until an owner or admin allows it in AI Firewall, Prompt Injection, since an agent that read the text may be the one asking. A report affects your organization only.
What Zabio keeps
Section titled “What Zabio keeps”The patterns run in memory on Zabio’s servers; no text is sent anywhere to be checked by them. When your organization turns on the paid tier, the text and images the model check reads are sent for security screening to the sub-processor named on the Privacy page; Zabio keeps none of them, only a hash of each screened text or image and its result for 24 hours. For a request with a detection Zabio keeps the metadata above (where, which rule, the action, the key and the call) and a hash of each detected span, for 90 days. The text itself is never stored or logged by the guard. See Privacy.
IP allow and deny lists
Section titled “IP allow and deny lists”You can limit which addresses may call the API with your keys. An organization, a project and a key each have two lists: addresses that are allowed and addresses that are denied. The lists are free, on every plan, and take IPv4 and IPv6.
For a call with a key, the rule is:
- If the address is in a deny list of the organization, of the key’s project or of the key, the call is refused.
- If any of the three has an allow list that is not empty and the address is not in it, the call is refused.
- Otherwise the call goes through.
So a deny list always wins, and each level can only narrow the one above it: a project cannot allow an address its organization refuses, and a key cannot allow one its project or its organization refuses. An empty allow list adds nothing of its own, so the level above decides. With no list at any level, any address may call.
A refused call gets 403 with the code ip_not_allowed. Nothing reaches a model and nothing is billed. See Errors.
| Entry | Means |
|---|---|
203.0.113.7 |
one IPv4 address |
203.0.113.0/24 |
an IPv4 block, in CIDR notation |
2001:db8::1 |
one IPv6 address |
2001:db8::/32 |
an IPv6 block |
What to know before you set a list:
- List both address families. If your servers can reach Zabio over IPv4 and over IPv6, list both. An allow list with only IPv4 entries refuses a call that arrives over IPv6.
- A list holds up to 100 entries. Use a wider block when you need more addresses.
- A block is written at its start.
203.0.113.7/24is refused with a message that names what to write:203.0.113.0/24for the block, or203.0.113.7for the one address. - A change applies at the next call, and within a minute at the latest.
- The lists limit API calls with a key, on every
/v1endpoint. They do not limit signing in to the web app or the dashboard API, so a list that locks your servers out can always be corrected. - Work already accepted finishes. The lists are checked when a request arrives. A background response, a batch or a generation job that was accepted before a list changed runs to its end.
- Apps connected through MCP. The
asktool of Zabio’s MCP server spends with a key of its project, so the same lists apply to it, on the address the app calls from. An app that runs on its vendor’s servers, such as Claude.ai or ChatGPT, calls from its vendor’s addresses: an allow list refuses its asks unless it holds those addresses. The MCP tools that only read are not limited.
Owners and admins of the organization set the lists at the three levels in the web app, under AI Firewall, Network Access, or through the dashboard API in a web session. Every member can read the lists that apply to the keys they see. Through the dashboard API:
| Method, path | What |
|---|---|
GET /admin/v1/orgs/{org}/ip-lists |
the organization’s lists |
PUT /admin/v1/orgs/{org}/ip-lists |
{"allow": ["203.0.113.0/24"], "deny": []} replaces both lists; an empty list clears it |
GET, PUT /admin/v1/orgs/{org}/projects/{project}/ip-lists |
the same for a project, with the organization’s lists shown as inherited |
GET, PUT /admin/v1/orgs/{org}/keys/{key}/ip-lists |
the same for a key, with the lists of its organization and its project shown as inherited |
Each answer also shows your_address, the address your browser is calling from, and whether a call from it would pass. Two changes are asked about before they are saved: a deny list that holds every address (0.0.0.0/0 or ::/0), and a change after which your own current address would be refused. The save answers 409 ip_list_confirm_required and names the reason; send it again with "confirm": true to save it. Your browser’s address is a hint only: your servers may call from other addresses.
Every change is written to the organization’s audit log with who made it and how many entries each list had before and after. The addresses themselves are not written to the audit log.