Hoja de trabajo de inventario de credenciales para agentes de programación con IA

Los agentes de programación con IA no deberían recibir un montón de credenciales heredadas junto con una instrucción vaga de tener cuidado. Antes de que un agente llame a una API, despliegue un servicio o abra una conexión SSH, alguien debe dejar constancia de qué alcanza la credencial, quién asume la responsabilidad y cómo la desactivará el equipo.

Una hoja de trabajo de inventario de credenciales parece una tarea administrativa hasta que un agente realiza veinte llamadas mientras su operador está lejos del teclado. Entonces se convierte en la diferencia entre revocar una capacidad conocida y desactivar a media organización de ingeniería porque nadie puede identificar el token. He visto equipos descubrir que su automatización de «staging» tenía un token de escritura en producción solo después de que un cambio automatizado llegara a un lugar al que no debía haber llegado.

El inventario debe describir la autoridad, no las cadenas secretas

Una hoja de trabajo de inventario de credenciales registra autoridad. No registra el token de API, el material SSH privado, la contraseña, el código de recuperación ni una exportación cifrada de ninguno de ellos. Si una hoja puede autenticar algo, se ha convertido en otro almacén de secretos, con controles de acceso más débiles y una audiencia mucho mayor.

La diferencia importa porque los equipos suelen confundir un identificador con una credencial. Los últimos cuatro caracteres de un token de API ayudan al operador a localizar la entrada correcta durante una rotación. No indican si puede eliminar un proyecto. La huella de una clave pública SSH identifica una identidad. No indica a qué cuenta de Unix permite acceder, si admite reenvío de puertos ni qué hosts confían en ella.

Usa una fila para cada autoridad que pueda revocarse de forma independiente. Una cuenta de proveedor puede necesitar varias filas: un token de informes de producción de solo lectura, un token de despliegue en staging, un token de administrador de emergencia que los agentes no pueden usar y un secreto de firma de webhook. Combinarlos en una sola fila oculta sus distintos riesgos y requisitos de rotación.

La misma regla se aplica a SSH. No escribas «Git y servidores» en una sola celda solo porque una clave privada funcione en ambos sitios. Una identidad de escritura en el control de código fuente y una identidad de inicio de sesión en un host tienen consecuencias distintas. Necesitan filas separadas, aunque la misma persona las haya creado la misma tarde.

NIST SP 800-57 Part 1 trata la gestión de claves criptográficas como un problema de ciclo de vida: generación, distribución, almacenamiento, uso, sustitución y destrucción requieren controles. El documento se centra en las claves criptográficas, pero su disciplina se aplica directamente aquí. Una lista que termina en «creamos un token» no es un inventario. Es una ayuda para la memoria que falla justo cuando el personal necesita registros fiables.

Da a cada credencial un responsable concreto

Cada fila necesita un responsable identificado que pueda responder «¿debería seguir existiendo esta autoridad?». No tiene que gestionar el administrador de secretos ni escribir la integración del agente. Sí necesita conocer suficientemente el sistema afectado para aprobar el acceso y asumir sus consecuencias operativas.

Evita valores como «plataforma», «equipo de desarrollo», «compartido» o el nombre de una persona que ya no trabaja allí. Un grupo puede gestionar un proceso, pero su nombre no indica a quién llamar a las dos de la madrugada durante un incidente. Registra un responsable principal y, si hace falta, uno de respaldo con autoridad para revocar o sustituir la credencial.

Separa cuatro funciones que los equipos suelen mezclar:

• El responsable del sistema decide si el acceso sigue siendo adecuado.
• El custodio de la credencial puede crearla, almacenarla, revocarla y rotarla.
• El operador del agente inicia o supervisa la ejecución.
• El contacto de incidentes gestiona un fallo urgente cuando las tres primeras personas no están disponibles.

Una misma persona puede ocupar varias funciones en un equipo pequeño. La hoja debe nombrarlas por separado. Cuando un token falla durante una publicación, el custodio puede corregir el almacenamiento, mientras el responsable del sistema decide si un reemplazo temporal merece el mismo alcance.

En una API de proveedor, la responsabilidad suele corresponder al equipo que paga u opera la cuenta, no al desarrollador que pegó el primer token en un archivo de configuración local. En el caso de SSH, normalmente corresponde al responsable del host o de la aplicación, no a quien generó el par de claves. Parece obvio, pero las credenciales huérfanas suelen empezar como un atajo razonable tomado por alguien que después cambia de equipo.

Añade una fecha de revisión distinta de la fecha de rotación del secreto. Un token puede seguir siendo técnicamente válido aunque su finalidad empresarial haya desaparecido. La revisión pregunta si el acceso debe existir. La rotación sustituye material que puede haber envejecido o quedado expuesto. Hacer una no completa la otra.

