Catálogo de acciones de agentes de IA: encuentra los accesos que no necesitas

Un catálogo de acciones de un agente de IA es la forma más rápida de encontrar permisos que nadie eligió conscientemente. Enumera las operaciones que un agente puede realizar fuera de su propio espacio de trabajo y obliga a tomar una decisión sobre cada una: quién es responsable, qué ocurre si algo sale mal y si debe aprobarla una persona.

La mayoría de los equipos empieza por el lugar equivocado. Inventarían las claves API, las integraciones o las cuentas de software y luego concluyen que entienden el acceso. No es así. Una credencial es un contenedor. La decisión de seguridad vive en el nivel de la operación: «crear una factura en borrador» es muy distinto de «emitir un reembolso», aunque ambas llamadas utilicen el mismo token.

He visto fracasar revisiones de permisos porque un equipo preguntó: «¿El agente necesita acceso al sistema de facturación?». La pregunta es demasiado amplia para responderla con honestidad. Pregunta si necesita leer una sola factura, crear un borrador, enviar un reembolso, actualizar los datos de pago o exportar la lista de clientes. Las respuestas suelen ser distintas. El acceso innecesario aparece precisamente en esas diferencias.

Una lista de integraciones oculta los permisos importantes

Un inventario de sistemas indica dónde se conecta un agente. Un catálogo de acciones indica qué puede provocar. Conserva ambos, pero no confundas uno con el otro.

Piensa en un agente conectado a un servicio de control de código fuente. «Acceso al repositorio» puede incluir leer código, abrir una solicitud de cambios, modificar la protección de ramas, crear una clave de despliegue, publicar una versión o eliminar un repositorio. Tratar todo eso como un único permiso convierte varias decisiones de riesgo independientes en un sí o no perezoso.

El mismo error aparece con SSH. «El agente puede conectarse por SSH a staging» no dice casi nada. Un comando limitado que consulta el estado de un servicio tiene consecuencias muy distintas del acceso a un shell con una cuenta capaz de reiniciar servicios, leer secretos de despliegue o modificar reglas del cortafuegos. Cataloga la familia de comandos o el endpoint, no solo el medio de transporte.

La diferencia importa porque la exposición tiene tres dimensiones que los equipos suelen mezclar:

• Accesibilidad indica si el agente puede contactar con un sistema.
• Autoridad indica qué permitirá el sistema después del contacto.
• Consecuencia indica qué puede ocurrir si el agente realiza una solicitud equivocada o manipulada.

Un endpoint interno puede tener una accesibilidad baja y una autoridad muy alta. Una API pública puede tener una accesibilidad amplia y una autoridad limitada. Diseñar aprobaciones basándose solo en si un servicio es «interno» hará que se pasen por alto ambos casos.

La publicación especial 800-53 del NIST, en el control AC-6, describe el mínimo privilegio como conceder únicamente el acceso necesario para cumplir las tareas asignadas. La frase parece obvia hasta que se aplica a un agente. «Tarea asignada» no puede significar «ayudar con ingeniería». Debe significar una operación con un objetivo, un método, un límite y un resultado esperado. Si no puedes escribirlo, no puedes afirmar que aplicas el mínimo privilegio.

Empieza con nombres de acciones que un revisor pueda entender sin abrir un repositorio de código. «POST /v1/issues» es una prueba útil, pero «crear una incidencia en el gestor de ingeniería» indica al responsable qué está aprobando. Conserva ambas formas en el registro.

Crea una fila para cada operación visible desde el exterior

Cada fila del catálogo debe representar la acción más específica que pueda recibir una decisión de acceso o aprobación independiente. Si dos operaciones podrían tener razonablemente responsables, impactos o requisitos de aprobación diferentes, necesitan filas separadas.

Una fila práctica contiene suficiente detalle para que un ingeniero implemente el control y suficiente lenguaje sencillo para que el responsable del sistema pueda rechazarla. Usa estos campos:

No escribas «varios», «tareas de administración», «API completa» o «según sea necesario» en el campo de operación. Esas frases indican que el catálogo se detuvo antes de que empezara el trabajo. Divide la entrada hasta que una persona pueda decir sí o no sin adivinar.

Este es un ejemplo compacto para un agente de desarrollo:

