Rota credenciales detrás de una pasarela de acciones con pruebas

Sustituir un token API o una identidad SSH que está a punto de caducar debería ser aburrido. Se vuelve peligroso cuando cada agente, perfil de shell, secreto del repositorio y herramienta local conserva su propia copia. En esa situación no rotas una sola credencial. Buscas un número desconocido de copias, esperas haberlas encontrado todas y rompes el trabajo en lugares que nadie pensó probar.

Una pasarela de acciones cambia el problema. La pasarela conserva la credencial, realiza la solicitud externa y devuelve el resultado al agente. La rotación pasa a tener una única ubicación que contiene el secreto, un único cambio controlado y pruebas que separan la sesión del agente de la identidad que utilizó. Esa separación importa especialmente durante un incidente, cuando es fácil confundir «este proceso envió la solicitud» con «este proceso tenía el token».

He visto equipos dar por terminada una rotación porque un nuevo valor apareció en un gestor de secretos. Después descubrieron que una clave de despliegue antigua seguía en el archivo authorized_keys de una cuenta, o que una variable de entorno local olvidada mantenía activo un token API caducado. Una rotación termina solo cuando el reemplazo ha demostrado que la ruta de acción prevista funciona y la identidad retirada ya no puede autenticarse.

Rotar es cambiar una identidad, no sustituir una cadena de texto

La rotación de credenciales sustituye una identidad autenticadora por otra y demuestra que el acceso se trasladó como estaba previsto. Pegar un token nuevo en un campo es solo una operación dentro de ese cambio.

Mantén diferenciados estos cuatro elementos en tus notas y herramientas:

• La identidad externa: un token API, un secreto de cliente, un par de claves SSH o una credencial de cuenta de servicio aceptada por un proveedor.
• El registro de credenciales: la entrada cifrada que almacena la identidad y los detalles de uso.
• El objetivo de autorización: la cuenta de API, el repositorio, la cuenta de máquina, el host o el extremo de red que la acepta.
• La sesión del agente: el proceso concreto que solicitó una acción.

La gente suele mezclar el primer y el cuarto elemento. Ese error produce informes de incidentes deficientes. Una sesión de agente puede haber llamado a un extremo mediante una pasarela, pero no necesitaba leer el token portador para hacerlo. A la inversa, un token filtrado puede ser utilizado por un proceso que nunca aparece en el registro del agente. Son investigaciones distintas, con medidas de contención distintas.

La misma diferencia se aplica a la caducidad. Un proveedor puede hacer caducar un token en una hora concreta, mientras el registro de la pasarela permanece perfectamente sano como dato almacenado. El registro no caduca por arte de magia. Debes sustituir la identidad externa antes de que el proveedor la rechace, validar la nueva identidad y retirar la antigua.

La Publicación Especial 800-57, Parte 1 del NIST trata los periodos criptográficos como algo más que recordatorios del calendario. Su análisis relaciona ese periodo con la exposición, el uso y el riesgo de compromiso. Ese es también el enfoque adecuado para las credenciales API y SSH. Un token que concede amplios permisos de escritura, se utiliza con frecuencia o tiene una propiedad poco clara merece una vida planificada más corta que una identidad de alcance limitado para una sola tarea de lectura. No conviertas esto en un ritual que cambie cadenas cada viernes mientras conserva permisos excesivos.

Una declaración clara de rotación debería decir: «La sesión del agente de compilación utilizó el registro de credenciales deploy-api-prod para esta solicitud. Ese registro cambió del token del proveedor cuyo identificador termina en 4K2 al token cuyo identificador termina en P9M. El token anterior se revocó después de que el nuevo registro completara la acción prevista». No debe incluir el token.

Coloca el secreto en un solo lugar antes de que la caducidad te obligue a hacerlo

No puedes controlar la rotación mientras las credenciales sigan en indicaciones para agentes, archivos de repositorios, variables de shell y configuraciones copiadas. Primero debes consolidarlas, aunque la fecha de caducidad esté cerca.