Escribe las acciones permitidas como verbos y objetivos

«Acceso a producción» no describe un permiso. Es una etiqueta de advertencia que no aporta nada útil al operador del agente. La hoja necesita verbos, recursos objetivo y límites que un revisor pueda comprobar.

Escribe los permisos con este formato:

verbo + objetivo + límite + acción prohibida

Por ejemplo:

• GET /v1/projects/acme/builds en staging; no realizar solicitudes al tenant de producción
• POST de revisiones de despliegue para el servicio catalog-api; sin rollback ni eliminación
• SSH como deploy en el grupo de hosts de compilación; ejecutar solo el comando de publicación aprobado; sin shell interactivo
• Crear comentarios de incidencias en el repositorio alpha; sin fusiones, eliminación de ramas ni cambios de configuración

Esto resulta más útil que una etiqueta amplia del proveedor como «escritura». Un agente que puede crear una revisión de despliegue y otro que puede eliminar un despliegue tienen permiso de escritura, pero su radio de impacto no se parece en nada.

Registra si la acción prevista consiste en leer, crear, modificar, eliminar, ejecutar o realizar un cambio administrativo. «Ejecutar» requiere especial cuidado. Una llamada API que inicia un trabajo en la nube, rota una credencial de servicio, activa una operación de pago o ejecuta un shell remoto puede parecer inofensiva en un registro de solicitudes y aun así provocar un resultado costoso o irreversible.

No conviertas la hoja en un documento legal lleno de expresiones imprecisas. «Usar solo cuando corresponda» y «tareas normales de despliegue» no establecen ningún límite. Una persona no puede aprobar basándose en ellas y un ingeniero no puede crear controles a partir de ellas. Si la acción depende del contexto, indícalo: un entorno, repositorio, grupo de hosts, cuenta o tipo de cambio concreto.

El atajo habitual consiste en conceder un token de administrador general y confiar en que las instrucciones del agente eviten las llamadas peligrosas. Es popular porque pone en marcha un prototipo en minutos. Es incorrecto porque las instrucciones no son un control de acceso y las llamadas posteriores a herramientas pueden heredar esa autoridad amplia sin que la persona que escribió las instrucciones se dé cuenta.

Los entornos necesitan filas y consecuencias separadas

Una credencial de staging y otra de producción nunca deberían compartir fila solo porque llamen a la misma API. Sus responsables pueden coincidir, pero la cuenta objetivo, la exposición de datos, el requisito de aprobación y la urgencia de revocación suelen ser distintos.

Trata el entorno como algo más que una etiqueta. Registra la cuenta o el tenant del proveedor, el endpoint o grupo de hosts, la clasificación de los datos y si una llamada puede cruzar la frontera entre entornos. «Prod» es demasiado impreciso cuando una organización tiene varias cuentas de producción, regiones o particiones de clientes.

Un campo de entorno útil podría ser:

production / tenant 4821 / datos de cuentas de clientes / endpoint api.example.internal

No incluyas un hostname interno real en una hoja que pueda leer mucha gente si el propio hostname es sensible. La idea es nombrar el objetivo con suficiente precisión para el equipo autorizado. La política de acceso al inventario debe corresponderse con la sensibilidad de sus detalles operativos.

Incluye un campo separado para los datos que el agente puede recibir en la respuesta. El permiso para llamar a un endpoint y el permiso para ver su respuesta están relacionados, pero no representan exactamente el mismo riesgo. Una solicitud de lectura puede devolver código fuente, datos de contacto de clientes, facturas, metadatos de acceso o un secreto incrustado en un valor antiguo de configuración.

Esto detecta un fallo frecuente. Un equipo crea una credencial de agente para «diagnósticos de solo lectura» en staging. Más tarde, durante un incidente, un ingeniero dirige el cliente de diagnóstico a producción porque la sintaxis del comando es idéntica. La credencial funciona porque el proveedor aplicó el alcance a toda la cuenta y el agente devuelve datos de clientes en su transcripción. La fila original habría mostrado el límite que faltaba si hubiera nombrado el tenant y los datos de respuesta en lugar de decir simplemente «lectura de diagnósticos».

Cuando un proveedor no puede aislar los entornos, no lo compenses con documentación optimista. Marca la credencial como transversal entre entornos, eleva su nivel de aprobación y decide si un agente debería usarla. A veces la respuesta honesta es no.

El acceso SSH necesita más detalle que el acceso API

Las credenciales SSH merecen sus propios campos porque una conexión SSH puede reunir varios tipos de autoridad. La cuenta de inicio de sesión, los hosts aceptados, las restricciones de comandos, los permisos de reenvío y el ajuste de reenvío del agente cambian lo que puede hacer la conexión.

