Alias de credenciales para agentes de IA: acciones locales más seguras

Los agentes deben solicitar una conexión por su nombre, no recibir la credencial que permite usarla. Parece una pequeña decisión de diseño de API. En realidad, marca la diferencia entre un agente que puede actuar dentro de unos límites y un proceso de agente que guarda un puñado de secretos reutilizables.

He visto equipos llamar GITHUB_TOKEN a un secreto, colocarlo en el entorno de un agente y felicitarse porque la interfaz de la herramienta parecía ordenada. El token sigue llegando a la memoria del proceso, al historial del shell, a la salida de depuración, a los procesos secundarios y, a veces, a las propias notas de trabajo del agente. Cambiar el nombre de lo expuesto no reduce la exposición.

Los alias de credenciales para agentes de IA funcionan cuando un ejecutor local de confianza resuelve un nombre de conexión breve y fácil de leer y realiza por sí mismo la solicitud autenticada. El agente solicita repo-release-prod; el ejecutor inyecta la credencial en el momento de uso; el agente recibe un código de estado, un cuerpo de respuesta filtrado para eliminar secretos o la salida del comando. El secreto nunca se convierte en entrada ni en salida del ciclo del agente.

Este límite debe diseñarse con más cuidado del que suelen recibir las primeras versiones. Un alias puede ofrecer un identificador operativo claro, una rotación sencilla y registros de auditoría útiles. También puede convertirse en una etiqueta decorativa sobre permisos amplios y permanentes si no defines qué permite el nombre, quién puede invocarlo y cómo detenerlo.

Un alias nombra permisos, no una cadena oculta

Un alias de credenciales útil nombra una conexión de servicio con una finalidad concreta. No nombra una base de datos de secretos que el agente pueda explorar ni promete que toda solicitud que incluya el alias sea aceptable.

Piensa en payments-prod. Ese nombre es demasiado impreciso para un agente autónomo. ¿Permite leer facturas, emitir reembolsos, editar datos de cuentas o descargar informes? Un único token bearer podría hacer técnicamente todo eso, pero el alias no debería borrar la distinción. Los nombres más claros expresan la intención operativa: payments-invoice-read-prod y payments-refund-review-prod indican al operador qué está a punto de autorizar y hacen que un registro de auditoría siga siendo comprensible seis meses después.

La gente suele mezclar tres conceptos distintos:

• Una referencia de secreto identifica material almacenado, como una ruta de una bóveda o un ID de secreto.
• Un alias de credenciales identifica una conexión autenticada que se puede utilizar.
• Un nombre de capacidad identifica una operación permitida, como publicar una versión o leer un registro de compilación.

En una configuración pequeña pueden coincidir uno a uno, pero no deberían convertirse accidentalmente en el mismo concepto. Una referencia de secreto puede apuntar a un token que permite llamar a muchos endpoints. Una conexión puede necesitar un token más un certificado de cliente. Una capacidad puede requerir conexiones distintas en entornos diferentes. Si los combinas, la rotación, la revisión y la respuesta ante incidentes se vuelven más difíciles porque nadie puede saber qué parte cambió.

Prefiero alias que incluyan el servicio de destino, el entorno y el trabajo, pero omitan el tipo de credencial. artifact-publish-prod es mejor que artifact-api-token-2. El primer nombre seguirá siendo válido si migras de un token estático a un intercambio de corta duración. El segundo introduce un detalle de implementación en cada prompt del agente, llamada de herramienta, prueba y guía operativa.

No permitas que los agentes enumeren todos los alias de forma predeterminada. Una lista de nombres de conexiones suele revelar nombres de servicios internos, entornos y flujos de trabajo privilegiados. Además, enumerarlos convierte a un agente limitado en un agente curioso. Proporciona a cada tarea el pequeño conjunto de nombres que necesita o expón una herramienta orientada a operaciones que seleccione la conexión internamente.

Un secreto fuera del contexto debe mantenerse fuera de todas las rutas

