Problema

Los agentes generados por LLM que interactúan con AWS suelen necesitar leer valores almacenados en AWS Secrets Manager. En entornos donde la confidencialidad es crítica, exponer el texto plano del secreto al modelo representa un riesgo: cualquier salida del agente podría filtrarlo accidentalmente o, peor aún, un atacante podría inducir al modelo a revelar la información.

El patrón problemático es que, por defecto, el agente ejecuta la llamada GetSecretValue, captura el valor y lo inserta en su contexto antes de usarlo. Cuando el agente genera código o comandos que incluyen la variable, el secreto viaja dentro del prompt y queda registrado en logs de depuración, auditorías de modelo o incluso en la salida del propio agente.

El objetivo es impedir que el texto plano del secreto llegue al modelo, manteniendo la capacidad del agente de usar la credencial para operaciones autorizadas (por ejemplo, autenticarse contra un servicio externo). La solución debe ser reutilizable en cualquier proyecto que emplee Agent Toolkit for AWS y no depender de un caso concreto.

Causa

  1. Ausencia de filtro en tiempo de ejecución
    La arquitectura original del toolkit ejecuta herramientas (CLI, SDK, scripts) sin inspección previa. Cuando el agente construye un comando que incluye aws secretsmanager get-secret-value …, el valor se resuelve en la propia máquina del agente y luego se inserta en la cadena de texto que alimenta al modelo.

  2. Instalación incompleta del plugin
    El secret‑safety skill y su hook forman parte del plugin aws-core. Si el agente se inicializa mediante aws configure agent-toolkit, solo se descargan habilidades genéricas del catálogo; el plugin que contiene la protección no se carga automáticamente. Por eso muchos entornos “funcionan” pero siguen exponiendo secretos.

  3. Hook no persistente entre sesiones
    Los hooks (PreToolUse) se registran al iniciar la sesión del agente. Cambiar la configuración del plugin sin reiniciar la sesión deja el hook inactivo, lo que permite que la llamada a la herramienta se ejecute sin la verificación de seguridad.

  4. Permisos IAM insuficientes o demasiado amplios
    El agente necesita secretsmanager:GetSecretValue para leer el secreto, pero si la política permite también secretsmanager:PutSecretValue o DeleteSecret, el agente podría escribir o borrar secretos sin restricción. La protección de lectura no cubre estas acciones.

Solución

La estrategia combina dos capas que ya están disponibles en el toolkit:

  1. PreToolUse hook – intercepta la solicitud de herramienta antes de que se ejecute. Si la forma del comando coincide con un patrón de lectura de secreto no autorizado, el hook devuelve un mensaje de denegación y sugiere la ruta segura.
  2. Wrapper asm-exec con referencias dinámicas – el agente escribe un placeholder ({{resolve:secretsmanager:arn:…}}). asm-exec resuelve el placeholder en su propio proceso, entrega el valor solo a la herramienta y nunca lo inserta en el contexto del modelo.

Pasos de implementación

  1. Instalar el plugin aws-core

    aws configure agent-toolkit add-plugin aws-core

  2. Activar el skill y el hook

    aws agent-toolkit enable-skill secret-safety
aws agent-toolkit enable-hook PreToolUse

  3. Reiniciar la sesión del agente
    La mayoría de los clientes ofrecen un comando restart o simplemente cierran y vuelven a iniciar la CLI. Sin este paso, los hooks no se cargan.

  4. Usar la sintaxis de referencia segura
    En los prompts o scripts que el agente genere, sustituir cualquier llamada directa a aws secretsmanager get-secret-value por:

    asm-exec --command "aws secretsmanager get-secret-value --secret-id {{resolve:secretsmanager:arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret}}"

    asm-exec intercepta la referencia, llama a Secrets Manager, devuelve el valor al proceso y lo mantiene fuera del contexto del LLM.

  5. Ajustar políticas IAM
    Limitar al agente a secretsmanager:GetSecretValue y, opcionalmente, a secretsmanager:DescribeSecret. Añadir una condición StringEquals sobre aws:CalledViaAWSMCP para que solo los accesos a través del wrapper queden registrados como “legítimos”.

  6. Validar la lista de patrones permitidos
    El hook incluye una lista de “shapes” permitidos (por ejemplo, grep get-secret-value ./src). Si se necesita un nuevo patrón (por ejemplo, una herramienta personalizada), añádalo al archivo de configuración del hook:

    allowed_patterns:
  - "grep get-secret-value"
  - "rg get-secret-value"

