Llamadas de descubrimiento frente a llamadas de mutación para agentes de IA más seguros

Un agente que puede inspeccionar un sistema ampliamente y modificarlo sin cuidado tiene una autoridad mal definida. La separación útil es sencilla: permite que el agente descubra lo suficiente para elaborar un plan fundamentado y establece después un límite claro para las operaciones que crean, modifican, activan o eliminan estado.

La idea parece obvia hasta que aparece una API real. Un endpoint supuestamente de solo lectura actualiza una caché. Una vista previa reserva un trabajo remoto. Un endpoint de actualización acepta un filtro vacío y afecta a todos los registros. Un comando SSH parece inofensivo hasta que una expansión del shell convierte una ruta concreta en una ruta mucho más amplia. Los nombres de los métodos y las buenas intenciones no protegen una cuenta de producción.

He visto equipos resolver esto colocando a una persona delante de cada llamada. Eso protege la cuenta durante una tarde y hace que el viernes todo el mundo apruebe sin leer. Un diseño mejor permite que los agentes inspeccionen, hace visibles los cambios de estado y coloca la mayor fricción donde una acción equivocada tendría un resultado irreversible o costoso.

El descubrimiento necesita un modelo de permisos diferente

Las llamadas de descubrimiento deben responder preguntas sobre el estado actual sin modificarlo. Las llamadas de mutación intentan crear, editar, ejecutar o eliminar algo. La diferencia importa porque un agente no puede planificar con seguridad a partir de suposiciones obsoletas, pero tampoco debería recibir un permiso permanente para actuar solo porque necesita contexto.

Un agente de programación que investiga un fallo de despliegue puede necesitar enumerar servicios, obtener eventos recientes, comparar una revisión de configuración, inspeccionar el estado del repositorio y leer una incidencia remota. Esas solicitudes reducen la incertidumbre. Si exiges aprobación para cada una, el operador verá una serie de avisos pequeños con demasiado poco contexto para valorarlos. El agente también perderá el hilo de la investigación mientras espera.

Ese mismo agente podría reiniciar después una carga de trabajo, fusionar una solicitud de cambios, rotar una credencial, cerrar una incidencia o eliminar un objeto. Cada operación modifica el mundo fuera de la ventana de contexto del agente. Antes de autorizarla, el operador debe ver el objetivo y el efecto propuestos.

Esto no equivale a conceder un rol amplio de «solo lectura» y dar el asunto por resuelto. El descubrimiento puede exponer información sensible. También puede generar costes, consumir límites de frecuencia o activar comportamientos en un servicio mal diseñado. La separación busca controlar las acciones, no declarar inofensiva toda inspección.

Una clasificación útil pregunta qué puede observar el sistema remoto cuando termina la solicitud:

1. Una llamada de descubrimiento devuelve información y no modifica ningún estado empresarial, operativo o de facturación relevante.
2. Una llamada de mutación crea, actualiza, elimina, ejecuta, publica, envía o modifica de cualquier otra forma un estado visible externamente.
3. Una llamada ambigua debe tratarse como una mutación hasta que alguien demuestre lo contrario.

La tercera categoría pesa más de lo que suelen admitir los equipos. Si nadie puede explicar los efectos secundarios de un endpoint a partir de su contrato y de una prueba controlada, no lo incluyas en el conjunto de descubrimiento sin supervisión solo porque su nombre parezca inofensivo.

Los verbos HTTP ofrecen una pista, no una decisión de permisos

Los nombres de los métodos HTTP ayudan a clasificar las llamadas, pero no sustituyen la revisión del endpoint. RFC 9110 define GET, HEAD, OPTIONS y TRACE como métodos «seguros», lo que significa que el cliente no solicita un cambio de estado. La propia RFC también advierte que un servidor puede registrar solicitudes, cobrar una cuenta o producir otros efectos incidentales.