Mantener el token fuera del prompt principal del modelo es necesario, pero está muy lejos de ser suficiente. Una credencial se escapa cuando cualquier componente del árbol de procesos al que el agente puede acceder consigue leerla o convencer a otro componente de imprimirla.

Considera un diseño fallido habitual. Un agente de programación llama a un helper local con connection=deploy-prod. El helper busca un token de API y después inicia un cliente de línea de comandos con ese token en una variable de entorno. El comando falla. Un wrapper de diagnóstico imprime su entorno en un archivo de registro. El agente tiene acceso al sistema de archivos del directorio de registros del espacio de trabajo y lee el token para explicar el fallo.

Nadie pretendía revelar el secreto. La arquitectura lo hizo porque el helper trató una variable de entorno como un canal privado. No lo es frente a procesos secundarios, informes de fallos, diagnósticos ni comandos que puedan inspeccionar su propio entorno. Poner credenciales en los argumentos de comandos es todavía peor, porque la inspección de procesos y el historial del shell pueden exponerlas.

El ejecutor local debe guardar la credencial en su propio almacenamiento protegido, construir la solicitud autenticada en memoria y devolver un resultado limitado deliberadamente. Para HTTP, normalmente esto significa que añade por sí mismo el encabezado de autorización. Para SSH, significa que selecciona la clave privada o invoca un helper capaz de usarla sin entregar al agente la ruta ni el contenido del archivo de clave.

La ruta de respuesta merece la misma atención. Algunas API devuelven credenciales al crear tokens, los webhooks pueden repetir datos de autorización y los informes de errores pueden incluir encabezados de solicitudes. El ejecutor necesita una política de respuesta que elimine los encabezados conocidos que contienen secretos y evite reflejar cómo construyó su propia solicitud. Esto no es motivo para reescribir silenciosamente los datos de negocio. Es motivo para decidir qué partes de una solicitud y una respuesta tiene derecho a ver el agente.

Una prueba limpia resulta más útil que un diagrama de diseño. Pide al agente que recupere el valor del alias, vuelque la configuración de las herramientas, provoque un error de autenticación, inspeccione los procesos secundarios en ejecución si puede y lea todas las ubicaciones de registros a las que tenga acceso. El resultado esperado es aburrido: encuentra un nombre y los resultados de las acciones, pero ningún token, contraseña, clave privada ni solicitud firmada reutilizable.

El alcance de la conexión debe ajustarse a la superficie de acción

Un alias solo es tan limitado como los permisos que hay detrás. Un token de administrador perfectamente oculto sigue siendo un token de administrador.

En los servicios HTTP, el alcance empieza con los permisos de la cuenta de servicio o del token. Da a un agente de versiones permiso para crear una versión y cargar el artefacto necesario. No le concedas administración del repositorio, pertenencia a la organización, acceso de facturación ni suplantación de usuarios porque podrían resultar útiles más adelante. Esa necesidad futura debe generar una revisión independiente y normalmente una conexión distinta.

Las restricciones de endpoints deben estar en el ejecutor cuando el modelo de autorización del propio servicio no pueda expresarlas. Aquí es donde los equipos suelen recurrir a un lenguaje de políticas grande. Parece flexible durante una demostración y se convierte en un problema de mantenimiento cuando un operador tiene que predecir si una solicitud desconocida será aceptada. Si necesitas restringir endpoints, hazlo de forma visible y sencilla: método permitido, host, familia de rutas y credencial esperada. Trata los cuerpos de solicitudes inusuales y las redirecciones como casos que requieren un diseño consciente, no como excepciones accidentales.

SSH necesita la misma disciplina, aunque sus controles tengan otro aspecto. Una clave que abre un shell interactivo ofrece al agente una superficie de acción enorme. Prefiere una cuenta que pueda realizar la tarea necesaria en un directorio limitado o un comando forzado que acepte la operación concreta que pretendes permitir. No supongas que un alias de host en ~/.ssh/config resuelve el problema. Ese alias elige un destino para el cliente, pero no limita lo que ocurre después de la autenticación.