Alternativas prácticas

  • Wrapper personalizado: Si asm-exec no cubre un caso (por ejemplo, una librería Python que llama directamente al SDK), crear un pequeño script que reciba la referencia, invoque boto3 y devuelva el resultado a través de stdout. Registrar ese script como herramienta en el toolkit y habilitar el mismo hook.
  • Proxy de Secrets Manager: Configurar un endpoint local que reenvíe la solicitud a Secrets Manager y registre la llamada en CloudTrail. El agente solo ve la URL del proxy, nunca el ARN real. Esta opción es más compleja y solo recomendable cuando se necesita auditoría adicional.

Cuándo aplicar esta solución

  • Síntomas: El agente devuelve valores de secretos en la salida del modelo, o los logs de depuración muestran el texto plano del secreto. Los intentos de “grep” sobre archivos de código que contienen la cadena del secreto son aceptados sin restricción.
  • Entornos típicos: Pipelines CI/CD que usan agentes LLM para generar scripts, bots de soporte que consultan credenciales, pruebas de integración que automatizan despliegues con valores sensibles.
  • No aplica: Cuando el agente nunca necesita leer secretos (por ejemplo, solo realiza operaciones de lectura de recursos que no requieren credenciales) o cuando la arquitectura ya separa completamente la capa de secretos (por ejemplo, usando IAM roles vinculados a la instancia y sin acceso directo a Secrets Manager).

Código

# 1. Añadir plugin que contiene la skill
aws configure agent-toolkit add-plugin aws-core

# 2. Habilitar skill y hook
aws agent-toolkit enable-skill secret-safety
aws agent-toolkit enable-hook PreToolUse

# 3. Reiniciar sesión del agente (ejemplo con CLI)
aws agent-toolkit session restart

# 4. Ejecutar comando seguro con asm-exec
asm-exec --command "aws secretsmanager get-secret-value --secret-id {{resolve:secretsmanager:arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret}}"

# 5. (Opcional) Añadir patrón nuevo al hook
cat <<EOF > ~/.aws/agent-toolkit/hooks/pretooluse.yaml
allowed_patterns:
  - "mycustomtool --fetch-secret"
EOF

Verificación

  1. Prueba de denegación
    Ejecuta un comando que intente leer el secreto sin usar asm-exec:

    aws secretsmanager get-secret-value --secret-id my-secret

    El agente debe responder con un mensaje de denegación que indique usar asm-exec.

  2. Prueba de aceptación
    Repite la llamada usando la sintaxis segura del paso 4. El valor debe devolverse al proceso, pero no aparecer en la salida del modelo ni en los logs de la sesión del agente.

  3. Revisar CloudTrail
    Busca eventos GetSecretValue. El campo invokedBy debe ser aws-mcp.amazonaws.com. Si aparecen llamadas directas desde la IP de tu máquina, la protección no está activa.

  4. Validar IAM
    En la consola de IAM, revisa la política adjunta al rol del agente. Asegúrate de que solo contenga secretsmanager:GetSecretValue y que la condición StringEquals sobre aws:CalledViaAWSMCP esté presente.

Notas adicionales

  • Instalación parcial: Si el agente ya estaba corriendo antes de añadir el plugin, la única forma de activar la protección es reiniciar la sesión. No basta con volver a ejecutar enable-skill.
  • Documentación implícita: La referencia {{resolve:secretsmanager:…}} se interpreta únicamente por asm-exec. Otros wrappers no la reconocerán, por lo que la sustitución fallará silenciosamente.
  • Auditoría: CloudTrail registra la llamada a Secrets Manager, pero no el valor. Si necesitas rastrear quién solicitó el secreto, revisa el campo userIdentity.sessionContext.sessionIssuer.arn del evento.
  • Compatibilidad: La skill y el hook están incluidos solo en la versión aws-core del plugin. Herramientas de terceros que instalen el toolkit mediante aws configure agent-toolkit no la obtienen automáticamente.
  • Mantenimiento: Cuando AWS añada nuevos “shapes” de herramienta (por ejemplo, nuevos clientes CLI), revisa la lista de patrones del hook y actualízala para evitar falsos negativos.