action_id: issue-tracker.create-bug
system: issue tracker, production tenant
operation: Create a bug report in the Engineering project
technical_route: POST /api/projects/engineering/issues
identity: service account agent-issues, scope issues:write
inputs: title, body, labels, repository reference
outputs: issue ID and URL
impact: internal write, reversible by project members
owner: Engineering operations manager
approval: per-session
review_date: 2026-09-30

La expresión «production tenant» pertenece a esta fila aunque la acción solo cree tickets. Muchos equipos utilizan un único tenant de producción de un SaaS para información real de clientes, empleados e incidentes. La etiqueta del entorno indica a los revisores qué límite están cruzando.

Evita la falsa precisión. No necesitas una fila distinta para cada actualización de un campo inofensivo cuando el destino, el responsable, la identidad, la aprobación y la consecuencia son realmente idénticos. Sí necesitas filas separadas cuando un campo especial cambia el resultado. «Actualizar el estado de un incidente» y «cambiar al responsable del incidente» pueden viajar por un mismo endpoint, pero no deberían recibir la misma decisión de aprobación.

Descubre las acciones siguiendo las credenciales y los flujos de trabajo

No encontrarás todo el conjunto de acciones leyendo el prompt de un agente. Los prompts describen la intención; el código, la configuración, las credenciales y el tráfico observado muestran lo que el agente puede solicitar realmente.

Empieza por los flujos de trabajo que esperas que el agente realice. Pide a los ingenieros que describan las diez últimas tareas que le dieron o quieren darle, usando verbos. «Investigar una compilación fallida» puede ampliarse a leer registros, consultar un servicio de despliegue, abrir una incidencia, reiniciar un entorno de pruebas y publicar un mensaje. Registra cada límite externo que se atraviesa.

Después, trabaja hacia atrás desde cada credencial. Inspecciona los scopes de API, las concesiones OAuth, los roles de las cuentas de servicio, las claves autorizadas de SSH, los envoltorios de comandos, las variables de CI y los almacenes locales de secretos. Una credencial suele revelar operaciones que nadie mencionó durante la conversación sobre el flujo de trabajo. Un token API con permisos de administración de usuarios es una acción candidata aunque el equipo insista en que el agente solo crea tickets.

Por último, compara la intención con las pruebas. Las trazas de red, los registros de la puerta de enlace API, las auditorías de comandos y las definiciones de herramientas del agente revelan llamadas que el documento del flujo de trabajo no contemplaba. Hazlo primero en un entorno de pruebas seguro cuando sea posible. Los registros de producción también importan porque los agentes y las personas suelen descubrir atajos bajo presión.

Usa esta rutina de recopilación en cinco pasadas:

1. Enumera cada flujo de trabajo del agente que sale de la tarea local.
2. Extrae de la configuración y el código del agente cada llamada a herramienta, endpoint y patrón de comando de shell.
3. Enumera lo que permite cada credencial, incluidos los roles heredados y los scopes comodín.
4. Revisa los registros recientes de acciones para encontrar destinos o verbos ausentes de la lista.
5. Reconcilia las diferencias con la persona responsable del sistema de destino.

La cuarta pasada es donde aparecen los hallazgos incómodos. Puedes descubrir un token antiguo con administración amplia de repositorios, una clave SSH de staging aceptada por hosts de producción o un webhook «interno» capaz de activar una versión. No reduzcas silenciosamente la entrada para que encaje con el plan original. Incluye la operación efectiva en el catálogo y haz que alguien decida si debe permanecer.

Una prueba útil consiste en entregar una fila a un compañero que no haya creado la integración. Debería poder explicar qué envía el agente, qué recibe y cuál es el peor error razonable. Si no puede, la fila es un residuo técnico, no un registro de control.

El impacto necesita consecuencias, no una puntuación de riesgo genérica

Clasifica el impacto según lo que una acción equivocada cambie, exponga, gaste o comprometa. Una sola valoración de «alto, medio o bajo» falla porque oculta por qué una acción necesita atención humana.

Yo uso cinco categorías de consecuencias en el catálogo: divulgación, integridad, disponibilidad, compromiso externo y cambio de privilegios. Una fila puede tener más de una. Leer una exportación de clientes implica una consecuencia de divulgación. Eliminar un despliegue cambia la disponibilidad. Añadir un administrador cambia los privilegios. Enviar un contrato crea un compromiso externo aunque la acción sea técnicamente reversible.

Añade dos modificadores: reversibilidad y alcance. La reversibilidad pregunta si una persona competente puede deshacer la acción sin pérdidas ni confusión. El alcance pregunta si un error afecta a un borrador, un proyecto, muchos usuarios o todo un entorno.