Empieza con un inventario que siga el uso, no solo el almacenamiento. Pregunta a cada equipo qué llamadas externas y destinos SSH puede realizar un agente. Para cada respuesta, registra la cuenta del proveedor o la cuenta del host, el tipo de credencial, el responsable, la acción prevista, el alcance, el comportamiento de caducidad y si la credencial aparece en algún otro lugar. El último campo es donde empieza el trabajo desagradable.

Un análisis del repositorio puede encontrar errores evidentes, pero no demostrar que no existan copias. Busca nombres de variables de entorno, claves de configuración, plantillas de despliegue, rutas copiadas de claves privadas y documentación que indique a la gente que pegue un token en la configuración de un agente. Revisa también las definiciones de herramientas del agente. Si una herramienta acepta token, api_key, authorization o el contenido de una clave privada como argumento, el agente todavía puede transportar secretos aunque otro sistema conserve una copia.

En HTTP, la forma prevista es sencilla: el agente proporciona una acción y datos normales de la solicitud, mientras la pasarela selecciona la credencial almacenada e inyecta el material de autorización solo cuando envía la solicitud. Una llamada de herramienta del agente podría contener conceptualmente esto:

{
  "credential": "deploy-api-prod",
  "method": "POST",
  "url": "https://api.example.internal/releases",
  "headers": {"Content-Type": "application/json"},
  "body": {"revision": "a81c2f"}
}

No debe contener un token portador, ni siquiera bajo un nombre de campo amable. Devolver una cabecera de autorización en el resultado de una herramienta es el mismo fallo a la inversa. Redáctala en el límite de la acción, no después en una transcripción de chat.

En SSH, el agente debe solicitar una conexión mediante un registro de credenciales y un destino con nombre. No debe recibir un bloque de clave privada, un archivo temporal de clave privada ni instrucciones para buscar en ~/.ssh. Una clave privada en el directorio de trabajo de un agente sobrevive en cachés, historiales del editor, archivos comprimidos y, a veces, en un commit. He limpiado suficientes archivos de ese tipo como para considerar que «temporal» no tiene ningún significado de seguridad.

Sallyport guarda las claves API y SSH en una bóveda cifrada dentro de la aplicación para macOS y después ejecuta acciones HTTP y SSH sin exponer el secreto al agente. Así tienes un único registro que cambiar, pero aún debes encontrar y eliminar las copias antiguas que existían antes del traslado.

Asigna a cada credencial un responsable y un propósito

Una credencial puede tener más de un usuario legítimo, pero necesita un único responsable y un propósito declarado. La responsabilidad compartida suele ser una forma amable de decir que nadie comprueba la caducidad, el alcance o la retirada.

Nombra los registros de modo que un operador pueda identificar el límite de autorización sin ver material secreto. billing-write-prod dice más que token-final-2. github-deploy-repo-a dice más que automation-key. Incluye el entorno cuando afecte al destino y evita insertar el nombre de una persona cuando la credencial pertenece a una función de servicio. Las personas se van; el propósito del servicio debe seguir siendo comprensible.

No coloques destinos no relacionados detrás de un token compartido solo para reducir el número de registros. Ese atajo resulta atractivo porque una sola renovación parece sencilla. Provoca tres fallos:

1. No puedes saber qué destino obligó a hacer la rotación.
2. Un aumento del alcance para un uso amplía el acceso de todos los demás.
3. Revocar la identidad durante un incidente interrumpe trabajos no relacionados.

Un registro puede admitir un conjunto estrechamente relacionado de acciones contra una cuenta de proveedor cuando el alcance y el responsable son realmente los mismos. Trátalo como una decisión explícita, no como la opción predeterminada. Si el publicador de compilaciones y el trabajo de exportación de soporte necesitan permisos distintos, necesitan identidades distintas aunque ambos llamen a la misma API.

SSH exige la misma disciplina. Una clave SSH vinculada a una cuenta de despliegue en un grupo de hosts no debe servir también como clave para acceder a bases de datos de producción solo porque ambos usos emplean SSH. Siempre que sea posible, aplica las restricciones en el servidor: una cuenta específica, un comando limitado, una restricción de origen cuando la red lo permita y un comentario claro en la clave autorizada. Un comentario no impone el acceso, pero hace visible la clave antigua que queda cuando alguien revisa authorized_keys bajo presión.