Es fácil pasar por alto esta diferencia. La seguridad de HTTP describe la semántica prevista de la solicitud, no una promesa criptográfica de que la implementación no hizo nada. RFC 9110 responsabiliza al propietario del recurso de evitar acciones inseguras cuando los usuarios siguen las convenciones de los métodos seguros. Tu agente no puede hacer cumplir esa promesa si el servicio la incumple.

Toma estas reglas como puntos de partida, no como decisiones definitivas:

1. GET y HEAD suelen pertenecer al conjunto candidato de descubrimiento. Revisa primero los parámetros de consulta y la documentación del endpoint.
2. POST, PUT, PATCH y DELETE pertenecen al conjunto de mutaciones, salvo que un endpoint concreto tenga un comportamiento de lectura documentado y probado.
3. OPTIONS puede inspeccionar las capacidades del servidor, pero algunas plataformas incluyen datos específicos de la cuenta que también necesitan límites de alcance.
4. Una prueba de webhook, una vista previa de un trabajo, una exportación de informes o un endpoint de búsqueda pueden usar POST y seguir siendo operaciones de observación. Verifícalo en lugar de conceder acceso general a POST.

También es frecuente el fallo inverso. A veces los desarrolladores conectan un enlace o una ruta GET a una acción porque resulta práctico. Una URL como /reports/monthly?refresh=true puede reconstruir una caché de informes costosa. Un endpoint GET con ?send=true puede enviar una notificación. Un agente seguirá la descripción que recibe de la API. No esperes que el modelo detecte que el diseñador del servidor ignoró la semántica de HTTP.

Lee la documentación del endpoint buscando palabras como «crea», «inicia», «actualiza», «genera», «envía», «registra», «sincroniza» y «cobra». Esos verbos deben sacar la llamada del conjunto de descubrimiento aunque la ruta use GET. Después prueba el endpoint con una cuenta desechable y compara el estado anterior y posterior, incluidas las colas de trabajos, las notificaciones, los contadores de uso y los registros de auditoría.

La respuesta HTTP también ayuda a clasificar la solicitud. Una respuesta que devuelve un identificador de trabajo, un identificador de operación o la URL de un recurso nuevo suele indicar que el servicio remoto ha iniciado un trabajo. Un estado 200 solo demuestra que el servidor gestionó la solicitud. No demuestra que la solicitud fuera de observación.

Define los recursos y los efectos antes de crear listas de permisos

Una lista de permisos basada solo en rutas es demasiado rudimentaria si ignora el recurso y el efecto que hay detrás de cada ruta. Define un inventario pequeño de acciones que indique qué puede inspeccionar un agente, qué puede proponer y qué no debe hacer nunca sin una decisión humana directa.

Usa un registro como este para cada acción externa. Los nombres no importan. La evidencia sí.

Action: repository pull request list
Channel: HTTP
Target pattern: GET /repos/{owner}/{repo}/pulls
Class: discovery
Data returned: title, status, branch names, review metadata
Side-effect evidence: API reference defines this endpoint as a list operation
Scope limit: named repositories only
Review date: 2025-02-14

Action: repository merge pull request
Channel: HTTP
Target pattern: PUT /repos/{owner}/{repo}/pulls/{number}/merge
Class: mutation
Effect: changes merge state and source history
Required control: explicit approval for each call

El inventario obliga a tomar una decisión que los equipos suelen dejar imprecisa: ¿el agente tiene permiso para conocer este recurso o para modificarlo? Son permisos distintos. Un sistema de gestión de incidencias puede permitir descubrir el título y el estado de una incidencia, pero negar los cuerpos de los comentarios porque contienen datos de clientes. Una cuenta en la nube puede permitir enumerar una carga de trabajo con un alcance limitado, pero negar el acceso a las identidades de toda la cuenta y a los registros de facturación.