El manual de authorized_keys de OpenSSH documenta opciones como command=, no-pty, no-port-forwarding y restrict. Son herramientas prácticas para conexiones entre máquinas. También tienen puntos delicados: un comando forzado debe validar sus argumentos, y una restricción que bloquee el reenvío de puertos no vuelve segura una cuenta de shell con permisos amplios. Lee primero los permisos efectivos de la cuenta. Después usa las opciones de SSH para reducir las rutas que no necesitas.

No uses un alias para staging y producción solo porque el endpoint cambie en un parámetro de URL. Un agente comete errores bajo presión igual que una persona. Los nombres separados permiten definir credenciales, tratamiento de aprobaciones y expectativas de auditoría diferentes. También impiden que una tarea de staging adquiera permisos de producción por un error de sustitución de cadenas.

El ejecutor debe autenticar al autor de la llamada antes de aceptar el alias

Un alias de credenciales no protege nada si cualquier proceso local puede invocarlo. El ejecutor necesita responder con claridad a una pregunta sencilla: ¿qué proceso solicitó esta acción?

Los identificadores de proceso por sí solos no son una identidad. Tienen una vida corta y pueden reutilizarse. El nombre del proceso es aún peor porque otro programa puede usar el mismo. En macOS, la autoridad de firma de código proporciona al aprobador más información sobre el ejecutable que hay detrás de una solicitud, aunque por sí sola no hace segura la acción solicitada. El operador todavía debe valorar si ese proceso firmado debería recibir esta conexión durante esta sesión.

La autorización por sesión funciona bien con agentes que emiten muchas llamadas relacionadas. La primera solicitud de un proceso de agente nuevo presenta la identidad del proceso que llama y la ejecución solicitada. La aprobación cubre ese proceso hasta que termina. Así no se obliga a una persona a aprobar una secuencia rutinaria de llamadas pequeñas, pero se conserva un límite entre ejecuciones distintas.

Algunos alias merecen una decisión en cada uso. El despliegue en producción, las operaciones destructivas de API y el acceso a datos de clientes son candidatos razonables. La pantalla de aprobación debe mostrar el alias, el destino, la operación y la identidad del proceso en un lenguaje claro. Pedir a la gente que apruebe un evento opaco es enseñarles a aceptarlo sin leer.

RFC 6749 establece una separación útil que los creadores de herramientas para agentes deberían conservar: el servidor de autorización emite tokens de acceso y el servidor de recursos los acepta. El agente no tiene por qué ser ninguno de los dos. En un diseño con ejecutor local, el ejecutor puede ser el componente que guarda u obtiene la credencial y envía la solicitud autenticada. El agente puede limitarse a solicitar una acción descrita de forma concreta. Es una separación más limpia que tratar al agente como un cliente OAuth general solo porque puede hacer llamadas HTTP.

Esto no significa que todos los agentes necesiten aprobación interactiva. Un worker de compilación controlado puede tener una conexión limitada y preaprobada. La cuestión es si puedes identificar al autor de la llamada y si los permisos coinciden con el trabajo asignado. Si ninguna de las dos respuestas es sólida, el alias solo ha ocultado una escalada de privilegios local detrás de una interfaz más amable.

La rotación debe cambiar el material sin romper el nombre

La ventaja operativa de los alias aparece durante la rotación. Sustituyes el token o la clave SSH que hay detrás de artifact-publish-prod; el agente sigue solicitando el mismo nombre de conexión; ningún prompt, archivo de código ni configuración del agente necesita la nueva credencial.

Eso no significa que un alias deba existir para siempre. Mantén estable el nombre solo mientras su significado siga siendo estable. Si un token pasa de acceso de solo lectura a acceso de escritura, el nombre antiguo ahora engaña. Si la responsabilidad pasa de un equipo a otro, las expectativas de aprobación anteriores pueden dejar de ser adecuadas. Si una credencial pasa de un tenant de pruebas a uno de producción, crea un alias nuevo aunque la API sea idéntica.