El manual de authorized_keys de OpenSSH documenta opciones como command=, restrict y from=. Solo son útiles si pruebas la ruta exacta que necesita la automatización. He visto que una entrada restrict bien intencionada rompía el reenvío de puertos del que dependía silenciosamente un trabajo de despliegue. Es mejor descubrir ese fallo durante una rotación planificada que a medianoche. No añadas a ciegas todas las restricciones disponibles; añade las que correspondan a la acción que has definido.

Usa un periodo de solapamiento con un final programado

Mantén activas las credenciales antigua y nueva solo el tiempo necesario para validar el reemplazo y recuperarte de un cambio fallido. El solapamiento es una medida de seguridad, no un modo de funcionamiento permanente.

Algunos proveedores permiten varios tokens API o varias credenciales de cliente activas. Crea primero el reemplazo, registra un identificador que sea seguro conservar y cárgalo en el registro de la pasarela. Después realiza una acción inocua mediante la misma ruta que usará el agente normalmente. Puede servir un extremo de lectura, crear un borrador en un proyecto de prueba o solicitar la identidad de quien llama, siempre que esa acción compruebe el alcance necesario y la cuenta de destino.

No dependas de un extremo genérico de «token válido» si el agente normalmente publica versiones o modifica tickets. Un token puede ser válido y, aun así, carecer del alcance de escritura, apuntar a una cuenta de pruebas o fallar porque la pasarela inyecta el tipo de cabecera incorrecto. Prueba el método, la familia de URL, la cuenta y la forma del contenido reales con un objeto inocuo.

Define la hora de revocación de la credencial antigua antes de probar. Si no puedes indicar esa hora, no tienes un periodo de solapamiento. Has creado otra credencial permanente.

Una secuencia práctica sería:

1. Crea la nueva credencial del proveedor con el alcance necesario y una política de caducidad conocida.
2. Actualiza el único registro de la pasarela y conserva la credencial anterior solo durante el solapamiento declarado.
3. Ejecuta una acción limitada mediante una sesión de agente autorizada o una sesión de prueba controlada por un operador.
4. Verifica el resultado en el proveedor y revisa el registro de acciones para confirmar la sesión y el destino esperados.
5. Revoca o elimina la credencial antigua y repite una vez más la acción limitada.

La prueba final después de la revocación no es una formalidad. Detecta el caso incómodo en el que tu prueba utilizó en silencio el token antiguo porque una variable de entorno, una configuración de proxy o un registro de credenciales diferente tuvo prioridad. Ocurre más a menudo de lo que la gente admite.

Si un proveedor solo permite una credencial API activa, no puedes tener un solapamiento real. Programa una ventana de cambio, captura una acción de referencia antes del cambio, sustituye el secreto en la pasarela, ejecuta inmediatamente la prueba limitada y mantén disponible al responsable de la cuenta para emitir un reemplazo si el proveedor lo rechaza. No «soluciones» la falta de solapamiento colocando el token nuevo en la configuración del agente por adelantado.

Valida la ruta que realmente sigue el agente

Una prueba de rotación debe ejercitar la pasarela, la selección de credenciales, la construcción de la solicitud, la autorización remota y el tratamiento del resultado. Probar cada componente por separado deja huecos justo donde se esconden los errores de credenciales.

En HTTP, haz que la solicitud de prueba sea lo bastante específica como para reconocerla en los registros del proveedor. Usa un token de idempotencia cuando la API lo admita o crea un objeto desechable claramente etiquetado. Comprueba que el proveedor informa de la cuenta o entidad prevista. Después confirma que el registro de acciones contiene una llamada coincidente, el destino, el resultado y la referencia de sesión, sin imprimir credenciales.

Una prueba genérica de shell sirve para aislar el comportamiento del proveedor, pero demuestra menos de lo que muchos creen:

curl -sS -D /tmp/headers.txt \\
  -H "Authorization: Bearer $NEW_TOKEN" \\
  https://api.example.internal/v1/whoami