Así obtendrás decisiones que las personas pueden defender. «Eliminar una rama temporal de pruebas» puede ser un cambio de integridad, reversible y limitado. «Rotar las credenciales de la base de datos de producción» puede preservar la seguridad y, al mismo tiempo, afectar a la disponibilidad de muchos servicios. Ambas son acciones de escritura, pero pertenecen a categorías de aprobación diferentes.

No dejes que «la API permite deshacerlo» resuelva la reversibilidad. Un reembolso puede revertirse en un libro contable mientras el cliente ya ha recibido un correo confuso. Un paquete publicado puede retirarse mientras los sistemas posteriores ya lo han descargado. Una cuenta eliminada puede restaurarse mientras su antiguo propietario pierde el acceso durante un incidente. Considera la consecuencia operativa, no solo la operación de base de datos.

Los datos devueltos por una acción merecen la misma atención que los datos enviados. Una consulta de estado aparentemente inofensiva que devuelve todas las variables de entorno, transcripciones de soporte o claves privadas es una acción de divulgación. Los equipos suelen concentrarse demasiado en la capacidad de escritura de un agente porque escribir parece una actividad. Un agente que puede leer todos los secretos y después llamar a un endpoint externo tiene acceso suficiente para causar un incidente grave.

Mantén concreto el lenguaje del impacto. Sustituye «alto impacto» por «puede cambiar la autorización de producción para todos los miembros del espacio de trabajo» o «puede transmitir identificadores de clientes a una API de terceros». La primera descripción indica al responsable qué debe decidir. La etiqueta por sí sola no.

La responsabilidad debe recaer en quien puede decir que no

Cada acción necesita un responsable identificado que pueda denegarla, reducirla o eliminarla. Esa persona es responsable de la decisión sobre el permiso, no de todos los resultados operativos que produzca el agente.

El mejor responsable suele pertenecer al sistema de destino o asumir la consecuencia de negocio. Un líder de ingeniería puede ser responsable de las acciones de despliegue en producción. Finanzas puede ser responsable del envío de reembolsos. El equipo de seguridad puede definir las condiciones para administrar accesos, pero no debe convertirse en el responsable predeterminado de cada línea por el simple hecho de ser el equipo de seguridad.

La responsabilidad compartida es donde los catálogos se deterioran. «Seguridad e ingeniería» significa que cada grupo supone que el otro hará la revisión. Registra a una sola persona responsable y añade los equipos consultados en las notas si los necesitas. Si un responsable cambia de puesto o de equipo, transfiere las filas del catálogo como parte de ese relevo.

Los responsables necesitan un paquete de decisión que quepa en una pantalla. Dales la operación, el sistema, la identidad efectiva, los datos implicados, la consecuencia, la aprobación propuesta y una breve razón por la que el agente la necesita. No les entregues una lista de scopes OAuth sin procesar y la llames gobernanza.

El responsable debe responder cuatro preguntas:

• ¿El agente necesita este resultado o el flujo de trabajo simplemente lo encuentra conveniente?
• ¿Puede un endpoint, rol, cuenta, objetivo o comando más limitado proporcionar el resultado?
• ¿Qué error produciría una consecuencia inaceptable?
• ¿Quién debería aprobar el uso y cuándo debería caducar esta decisión?

La primera suele ser la pregunta incómoda. Los equipos suelen conceder una operación amplia porque así evitan una conversación futura. Eso no es un requisito. Es una revisión de acceso aplazada con una credencial adjunta.

Haz visible la responsabilidad en el flujo de ejecución. Si nadie puede identificar al responsable durante un incidente, el catálogo no cumplió su función. Un responsable identificado también hace posible la revisión periódica, porque la revisión plantea una pregunta directa: «¿Sigues autorizando la acción X para este agente y esta identidad?»

La aprobación debe coincidir con el momento del compromiso

La aprobación es útil cuando aparece antes del punto en que un agente provoca una consecuencia y cuando el revisor puede entender qué está permitiendo. Un botón que dice «permitir el uso de la herramienta» después de que el agente haya agrupado diez operaciones sin relación es teatro de seguridad.

Usa tres estados de aprobación en el catálogo. «Ninguna» significa que la acción puede continuar después de que el agente haya obtenido la autoridad de su sesión. «Por sesión» significa que una persona aprueba un proceso específico del agente antes de que pueda llamar a las acciones autorizadas. «Por llamada» significa que una persona revisa cada uso de esa acción.

