Utilice los secretos de forma segura con los agentes de codificación de IA

Cuando los agentes de programación de IA tienen acceso al shell o a la AWS API, pueden llamar get-secret-value y recibir secretos en texto simple en su ventana de contexto. Esto conlleva múltiples riesgos: los valores secretos pueden filtrarse al historial de conversaciones, a los registros o a las llamadas posteriores a las herramientas.

Para evitarlo, usa la habilidad secreta de seguridad incluida en el kit de herramientas para agentes.AWS Esta habilidad enseña a los agentes de IA a usar referencias dinámicas que se resuelven en tiempo de ejecución, de modo que el agente organiza el uso secreto sin ver nunca el valor del texto simple.

Funcionamiento

La habilidad de seguridad secreta proporciona dos niveles de protección:

Requisitos previos

Instalación del complemento

Instala el aws-core complemento para tu plataforma de agentes. La habilidad de seguridad secreta y el anzuelo se activan automáticamente.

Para Claude Code:

claude plugin add ./plugins/aws-core

Para OpenAI Codex:

codex plugin add ./plugins/aws-core

Para ver otras plataformas compatibles, consulte el kit de herramientas para agentes de README.AWS

El {{resolve:...}} sintaxis

Cuando el agente necesita pasar un secreto a un comando, utiliza una referencia dinámica en lugar de llamar aget-secret-value:

{{resolve:secretsmanager:<secret-id>:<field-type>:<json-key>:<version-stage>}}

Use asm-exec para ejecutar comandos con secretos

asm-execes un script contenedor que resuelve las {{resolve:...}} referencias en los argumentos de los comandos y, a continuación, ejecuta el comando de destino. El valor secreto solo existe en el proceso secundario.

asm-exec -- <command> [arguments with {{resolve:...}} references]

asm-execresuelve las referencias a través del primer backend disponible:

asm-exec -- psql \
  "host=mydb.example.com \
  user={{resolve:secretsmanager:prod/db-creds:SecretString:username}} \
  password={{resolve:secretsmanager:prod/db-creds:SecretString:password}}" \
  -c "SELECT * FROM users LIMIT 10"

asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \
  https://api.example.com/data

asm-exec -- mysql \
  -h {{resolve:secretsmanager:prod/mysql:SecretString:host}} \
  -u {{resolve:secretsmanager:prod/mysql:SecretString:username}} \
  -p{{resolve:secretsmanager:prod/mysql:SecretString:password}} \
  -e "SHOW TABLES"

asm-exec -- docker run \
  -e "DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}" \
  myapp:latest

Cross-region secretos

Para los secretos almacenados en una región diferente a la región predeterminada, utilice el ARN completo (que incluye la región) o establezca la variable de AWS_REGION entorno.

# Using full ARN (region is extracted automatically)
asm-exec -- curl -H "X-Api-Key: {{resolve:secretsmanager:arn:aws:secretsmanager:eu-west-1:123456789012:secret:prod/key-a1b2c3}}" \
  https://eu.api.example.com/data

# Using AWS_REGION
export AWS_REGION=eu-west-1
asm-exec -- curl -H "X-Api-Key: {{resolve:secretsmanager:prod/key}}" \
  https://eu.api.example.com/data

Consideraciones de seguridad

Cómo bloquea el gancho el acceso secreto directo

Cuando el aws-core complemento está activado, un PreToolUse gancho intercepta las llamadas a la herramienta antes de su ejecución. Bloquea:

Cuando se bloquea una llamada, el agente recibe un mensaje de rechazo que le indica que utilice las {{resolve:...}} referencias asm-exec en su lugar.

Resolución de problemas

Errores de tipo «Secreto no encontrado»

Compruebe que el secreto existe y que su función de IAM tiene secretsmanager:GetSecretValue permiso. Los nombres secretos distinguen mayúsculas de minúsculas.

AWS Se rechazó la conexión con el proveedor de credenciales de carga

Es posible que el proveedor de credenciales de AWS carga de trabajo no se esté ejecutando. Esto no es mortal: afecta asm-exec al punto final del SigV4-signed MCP. Asegúrese de que AWS las credenciales estén disponibles para que el backend pueda autenticarse.

Errores de «No se pudo resolver»

No se podía acceder a ambos backends. Compruebe que el proveedor de credenciales de AWS carga de trabajo esté activo o que AWS las credenciales sean válidas (aws sts get-caller-identity), que la región del secreto sea correcta y que su identidad figure secretsmanager:GetSecretValue en el secreto.

La resolución produce una cadena vacía

Es posible que la clave JSON no exista en el valor secreto. Verifica la estructura secreta en la AWS consola o pide al propietario del secreto que confirme las claves disponibles.

Hook no bloquea una llamada

Los ganchos se cargan al inicio de la sesión del agente. Si instaló el complemento a mitad de la sesión, reinicie la sesión del agente para que se active el enlace.