El resultado esperado suele incluir un estado 200 en /tmp/headers.txt y un cuerpo que identifica la cuenta de servicio. Eso indica que el proveedor acepta el token. No demuestra que la pasarela de acciones inyecte la misma cabecera, seleccione el registro correcto o impida que el agente vea $NEW_TOKEN. Usa esta prueba solo bajo el control de un operador y elimina la variable del shell al terminar. Nunca pegues un token real en un ticket ni en una grabación de terminal guardada.

En SSH, prueba con el mismo nombre de host, usuario y forma de comando que necesita la automatización. La siguiente comprobación de clave pública ayuda a diagnosticar la autorización del servidor sin revelar material privado en la salida:

ssh -o BatchMode=yes -o IdentitiesOnly=yes \\
  [email protected] 'id && test -w /srv/releases && echo write-ok'

BatchMode=yes hace que un fallo de autenticación termine en lugar de esperar una contraseña interactiva. IdentitiesOnly=yes impide que el cliente SSH pruebe todas las claves no relacionadas cargadas en un agente. No consideres que un inicio de sesión correcto con ssh deploy@host demuestra que la acción de despliegue funciona. La cuenta remota puede aceptar un shell y rechazar el comando, el directorio o la restricción de comando forzado que utiliza el trabajo.

El manual de ssh de OpenSSH explica que IdentitiesOnly limita las identidades que ofrece el cliente. Esa opción detecta un resultado positivo falso habitual en los equipos de desarrollo: el agente local funciona con una clave personal cargada en un agente de autenticación, mientras la nueva clave de automatización fallaría en producción. En un diseño con pasarela, realiza la comprobación equivalente mediante la ruta SSH de la pasarela, donde la clave seleccionada no deja lugar a dudas.

Prueba también los fallos. Intenta deliberadamente una solicitud con un método no autorizado o un comando SSH fuera de los permisos de la cuenta prevista. Debes obtener una denegación clara del sistema remoto y una entrada precisa en el registro. Si una credencial supuestamente limitada funciona en una acción no relacionada, detén la rotación y reduce su alcance antes de retirar la identidad antigua.

La rotación de SSH falla en el servidor cuando sobreviven claves públicas antiguas

Sustituir una clave privada SSH en una bóveda no revoca la clave antigua. El servidor seguirá aceptando la identidad anterior hasta que elimines su clave pública de todas las fuentes de autorización que confían en ella.

SSH complica el inventario porque las claves públicas pueden aparecer en varios lugares: ~/.ssh/authorized_keys, un servicio de gestión de identidades, una configuración de metadatos de una instancia en la nube, una plantilla de gestión de configuración o la interfaz de claves de despliegue de un proveedor. Encuentra la fuente de verdad antes de cambiar nada. Si la gestión de configuración vuelve a escribir authorized_keys, una eliminación manual de emergencia reaparecerá en la siguiente ejecución.

Genera una identidad de reemplazo con las herramientas aprobadas y guarda su parte privada solo en el límite de la pasarela. Instala la nueva parte pública junto a la antigua. Añade a cada entrada un comentario que identifique el propósito y la fecha de rotación y, después, pruébala mediante la ruta prevista. Cuando funcione, elimina la entrada pública antigua de la fuente de verdad y confirma que el servidor la rechaza.

Puedes inspeccionar la huella de una clave pública sin exponer una clave privada:

ssh-keygen -lf deploy-release-ed25519.pub
# 256 SHA256:exampleFingerprint deploy-release-2025 (ED25519)

Importa más la estructura de la salida que la huella de ejemplo: longitud en bits, huella, comentario y tipo de clave. Incluye la huella real en el registro del cambio. No pongas las opciones de autorización que rodean la clave pública en una captura de pantalla imprecisa. Copia la regla exacta del servidor en la configuración revisada para que otro operador pueda ver si contiene un comando forzado o una restricción de origen.

Después realiza una prueba negativa con la clave antigua antes de destruir la última copia controlada. El servidor debería rechazarla después de eliminarla. Si no puedes hacer la prueba porque ya no tienes la clave privada antigua, inspecciona en su lugar la fuente autorizada de claves y los registros de auditoría del proveedor. Indica esa limitación en el registro. Fingir que probaste una revocación es peor que documentar una comprobación incompleta.