Mantén el alcance en el registro de la acción. GET /projects no es una descripción útil de permisos si la credencial puede enumerar todos los proyectos que una empresa ha creado. Una descripción mejor nombra la organización, el repositorio, el espacio de nombres, la cuenta o la ruta que necesita el agente. Si el servicio externo no puede limitar la credencial de esa forma, aplica una lista de objetivos permitidos en la puerta de enlace de acciones o no hagas que ese descubrimiento sea automático.

No rellenes esta lista únicamente a partir de archivos Swagger. Las descripciones de las API suelen identificar el método y los parámetros, pero omiten las consecuencias operativas. Combina la documentación con una cuenta de prueba, el registro de auditoría del servicio y una persona responsable del sistema remoto. El objetivo es formular una afirmación explícita que alguien pueda revisar cuando cambie la API.

Una solicitud de lectura también puede dañar el sistema

El acceso de lectura tiene un radio de impacto y necesita sus propios límites. Un agente con permiso para inspeccionar todos los repositorios, nombres de secretos, notas de incidentes, registros de clientes y eventos de despliegue recibe suficiente contexto para causar daños si un atacante controla el proceso del agente o sus instrucciones.

La recomendación habitual es «concede primero acceso de solo lectura». Es popular porque suena prudente y encaja con nombres conocidos de roles IAM. Se equivoca cuando sustituye el análisis de la clasificación de datos por un rol de lectura amplio. El descubrimiento generalizado suele crear la mayor exposición de información del diseño.

Separa dos preguntas:

• ¿Puede la solicitud modificar el estado remoto?
• ¿Puede la respuesta revelar información que el agente no debería recibir?

Una solicitud solo debe tratarse como descubrimiento después de superar la primera pregunta. Solo necesita permisos después de superar la segunda. No reduzcas ambas pruebas a una única etiqueta.

En los recursos sensibles, devuelve únicamente los campos que necesita el agente. Un diagnóstico de despliegue puede necesitar la fase del pod, el resumen de la imagen y los mensajes de eventos recientes. No necesita valores de entorno ni un objeto de configuración completo. Un agente de clasificación de incidencias puede necesitar etiquetas y marcas de tiempo, no todos los comentarios privados. Si una API no permite seleccionar campos, coloca delante un intermediario limitado o mantén la operación detrás de una aprobación.

La paginación requiere atención. Un endpoint de lista puede parecer limitado durante una prueba normal y convertirse en una vía de extracción de datos sin límite cuando el agente sigue los cursores. Establece un máximo para el tamaño de página y el número total de páginas cuando el canal lo permita. Registra ese límite en el inventario de acciones. Los límites de frecuencia protegen al proveedor, pero no definen un límite de información adecuado para tu agente.

Los endpoints de búsqueda necesitan el mismo tratamiento. Una búsqueda de texto completo sobre código fuente o registros de soporte puede revelar más que una consulta directa de objetos, y el texto de la instrucción puede influir en la consulta. Limita las colecciones y la sintaxis que se pueden buscar. No pases expresiones de búsqueda creadas por el agente directamente a un backend potente solo porque la solicitud use GET.

Las credenciales deben hacer cumplir la separación cuando sea posible

El lugar más seguro para distinguir entre inspección y acción es el modelo de autorización del servicio remoto. Usa una credencial que pueda leer los recursos aprobados para el descubrimiento y otra credencial que pueda ejecutar las mutaciones limitadas que necesita el flujo de trabajo.

Esta configuración limita un fallo sencillo pero peligroso: que un agente malicioso o confundido encuentre un endpoint de mutación que olvidaste denegar. Si la credencial de descubrimiento no puede escribir, la llamada al endpoint falla aunque la capa de acciones la clasifique de forma incorrecta. Es una defensa basada en controles independientes, no una razón para descuidar el inventario de acciones.

Algunos servicios lo facilitan mediante ámbitos, roles, permisos de proyecto o identidades de máquina separadas. Otros solo ofrecen un token personal amplio. Cuando un proveedor solo ofrece esta última opción, usa el límite más estrecho de cuenta y proyecto disponible y aplica después endpoints y patrones de objetivos concretos en tu puerta de enlace. No entregues nunca a un agente autónomo la credencial personal de un administrador solo porque ya está disponible.

