Las herramientas HTTP genéricas borran los permisos

Una llamada HTTP genérica parece una sola herramienta para el host de un agente. En la práctica, puede contener miles de capacidades. Basta cambiar la URL, la credencial, el método, los encabezados o el cuerpo para que la misma función lea una página de estado, exporte datos de clientes, rote un secreto de firma o elimine un recurso de producción.

Ese desajuste hace que el permiso por herramienta sea un límite de seguridad débil. Aprobar que un agente use http_request no aclara qué puede hacer. La decisión útil está una capa más abajo, donde el sistema puede vincular una credencial concreta con un destino resuelto, un método permitido y unos detalles de solicitud restringidos.

La distinción importa incluso cuando el agente se comporta bien. Los prompts contienen errores, el texto recuperado puede incluir instrucciones hostiles y una herramienta amplia puede convertir un pequeño fallo de planificación en una acción real sobre una API. Darle a la herramienta un nombre más amable no arregla nada. Hay que autorizar la acción que va a cruzar la red.

Una herramienta de llamada contiene muchas capacidades

Una herramienta solo es un límite de capacidad cuando sus entradas no pueden cambiar de forma radical su autoridad. Una consulta meteorológica con un proveedor fijo, método GET fijo y respuesta fija se acerca a una sola capacidad. Una función que acepta cualquier URL, verbo, encabezado y cuerpo es un cliente de red programable.

Pensemos en un esquema con cinco campos corrientes: url, method, headers, body y credential_name. El host del agente puede presentarlo como un solo elemento de la lista de herramientas. Sin embargo, GET /projects/42 con un token de lectura y DELETE /projects/42 con un token de administrador no merecen la misma decisión. Tampoco la merece una solicitud a una API pública frente a otra que se resuelve como un servicio de una red privada.

Las anotaciones de herramientas de Model Context Protocol no corrigen este colapso. La especificación de herramientas MCP describe las anotaciones sobre lectura o comportamiento destructivo como indicaciones y pide a los clientes que no confíen en ellas salvo que procedan de servidores fiables. Un cliente genérico tampoco puede asignar un valor siempre cierto a readOnlyHint, pues su comportamiento depende de argumentos que aún no ha recibido.

Esta es la distinción que los equipos suelen confundir: elegir una herramienta responde qué implementación se ejecutará, mientras que autorizar una acción responde qué efecto externo puede ocurrir. Si el host solo aprueba el nombre de la implementación, cada solicitud materialmente distinta hereda esa aprobación. Un selector de herramientas ordenado puede esconder así un canal de salida casi sin restricciones.

Separar cada operación de API en una herramienta distinta puede mejorar las descripciones y la planificación, pero no resuelve toda la seguridad. Las herramientas generadas siguen necesitando un punto de aplicación, las credenciales conservan su propia autoridad y una redirección puede llevar una operación aparentemente estrecha a otro lugar. Use herramientas específicas para facilitar el uso. Aplique los permisos sobre la solicitud final.

Un permiso necesita cuatro coordenadas

Una decisión HTTP defendible tiene cuatro coordenadas: la credencial, el destino resuelto, el método y los detalles de la solicitud. Si falta una, una solicitud puede conservar la apariencia aprobada y cambiar su efecto.

La credencial identifica la autoridad que se ejerce. Un token de despliegue y otro de facturación pueden apuntar al mismo host y ruta, pero exponer poderes distintos. El destino identifica dónde se puede presentar esa autoridad. El método expresa la intención general de HTTP. Los demás detalles, como ruta, consulta, ciertos encabezados, tipo de contenido y campos del cuerpo, determinan la operación real.

Un registro compacto de autorización puede tener este aspecto:

credential: issue-tracker-read
origin: https://api.example.test:443
path_prefix: /v2/issues/
methods:
  - GET
redirects: deny
headers:
  allow:
    - Accept
query:
  deny:
    - include_deleted
body: forbidden