La secuencia de rotación debe demostrar las dos partes del cambio:

1. Añade la credencial de reemplazo detrás del alias existente y realiza una llamada de comprobación con alcance limitado a través del ejecutor.
2. Revoca o desactiva el material antiguo en el proveedor del servicio y repite la acción esperada del agente.
3. Inspecciona el registro de auditoría en busca de reintentos fallidos o autores de llamadas inesperados, porque los procesos antiguos suelen revelarse después de una rotación.
4. Elimina los archivos de credenciales copiados, las configuraciones de entorno antiguas y los scripts de emergencia que evitaban el ejecutor.

El último punto es donde las rotaciones suelen fallar en la práctica. Alguien crea un token temporal para mantener un lanzamiento en marcha, lo deja en una variable de CI o en un script local y lo olvida. La ruta cuidada del alias rota correctamente, mientras el bypass abandonado sigue funcionando. No has completado la rotación hasta encontrar y cerrar la ruta alternativa.

La OWASP Secrets Management Cheat Sheet aconseja rotar los secretos y aplicar el principio de privilegio mínimo. Ambas recomendaciones son correctas, pero suelen presentarse como prácticas de almacenamiento. Para los agentes, la rotación también protege la capa de instrucciones. Un alias estable significa que el contexto del modelo no contiene un secreto cambiante ni necesita una tarea de actualización de secretos que podría aparecer en transcripciones, mensajes de commit o salidas de herramientas.

Los registros de auditoría deben describir las decisiones sin guardar secretos

Los registros deben permitirte responder quién solicitó una acción, qué conexión solicitó, qué hizo el ejecutor y si se aprobó. Nunca deben convertirse en una copia cómoda de la bóveda de credenciales.

Un registro de evento práctico incluye una marca de tiempo, un identificador de sesión, la identidad del proceso que llama, el alias, el canal, el destino, el método o la clase de comando, la decisión de autorización y la clase de resultado. Para una llamada HTTP, registrar POST /releases suele bastar para explicar la acción. Registrar el encabezado Authorization completo nunca resulta útil y crea un grave problema de limpieza. Para SSH, registra el alias del host, la cuenta remota o la clase de comando y el estado de salida, no la huella de una clave privada si esa huella revela información sensible del inventario.

Mantén separados el registro de sesión y el registro de cada acción. Una sesión indica cuándo comenzó una ejecución del agente, qué proceso local la controlaba y si la revocaste. Los registros individuales indican qué ocurrió dentro de esa ejecución. Si los mezclas en un único flujo de actividad impreciso, revocar una ejecución sospechosa y encontrar sus acciones tardará más de lo necesario.

La evidencia de manipulación cambia la calidad de un registro de auditoría. Cualquiera que pueda modificar un archivo de solo adición puede editarlo fácilmente. Una cadena de hashes hace detectable una modificación posterior porque cada entrada incorpora el resumen de la entrada anterior. No impide la eliminación ni demuestra que un ejecutor malicioso haya registrado contenido veraz. Sí hace mucho más difícil presentar una reescritura silenciosa como si fuera el historial real.

Un comando de verificación útil tiene un contrato deliberadamente sencillo:

$ sp audit verify
verified 184 records
chain: valid
first record: 2025-04-03T09:14:22Z
last record:  2025-04-03T16:48:01Z

El número exacto y las marcas de tiempo serán diferentes. Lo importante es que la verificación lea el flujo de registros cifrado almacenado, compruebe la cadena e indique la posición no válida si alguien modifica un registro. La verificación sin conexión sobre texto cifrado resulta especialmente útil porque un investigador puede comprobar la continuidad sin abrir la bóveda ni exponer los detalles almacenados de las acciones.