Una configuración clara suele tener tres clases de credenciales:

1. Una credencial de descubrimiento con acceso exacto a los recursos que el agente puede inspeccionar.
2. Una credencial de mutación para escrituras limitadas que aún requieren una decisión de aprobación.
3. Una credencial de emergencia que los agentes nunca utilizan y que los humanos recuperan únicamente mediante un proceso de incidentes.

No permitas que una credencial de mutación responda por defecto a las llamadas de descubrimiento. Parece inofensivo porque el endpoint es de solo lectura, pero dificulta las revisiones futuras. Un registro que indica que una credencial potente consultó un recurso no dice si el agente necesitaba esa autoridad. Mantén el significado de la identidad.

Sallyport guarda las credenciales de API y SSH en su bóveda cifrada y ejecuta la acción saliente directamente, por lo que un agente MCP recibe el resultado en lugar del secreto. Este diseño permite exponer una ruta de descubrimiento limitada sin colocar un token de acceso ni material SSH privado en el contexto del agente.

La aprobación debe describir el cambio, no castigar cada solicitud

La aprobación por llamada funciona cuando el revisor puede ver un efecto concreto y decidir rápidamente. Falla cuando el sistema pide consentimiento después de cada consulta inofensiva, porque la persona aprende que el aviso no contiene ninguna decisión que merezca la pena tomar.

Usa la autorización de sesión para establecer qué proceso de agente puede utilizar el conjunto de descubrimiento. Después exige aprobación individual para las acciones de mutación y muestra la solicitud en términos que una persona pueda valorar. «POST /v1/jobs» es un texto de aprobación deficiente. «Iniciar una exportación de datos para el proyecto northwind, destino: depósito de archivo, estimación: 30 días» ofrece al revisor algo que puede comprobar.

La tarjeta de aprobación debe incluir el objetivo, la operación, los parámetros relevantes y la identidad de la credencial. No escondas el objetivo en un cuerpo JSON largo. Si una acción afecta a más de un recurso, muestra el número y una muestra breve. Cuando el número supere el rango habitual, exige que el operador abra el conjunto completo antes de aprobar.

Una solicitud para una actualización limitada podría tener este aspecto:

{
  "action": "update_issue",
  "target": {
    "repository": "payments-api",
    "issue": 1842
  },
  "changes": {
    "labels_add": ["needs-review"],
    "assignee": "release-manager"
  },
  "reason": "The release checklist is complete."
}

El agente puede preparar esa solicitud después de realizar un descubrimiento sin restricciones dentro de su alcance permitido. La persona debe aprobar el cambio, no reconstruir toda la investigación del agente. Conserva el motivo porque facilita las revisiones posteriores, pero no lo trates como un control de seguridad. Un agente puede producir una frase convincente para un objetivo incorrecto.

Evita las políticas de aprobación basadas únicamente en la intención expresada en lenguaje natural. «Aprobar cambios de despliegue» parece razonable hasta que un agente etiqueta la eliminación de una base de datos como un cambio de despliegue. Vincula la aprobación a una clase de operación, un alcance de objetivos y una credencial. El texto ayuda a las personas a entender la solicitud. Los límites tipados de las acciones evitan las discrepancias.

La eliminación y la ejecución externa necesitan su propia categoría

La eliminación, los cambios de permisos, la rotación de credenciales, las operaciones financieras y las llamadas que activan sistemas externos deben recibir un tratamiento más estricto que las actualizaciones normales. Pueden eliminar vías de recuperación, cambiar quién tiene acceso, generar costes o provocar trabajos fuera del sistema donde comenzó el agente.