Evita rotar una clave SSH sobrescribiendo un archivo en la misma ruta y reiniciando un cliente desconocido. Los procesos de larga duración pueden mantener conexiones abiertas, los agentes SSH pueden ofrecer una identidad antigua y un ayudante puede almacenar en caché un descriptor de archivo. Un ayudante de acciones sin estado reduce esta ambigüedad porque cada conexión empieza con una selección conocida. Lo importante es el comportamiento observable, no un lenguaje de implementación concreto.

Mantén separados la autorización y la rotación

La aprobación para que un agente ejecute una acción es distinta de la aprobación para que use una credencial concreta en cada llamada. Tratarlas como el mismo control provoca fatiga de aprobaciones o deja las identidades sensibles demasiado expuestas.

Un control de sesión responde: «¿Puede este proceso de agente recién iniciado realizar acciones durante esta ejecución?». Sirve para detectar un proceso nuevo antes de que obtenga acceso externo. Un control por llamada responde: «¿Puede utilizarse esta credencial concreta ahora?». Es apropiado para un pago, una versión de producción o una credencial cuyo alcance haga que cada uso merezca una comprobación humana.

No pidas a una persona que apruebe cada lectura de estado inofensiva solo porque el proceso de rotación de credenciales ha puesto nervioso a todo el mundo. La gente aprueba avisos repetidos e idénticos sin leerlos. Usa aprobaciones frecuentes para identidades cuyas acciones individuales requieren criterio y una aprobación de sesión claramente limitada para el resto. La rotación no debe enseñar a los operadores a pulsar avisos sin leerlos.

La escala de decisiones de Sallyport mantiene absoluta la puerta de la bóveda y, de forma predeterminada, autoriza a un nuevo proceso de agente para su sesión, con la opción de exigir una aprobación para cada uso de una credencial seleccionada. Durante la rotación, esto permite que un operador autorice la sesión de prueba y exija confirmación explícita para la nueva credencial de producción hasta finalizar el cambio.

La puerta de la bóveda tiene una función independiente. Una bóveda bloqueada debe denegar las acciones sin importar lo que una sesión de agente pudiera hacer antes. Así el operador tiene un bloqueo firme durante una posible filtración o un cambio que empieza a comportarse de forma inesperada. Eso no revoca la credencial del proveedor. Después de bloquear el acceso, revoca o desactiva también la identidad externa si alguien pudo copiarla fuera de la pasarela.

Conserva una nota breve de quién aprobó una prueba de producción excepcional y por qué. No conviertas las notas de aprobación en un diario. Bastan la identidad de la sesión, la hora, el registro de credenciales, el destino y la referencia del cambio para conectar la aprobación con el evento de rotación.

Las pruebas de auditoría deben responder a dos preguntas distintas

Un registro de rotación útil puede responder tanto a «¿qué hizo el agente?» como a «¿podemos confiar en el registro?». Un registro de aplicación corriente suele responder mal a ambas preguntas después de que alguien haya editado archivos, borrado una línea o mezclado llamadas rutinarias con un incidente.

La primera pregunta necesita campos operativos: identidad de sesión, autoridad de firma del código o identidad del proceso cuando esté disponible, hora, tipo de acción, destino, nombre del registro de credenciales, resultado y una referencia de solicitud del proveedor si existe. El registro no debe conservar tokens portador, contraseñas, claves privadas ni cabeceras completas que contengan secretos. Los registros con credenciales convierten a cada lector del registro en otro poseedor de credenciales.

La segunda pregunta se refiere a la integridad. Decir que un registro es de solo anexado no basta si un administrador puede reescribir el registro de ayer. Una cadena de hashes hace que cada entrada dependa de la anterior, de modo que un verificador puede detectar eliminaciones o modificaciones al comprobarla. No demuestra que una acción nunca ocurriera ni convierte entradas falsas en verdaderas. Sí dificulta mucho presentar modificaciones silenciosas como el registro original.

Aquí resultan útiles los registros separados de sesiones y actividades. Un registro de sesiones responde qué proceso de agente recibió autoridad y si alguien revocó esa ejecución. Un registro de actividad responde qué acciones HTTP o SSH individuales ocurrieron durante ella. Si un token API rota a las 14:00, puedes examinar las llamadas que usaron el registro antes y después del cambio sin tratar cada aprobación de sesión como prueba de cada solicitud.