No confundas la evidencia de manipulación con la supervisión. También necesitas revisar la actividad sospechosa, conservar copias cuando comience un incidente y decidir quién tiene autoridad para revocar sesiones. La criptografía puede decirte que una secuencia de registros cambió. No puede decirte que delete-production-data fuera una solicitud sensata.

La fatiga de aprobación indica un mal diseño de alias

Si una persona debe aprobar cada acción inofensiva, terminará aprobándolas sin leer. No es un problema de las personas. Es un sistema que no distingue entre permisos rutinarios y permisos con consecuencias.

Usa la aprobación de sesión para una ejecución de agente delimitada cuyos alias permitidos tengan un riesgo operativo normal. La aprobación debe identificar la autoridad de firma de código del proceso, porque una etiqueta como agent dice muy poco. Si el proceso termina, exige otra aprobación para el siguiente proceso. Esto contiene mejor una invocación de herramienta copiada que una aprobación única que permanezca válida indefinidamente.

Usa la aprobación por llamada para los alias cuya invocación merezca un examen individual. El ejecutor debe hacer que el evento de decisión sea lo bastante claro para que una persona pueda rechazarlo rápidamente. Usa payments-refund-review-prod para enviar una solicitud de reembolso para el pedido 4821 es una petición accionable. La llamada de herramienta requiere aprobación es un diseño perezoso.

Sallyport utiliza una escala fija de decisiones por este motivo: una bóveda bloqueada deniega todas las acciones, un proceso de agente nuevo requiere autorización de sesión de forma predeterminada y cada credencial puede requerir aprobación en cada uso. Evita un lenguaje de políticas porque los operadores locales no deberían tener que depurar un intérprete de autorizaciones antes de poder detener un agente.

No conviertas cada confirmación en un debate con el agente. Una aprobación es un punto de control, no un prompt conversacional. Rechaza la acción, revoca la sesión si la ejecución se ha desviado e inspecciona los registros anteriores. Si una tarea necesita aprobaciones excepcionales con frecuencia, revisa sus límites o crea una conexión más estrecha cuyos permisos coincidan con el trabajo recurrente.

Los alias no solucionan la inyección de instrucciones ni un mal diseño de tareas

El aislamiento de credenciales limita el daño del robo de secretos. No decide si un agente debe llamar a una API, cargar un archivo o ejecutar un comando remoto.

Una inyección de instrucciones oculta en una incidencia de un repositorio puede decirle a un agente que publique una versión, extraiga un informe a través de un endpoint permitido o use una conexión SSH para un comando que entre dentro de los permisos amplios de una cuenta. El alias cumplió su función si el atacante nunca obtuvo el token. Aun así, el agente puede ejecutar una acción permitida que resulte perjudicial.

Por eso un alias amplio es peligroso aunque el secreto nunca se filtre. cloud-admin-prod deja demasiado margen a una instrucción inyectada. artifact-publish-prod, junto con una cuenta de servicio restringida y un destino esperado, deja menos. Aun así, necesitas limitar los archivos que el agente puede leer, separar el contenido no fiable de las instrucciones de acción y exigir aprobación para las acciones cuyas consecuencias superen la tarea.

Otro diseño débil expone una herramienta genérica http_request junto con un parámetro de alias. El agente puede entonces dirigir una credencial potente a rutas arbitrarias, hosts después de redirecciones o endpoints que el operador nunca consideró. Una herramienta creada para una finalidad concreta, como create_release, tiene menos flexibilidad, pero a menudo eso es una ventaja de seguridad. La generalidad no es neutral cuando un agente sigue texto no fiable.

Trata cada alias como la respuesta a una frase que puedas escribir: «Este proceso identificado puede realizar esta clase de acción contra este destino, con este tratamiento de aprobación». Si no puedes escribir la frase sin palabras como «cualquier cosa» o «según sea necesario», la conexión necesita más diseño antes de entregársela a un agente.

Un ejecutor local debe ser sencillo y fácil de inspeccionar