La aprobación por sesión encaja con acciones limitadas y rutinarias de consecuencias moderadas, como leer el estado de una compilación o crear incidencias internas en borrador. Confirma que el proceso de agente previsto está activo y le permite completar el trabajo ordinario sin pedir a una persona que confirme avisos repetitivos.

La aprobación por llamada encaja con acciones que crean un compromiso o cruzan un límite difícil. Úsala para cambiar accesos de producción, eliminar registros importantes, activar despliegues que afecten a clientes, enviar mensajes fuera de la empresa, gestionar dinero y exportar conjuntos de datos sensibles. Aquí es apropiado exigir que una persona inspeccione cada solicitud.

El registro de aprobación necesita contexto. Como mínimo, muestra la identidad del proceso que llama, la operación, el destino, el entorno objetivo y los parámetros importantes. «El agente solicita POST» obliga al revisor a reconstruir la acción bajo presión. «Reiniciar el servicio de pagos en producción, solicitado por el proceso firmado X» le ofrece una decisión que puede tomar.

No uses avisos de aprobación para compensar un permiso que no debería existir. Un aviso por llamada para «ejecutar cualquier comando de shell en producción» sigue dejando al revisor la tarea de aprobar repetidamente un cheque en blanco. Sustituye la capacidad amplia de shell por comandos limitados u operaciones separadas y aprueba esas operaciones cuando sea necesario.

La puerta de enlace de acciones importa porque puede mantener las credenciales lejos del agente y situar la decisión humana cerca de la ejecución. Sallyport utiliza una escala fija de decisiones: una bóveda bloqueada rechaza todas las acciones, un proceso de agente nuevo obtiene por defecto una autorización por sesión y algunas claves pueden exigir aprobación en cada uso.

Esta estructura evita un error habitual: inventar un lenguaje de reglas enorme antes de haber catalogado las acciones con suficiente precisión para escribir reglas seguras. Las políticas complejas parecen maduras en un documento de diseño y se vuelven imposibles de revisar cuando llegan las excepciones. Empieza con operaciones claras, identidades limitadas y aprobaciones que correspondan al impacto.

Un catálogo muestra la ruta del fallo antes de que llegue a producción

Un catálogo demuestra su utilidad cuando detecta una cadena de decisiones ordinarias que parece aceptable por separado. Imagina un agente de programación al que piden investigar por qué falló un flujo de pedidos.

Un ingeniero le entrega un token de servicio porque el token puede leer registros. El mismo token también tiene permiso para consultar la API de pedidos. El agente encuentra un pedido mal formado y recibe la instrucción de «limpiar los datos de prueba». Llama a un endpoint de eliminación contra el tenant de producción porque la integración no distinguía claramente los nombres de los tenants. El endpoint acepta la solicitud. Más tarde, una persona descubre que el pedido era real, pero restaurarlo requiere reconciliar los sistemas de pagos, inventario y soporte al cliente.

Cada frase aislada parecía inofensiva: leer registros, consultar pedidos, eliminar datos de prueba. El catálogo de acciones habría dividido la cadena en filas:

La conclusión útil no es «los agentes cometen errores». Las personas cometen la misma cadena de errores cuando los límites de acceso son imprecisos. Los agentes ejecutan más rápido, reintentan con mayor facilidad y pueden seguir una instrucción que parece razonable en el contexto inmediato sin percibir el contexto de negocio que una persona inferiría.

Escribe las rutas de fallo en las notas de las filas de mayores consecuencias. Usa un formato sencillo: activador, objetivo o interpretación incorrecta, acción realizada, efecto inmediato y esfuerzo de recuperación. Esto hace que las decisiones de aprobación sean menos abstractas y da a los revisores una razón para rechazar el acceso amplio.

Un catálogo también detecta combinaciones peligrosas. Leer notas de incidentes puede ser aceptable. Publicar en una página de estado pública puede ser aceptable con revisión. Permitir que un mismo agente haga ambas cosas sin un límite de contenido puede exponer detalles internos del incidente. Revisa las combinaciones en las que una acción proporciona información sensible y otra envía datos fuera de la organización.

Haz que el catálogo se pueda aplicar y demuestra que coincide con la realidad

