AI Firewall
El AI Firewall es lo que está entre una petición y tus modelos. Tiene dos partes: la protección contra prompt injection, que lee lo que trae una petición y se describe primero, y las listas de direcciones IP permitidas y denegadas, que deciden desde dónde puede llegar una llamada con tus keys.
Un prompt injection es un texto que intenta dar nuevas órdenes a tu modelo: “ignore all previous instructions”, “reveal your system prompt”, una línea falsa <|im_start|>system escondida en una página web que tu agente leyó. Zabio revisa cada petición en busca de estos patrones antes de que llegue a un modelo. La revisión es gratuita, corre en los servidores de Zabio y está activa en todas las API keys.
No es una garantía. Los patrones detectan las frases comunes y conocidas y sus disfraces habituales. No detectan lo que no nombran, una frase nueva ni un ataque en otro idioma. La detección está medida en inglés; las frases de anulación, extracción, cambio de personaje y evasión también se revisan en español, portugués, francés, alemán, italiano, ruso y chino. Usa la protección como una capa más y mantén las tuyas: da a los agentes los permisos mínimos que necesitan y haz que una persona confirme las acciones irreversibles.
Qué se revisa
Section titled “Qué se revisa”La protección lee tres tipos de texto de la petición, en POST /v1/chat/completions, POST /v1/responses y POST /v1/messages:
source |
Qué |
|---|---|
user |
los mensajes del usuario |
tool |
los resultados de herramientas: los mensajes tool de chat, los elementos function_call_output de la API Responses, los bloques tool_result de Anthropic. Es por donde suele llegar un injection escondido en una página, un archivo o un correo |
assistant |
los turnos del asistente que tu cliente reenvía en el historial, porque uno falsificado también puede traer órdenes |
Una parte de texto de un mensaje del usuario que marcas como texto que no escribiste se lee como un resultado de herramienta (consulta Texto que no escribiste). Los mensajes de sistema y de desarrollador y instructions no se revisan: son tus propias palabras. Los patrones leen solo texto. La revisión con un modelo del nivel de pago lee además las imágenes de los resultados de herramientas, las imágenes que marcas y el texto de los documentos PDF y de texto plano (consulta El nivel de pago); el audio y el video no se leen. La respuesta cuenta lo que no se leyó (zabio.guard.not_read). En la API Responses solo se revisa el input nuevo del turno: los turnos anteriores se revisaron cuando se enviaron. En la API Responses, un resultado de herramienta enviado como objeto o lista JSON se lee como su texto JSON, el texto que recibe el modelo. Los elementos que agregas a una conversación directamente (items en POST /v1/conversations, o POST /v1/conversations/{id}/items) no se revisan. POST /v1/messages/count_tokens no se revisa, porque no llama a ningún modelo. Los batches todavía no se revisan.
Antes de aplicar los patrones, el texto se normaliza para que los disfraces habituales vuelvan a las mismas palabras: los caracteres invisibles (de ancho cero y los caracteres de etiqueta de Unicode) se quitan o se decodifican, las letras parecidas de otros alfabetos y las letras de ancho completo o con estilo se convierten en letras normales, las letras separadas por espacios (i g n o r e) y las palabras clave partidas con espacios (ign ore prev ious) se unen, y una palabra clave mal escrita o desordenada (ignroe, instrcutions) se lee como la palabra. El texto codificado también se decodifica y se revisa: Base64, hexadecimal (también con espacios, dos puntos, \x o 0x entre los bytes), codificación por porcentaje (%69), referencias de caracteres de HTML (i), escapes \u, códigos de caracteres en decimal, octetos en binario, ROT13 y texto escrito al revés, y una codificación dentro de otra (Base64 de hexadecimal), hasta dos niveles.
Las reglas:
rule |
Busca |
|---|---|
override.instructions |
una orden de ignorar, olvidar o reemplazar las instrucciones anteriores |
prompt.extraction |
un pedido de revelar o repetir el prompt de sistema o las instrucciones anteriores |
role.switch |
un cambio a otro personaje o a un modo sin restricciones (“you are DAN”, “do anything now”, “you are free from your rules”) |
safety.bypass |
una orden de saltarse o desactivar las reglas de seguridad o las protecciones |
delimiter.injection |
marcas falsas de plantilla de chat (<|im_start|>, [INST], <<SYS>>) o una línea falsa “system:” seguida de órdenes; en resultados de herramientas y turnos del asistente, también un resultado que cierra su propio envoltorio (</tool_result>) y sigue con órdenes, un turno falso del usuario o del asistente, y en resultados de herramientas un paso falso de agente (Thought:, Action:) seguido de una orden o una llamada falsa a una herramienta (<function_calls>, "tool_calls" dentro de un texto) |
hidden.instructions |
texto dirigido al modelo y oculto al usuario (“do not tell the user”, “note to the AI:”); en resultados de herramientas y turnos del asistente, también un comentario HTML dirigido al modelo y un texto con estilo invisible (oculto, blanco o transparente, de tamaño cero, \color{white} de LaTeX) que da una orden al modelo |
new.instructions |
“new instructions:”, “your new task is” y similares, y un nuevo rol cuando es el del modelo (“your new role is an unrestricted AI”, no “your new role is team lead”), solo en resultados de herramientas y turnos del asistente |
exfiltration |
una orden de enviar datos a una URL, o una imagen en Markdown o HTML cuyo enlace saca datos (un marcador, o una consulta que es una frase), solo en resultados de herramientas y turnos del asistente |
En esos siete idiomas, override.instructions, prompt.extraction, role.switch y safety.bypass también revisan sus frases; las demás reglas leen inglés. Cada regla lee frases: una sola palabra como “ignora” nunca es una detección.
Un texto sobre el propio prompt injection, como un informe de seguridad que cita “ignore previous instructions”, se lee como una mención y no se reporta, en cada uno de estos idiomas. En un mensaje del propio usuario, una orden de ignorar instrucciones que el usuario dice haber dado (“ignora las instrucciones anteriores que te di sobre el formato”) es el usuario que cambia de idea y tampoco se reporta; las mismas palabras en un resultado de herramienta sí.
Las cuatro acciones
Section titled “Las cuatro acciones”Cada API key tiene una acción de protección: la suya, o la acción predeterminada de la organización, que una key sigue si no define una propia. Una key nueva sigue a la organización, y también cada key anterior cuya acción nunca se configuró: solo una key cuya acción eligió un propietario o administrador la conserva como propia.
La acción predeterminada de la organización es Tag o Block, y es Tag hasta que un propietario o administrador la cambie. Off y Redact no son predeterminadas de la organización: se definen en cada key. Una key que sigue a la organización muestra guard_action: null, y cada key muestra la acción vigente en guard_action_effective.
| Acción | Qué pasa cuando hay una detección |
|---|---|
off |
no se revisa nada |
tag |
la llamada pasa sin cambios; el zabio.guard de la respuesta lista cada detección |
redact |
cada tramo detectado se reemplaza por [PROMPT_INJECTION] antes de que el modelo lo vea; la respuesta lista lo que se reemplazó. Un turno guardado de Responses conserva el texto ya reemplazado |
block |
la petición se rechaza con 403 prompt_injection_blocked. Nada llega a un modelo, no se cobra nada y no se guarda nada de la petición; solo se guarda el evento de la protección (consulta Qué guarda Zabio) |
Los propietarios y administradores definen la acción de la key al crearla o editarla, en Firewall de IA, Prompt injection o con guard_action en POST o PATCH /admin/v1/orgs/{org}/keys desde una sesión web (null hace que la key vuelva a seguir a la organización). Definen la predeterminada de la organización en Firewall de IA, Prompt injection, Acción predeterminada ante una coincidencia, o con {"action": "block"} en PATCH /admin/v1/orgs/{org}/guard; se aplica a cada key que la sigue desde su siguiente petición. Un miembro, o un token de usuario, no puede cambiar los ajustes de guard de una key ni de la organización.
Prueba tag antes de block. A veces los patrones también coinciden con texto normal: una frase que por casualidad suena a orden, o una cita de un artículo sobre injections. Con tag esa llamada pasa y solo el reporte es erróneo; con block se rechaza. Usa primero una key en tag, revisa las detecciones de su tráfico real, agrega las inofensivas a la lista de permitidos y cambia a block cuando lo que quede sea lo que quieres detener.
Una petición puede pedir una acción más estricta que la de su key, en el cuerpo o como cabecera, que tiene prioridad sobre el cuerpo:
{"model": "auto", "messages": [...], "zabio": {"guard": {"action": "block"}}}x-zabio-guard: blockUna petición solo puede endurecer la acción de la key, nunca suavizarla, así que el texto que lee tu agente no puede apagar la protección. Un pedido más débil se ignora y aparece en zabio.ignored_parameters como zabio.guard.action; la llamada no se rechaza por eso. Un valor distinto de los cuatro nombres es un 400 invalid_value.
La respuesta
Section titled “La respuesta”Toda respuesta que la protección revisó trae zabio.guard. Las detecciones dicen dónde estaba el texto y qué regla coincidió, nunca el texto:
"zabio": { "guard": { "action": "tag", "detections": [ {"message_index": 2, "path": "messages[2].content", "source": "tool", "rule": "override.instructions", "start": 41, "end": 74} ] }}| Campo | Significado |
|---|---|
action |
la acción aplicada: la de la key, o la más estricta que pidió la petición |
detections |
una entrada por coincidencia; una lista vacía cuando no se encontró nada |
detections[].message_index |
el índice en tu propio arreglo messages o input |
detections[].path |
la ruta JSON del texto en el cuerpo de tu petición |
detections[].source |
user, tool o assistant |
detections[].rule |
la regla que coincidió |
detections[].start, end |
las posiciones del tramo en ese texto, en caracteres Unicode, sin incluir end |
detections[].encoding |
cómo estaba codificado el tramo, cuando lo estaba: base64, hex, percent, html, unicode, decimal, binary, rot13 o reversed, la exterior primero para una codificación dentro de otra (base64+hex). En un tramo codificado las posiciones son las del tramo entero; en ROT13 y en texto al revés, las de la frase |
truncated |
true cuando parte de la petición no se revisó: era más grande de lo que la protección lee (256 KB por texto, 1 MB por petición), tenía más de 64 detecciones, o su texto estaba construido para ser costoso de leer y los patrones de caracteres se detuvieron antes |
detections[].detector |
pattern para los patrones gratuitos; model solo cuando el nivel de pago de la protección leyó la petición, para un texto que su revisión con un modelo señaló |
detections[].trusted |
true para una detección en un resultado de una herramienta en la que la key confía: se informa y nunca se oculta ni se bloquea (consulta Herramientas de confianza) |
detections[].untrusted |
true para una detección en una parte de texto del usuario que marcaste como texto que no escribiste; source es user (consulta Texto que no escribiste) |
paid |
presente solo cuando el nivel de pago leyó la petición, como true |
unchecked |
presente solo cuando el nivel de pago leyó la petición y no pudo leer un texto, una imagen o un documento: cada uno con message_index, path, source y reason (timeout, rate_limited, error, no_credit, image_limit o unsupported), y untrusted para una parte marcada; los patrones gratuitos leen ese texto, y el texto de un documento, como siempre; una imagen no la leen. Un texto largo que la revisión con un modelo señaló mientras una de sus partes no se pudo leer está en detections y también aquí, con partial: true y windows_unread, el número de partes sin leer |
not_read |
presente cuando la petición trae algo que la protección no leyó, como cuentas, nunca texto: images, audio, video, files (un archivo, un documento o cualquier otra parte que no es texto) y system (mensajes de sistema y de desarrollador, instructions) no los leen ni los patrones ni la revisión con un modelo (una imagen o un documento que la revisión con un modelo leyó, o que informa en unchecked, no se cuenta aquí); cuando la revisión con un modelo corrió, también earlier_messages (mensajes del usuario anteriores al turno actual), assistant_turns y trusted_results (resultados de las herramientas de confianza de la key), que los patrones leen y la revisión con un modelo no. Una cuenta en cero no aparece |
Si no hay zabio.guard, la protección no corrió: la acción es off. La cabecera x-zabio-guard repite la acción y el número de detecciones (tag; detections=1) en cada respuesta revisada, también en streaming. La cabecera x-zabio-guard-unread repite not_read en cada respuesta revisada (images=1; system=1, o none), y cuando la revisión con un modelo corrió termina con unchecked= y el número de textos que no pudo leer. Cuando las cabeceras se envían antes de que la revisión con un modelo termine (un stream, o una respuesta cuyas cabeceras salen en cuanto el proveedor acepta la llamada), dice unchecked=pending: lee zabio.guard.unchecked en el cuerpo. Un stream en /v1/messages no tiene objeto zabio, así que ahí pending no se puede resolver. Un stream trae zabio.guard donde trae el objeto zabio: en el último chunk en chat completions y en la respuesta final en la API Responses. Un stream en /v1/messages trae solo la cabecera. Una respuesta en segundo plano trae zabio.guard desde que entra en la cola.
Una petición bloqueada responde con el formato de error de su endpoint, con zabio.guard junto al error, para que tu código pueda mostrar dónde estaba el texto:
{ "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": [...]}}}En /v1/messages el error es el de Anthropic, con zabio.code y zabio.guard (consulta Errores).
Herramientas de confianza
Section titled “Herramientas de confianza”Una key puede confiar en algunas de sus herramientas por nombre, con guard_trusted_tools en POST o PATCH /admin/v1/orgs/{org}/keys, o en Firewall de IA, Prompt injection; las definen los propietarios y administradores, igual que la acción de la key. Lo que los patrones encuentran en los resultados de esas herramientas se informa con trusted: true y nunca se oculta ni se bloquea, sea cual sea la acción de la key. Un resultado se asocia con su herramienta a través de su llamada en la misma petición (los tool_calls de chat, la function_call de la API de Responses, el tool_use de Anthropic); un resultado cuya llamada no está en la petición no es de confianza. Confía en una herramienta solo cuando controlas lo que devuelve: un injection en el resultado de una herramienta de confianza llega a tu modelo.
El nivel de pago: una revisión con un modelo
Section titled “El nivel de pago: una revisión con un modelo”Para revisar un texto, una imagen o un PDF por separado, sin llamar a un modelo, usa la revisión del AI Firewall.
Además de los patrones gratuitos, una organización puede activar una revisión con un modelo. Un modelo creado para juzgar textos lee cada resultado de herramienta junto con la petición del usuario a la que responde, y los mensajes nuevos de tus usuarios, y señala lo que parece un injection. Encuentra tareas inyectadas que no usan ninguna frase conocida, como un correo que le pide al asistente abrir una puerta o reenviar la bandeja de entrada, que los patrones no ven. Como los patrones, no es una garantía, y no bloquea: una llamada señalada pasa sin cambios y la respuesta lo informa.
Qué lee:
- Los resultados de herramientas, de las mismas fuentes de arriba, cada uno con el mensaje del usuario que lo originó (sus primeros 2.000 caracteres).
- Los mensajes nuevos de tus usuarios: los que siguen al último turno del asistente y al último resultado de herramienta. Los anteriores se leyeron cuando eran nuevos.
- El texto que marcaste como ajeno en esos mensajes nuevos, leído como un resultado de herramienta (consulta Texto que no escribiste).
- Las imágenes de los resultados de herramientas en
/v1/messages, y las imágenes que marcaste en los mensajes nuevos de tus usuarios en cualquier API, en PNG o JPEG: el modelo mira la imagen misma, junto al pedido del usuario, y la lee como un resultado de herramienta. Una imagen de más de 1568 píxeles por lado se reduce antes, y una de menos de 280 se completa con blanco. Se leen como máximo 8 imágenes por petición, las más nuevas primero; una imagen ya leída en la conversación no se vuelve a leer durante 24 horas y no cuenta. Las demás quedan sin revisar conimage_limit, igual que una imagen de más de 12 megapíxeles. Una imagen dada por URL, un GIF o un WebP no se lee: Zabio no descarga tus URL durante la revisión. En un resultado de herramienta se cuenta ennot_read; marcada, queda sin revisar conunsupported. El texto dibujado a pocos tonos de un fondo liso (blanco sobre blanco, el color de una banda) se hace legible antes de leer la imagen; el texto tenue sobre una fotografía o una textura a menudo se pasa por alto. Un JPEG que lleva una orientación EXIF se gira como lo giran los modelos. - Los documentos en
/v1/messages, en un resultado de herramienta o en los mensajes nuevos de tus usuarios: el texto de un bloquedocumentPDF (el texto de cada página, también el oculto, y su título, asunto, palabras clave y autor) y un documento de texto plano, leídos como un resultado de herramienta. También se leen eltitley elcontextde un bloque de documento, cada uno como un texto propio, incluso cuando el documento se da por URL o por id de archivo. Un PDF escaneado, cuyas páginas no tienen texto, se lee por las imágenes de sus páginas cuando están guardadas como JPEG: cada una se lee como una imagen, las 8 primeras de un documento, dentro de las 8 imágenes de la petición, y se cobra como una imagen. Las páginas siguientes quedan sin revisar conimage_limit, y las páginas guardadas en otra codificación conunsupported. Un escaneo del que no se puede leer ninguna página se cuenta ennot_readcomo un archivo. En un PDF cuyas páginas tienen texto las imágenes no se leen, y tampoco el texto que solo está dibujado como formas. Un PDF que no se puede leer (protegido con contraseña, dañado o demasiado grande) queda sin revisar conerror. Leer los PDF de una petición toma como máximo un cuarto de segundo; uno que no se leyó para entonces queda sin revisar contimeout.
La revisión con un modelo no lee los mensajes de sistema ni de desarrollador, los turnos del asistente, el audio, el video, las imágenes propias de tus usuarios ni otros archivos (zabio.guard.not_read los cuenta), ni tampoco los resultados de las herramientas de confianza de tu key ni un texto que tu organización reportó como no injection. Un resultado de herramienta ya revisado en la conversación no se vuelve a revisar durante 24 horas, así que un agente que envía su historial en cada turno tiene cada resultado leído una sola vez. Un texto de más de unos 100.000 caracteres se lee en partes que se solapan, y se señala cuando cualquiera de ellas lo es.
La respuesta: una detección del modelo tiene detector model y rule model.injection, y su start y end cubren el texto entero, o la parte de un texto largo que se señaló. En una imagen, path nombra el bloque de la imagen y start y end son 0; en un documento, path nombra el bloque del documento y start y end cuentan en el texto que se leyó de él; para el title o el context de un documento, path termina en .title o .context; para una página escaneada, path nombra el bloque del documento y start y end son 0. zabio.guard.paid es true cuando la revisión con un modelo leyó la petición. zabio.guard.unchecked lista lo que no pudo leer, cada uno con reason: timeout, rate_limited, error, no_credit cuando tu saldo está en cero, image_limit para una imagen fuera de los límites de arriba, o unsupported para una imagen marcada que no puede leer o para las páginas de un escaneo guardadas en una codificación que no lee. Nada sin revisar se informa como limpio. Los patrones gratuitos leen un texto sin revisar como siempre, también en una key cuya acción es off, y leen el texto de un documento sin revisar con cualquier acción, solo para etiquetarlo; una imagen sin revisar no la lee ninguno.
Latencia: la revisión con un modelo lee la petición mientras tu modelo la responde, así que no suma nada a una llamada que tarda más que ella. Espera como mucho 2 segundos; lo que no se leyó para entonces queda sin revisar. La cabecera x-zabio-guard se envía antes de la respuesta y cuenta solo las detecciones de los patrones; zabio.guard en el cuerpo trae ambas.
Precio: 0,50 USD por millón de tokens revisados, en su propia línea de tu factura y de la página de uso (“Firewall de IA”), también en las llamadas que usan tus propias keys de proveedores. Los tokens revisados son la cuenta de Zabio de cada texto que la revisión con un modelo leyó esta vez, y para una imagen los tokens que el modelo cuenta al leerla con su pedido (unos 3.000 para una captura de 1280 por 800): un texto o una imagen ya revisados, permitidos o de confianza no cuentan nada. La revisión con un modelo necesita saldo positivo: en cero se detiene, sus elementos quedan sin revisar con no_credit y no se cobra nada.
Cómo activarlo: los propietarios y administradores lo activan en Firewall de IA, Prompt injection, o envían {"paid": true} en PATCH /admin/v1/orgs/{org}/guard; también pueden elegir para una sola key con guard_paid (true, false, o null para seguir a la organización). Una organización en el plan gratuito puede activarlo, para sí misma o para una key, después de su primera recarga.
Texto que no escribiste
Section titled “Texto que no escribiste”El texto de otra persona que tu aplicación pone delante del modelo, como una publicación de un foro, un correo, una página web o un documento, es donde suele esconderse un injection. Envíalo de una forma que le diga a Zabio que no son palabras de tu usuario:
- Como resultado de herramienta, cuando tu aplicación lo obtuvo con una llamada a una herramienta: el mensaje
toolde chat, elfunction_call_outputde la API Responses, eltool_resultde Anthropic. - O márcalo, cuando lo pegas en un mensaje del usuario: ponlo en una parte de texto propia con
"zabio": {"untrusted": true}. Una captura o una foto que no tomaste se marca igual en su parte de imagen: unimage_urlde chat o uninput_imagede Responses con una data URL, o un bloqueimagede/v1/messagescon una fuente base64.
Chat completions:
{"model": "auto", "messages": [{"role": "user", "content": [ {"type": "text", "text": "Escribe una respuesta amable a esta publicación del foro."}, {"type": "text", "text": "<la publicación>", "zabio": {"untrusted": true}}]}]}La API Responses, con partes input_text:
{"model": "auto", "input": [{"role": "user", "content": [ {"type": "input_text", "text": "Resume este correo."}, {"type": "input_text", "text": "<el correo>", "zabio": {"untrusted": true}}]}]}/v1/messages, con bloques text:
{"model": "claude-sonnet-5", "max_tokens": 1024, "messages": [{"role": "user", "content": [ {"type": "text", "text": "Resume esta página."}, {"type": "text", "text": "<la página>", "zabio": {"untrusted": true}}]}]}Con el SDK de OpenAI para Python la parte es un diccionario normal y se envía tal como está escrita:
client.chat.completions.create(model="auto", messages=[{"role": "user", "content": [ {"type": "text", "text": "Escribe una respuesta amable a esta publicación del foro."}, {"type": "text", "text": post, "zabio": {"untrusted": True}},]}])Los SDK oficiales de OpenAI para Python y Node y el SDK de Anthropic para Python envían la clave sin cambios. En TypeScript los tipos del SDK no la nombran, así que la parte necesita un cast.
Qué cambia la marca:
- La revisión con un modelo lee una parte marcada como lee un resultado de herramienta, con las propias palabras de tu usuario en el mismo mensaje, o si no las palabras del usuario anteriores a ella, a su lado como la petición a la que responde. Un resultado de herramienta se lee con un criterio más estricto que un mensaje del propio usuario, y una parte marcada se lee con ese criterio. Una parte marcada se lee mientras su mensaje es nuevo, como las palabras del propio usuario.
- Los patrones la leen con las reglas de los resultados de herramientas (consulta Qué se revisa). Con
redactoblock, una parte marcada puede ocultarse o rechazarse donde el mismo texto en palabras de tu usuario pasaría. - La respuesta informa una detección en una parte marcada con
sourceuseryuntrusted: true. - Nada más. El modelo recibe el texto como una parte de texto normal, sin la marca, y el precio es el mismo que el de cualquier texto que lee la revisión con un modelo.
La marca solo se lee en una parte de texto o de imagen de un mensaje del usuario. En cualquier otra parte, mensaje o bloque (un mensaje del asistente o de sistema, un resultado de herramienta, un documento, audio), o con cualquier forma que no sea un objeto con untrusted en true o false, la petición se rechaza con 400 invalid_value en lugar de atenderse sin la marca. Donde la protección no lee la petición (una key cuya acción es off sin el nivel de pago, las líneas de un batch, los elementos que agregas a una conversación directamente), una marca en el lugar correcto se acepta y no cambia nada. Un mensaje cuyo contenido es un solo string no puede llevar la marca: envíalo como partes.
Cuando no es un injection
Section titled “Cuando no es un injection”Una detección que tu organización sabe que es inofensiva se puede permitir. Una entrada de la lista de permitidos guarda la regla y un hash del texto detectado, nunca el texto, y vale para toda la organización: la misma frase ya no se reporta, no se reemplaza ni se bloquea en ninguna de sus keys, aunque venga escrita con los disfraces de arriba. Una entrada puede llevar una nota de hasta 200 caracteres, para tu equipo. Los propietarios y administradores agregan una entrada desde un evento de la protección, o escribiendo el texto antes de que se señale ninguna llamada, con la API del panel:
| Método, ruta | Qué |
|---|---|
GET /admin/v1/orgs/{org}/guard |
la configuración de la protección de la organización y su lista de permitidos |
GET /admin/v1/orgs/{org}/guard/events |
las peticiones con una detección, de la más reciente a la más antigua, guardadas 90 días |
POST /admin/v1/orgs/{org}/guard/allowlist |
{"event_id": "...", "detection_index": 0} agrega esa detección a la lista de permitidos |
POST /admin/v1/orgs/{org}/guard/allowlist/text |
{"text": "...", "rule": "all", "note": "Nuestros prompts de prueba"} permite un texto que escribes: rule es una regla o all. Los patrones leen el texto y se agrega una entrada por cada coincidencia, cada una con la regla y un hash; el texto no se guarda. Si los patrones no encuentran nada en él, no se agrega nada y la respuesta es 400 guard_text_not_flagged |
DELETE /admin/v1/orgs/{org}/guard/allowlist/{id} |
quita una entrada |
POST /admin/v1/orgs/{org}/guard/reports |
{"event_id": "...", "detection_index": 0, "kind": "not_injection"} reporta una falsa alarma y permite ese texto exacto al momento; "kind": "confirmed" reporta un ataque real y no cambia nada. Agrega "text" para compartir el texto señalado: solo se acepta ese texto exacto, guardado cifrado durante 90 días para mejorar la protección |
Los mismos reportes están en Uso, Registros: abre una llamada que la protección señaló (el filtro Protección muestra solo esas) y elige No es una inyección o Confirmar ataque. Firewall de IA, Prompt injection lista los textos permitidos, con un botón para quitar cada uno, y Añadir texto para permitir uno escribiéndolo o pegándolo, como tus propios prompts de prueba o las instrucciones fijas de un producto. Un texto escrito cubre solo los patrones: los hallazgos de la revisión con un modelo se permiten desde la llamada señalada. Permitir un texto requiere una sesión web de un propietario o administrador; un token de usuario, una API key o una app MCP no pueden hacerlo, así que un agente nunca puede permitir un texto. Un reporte enviado con la herramienta MCP feedback (su campo injection) se registra y no cambia nada hasta que un propietario o administrador lo permita en Firewall de IA, Prompt injection, porque el agente que leyó el texto puede ser quien lo pide. Un reporte solo afecta a tu organización.
Qué guarda Zabio
Section titled “Qué guarda Zabio”Los patrones corren en memoria en los servidores de Zabio; ellos no envían ningún texto a otro lugar para revisarlo. Cuando tu organización activa el nivel de pago, el texto y las imágenes que lee la revisión con un modelo se envían para una revisión de seguridad al subencargado que nombra la página de Privacidad; Zabio no guarda nada de ellos, solo un hash de cada texto o imagen revisados y su resultado durante 24 horas. De una petición con una detección, Zabio guarda los metadatos de arriba (dónde, qué regla, la acción, la key y la llamada) y un hash de cada tramo detectado, durante 90 días. La protección nunca guarda ni registra el texto. Consulta Privacidad.
Listas de direcciones IP permitidas y denegadas
Section titled “Listas de direcciones IP permitidas y denegadas”Puedes limitar desde qué direcciones se puede llamar a la API con tus keys. Una organización, un proyecto y una key tienen cada uno dos listas: las direcciones permitidas y las direcciones denegadas. Las listas son gratuitas, están en todos los planes y aceptan IPv4 e IPv6.
Para una llamada con una key, la regla es:
- Si la dirección está en una lista de denegadas de la organización, del proyecto de la key o de la key, la llamada se rechaza.
- Si alguno de los tres tiene una lista de permitidas que no está vacía y la dirección no está en ella, la llamada se rechaza.
- En cualquier otro caso la llamada pasa.
Así, una lista de denegadas siempre gana, y cada nivel solo puede restringir al de arriba: un proyecto no puede permitir una dirección que su organización rechaza, y una key no puede permitir una que su proyecto o su organización rechazan. Una lista de permitidas vacía no agrega nada propio, así que decide el nivel de arriba. Sin listas en ningún nivel, cualquier dirección puede llamar.
Una llamada rechazada recibe 403 con el código ip_not_allowed. Nada llega a un modelo y no se cobra nada. Consulta Errores.
| Entrada | Significa |
|---|---|
203.0.113.7 |
una dirección IPv4 |
203.0.113.0/24 |
un bloque IPv4, en notación CIDR |
2001:db8::1 |
una dirección IPv6 |
2001:db8::/32 |
un bloque IPv6 |
Lo que conviene saber antes de definir una lista:
- Incluye las dos familias de direcciones. Si tus servidores pueden llegar a Zabio por IPv4 y por IPv6, incluye las dos. Una lista de permitidas con solo entradas IPv4 rechaza una llamada que llega por IPv6.
- Una lista admite hasta 100 entradas. Usa un bloque más amplio cuando necesites más direcciones.
- Un bloque se escribe desde su inicio.
203.0.113.7/24se rechaza con un mensaje que dice qué escribir:203.0.113.0/24para el bloque, o203.0.113.7para esa sola dirección. - Un cambio se aplica en la siguiente llamada, y como máximo en un minuto.
- Las listas limitan las llamadas a la API con una key, en todos los endpoints
/v1. No limitan el inicio de sesión en la aplicación web ni la API del panel, así que una lista que deja fuera a tus servidores siempre se puede corregir. - El trabajo ya aceptado termina. Las listas se revisan cuando llega una petición. Una respuesta en segundo plano, un batch o un trabajo de generación aceptado antes de que cambiara una lista sigue hasta su final.
- Aplicaciones conectadas por MCP. La herramienta
askdel servidor MCP de Zabio gasta con una key de su proyecto, así que se le aplican las mismas listas, sobre la dirección desde la que llama la aplicación. Una aplicación que corre en los servidores de su proveedor, como Claude.ai o ChatGPT, llama desde las direcciones de su proveedor: una lista de permitidas rechaza sus llamadas aasksi no incluye esas direcciones. Las herramientas MCP que solo leen no tienen este límite.
Los propietarios y administradores de la organización definen las listas en los tres niveles en la app web, en Firewall de IA, Acceso de red, o con la API del panel desde una sesión web. Cada miembro puede leer las listas que se aplican a las keys que ve. Con la API del panel:
| Método, ruta | Qué hace |
|---|---|
GET /admin/v1/orgs/{org}/ip-lists |
las listas de la organización |
PUT /admin/v1/orgs/{org}/ip-lists |
{"allow": ["203.0.113.0/24"], "deny": []} reemplaza las dos listas; una lista vacía la borra |
GET, PUT /admin/v1/orgs/{org}/projects/{project}/ip-lists |
lo mismo para un proyecto, con las listas de la organización mostradas como heredadas |
GET, PUT /admin/v1/orgs/{org}/keys/{key}/ip-lists |
lo mismo para una key, con las listas de su organización y de su proyecto mostradas como heredadas |
Cada respuesta muestra también your_address, la dirección desde la que llama tu navegador, y si una llamada desde ella pasaría. Dos cambios se preguntan antes de guardarse: una lista de denegadas que contiene todas las direcciones (0.0.0.0/0 o ::/0), y un cambio tras el cual tu propia dirección actual quedaría rechazada. El guardado responde 409 ip_list_confirm_required y dice el motivo; envíalo otra vez con "confirm": true para guardarlo. La dirección de tu navegador es solo una pista: tus servidores pueden llamar desde otras direcciones.
Cada cambio queda en el registro de auditoría de la organización, con quién lo hizo y cuántas entradas tenía cada lista antes y después. Las direcciones no se escriben en el registro de auditoría.