Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Utilisez les secrets en toute sécurité avec les agents de codage AI Lorsque les agents de codage AI ont accès au shell ou à l'AWS API, ils peuvent appeler `get-secret-value` et recevoir des secrets en texte brut dans leur fenêtre contextuelle. Cela crée de multiples risques : des valeurs secrètes peuvent être divulguées dans l'historique des conversations, les journaux ou les appels aux outils en aval. Pour éviter cela, utilisez la compétence de *sécurité secrète* du [kit d'outils des agents pour AWS](https://github.com/aws/agent-toolkit-for-aws). Cette compétence enseigne aux agents d'intelligence artificielle à utiliser des références dynamiques résolues lors de l'exécution, de sorte que l'agent orchestre l'utilisation du secret sans jamais voir la valeur en texte clair. **Important** Il s'agit d'une défense optimale, et non d'une limite de sécurité. Il empêche le chemin de fuite le plus courant mais ne peut pas arrêter tous les vecteurs d'évasion. Combinez avec les politiques IAM relatives au moindre privilège, à la CloudTrail surveillance et aux points de terminaison VPC. ## Comment ça marche La compétence de sécurité secrète fournit deux niveaux de protection : 1. **Conseils relatifs aux compétences** : apprend à l'agent à utiliser des références `{{resolve:secretsmanager:...}}` dynamiques grâce `asm-exec` à un script wrapper qui résout les références lors de l'exécution. La valeur en texte brut n'existe que dans le processus enfant et n'entre jamais dans la fenêtre contextuelle de l'agent. 1. **Application structurelle (hook)** — Un `PreToolUse` hook bloque automatiquement toute tentative d'appel `get-secret-value` ou d'accès direct au AWS CLI daemon AWS Workload Credentials Provider `batch-get-secret-value` via un SDK ou des outils MCP. Aucune configuration manuelle n’est requise. ## Conditions préalables + Un agent de codage basé sur l'IA qui prend en charge les plugins, tels que [Claude Code](https://docs.anthropic.com/en/docs/claude-code) ou [OpenAI](https://openai.com/index/codex/) Codex. + L'[Agent Toolkit pour le AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-core` plugin est installé. + L'un des backends de résolution secrète suivants : + **AWS Fournisseur d'informations d'identification de charge** de travail exécuté sur`localhost:2773`. Consultez [Utilisation de AWS Fournisseur d'identifiants de charge de travail](workload-credentials-provider.md). + **AWS informations d'identification** permettant de signer des demandes adressées au point de terminaison AWS MCP. + Autorisations IAM : `secretsmanager:GetSecretValue` sur les secrets que vous souhaitez résoudre. ## Installer le plug-in Installez le `aws-core` plugin pour votre plateforme d'agents. La compétence de sécurité secrète et le crochet s'activent automatiquement. Pour Claude Code : ``` claude plugin add ./plugins/aws-core ``` Pour OpenAI Codex : ``` codex plugin add ./plugins/aws-core ``` Pour les autres plateformes prises en charge, consultez le [kit d'outils de l'agent pour AWS README.](https://github.com/aws/agent-toolkit-for-aws) ## Le `{{resolve :...}}` syntaxe Lorsque l'agent doit transmettre un secret à une commande, il utilise une référence dynamique au lieu d'appeler `get-secret-value` : ``` {{resolve:secretsmanager::::}} ``` | Composant | Obligatoire | Par défaut | Description | | --- | --- | --- | --- | | secret-id | Oui | – | Nom secret ou ARN complet | | field-type | Non | SecretString | Doit être SecretString | | json-key | Non | (valeur totale) | Clé à extraire de la valeur secrète JSON | | version-stage | Non | AWSCURRENT | Étiquette de phase de version | ## Utilisez `asm-exec` pour exécuter des commandes avec des secrets `asm-exec`est un script wrapper qui résout les `{{resolve:...}}` références dans les arguments de commande, puis exécute la commande cible. La valeur secrète n'existe que dans le processus enfant. ``` asm-exec -- [arguments with {{resolve:...}} references] ``` `asm-exec`résout les références via le premier backend disponible : 1. **AWS Fournisseur d'informations d'identification de charge** de travail activé `localhost:2773` : mis en cache localement. 1. AWS Point de **terminaison MCP** : SigV4-signed demande à l'aide des AWS informations d'identification disponibles. **Example Connect à une base de données 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 Effectuer un appel d'API avec un jeton porteur** ``` asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \ https://api.example.com/data ``` **Example Connectez-vous à MySQL avec plusieurs secrets** ``` 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 Transmettre un secret en tant que variable d'environnement à un conteneur Docker** ``` asm-exec -- docker run \ -e "DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}" \ myapp:latest ``` ## Cross-region secrets Pour les secrets stockés dans une région différente de votre région par défaut, utilisez l'ARN complet (qui inclut la région) ou définissez la variable d'`AWS_REGION`environnement. ``` # 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 ``` ## Considérations sur la sécurité + **Isolation des sous-processus** — La commande cible s'exécute via`subprocess.run`. Les valeurs secrètes existent uniquement dans la mémoire du `asm-exec` processus et dans les arguments du processus enfant. ## Comment le crochet bloque l'accès secret direct Lorsque le `aws-core` plugin est activé, un `PreToolUse` hook intercepte les appels à l'outil avant son exécution. Il bloque : + `aws secretsmanager get-secret-value`et `batch-get-secret-value` via CLI + `get_secret_value`et `batch_get_secret_value` via des appels au SDK dans des scripts + Accès direct au daemon path (`localhost:2773/secretsmanager/get`) du fournisseur d'informations d'identification de AWS charge de travail + `GetSecretValue`opérations via des outils MCP ou des appels d'AWS API structurés Lorsqu'un appel est bloqué, l'agent reçoit un message de refus lui demandant d'utiliser des `{{resolve:...}}` références à la `asm-exec` place. ## Résolution des problèmes ### Erreurs « Secret introuvable » Vérifiez que le secret existe et que votre rôle IAM est `secretsmanager:GetSecretValue` autorisé. Les noms secrets distinguent les majuscules et minuscules. ### AWS Informations d'identification de charge de travail : connexion du fournisseur Le fournisseur d'informations d'identification de AWS charge de travail n'est peut-être pas en cours d'exécution. Cela n'est pas fatal : cela `asm-exec` se répercute sur le paramètre SigV4-signed MCP. Assurez-vous que les AWS informations d'identification sont disponibles afin que le backend puisse s'authentifier. ### Erreurs « Impossible de résoudre » Les deux backends étaient inaccessibles. Vérifiez que le fournisseur d'informations d'identification de AWS charge de travail est AWS actif ou que les informations d'identification sont valides (`aws sts get-caller-identity`), que la région du secret est correcte et que votre identité `secretsmanager:GetSecretValue` figure sur le secret. ### La résolution produit une chaîne vide La clé JSON n'existe peut-être pas dans la valeur secrète. Vérifiez la structure secrète dans la AWS console ou demandez au propriétaire du secret de confirmer les clés disponibles. ### Hook ne bloque pas un appel Les hooks se chargent au début de la session de l'agent. Si vous avez installé le plugin en cours de session, redémarrez la session de l'agent pour que le hook soit activé.