El ejecutor tiene más permisos que el agente, así que debe hacer menos que el agente. Necesita almacenamiento cifrado de credenciales, un conjunto pequeño de canales de acción, identificación del autor de la llamada, gestión de decisiones y registro de auditoría. No necesita convertirse en una pasarela de acceso remoto, un proxy universal ni un lenguaje de reglas personalizado con cientos de excepciones.

En una configuración de desarrollo local, una aplicación de la barra de menús puede hacer visible el estado de la bóveda y las aprobaciones pendientes sin añadir otro servicio en segundo plano cuya existencia los operadores olviden. Eso no elimina la necesidad de una ingeniería cuidadosa. Sí concentra la operación sensible en un lugar que puede bloquearse, denegar solicitudes y mantener sus propios registros.

Sallyport guarda las claves de API y SSH en una bóveda local cifrada y ejecuta acciones HTTP y SSH en nombre de agentes compatibles con MCP, en lugar de pasar las credenciales al contexto del agente. Su adaptador sp mcp ofrece al agente una conexión stdio normal mientras la aplicación sigue siendo el ejecutor.

La facilidad de inspección significa que un operador puede responder preguntas básicas sin leer el código fuente durante un incidente: ¿Está bloqueada la bóveda? ¿Qué ejecución está activa? ¿Qué conexión solicitó? ¿Puedo revocar esa ejecución? ¿Ha cambiado la secuencia registrada? Si la respuesta exige combinar registros de cinco componentes distintos, el sistema puede ser ingenioso, pero no es manejable a las dos de la madrugada.

Mantén estrecho el protocolo de herramientas. Devuelve resultados estructurados de éxito y error. Evita mensajes de error que incluyan objetos de solicitudes internas o rutas de almacenamiento de secretos. Haz explícita la cancelación para que un usuario pueda detener una acción larga sin terminar trabajos no relacionados. Estas decisiones parecen normales. Marcan la diferencia entre un límite que puedes operar y un límite que solo esperas que exista.

Prueba el límite como un atacante que puede escribir prompts

Una demostración del caso ideal solo demuestra que el alias se resuelve. Antes de confiar en el diseño, prueba las formas en que un agente o un plugin comprometido intentaría convertir un nombre de conexión en un acceso más amplio.

Empieza con un alias que apunte a una cuenta de servicio de no producción. Ejecuta una tarea del agente que realice la llamada prevista y después dale instrucciones adversarias para inspeccionar los esquemas de las herramientas, solicitar volcados de configuración, provocar solicitudes malformadas, seguir redirecciones, iniciar comandos secundarios y leer los registros accesibles. Revisa tanto la transcripción visible como los registros del ejecutor. Busca material secreto, destinos inesperados y llamadas que eviten el límite de acción previsto.

Después prueba los fallos de forma deliberada. Bloquea la bóveda durante una solicitud. Revoca la sesión antes de la segunda llamada. Rota la credencial subyacente. Cambia un registro de auditoría en una copia y ejecuta la verificación. Cada fallo esperado debe ser claro para el operador y poco útil para un atacante. «Acceso denegado porque la bóveda está bloqueada» está bien. Un stack trace que contenga un registro de la bóveda o un valor de encabezado no.

Por último, prueba el caso operativo incómodo: una ejecución del agente está realizando un trabajo legítimo cuando su comportamiento se vuelve sospechoso. ¿Puede el operador identificar la ejecución, revocarla de inmediato, determinar qué llamadas ya tuvieron éxito y comprobar que la secuencia de registros no se ha editado? Si esas acciones requieren una búsqueda por terminales y paneles de servicios en la nube, corrígelo antes de añadir más alias.

Una conexión con nombre es una interfaz pequeña con consecuencias grandes. Haz que su nombre sea honesto, que sus permisos sean limitados, que su autor sea identificable y que sus registros resulten útiles. Después permite que el agente solicite acciones sin darle nunca un secreto que merezca la pena robar.