Firewall

Los guardrails examinan el texto que fluye a través de un modelo. El Firewall gobierna las acciones que toma un agente — las herramientas que llama, los servidores MCP que alcanza, las skills que carga y los hosts con los que habla. Es el par a nivel de acción de Guardrails: mismo alcance de espacio de trabajo, mismo modelo de adjuntar-una-vez, misma promesa de “la política vive en el gateway, no en tu aplicación”. Esta página es la visión conceptual general y la referencia de operaciones. Tres páginas complementarias cubren las piezas móviles en profundidad:

​

1. Qué es el Firewall

Un agente de IA no solo genera texto — actúa. Llama a shell.exec, consulta db.query, recupera una URL, carga una skill de la comunidad o enruta una llamada a herramienta a través de un servidor MCP de terceros. Cada una de esas es una acción con consecuencias en el mundo real, y los guardrails a nivel de prompt no pueden verlas. El Firewall es una política nombrada, con alcance de espacio de trabajo que el gateway evalúa en cada llamada a herramienta. Autoras una política una vez, adjuntas una clave API a ella (o estableces una como el valor por defecto del espacio de trabajo), y a partir de entonces cada llamada a herramienta que emite esa clave se verifica contra la política — antes de que llegue a la herramienta. Cada política es una lista ordenada de reglas. Una regla decide una cosa — a qué llamadas a herramienta aplica (un glob de nombre de herramienta, opcionalmente acotado a una skill y a una superficie de aplicación) y qué hacer al respecto (un veredicto: allow, audit, deny, sanitize, retener para aprobación o limitar coste). El motor recorre las reglas en orden de prioridad, gana la primera coincidencia, y hace fallback al veredicto por defecto de la política si nada coincide. Editar una política surte efecto en cada clave adjunta a ella en la siguiente llamada. Sin redespliegue. Sin cambio de código del agente. La política se aplica en el gateway — tu agente sigue emitiendo llamadas a herramienta exactamente como antes.

​

2. Las cuatro superficies de aplicación

Cada llamada a herramienta se evalúa contra exactamente una superficie — el punto en el ciclo de vida de la solicitud donde el firewall la ve: Una regla sin etapa aplica a todas las superficies; fija una regla a una superficie cuando un veredicto solo tiene sentido ahí (p. ej. una allowlist de egress).

​

3. Conceptos centrales

​

Alcance y resolución

Las políticas se resuelven exactamente como los Guardrails y las claves API — compartidas en el espacio de trabajo cuando tienes uno activo. Para cualquier llamada a herramienta el gateway resuelve la política en este orden:

1. Vinculación de clave — si la clave que llama tiene un firewall_policy_id, esa política aplica (cuando existe y está habilitada).
2. Valor por defecto del espacio de trabajo — en caso contrario aplica la política habilitada is_default del espacio de trabajo.
3. Ninguna — sin aplicación. Con el modo observe activado, la llamada se permite y se registra como un hueco; con él apagado, la llamada se permite silenciosamente (idéntica byte a byte a un espacio de trabajo que nunca habilitó la función).

A lo sumo una política por espacio de trabajo puede ser el valor por defecto; promover un nuevo valor por defecto degrada al anterior en la misma transacción.

​

4. Veredictos

Una regla (o el veredicto por defecto) produce uno de: En modo shadow, deny / sanitize / pending_approval se degradan todos a audit para que puedas medir el impacto de una política antes de que cambie el tráfico.

​

5. Cómo se evalúa una llamada a herramienta

1. Una llamada a herramienta llega al gateway (anunciada inbound, emitida en una respuesta, despachada a través del gateway MCP, o reportada como egress).
2. El motor resuelve la política activa (§3).
3. Recorre las reglas de la política en orden de prioridad (menor prioridad primero; los empates se rompen por id de regla). Una regla coincide cuando su superficie, su glob de nombre de herramienta, su glob de nombre de skill opcional, sus cláusulas de argumentos opcionales y su alcance de egress opcional coinciden todos.
4. Gana la primera coincidencia → aplica el veredicto de la regla. Si ninguna regla coincide → el default_verdict de la política.
5. Si la llamada es propiedad de una skill gobernada, el modo de aplicación de la skill se aplica encima — una skill en modo block fuerza un deny; una skill en modo quarantine escala cualquier cosa por debajo de deny a pending_approval.
6. La decisión se registra como un evento del firewall (a menos que sea una ejecución en seco), correlacionada con la ejecución y la sesión del agente.

​

6. Cómo se ve un block