No escondas la eliminación dentro de la categoría general de mutaciones. Un parche que corrige la etiqueta de una incidencia suele poder revertirse fácilmente. Una llamada de eliminación puede borrar archivos adjuntos, registros secundarios, historial o un entorno concreto. La API puede poner en cola una limpieza asíncrona después de devolver un resultado correcto, lo que significa que el operador no siempre puede deshacer el error con una única solicitud compensatoria.

Exige un control individual específico para acciones como estas:

1. Eliminar, purgar, archivar cuando el archivo cambie la disponibilidad y eliminar en bloque.
2. Cambiar permisos, miembros, roles, secretos, credenciales y políticas de acceso.
3. Desplegar, reiniciar, escalar, migrar y ejecutar comandos remotos.
4. Enviar correos, publicar mensajes, abrir incidencias externas e iniciar trabajos de pago.

Antes de que la aprobación llegue a una persona, obliga al agente a resolver los identificadores en una vista previa. Una solicitud de eliminación contra records?filter=status=inactive debe mostrar el número exacto, el filtro y nombres representativos. Mejor aún, haz que el agente obtenga primero los identificadores candidatos y envíe una lista que la puerta de enlace compare con la solicitud de ejecución. Esto no elimina las condiciones de carrera, pero detecta el error más común: que un filtro signifique algo distinto de lo que el agente suponía.

También es razonable exigir una confirmación limitada en el tiempo. Si un operador aprobó una solicitud destructiva hace una hora, el agente no debería usar esa aprobación después de que cambie el estado del entorno. Vincula la aprobación a un único cuerpo de solicitud o a un resumen inmutable de la solicitud, no a una categoría amplia como «eliminar el acceso de hoy».

SSH requiere una clasificación a nivel de comando

SSH es más difícil de clasificar que una API bien diseñada porque una línea de comandos puede combinar inspección y mutación, llamar a un shell, seguir alias o cambiar su comportamiento según el entorno remoto. No puedes considerar un host completamente de solo lectura porque el agente pretenda ejecutar un comando de lectura.

Empieza con comandos y argumentos explícitos. git status --short, git log -n 20 --oneline y kubectl get pods -n staging son acciones de descubrimiento plausibles cuando limitas el directorio de trabajo, el contexto del clúster y el espacio de nombres. git push, kubectl apply, kubectl delete, rm, la instalación de paquetes y los reinicios de servicios pertenecen a las categorías de mutación o ejecución destructiva.

Rechaza la composición de shells para el descubrimiento sin supervisión. Este es el tipo de comando que parece una solicitud de listado, pero devuelve el control al shell:

find "$WORKDIR" -maxdepth 2 -type f -name '*.log' -print; $EXTRA_COMMAND

Aunque durante las pruebas el agente proporcione un EXTRA_COMMAND vacío, un valor posterior puede ejecutar cualquier acción permitida por la identidad SSH. No apruebes una gramática de comandos que contenga ;, &&, ||, sustitución de comandos, redirecciones, expansión de comodines sobre rutas no controladas o una invocación de intérprete, salvo que la propia acción se revise como una ejecución.

Usa argumentos estructurados. Una puerta de enlace puede aceptar una acción llamada list_recent_logs, validar un directorio fijo y un límite numérico y construir después el comando remoto. El agente nunca debería enviar una cadena de shell cuando puede utilizar una acción tipada.

El mismo principio se aplica a las herramientas con verbos de lectura. kubectl get puede filtrar datos secretos si el recurso y el espacio de nombres son demasiado amplios. git show puede revelar una credencial que se confirmó por error. Define los permisos de los comandos según el ejecutable, el subcomando, los argumentos, el directorio de trabajo y la identidad remota. El verbo por sí solo dice muy poco.

Los registros de auditoría deben demostrar que el límite se mantuvo

Un registro de auditoría debe permitir que un revisor responda quién realizó una llamada, qué ruta de credenciales utilizó la acción, a qué objetivo llegó, si una persona la aprobó y qué devolvió el sistema remoto. Si el registro solo indica «el agente invocó una herramienta», no puede demostrar que el acceso de descubrimiento permaneció separado de la autoridad de mutación.