Este fragmento evita varios fallos a la vez. El agente no puede sustituir la credencial por otra más potente, enviarla a otro origen, convertir la lectura en un POST, seguir una redirección, añadir un encabezado parecido al de autorización, pedir registros eliminados con ese parámetro ni introducir un cuerpo en una operación que se esperaba de solo lectura.

El objeto de política no es una plantilla universal. Algunas API requieren rutas exactas, otras incluyen un identificador de inquilino en la ruta y otras expresan una acción mediante el cuerpo de un POST. Lo importante es la forma de la decisión: evaluar juntas las cuatro coordenadas después de analizar y normalizar, y solo entonces inyectar la credencial si la solicitud pasa.

No permita que el agente aporte el secreto real mediante headers. Haga que se refiera a una credencial con un nombre opaco y que un ejecutor de confianza añada el token bearer, las credenciales básicas o el encabezado personalizado después de autorizar. De otro modo, el agente puede copiar un secreto en otro campo, un registro o un segundo destino, y la cuidada regla de destinos queda en mera apariencia.

Las credenciales definen la autoridad

Las credenciales deben ser concesiones separadas con la menor autoridad que admita la API de origen. Una herramienta HTTP genérica resulta mucho menos peligrosa cuando el ejecutor elige entre credenciales con nombre y alcance limitado, en vez de conservar un solo token para toda la organización.

Los ámbitos OAuth ayudan, pero el ámbito y la audiencia responden preguntas diferentes. Un ámbito puede indicar que un token puede leer contactos. La audiencia indica qué servidor de recursos debe aceptarlo. RFC 8707 define el parámetro OAuth resource para que un cliente solicite un token destinado a un recurso protegido concreto, y recomienda que los servidores de autorización restrinjan la audiencia del token emitido. Su argumento de seguridad es práctico: un token presentado a un recurso no debe servir en otro.

La especificación vigente de autorización MCP aplica la misma separación. Exige que los servidores MCP solo acepten tokens destinados a ellos y prohíbe pasar el token MCP entrante a una API posterior. Cuando un servidor MCP llama a otra API, actúa como un cliente OAuth distinto y usa otro token para ese servicio. Es un límite limpio que un ejecutor HTTP genérico debe conservar aunque el agente no vea ningún flujo OAuth.

Las claves API suelen ofrecer controles nativos más débiles. Aun así, trate cada una como una autoridad distinta. Registre qué orígenes pueden recibirla, qué formato de encabezado inyectará el ejecutor, cuándo caduca y quién se ocupa de rotarla. No considere inocua una entrada de la bóveda llamada staging solo por su nombre. Compruebe sus privilegios reales en el servicio de origen.

La elección de credencial también debe aparecer en la vista de aprobación. Un aviso que solo dice POST api.example.test no revela si la llamada usa una clave de pruebas o un token del propietario de la cuenta. Muestre una etiqueta legible y la cuenta o el inquilino previstos, pero nunca el secreto. Si el ejecutor no puede identificar ese contexto, la concesión es demasiado ambigua para reutilizarla en silencio.

Mantener los secretos fuera del modelo reduce su divulgación accidental, pero el secreto por sí solo no limita el uso. Un agente puede usar mal un secreto sin ver sus bytes si un ejecutor amplio está dispuesto a adjuntarlo a solicitudes arbitrarias. La no divulgación y la autoridad mínima resuelven problemas diferentes. Se necesitan ambas.

El destino es el extremo resuelto

Comprobar una cadena URL una sola vez no controla el destino. El ejecutor debe analizar la URL, normalizarla, resolver el host, aplicar reglas de red y repetir la decisión ante cada redirección antes de adjuntar una credencial.

Empiece por el esquema, el host y el puerto efectivo exactos. https://api.example.test y https://api.example.test:8443 son orígenes distintos. Rechace información de usuario en la URL, codificaciones ambiguas, esquemas no admitidos y nombres de host que solo parecen tener un sufijo aprobado. Una comprobación de sufijo que acepte api.example.test.attacker.invalid no es una lista de permitidos.