Una llamada denegada en la superficie inbound devuelve HTTP 400 con un cuerpo de error con forma de OpenAI, el código de error firewall_blocked y un mensaje que nombra la herramienta y la razón — p. ej. tool "shell.exec" blocked by firewall: destructive shell command. El error lleva metadata estructurada (código de razón, factores de riesgo, puntuación) y se marca como skip-retry (reejecutar la misma llamada simplemente volvería a bloquear). Una llamada despachada a través del gateway MCP se bloquea como un error de herramienta (firewall deny: <reason>) en vez de un fallo de transporte, así que el modelo ve el rechazo y puede reaccionar — elegir otra herramienta, preguntar al usuario o detenerse — en vez de fallar. Una llamada retenida (pending_approval) devuelve HTTP 400 con el código firewall_approval_pending y un id de aprobación sobre el que el cliente hace polling.

​

7. Aprobación humana (HITL)

Un veredicto pending_approval convierte una llamada a herramienta en una revisión fuera de banda:

1. El motor encola un registro de aprobación y devuelve una respuesta “retenida” que lleva su id; la llamada no llega a la herramienta.
2. Un revisor la resuelve — desde la consola (Developer+), o vía un callback de webhook firmado con HMAC a tu propio sistema de aprobación.
3. Tu agente (o el SDK de MCP) hace polling del id de aprobación; una vez aprobado reenvía la llamada original con una cabecera X-OrcaRouter-Firewall-Approval de un solo uso, y el gateway la deja pasar esa única vez.

Las decisiones son first-writer-wins e idempotentes. Si la regla subyacente se editó después de la retención, el enriquecimiento anota rule_changed para que los revisores sepan que el contexto cambió.

​

8. Niveles de autonomía — un interruptor para toda tu postura

Afinar las políticas regla por regla es la ruta precisa; los niveles de autonomía son la rápida. Un único control reemplaza atómicamente la postura de Firewall y de Guardrails de tu espacio de trabajo en una transacción, con deshacer de un clic: Deshacer restaura el estado previo exacto desde el snapshot de auditoría.

​

9. Detección de anomalías

Más allá de las reglas estáticas, el Firewall aprende la forma normal de uso de herramientas de cada espacio de trabajo y marca las desviaciones en un feed legible por el visualizador:

• Picos de tasa / coste — la actividad por herramienta se puntúa contra una línea base de hora-de-la-semana aprendida (un promedio móvil de 14 días), así que “100 llamadas a db.query a las 3am del domingo” resalta incluso si cada llamada está individualmente permitida.
• retry_loop — un agente martillando la misma herramienta que falla.
• novel_path — una transición de herramienta a herramienta que este espacio de trabajo nunca ha hecho antes.

El feed reporta nombres de herramienta, ids de token redactados y solo conteos. Puedes posponer (snooze) una anomalía hasta 7 días mientras investigas.

​

10. Observabilidad

El Firewall deja un rastro sobre el que puedes actuar, todo con alcance de espacio de trabajo:

​

11. Relación con el resto del gateway

​

12. Conectar un agente al gateway del Firewall

Hay dos formas en que una llamada a herramienta llega al motor:

• Gateway MCP — apunta tu cliente MCP (Claude Desktop, Cursor, un framework de agentes) a https://api.orcarouter.ai/api/v1/firewall/mcp. El gateway expone las herramientas de cada servidor registrado alcanzable, con espacio de nombres <server>.<tool>, y evalúa cada tools/call en línea. Ver Servidores MCP.
• Hook de evaluación — llama a POST /api/v1/firewall/evaluate desde tu propio bucle de agente antes de despachar una llamada a herramienta, y actúa sobre el veredicto.

Ambos requieren un token con alcance de gateway de firewall — una clave API dedicada acuñada para este propósito. Una clave normal obtiene 403 en estas rutas.

​

13. Referencia de la API

Todas las rutas de consola tienen alcance de espacio de trabajo vía el contexto del espacio de trabajo y aplican RBAC de manera consistente: las lecturas y los sandboxes de test/simulate están abiertos a cada miembro; las escrituras requieren Developer+.

​

Políticas y configuración

​

Postura, presets y sandboxes

​

Observabilidad

Las reglas, los servidores MCP y las skills tienen cada uno sus propios endpoints — ver Reglas, Servidores MCP y Skills.

​

Gateway (máquina a máquina)

Estos se ejecutan sobre un token con alcance de gateway de firewall, no la sesión de consola:

​

14. FAQ

​

Véase también

¿Quieres profundizar en la seguridad de agentes? Las guías de Protege tus agentes (Zero Trust) sitúan esta función dentro de un flujo de trabajo de confianza cero.