Para cada fila SSH, registra la huella de la clave pública, la ubicación del material privado, la cuenta de inicio de sesión, el host o grupo de hosts y el comando exacto previsto. No copies la clave privada en la hoja. Una huella SHA256 basta para identificarla y los operadores pueden obtenerla localmente.

Ejecuta este comando sobre el archivo de clave pública:

ssh-keygen -lf ~/.ssh/id_agent_deploy.pub

Un resultado normal tiene esta forma:

256 SHA256:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcd agent-deploy (ED25519)

Guarda el valor SHA256: y el comentario solo si este ayuda a las personas a identificar la función. Los comentarios no son controles de seguridad. Cualquiera puede cambiarlos al copiar una clave pública.

Para los hosts objetivo, revisa las restricciones de authorized_keys en lugar de suponer que una cuenta de despliegue está limitada solo porque esa era la intención. OpenSSH documenta opciones como command=, no-port-forwarding, no-agent-forwarding y no-pty en el manual de sshd. Estas restricciones pueden convertir una identidad de automatización en un ejecutor de comandos limitado. No pueden reparar una credencial que inicia sesión como una cuenta de administrador sin restricciones.

Una entrada podría indicar: «inicio de sesión deploy, hosts del grupo de publicación A, comando forzado /usr/local/bin/release-catalog, sin reenvío de puertos, sin PTY y sin reenvío del agente». Si el acceso necesita un shell interactivo para tareas de emergencia, crea una identidad separada operada por personas. No reutilices discretamente la identidad del agente solo porque ya esté disponible.

La verificación del host también debe constar en el registro. Indica cómo comprueba la integración del agente la identidad del host, dónde viven las entradas de hosts conocidos y quién las actualiza después de sustituir legítimamente un host. Desactivar la verificación para superar una reconstrucción es una invitación a enviar una credencial válida a la máquina equivocada.

Una hoja útil obliga a responder preguntas difíciles

Copia esta plantilla en un documento controlado, un sistema de tickets o una base de datos de inventario. Elimina las columnas que tu equipo no pueda mantener, pero no quites los campos que establecen la autoridad, el alcance y la recuperación.

La columna ruta del agente obliga a plantear una pregunta útil: ¿cómo obtiene el agente el efecto de esta credencial? «Variable de entorno en el shell de programación» es una respuesta, pero debería incomodarte porque el proceso puede imprimirla, transmitirla o conservarla. «La pasarela de acciones realiza la solicitud y devuelve la respuesta» describe un diseño distinto, con una vía de exposición menor.

El campo método de revocación debe poder ejecutarlo otra persona. «Pregúntale a Sam» no es un método. «Desactiva el token en la configuración del proyecto del proveedor y después revoca la sesión activa del agente» sí lo es. Prueba esta instrucción cuando añadas la fila, antes de que un incidente haga que cada página de la consola resulte desconocida.

Evita un campo de estado que solo diga activo o inactivo. Incluye último uso, última revisión y retirada prevista. Una credencial sin uso no es inofensiva. Suele ser la que nadie recuerda revocar cuando termina un proyecto.

Los planes de rotación deben incluir reemplazo y comprobación

La rotación solo termina cuando la credencial antigua está desactivada y el reemplazo ha completado una acción prevista mediante la ruta real del agente. Crear un token nuevo, añadirlo al almacenamiento y prometer revisar el antiguo más tarde deja ambas identidades activas. Eso duplica el trabajo durante un incidente.

Un plan de rotación debe indicar cinco hechos operativos:

1. El evento que provoca la rotación, como una caducidad programada, la salida de un empleado, una posible exposición o un cambio de alcance.
2. La persona que crea el reemplazo y la que aprueba el cambio de autoridad.
3. El lugar donde se almacena el material nuevo sin que llegue al agente.
4. La acción de prueba limitada que demuestra que el reemplazo funciona.
5. El momento exacto en que se revoca el material antiguo y se registra la evidencia.

Usa una prueba limitada. Para una credencial HTTP, llama a un endpoint inofensivo que requiera el alcance previsto y confirma el estado y la forma de respuesta esperados. Para SSH, ejecuta el comando forzado de estado del despliegue contra el grupo de hosts aprobado, en lugar de probar con un inicio de sesión general en un shell.

Un registro de prueba puede ser tan sencillo como este:

Credential ID: api-catalog-deploy-prod-01
Replacement ID suffix: ...7KQ2
Test: POST /deployments/validate for catalog-api revision 8f3c
Expected: HTTP 200 with validation status accepted
Old credential revoked: provider audit event recorded
Reviewer: production service owner