Después resuelva el DNS e inspeccione todas las direcciones devueltas. Un nombre que parece público puede resolver a loopback, link-local, una red privada o metadatos de una instancia en la nube. La resolución también puede cambiar entre la validación y la conexión. El componente que valida debe controlar la conexión y verificar la dirección que realmente usa, en lugar de entregar la URL a otro cliente que vuelva a resolverla.

La Server Side Request Forgery Prevention Cheat Sheet de OWASP recomienda incluir en una lista de permitidos los destinos de confianza conocidos cuando la aplicación puede identificarlos. También aconseja desactivar el seguimiento automático de redirecciones, porque una redirección puede eludir la validación de entradas. El consejo encaja especialmente bien con las herramientas de agentes: el modelo suele proporcionar la URL y la solicitud puede llevar una credencial que solo debía recibir el primer destino.

Las redirecciones requieren una nueva decisión de autorización. RFC 9110 dice que las redirecciones automáticas exigen cuidado con métodos no seguros y recomienda retirar campos propios del recurso, como Authorization y Cookie, al seguirlas. Un ejecutor seguro puede ser más simple: denegar por defecto las redirecciones en llamadas autenticadas o presentar el nuevo destino como otra acción e inyectar de nuevo las credenciales solo cuando pase la política.

El control de ruta sigue importando dentro de un origen aprobado. Pasarelas multiinquilino, hosts SaaS compartidos y rutas administrativas pueden vivir tras el mismo nombre de host. RFC 8707 señala que una ruta que identifica al inquilino puede tener que formar parte del identificador de recurso en sistemas multiinquilino. Una lista de orígenes sin una restricción de ruta o inquilino puede ser mucho más amplia de lo que espera quien la revisa.

Los métodos HTTP son señales, no veredictos

Restringir métodos elimina muchos errores, pero el nombre del método no demuestra que una solicitud sea inofensiva. RFC 9110 define GET, HEAD, OPTIONS y TRACE como seguros porque su semántica especificada es esencialmente de lectura. Define PUT, DELETE y los métodos seguros como idempotentes, lo que significa que repetir la operación tiene el mismo efecto previsto que realizarla una vez.

Seguro e idempotente no son sinónimos. DELETE puede ser idempotente y aun así destruir un recurso. POST no suele ser seguro ni idempotente, pero una API puede usarlo para una búsqueda de solo lectura porque la consulta no cabe en una URL. Un sistema de aprobación que reduzca el riesgo a GET frente a POST clasificará mal ambos casos.

Peor aún, las API reales a veces incumplen la semántica de los métodos. RFC 9110 advierte de los recursos que colocan acciones como el borrado en una consulta GET y dice que su propietario debe impedir esa conducta insegura mediante métodos seguros. El ejecutor no puede suponer que todos los servicios cumplen la regla. Si GET /jobs?id=7&action=cancel cambia el estado, permitir todos los GET no crea una concesión de solo lectura.

Use el método como una entrada. Combínelo con una ruta y, cuando haga falta, con restricciones específicas de la operación. Para una API bien descrita, una operación OpenAPI aporta un mapa útil: la Especificación OpenAPI permite declarar requisitos de seguridad por operación y las entradas OAuth enumeran los ámbitos requeridos. Importe esa información como configuración y compruébela después contra lo que el servicio emite y acepta de verdad. Un archivo descriptivo no aplica controles por sí mismo.

El comportamiento de los reintentos también pertenece a esta decisión. Un tiempo de espera agotado tras un POST no indica si el servidor aplicó la acción. No reintente automáticamente una solicitud insegura y no idempotente salvo que la API proporcione un mecanismo de idempotencia o el cliente pueda probar que la primera no se aplicó. La idempotencia puede hacer más seguro el reintento operativo, pero no autoriza la acción original.

Los detalles de la solicitud deciden el efecto

Dos solicitudes con la misma credencial, origen, ruta y método pueden producir resultados opuestos. El cuerpo, la consulta y ciertos encabezados suelen contener la operación que de verdad importa.

Un extremo de facturación puede aceptar POST /v1/subscriptions/update tanto para reducir asientos como para mover una cuenta a un plan caro. Un extremo de repositorios puede usar una sola ruta de mutación con un campo operation para archivar, transferir o eliminar. Un buscador puede exponer registros ocultos o eliminados cuando aparece include_deleted=true. Conceder la ruta sin restringir esos campos concede todos los modos que implementa.