Registra tanto las acciones intentadas como las completadas. Una solicitud de eliminación denegada es importante. Puede indicar que el agente no entendió su alcance, que una inyección de instrucciones intentó desviarlo o que alguien está probando el límite. Registra el motivo de la denegación sin escribir secretos ni cuerpos de respuesta sensibles en un registro con un acceso más amplio que el sistema original.

Para cada acción, captura al menos estos campos en un registro resistente a manipulaciones:

• Identidad del proceso del agente e identificador de sesión.
• Clase de acción: descubrimiento, mutación, destructiva o ejecución externa.
• Identidad del objetivo, método de solicitud o forma del comando y una representación segura de los parámetros.
• Evento de aprobación, incluida la persona que aprobó cuando era necesario.
• Resultado, estado remoto, referencia del resultado y marcas de tiempo.

Una cadena de hashes ayuda a detectar modificaciones del registro, pero no hace útil un evento impreciso. Guarda un registro canónico de la acción antes de ejecutarla y vincula después el registro de respuesta con él. Si el registro solo dice POST /jobs, un revisor seguirá sin saber si el agente inició un informe inofensivo o una exportación costosa.

Sallyport proyecta las sesiones y los diarios de llamadas desde un único registro de auditoría cifrado y encadenado mediante hashes, y sp audit verify comprueba la cadena sin conexión y sin necesitar acceso a la bóveda. La verificación solo sirve si la taxonomía de acciones hace inteligible el evento, así que mantén la clasificación cerca de la ruta de ejecución en lugar de añadir etiquetas más tarde en una capa de informes.

Prueba el límite con fallos, no solo con casos correctos

Una separación de permisos merece confianza cuando bloquea las solicitudes incorrectas que puedes prever. Trata cada acción de descubrimiento como un contrato comprobable y ejecuta casos negativos cada vez que cambien la API, el envoltorio de comandos o el flujo de trabajo del agente.

Para una ruta HTTP de descubrimiento, prueba un objetivo permitido, otro vecino que esté prohibido, un método no compatible, una solicitud de página demasiado grande y una consulta que intente cruzar el límite de un inquilino o proyecto. Espera denegaciones concretas. Un error genérico del servidor ofrece pocas pruebas, porque puede convertirse en un resultado correcto después de un cambio menor del código.

Para una ruta de mutación, prueba que una solicitud válida se detenga para pedir aprobación, que el cambio de cualquier campo relevante invalide la aprobación y que un segundo proceso de agente no herede el permiso de sesión del primero. En las eliminaciones, prueba selectores vacíos, selectores parecidos a comodines, listas mayores de lo esperado y objetivos que hayan desaparecido entre la vista previa y la ejecución.

Conserva un ejemplo completo para cada clase de acción. Un buen ejemplo debe ser lo bastante breve para que un revisor lo lea y lo bastante concreto para revelar una discrepancia:

09:14:03  discovery  GET /projects/acme/services?limit=20  allowed
09:14:05  discovery  GET /projects/acme/services/api-7/events  allowed
09:14:11  mutation   POST /projects/acme/services/api-7/restart  approval required
09:14:32  mutation   POST /projects/acme/services/api-7/restart  approved by operator
09:14:34  mutation   result: accepted, operation=op_481

Si la tercera línea dijera GET /services/api-7?action=restart, tu modelo de clasificación ya habría encontrado un defecto. Corrige el contrato de la acción o mantén esa ruta bajo el control de mutaciones. No crees una excepción porque el endpoint sea incómodo.

Empieza por las acciones externas que tus agentes ya realizan. Marca cada una según su efecto, verifica su comportamiento real, limita el objetivo y prueba los casos de denegación. Cuando el agente pida hacer algo nuevo, exige una clasificación explícita antes de que la acción llegue a producción. Esa pequeña pausa cuesta menos que intentar explicar después un cambio que nadie revisó.