No establezcas calendarios de rotación que tu equipo no pueda cumplir. Un intervalo corto con excepciones repetidas enseña a las personas a tratar el inventario como una ficción. Usa la caducidad del proveedor cuando exista, establece activadores basados en eventos y programa una frecuencia de revisión acorde con el riesgo. El acceso de escritura en producción, el acceso de lectura amplio a datos sensibles y el acceso SSH a hosts compartidos merecen más atención que un token de staging desechable sin datos sensibles en la respuesta.

Si sospechas que ha habido una exposición, revoca primero cuando el servicio pueda soportarlo. Los equipos pierden tiempo intentando demostrar si un token filtrado se copió desde un búfer de terminal, un registro de CI, una transcripción de indicaciones o el historial local. Rara vez necesitas esa prueba antes de detener la credencial. Conserva los registros, sustituye la credencial y después investiga la vía.

La aprobación del agente debe seguir las consecuencias de la llamada

Una ejecución de agente tiene un ciclo de vida que los scripts normales a menudo no tienen: una persona puede iniciarla, dejarla trabajando, regresar más tarde y descubrir que realizó muchas llamadas externas. Por eso la hoja debe indicar cuándo se aplica la autorización humana, no solo quién es responsable de la credencial.

La aprobación por sesión encaja con una ejecución contenida, un proceso de agente local identificado y de confianza, y consecuencias bajas o moderadas. Confirma que este proceso puede usar las autoridades indicadas mientras siga activo. No significa que todas las llamadas futuras tengan vía libre.

Exige aprobación en cada uso para operaciones que puedan publicar, desplegar, modificar datos de producción, acceder a respuestas muy sensibles o crear un nuevo compromiso externo. Un clic adicional cuesta menos que explicar a un cliente o al equipo financiero una acción no prevista. Usa una credencial separada para acciones con un nivel de aprobación distinto cuando el proveedor lo permita.

La aprobación no sustituye al alcance. Una persona puede aprobar algo incorrecto porque la descripción de la solicitud era imprecisa, la acción llegó durante un incidente o el agente realizó varias llamadas similares en rápida sucesión. Mantén primero los permisos limitados y usa la aprobación para cubrir el riesgo residual que el alcance no puede expresar.

Sallyport guarda las credenciales API y SSH en una bóveda cifrada del Mac y puede exigir autorización para un proceso de agente nuevo o para cada uso de una credencial seleccionada, mientras el agente recibe los resultados y no los secretos.

Una buena hoja relaciona cada fila de alto impacto con las evidencias de auditoría que esperas después del uso. Registra el identificador de sesión o la ubicación del diario de ejecución, el registro de actividad de cada llamada, el objetivo, la hora, el resultado y la persona que aprobó cuando corresponda. Si las evidencias no pueden decirte qué credencial se usó para obtener cada resultado, la integración del agente es demasiado opaca para la autoridad que le concediste.

Los registros de auditoría resuelven las dudas después de una mala ejecución

El inventario es un trabajo preventivo. Los registros de auditoría responden a otra pregunta después de que un agente se comporte de forma inesperada: ¿qué intentó realmente, qué tuvo éxito y qué autoridad lo hizo posible? No mezcles ambas funciones. Una hoja bien mantenida no puede demostrar que ocurrió una llamada y un registro no puede demostrar que un permiso estaba justificado.

Organiza un simulacro de incidente alrededor de una fila del inventario. Pide a un operador que localice al responsable, revoque la credencial, detenga el acceso actual del agente, identifique la última llamada correcta y verifique que el registro de auditoría no ha cambiado. Mide la confusión, no el tiempo transcurrido. Si las personas no pueden nombrar la cuenta objetivo o distinguir el token antiguo del reemplazo, corrige los campos de la hoja.

La evidencia contra manipulaciones importa cuando varias personas pueden consultar o exportar registros. Una base de datos sencilla de solo anexado puede ser modificada por un administrador con suficiente acceso y después presentarse como historial. Un registro encadenado mediante hashes permite detectar cambios no autorizados al verificar la cadena contra la secuencia almacenada. No hace que la solicitud original sea sensata ni impide que una persona autorizada realice una llamada incorrecta. Son controles distintos.

Mantén la decisión sobre la conservación de auditorías junto al registro del inventario, especialmente cuando las respuestas puedan contener información sensible. Un registro de actividad debe conservar contexto suficiente para investigar sin guardar despreocupadamente el contenido completo de los clientes para siempre. Almacena metadatos de la solicitud y el estado del resultado cuando sea posible; reserva la captura completa de la respuesta para los casos en que sea realmente necesaria y esté permitida.

La primera fila de credencial que deberías completar es la que un agente puede usar hoy para realizar un cambio en producción. Nombra el objetivo con precisión, concreta el verbo permitido, escribe la instrucción de revocación para que otra persona pueda seguirla y prueba la ruta de reemplazo. Si esa fila contiene suposiciones, el resto del inventario es decoración.