Los encabezados merecen la misma sospecha. El ejecutor debe controlar Authorization, Proxy-Authorization, Host y cualquier encabezado de credencial personalizado. Normalmente debe rechazar los intentos del agente de definirlos. Los encabezados que seleccionan una cuenta, suplantan a un usuario, sustituyen el método, solicitan ejecución asíncrona o transportan controles de escritura condicional pueden cambiar la autoridad o el efecto. Reenviar encabezados arbitrarios es otra herramienta genérica escondida dentro de la primera.

El tipo de contenido controla el análisis. Si la política inspecciona JSON pero el cliente puede enviar datos de formulario, contenido multiparte o bytes comprimidos, un agente puede sacar el campo sensible del analizador. Imponga el tipo declarado, fije límites de tamaño antes de almacenar en búfer, rechace campos duplicados o ambiguos y autorice la misma representación de bytes que enviará el ejecutor. Validar un objeto y serializar después otro deja huecos.

El tratamiento de la respuesta también forma parte del límite, aunque no sea una coordenada de permiso para el efecto saliente. Limite el tamaño, clasifique los tipos de contenido y trate las instrucciones devueltas como datos no fiables. Un GET permitido puede recuperar una página con inyección de prompts, secretos o una carga enorme. Autorizar la salida no vuelve segura la respuesta para entregarla al agente.

Mantener esquemas exactos de cuerpos es costoso, así que reserve ese esfuerzo para rutas con mucho poder. Para lecturas de bajo riesgo puede bastar con prohibir el cuerpo y restringir los nombres de consulta. Para cambios de cuenta, despliegues, rotación de secretos, movimiento de dinero o acciones destructivas, valide los campos que identifican objeto, inquilino, importe, entorno y transición solicitada. Si la API ofrece un extremo o una credencial más estrechos, prefiera eso a una regla local complicada.

La aprobación debe describir la acción resuelta

Una aprobación útil muestra lo que el ejecutor de confianza va a enviar después de normalizar, no la llamada propuesta por el modelo. Quien revisa necesita la etiqueta de credencial, cuenta o inquilino, destino resuelto, método, ruta, campos relevantes de la consulta y del cuerpo, y conducta de redirección.

Eso no implica volcar JSON sin procesar en un cuadro de diálogo. La carga completa esconde el campo peligroso entre marcas de tiempo y valores predeterminados. Muestre primero un resumen de la operación y permita luego inspeccionar la solicitud canónica. Una aprobación de despliegue podría decir que la credencial production-deployer creará la versión 2026.07.24 en el inquilino de producción, seguida del host exacto, la ruta POST y las diferencias del cuerpo.

Vincule la aprobación con un resumen de la acción canónica. Si el host, método, ruta, encabezados protegidos o cuerpo cambian después del clic, calcule otro resumen y exija una nueva decisión. Así se cierra un fallo común entre la comprobación y el uso, cuando la interfaz aprueba un objeto y después un middleware sigue una redirección, añade valores o modifica el cuerpo.

Elija conscientemente el límite de reutilización. Aprobar una sesión puede ser razonable para lecturas repetidas con una credencial y un destino estrechos. Una credencial capaz de borrar recursos debe requerir aprobación por llamada o una operación preautorizada mucho más limitada. No sustituya el alcance por avisos repetidos. Los humanos dejan de leer diálogos ruidosos, sobre todo si todas las tarjetas parecen iguales.

La aprobación debe denegar por defecto cuando falte contexto necesario. Un host sin resolver, un tipo de contenido desconocido, una sustitución de método no reconocida o un cuerpo que la política no puede analizar no son solicitudes de bajo riesgo. Son acciones que el sistema no puede describir con precisión.

Un plan inocuo puede acabar en una llamada peligrosa

