Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # 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](https://github.com/aws/agent-toolkit-for-aws).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. **importante** Se trata de una defensa que hace todo lo posible, no de un límite de seguridad. Evita la ruta de fuga más común, pero no puede detener todos los vectores de evasión. Combínelo con las políticas de puntos finales de VPC CloudTrail , supervisión y privilegios mínimos de IAM. ## Funcionamiento La habilidad de seguridad secreta proporciona dos niveles de protección: 1. **Guía de habilidades**: enseña al agente a usar referencias `{{resolve:secretsmanager:...}}` dinámicas con `asm-exec` un script contenedor que resuelve las referencias en tiempo de ejecución. El valor de texto plano solo existe en el proceso secundario y nunca entra en la ventana de contexto del agente. 1. **Aplicación estructural (gancho)**: un `PreToolUse` enlace bloquea automáticamente cualquier intento de llamada `get-secret-value` o `batch-get-secret-value` mediante el SDK AWS CLI, las herramientas MCP o el acceso directo al daemon del proveedor de credenciales de AWS carga de trabajo. No se requiere ninguna configuración manual. ## Requisitos previos + Un agente de codificación de IA que admite complementos, como [Claude Code](https://docs.anthropic.com/en/docs/claude-code) u [OpenAI](https://openai.com/index/codex/) Codex. + Se ha instalado el kit [de herramientas Agent Toolkit para el complemento AWS](https://github.com/aws/agent-toolkit-for-aws)`aws-core`. + Uno de los siguientes backends de resolución secreta: + AWS El **proveedor de credenciales de carga** de trabajo se está ejecutando. `localhost:2773` Consulte [Uso de AWS Proveedor de credenciales de carga de trabajo](workload-credentials-provider.md). + **AWS credenciales** que pueden firmar solicitudes al punto final del AWS MCP. + Permisos de IAM: `secretsmanager:GetSecretValue` sobre los secretos que desee resolver. ## 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](https://github.com/aws/agent-toolkit-for-aws).AWS ## El `{{resolve:...`}} sintaxis Cuando el agente necesita pasar un secreto a un comando, utiliza una referencia dinámica en lugar de llamar a`get-secret-value`: ``` {{resolve:secretsmanager::::}} ``` | Componente | Obligatorio | Predeterminado | Description (Descripción) | | --- | --- | --- | --- | | secret-id | Sí | – | Nombre secreto o ARN completo | | field-type | No | SecretString | Debe ser SecretString | | json-key | No | (valor completo) | Clave para extraer el valor secreto de JSON | | version-stage | No | AWSCURRENT | Etiqueta de fase de versión | ## Use `asm-exec` para ejecutar comandos con secretos `asm-exec`es 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 -- [arguments with {{resolve:...}} references] ``` `asm-exec`resuelve las referencias a través del primer backend disponible: 1. AWS El **proveedor de credenciales de carga** de trabajo está activado`localhost:2773`: se almacena en caché local. 1. **AWS Punto final MCP**: SigV4-signed solicitud con las credenciales disponibles AWS. **Example Connect a una base de datos PostgreSQL** ``` 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" ``` **Example Realice una llamada a la API con un token portador** ``` asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \ https://api.example.com/data ``` **Example Connect a MySQL con múltiples secretos** ``` 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" ``` **Example Pase un secreto como variable de entorno a un contenedor de Docker** ``` 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 + **Aislamiento del subproceso**: el comando target se ejecuta mediante. `subprocess.run` Los valores secretos solo existen en la memoria del `asm-exec` proceso y en los argumentos del proceso secundario. ## 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: + `aws secretsmanager get-secret-value`y `batch-get-secret-value` mediante CLI + `get_secret_value`y `batch_get_secret_value` mediante llamadas al SDK en scripts + Acceso directo a la ruta del daemon del proveedor de credenciales de AWS carga de trabajo () `localhost:2773/secretsmanager/get` + `GetSecretValue`operaciones mediante herramientas MCP o llamadas estructuradas AWS a la API 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.