Un catálogo que vive solo en una hoja de cálculo se convierte en una lista de deseos de permisos. Conecta cada fila aprobada con un límite técnico: una credencial separada, un scope de API restringido, una lista permitida de destinos, un comando SSH limitado o una configuración de aprobación.

Usa los IDs de acción en la configuración y los registros. Así tendrás una prueba sencilla: cada acción externa observada debería corresponder a un ID del catálogo y cada ID activo del catálogo debería corresponder a un punto de aplicación vigente. Investiga ambas discrepancias. Una acción observada sin fila es acceso oculto. Una fila sin aplicación puede ser un plan antiguo o una ruta sin control.

Para las llamadas HTTP, verifica el método, el host, el patrón de ruta, el entorno de destino y el alcance de la credencial. Para SSH, verifica la cuenta, el grupo de hosts, las restricciones de comandos y si el asistente puede pasar argumentos arbitrarios. «El acceso SSH está aprobado» no es una afirmación aplicable técnicamente.

Por ejemplo, esta entrada del catálogo afirma que el agente solo puede consultar el estado de un despliegue:

Action ID: deploy.status.read
Host: deploy.internal.example
Command: deployment-status --service <approved-service>
Identity: agent-deploy-read
Approval: per-session

Esta implementación contradice esa afirmación:

command="/usr/local/bin/deployment-status $SSH_ORIGINAL_COMMAND" ssh-ed25519 AAAA... agent

El envoltorio pasa un comando original arbitrario como argumento. Si deployment-status invoca un shell o acepta una opción no validada, el límite del catálogo es ficticio. Un diseño más seguro asigna un nombre de servicio aprobado a un comando fijo y rechaza cualquier otra entrada. Prueba deliberadamente la ruta de rechazo.

case "$1" in
  checkout) exec /usr/local/bin/deployment-status --service checkout ;;
  search) exec /usr/local/bin/deployment-status --service search ;;
  *) echo "service not permitted" >&2; exit 1 ;;
esac

No copies ese fragmento a ciegas en una configuración de authorized-keys. Sirve para ilustrar la propiedad que necesitas: el agente elige entre acciones definidas, no entre comandos arbitrarios. Tu entorno también necesita validación de entradas, restricciones de cuentas y pruebas realizadas por alguien que entienda el comportamiento del comando.

Como evidencia de cada acción, registra una prueba que demuestre ambos lados del límite. Una prueba positiva demuestra que la llamada aprobada funciona. Una prueba negativa demuestra que una llamada prohibida cercana falla. Los equipos suelen conservar solo la prueba positiva, por eso las credenciales amplias sobreviven en silencio.

Sallyport registra las sesiones de los agentes y las llamadas individuales en un único registro de auditoría cifrado y encadenado mediante hashes. Su comando sp audit verify puede verificar esa cadena sin conexión sobre el texto cifrado y sin acceso a la clave de la bóveda. Esa evidencia ayuda a reconciliar el catálogo con el comportamiento real, pero no sustituye la decisión de retirar una acción innecesaria.

Revisa el acceso cuando cambie el trabajo, no después de una sorpresa trimestral

Revisa el catálogo cuando añadas una herramienta, modifiques un flujo de trabajo del agente, emitas o rotes una credencial, cambies al responsable de un sistema o descubras un casi incidente. Esos eventos cambian el acceso efectivo. Esperar a una revisión del calendario permite que las suposiciones antiguas persistan mientras se acumulan integraciones.

Fija de todos modos una fecha de revisión para cada fila. Las operaciones de mayores consecuencias merecen un intervalo más corto que las lecturas internas inofensivas. Una revisión no debe preguntar si la hoja de cálculo sigue existiendo. Debe preguntar si el agente todavía necesita esa operación exacta, si la identidad sigue siendo limitada, si el responsable continúa siendo el correcto y si el uso observado justifica conservarla.

Elimina las acciones sin uso de forma decidida. Los equipos se resisten porque temen que el agente necesite el permiso más adelante. Si ocurre, vuelve a añadirlo mediante la misma decisión del responsable y de aprobación. Conceder de nuevo una operación conocida requiere menos esfuerzo que limpiar una acción que nunca debería haber sobrevivido.

El primer catálogo útil no necesita una cobertura perfecta. Elige un agente, enumera todas las operaciones externas que puede realizar hoy y obliga a un responsable a decidir sobre cada fila. Encontrarás accesos que existen porque nadie había tenido que darles un nombre. Ese es el acceso que conviene retirar antes de que se utilice en el peor momento posible.