El fallo suele empezar con una tarea normal y una solicitud que cambia de sentido al atravesar varias capas. Supongamos que un agente debe leer una incidencia y publicar una nota breve. El host concede el cliente genérico para toda la sesión porque ambas operaciones usan el mismo servicio de proyectos.

La credencial de lectura falla con POST, así que el planificador elige otra entrada de la bóveda cuya descripción menciona automatización de proyectos. Ese token también puede administrar webhooks. Un comentario recuperado indica al agente que avise a un callback externo y el planificador presenta su URL como destino del estado. La herramienta sigue aprobada para la sesión, el nombre de la credencial parece relacionado y el método sigue siendo POST. El permiso por herramienta no ve ningún cruce de límites.

El callback inicial responde con una redirección 307 a una dirección privada. Una biblioteca HTTP cómoda conserva el cuerpo POST con ese estado. Puede retirar un encabezado Authorization generado automáticamente, pero un encabezado de credencial personalizado añadido por el código puede sobrevivir si el cliente no lo trata expresamente. La solicitud lleva ahora autoridad del proyecto y contenido de la incidencia hacia un destino que nadie revisó. Aunque el servicio privado rechace la credencial, el cuerpo puede divulgar datos o activar una acción sin autenticar.

Cuatro comprobaciones coordinadas detienen la secuencia en puntos distintos. La credencial de lectura no puede autorizar POST. La credencial de automatización no puede llegar a un host de callback no registrado. La redirección exige otra decisión de destino. Las reglas del cuerpo rechazan un destino arbitrario. Ninguna comprobación sostiene toda la defensa y los nombres amables de herramientas y credenciales no sostienen ninguna parte.

Por eso desaconsejo aprobar un cliente genérico una vez por sesión. Es una pauta popular porque los avisos repetidos interrumpen el trabajo y un nombre estable parece describir un riesgo estable. No lo hace. Limite la concesión de sesión a una credencial y destino con operaciones restringidas, y vuelva a preguntar cuando cambie cualquier coordenada.

La misma secuencia puede fallar sin ningún comentario malicioso. Un agente puede inferir un extremo a partir de documentación antigua, copiar una URL de un error o elegir una credencial de nombre parecido cuando la prevista devuelve 403. Son conductas normales de recuperación para un planificador. El diseño de seguridad debe esperarlas y mantener el intento dentro de la concesión original.

La normalización debe ocurrir antes de comparar. Decodifique los segmentos de ruta codificados con porcentajes según una regla documentada, rechace segmentos de puntos que escapen del prefijo permitido, normalice el puerto efectivo y decida cómo trata la API los nombres de consulta repetidos. Si la política considera /v2/issues/%2e%2e/admin una ruta de incidencias y el servidor la resuelve como /v2/admin, ambos autorizan recursos distintos. Rechace las formas ambiguas en vez de adivinar la interpretación de cada intermediario.

La credencial debe inyectarse después de ese trabajo y tan cerca de la transmisión como sea posible. Construya una solicitud canónica, autorícela, vincule el resumen de aprobación, abra la conexión aprobada y entonces añada el secreto desde el ejecutor. Si un middleware puede reescribir host, método o cuerpo después, incluya su salida en la autorización o elimine su libertad para reescribir.

Los fallos también necesitan un camino cerrado. Si la credencial elegida recibe 401 o 403, devuelva ese resultado al agente sin probar automáticamente todas las entradas de la bóveda. Probar otras credenciales convierte un fallo limitado en exploración de privilegios. El siguiente intento debe nombrar otra credencial y pasar una nueva decisión con su autoridad y cuenta.

Trate también como datos los errores del servicio. Las API suelen repetir URL, nombres de operación o acciones sugeridas. Es razonable que un planificador use ese texto para la llamada siguiente, pero el texto no adquiere autoridad por proceder de un host aprobado. La nueva solicitud pasa por las mismas comprobaciones de destino y detalles.

Pruebe esta conducta como secuencia, no solo como solicitudes aisladas. Empiece con una lectura permitida, devuelva una redirección preparada o una sugerencia de error, deje que el planificador construya la continuación y confirme que reutilizar la sesión no amplía el permiso. Haga fallar luego la credencial prevista y compruebe que el ejecutor no prueba otra en silencio. Estas pruebas detectan herencias de permisos que una prueba unitaria sobre una coincidencia individual no ve.