Sallyport proyecta ambas vistas desde un registro de auditoría cifrado y de escritura ciega, y puede verificar su cadena sin conexión con sp audit verify, sin necesitar la clave de la bóveda. Ejecuta la verificación antes y después de una rotación sensible y conserva el resultado junto al registro del cambio. Una verificación correcta indica que la cadena registrada es internamente coherente; no sustituye la revisión de los destinos y resultados reales.

Para una rotación de alto riesgo, reúne estas pruebas en una entrada compacta:

• Por qué cambió la credencial y quién es responsable del objetivo de autorización.
• Identificadores seguros de las credenciales antiguas y nuevas del proveedor, además del final previsto del solapamiento.
• La acción de validación limitada y su resultado en el proveedor.
• Las referencias de sesión y actividad del agente implicadas en la validación.
• La prueba de revocación de la identidad antigua o la limitación documentada de esa comprobación.

Ese registro permite a un investigador posterior distinguir un cambio normal planificado de una credencial nueva inexplicable. También deja al descubierto una comprobación de revocación ausente antes de que pasen meses.

Trata una posible filtración como una contención antes de hacer el reemplazo

Cuando sospeches que un agente ha visto o exportado un secreto, detén primero el acceso. Crear un token de reemplazo sin desactivar el expuesto deja disponible la ruta antigua para quien lo haya copiado.

Bloquea la pasarela de acciones si necesitas una contención local inmediata, revoca las sesiones activas de agentes que ya no deban operar y desactiva o revoca la credencial del proveedor. Conserva las pruebas relevantes de sesiones y actividades antes de que los trabajos de limpieza eliminen el contexto. Después emite una identidad nueva con un alcance limitado al trabajo que deba reanudarse.

No esperes a tener pruebas perfectas de que el valor se filtró. Un token en una transcripción de agente, un historial de shell, un commit del repositorio, un registro de compilación o un chat copiado basta para considerarlo expuesto. En el caso de una clave privada SSH, elimina la clave pública correspondiente de todas las fuentes de confianza y busca copias del material privado en los lugares donde la automatización escribe artefactos. Rotar una clave privada mientras su clave pública antigua sigue autorizada no es contención.

Cuando el servicio vuelva, identifica cómo cruzó el secreto el límite. Las causas habituales son dolorosamente corrientes: un parámetro de herramienta aceptaba credenciales sin procesar, un registro de depuración imprimía cabeceras de solicitud, un desarrollador copió un archivo de entorno local en el espacio de trabajo del agente o un cliente alternativo evitó la pasarela. Corrige esa ruta antes de declarar cerrado el incidente. De lo contrario, el reemplazo iniciará su propia cuenta atrás hacia la siguiente filtración.

Convierte la caducidad en una prueba operativa programada

Un recordatorio del calendario debería activar una prueba repetible, una comprobación de propiedad y una decisión de revocación. No debería generar una petición de pánico para que alguien pegue un token nuevo en el archivo de configuración que funcionó por última vez.

Revisa cada registro de credenciales antes de la fecha de caducidad del proveedor. Confirma que el responsable indicado sigue siendo responsable de la cuenta externa, que el propósito documentado continúa existiendo, que los alcances todavía coinciden con la acción y que las sesiones de agente seleccionadas siguen necesitando acceso. Si alguna respuesta es negativa, retira la identidad en lugar de rotarla.

En el caso de las identidades que siguen siendo necesarias, ensaya pronto la acción de validación limitada para detectar cambios en la cuenta del proveedor, nuevas restricciones SSH o permisos API modificados. Conserva el registro del ensayo separado de la rotación real para que nadie confunda una prueba anterior correcta con una demostración de que el reemplazo actual funciona.

La prueba incómoda es la que detecta más defectos: después de revocar la credencial antigua, repite exactamente la acción de la que depende el agente y comprueba que el registro la atribuye a la sesión y al registro previstos. Si la prueba falla, tienes un fallo contenido, con un responsable, pruebas y una ruta de recuperación conocida. Es mucho mejor que descubrir una credencial caducada en plena ejecución autónoma de un despliegue.