Los registros deben guardar la decisión y la llamada

Los registros de invocación de herramientas son demasiado generales para investigar incidentes. Anotar que un agente llamó a http_request deja sin respuesta las preguntas centrales: qué credencial se usó, adónde fue la solicitud, qué operación se permitió y si lo enviado coincidía con lo aprobado.

Registre la identidad de sesión o proceso, identificador de llamada, identificador de credencial, destino canónico, dirección resuelta, método, resumen redactado, versión de política, identidad de quien aprobó, resumen de acción, estado de respuesta, duración y resultado final. No guarde bytes secretos ni cuerpos sensibles en los registros corrientes. Para campos necesarios como prueba, conserve un resumen o cifre con otros controles de acceso.

Registre las denegaciones además de los éxitos. Una serie de intentos rechazados contra direcciones privadas o hosts alternativos puede revelar una inyección de prompts o un planificador defectuoso antes de que ocurra un efecto externo. Distinga denegación de política, denegación humana, fallo de red, rechazo del servicio y cancelación local para no confundir una conexión fallida con una acción bloqueada.

La evidencia debe ser difícil de reescribir para el agente que actúa. El almacenamiento solo anexable, los escritores restringidos y las comprobaciones de integridad mantienen útil el registro cuando se cuestiona un equipo o proceso. Sallyport registra sesiones y llamadas individuales en un único registro de auditoría cifrado, encadenado mediante hashes y que el escritor no puede leer, mientras sp audit verify comprueba la cadena sin conexión y sin clave. También conserva las credenciales API y SSH en una bóveda cifrada y ejecuta las acciones sin revelar los secretos al agente.

Sustituya la concesión amplia en el ejecutor

Puede conservar una interfaz HTTP genérica sin conservar autoridad genérica. Traslade la inyección de credenciales y la aplicación de controles a un ejecutor de confianza, y haga que el modelo envíe una solicitud sin credenciales junto con una referencia opaca.

Una migración práctica empieza inventariando llamadas reales, no imaginadas. Agrupe solicitudes recientes por credencial, origen, método y operación. Las credenciales amplias y los destinos que nunca aparecen juntos son candidatos a separarse. Las rutas que concentran varios modos destructivos en un cuerpo necesitan restricciones propias o credenciales distintas en el servicio.

Después, evalúe el tráfico actual en modo informativo. Normalice cada solicitud, resuelva su destino y muestre si la concesión propuesta la permitiría o denegaría, sin cambiar aún la ejecución. Revise coincidencias sorprendentes. Una regla que parece permitir leer incidencias puede admitir exportaciones, registros eliminados u otro inquilino a través de un host compartido.

Aplique primero los límites sencillos: credenciales propiedad del ejecutor, orígenes HTTPS exactos, sin redirecciones automáticas, métodos explícitos y rechazo de direcciones privadas salvo que una integración concreta las necesite. Añada restricciones de ruta, consulta, encabezados y cuerpo alrededor de las operaciones de mayor impacto. Mantenga una vía excepcional que exija aprobación por llamada y produzca una entrada de auditoría visible; no vuelva en silencio a la herramienta antigua.

Por último, pruebe el límite con variaciones de solicitudes conocidas como correctas. Cambie el sufijo del host, puerto, respuesta DNS, destino de redirección, referencia de credencial, método, tipo de contenido, campo de inquilino, campo de operación y ruta codificada. Cada variación debe coincidir con una concesión intencional o fallar antes de adjuntar credenciales. Compruebe también que los bytes registrados, aprobados y enviados comparten el mismo resumen de acción.

La lista de herramientas sigue siendo útil para ayudar al agente a elegir operaciones sensatas. Simplemente no es el lugar adecuado para terminar la autorización. Conserve la superficie cómoda si gusta a los desarrolladores, pero haga que cada efecto de red obtenga permiso cuando ya se conocen la credencial, el destino, el método y los detalles.