As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Use segredos com segurança com agentes de codificação de IA Quando os agentes de codificação de IA têm acesso ao shell ou àAWS API, eles podem chamar `get-secret-value` e receber segredos em texto simples em sua janela de contexto. Isso cria vários riscos: valores secretos podem vazar para o histórico de conversas, registros ou chamadas de ferramentas posteriores. Para evitar isso, use a habilidade de *segurança secreta* no [kit de ferramentas do agente para AWS](https://github.com/aws/agent-toolkit-for-aws). A habilidade ensina os agentes de IA a usar referências dinâmicas resolvidas em tempo de execução, para que o agente orquestre o uso secreto sem nunca ver o valor do texto simples. **Importante** Essa é a melhor defesa, não um limite de segurança. Ele evita o caminho de vazamento mais comum, mas não pode impedir todos os vetores de evasão. Combine com as políticas de menor privilégio CloudTrail , monitoramento e VPC endpoint do IAM. ## Como funciona A habilidade secreta de segurança fornece duas camadas de proteção: 1. **Orientação de habilidades** — ensina o agente a usar referências `{{resolve:secretsmanager:...}}` dinâmicas com `asm-exec` um script de wrapper que resolve referências em tempo de execução. O valor em texto simples existe somente no processo secundário e nunca entra na janela de contexto do agente. 1. **Aplicação estrutural (gancho)** — Um `PreToolUse` gancho bloqueia automaticamente qualquer tentativa de chamada `get-secret-value` ou `batch-get-secret-value` por meio de ferramentas SDK AWS CLI, MCP ou acesso direto ao daemon do AWS Workload Credentials Provider. Nenhuma configuração manual é necessária. ## Pré-requisitos + [Um agente de codificação de IA que oferece suporte a plug-ins, como [Claude Code ou OpenAI Codex](https://docs.anthropic.com/en/docs/claude-code).](https://openai.com/index/codex/) + O [kit de ferramentas do agente para AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-core` plug-in instalado. + Um dos seguintes back-ends de resolução secreta: + **AWS Provedor de credenciais de carga** de trabalho em execução. `localhost:2773` Consulte [Usar o AWS Provedor de credenciais de carga de trabalho](workload-credentials-provider.md). + **AWS credenciais** que podem assinar solicitações para o endpoint AWS MCP. + Permissões do IAM: `secretsmanager:GetSecretValue` sobre os segredos que você deseja resolver. ## Instalar o plug-in Instale o `aws-core` plug-in para sua plataforma de agente. A habilidade secreta de segurança e o gancho são ativados automaticamente. Para Claude Code: ``` claude plugin add ./plugins/aws-core ``` Para o OpenAI Codex: ``` codex plugin add ./plugins/aws-core ``` Para outras plataformas compatíveis, consulte o [Agent Toolkit for AWS README](https://github.com/aws/agent-toolkit-for-aws). ## O `{{resolve:...}}` sintaxe Quando o agente precisa passar um segredo para um comando, ele usa uma referência dinâmica em vez de chamar`get-secret-value`: ``` {{resolve:secretsmanager::::}} ``` | Componente | Obrigatório | Padrão | Description | | --- | --- | --- | --- | | secret-id | Sim | – | Nome secreto ou ARN completo | | field-type | Não | SecretString | Deve ser SecretString | | json-key | Não | (valor total) | Chave para extrair do valor secreto JSON | | version-stage | Não | AWSCURRENT | Etiqueta de palco da versão | ## Use `asm-exec` para executar comandos com segredos `asm-exec`é um script de wrapper que resolve `{{resolve:...}}` referências em argumentos de comando e, em seguida, executa o comando de destino. O valor secreto existe somente no processo filho. ``` asm-exec -- [arguments with {{resolve:...}} references] ``` `asm-exec`resolve referências por meio do primeiro back-end disponível: 1. **AWS Provedor de credenciais de carga** de trabalho ativado `localhost:2773` — armazenado em cache localmente. 1. **AWS Endpoint MCP** — SigV4-signed solicitação usando as credenciais disponíveis AWS. **Example Conecte-se a um banco de dados 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 Faça uma chamada de API com um token portador** ``` asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \ https://api.example.com/data ``` **Example Conecte-se ao MySQL com vários segredos** ``` 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 Passe um segredo como variável de ambiente para um contêiner Docker** ``` asm-exec -- docker run \ -e "DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}" \ myapp:latest ``` ## Cross-region segredos Para segredos armazenados em uma região diferente da sua região padrão, use o ARN completo (que inclui a região) ou defina a variável de `AWS_REGION` ambiente. ``` # 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 ``` ## Considerações sobre segurança + **Isolamento do subprocesso** — O comando de destino é executado via`subprocess.run`. Os valores secretos existem apenas na memória do `asm-exec` processo e nos argumentos do processo filho. ## Como o gancho bloqueia o acesso secreto direto Quando o `aws-core` plug-in está ativado, um `PreToolUse` gancho intercepta as chamadas da ferramenta antes da execução. Ele bloqueia: + `aws secretsmanager get-secret-value`e `batch-get-secret-value` via CLI + `get_secret_value`e `batch_get_secret_value` por meio de chamadas do SDK em scripts + Acesso direto ao caminho do daemon do AWS Workload Credentials Provider () `localhost:2773/secretsmanager/get` + `GetSecretValue`operações por meio de ferramentas MCP ou chamadas de AWS API estruturadas Quando uma chamada é bloqueada, o agente recebe uma mensagem de negação que o direciona a usar `{{resolve:...}}` referências com`asm-exec`. ## Solução de problemas ### Erros de “Segredo não encontrado” Verifique se o segredo existe e se sua função do IAM tem `secretsmanager:GetSecretValue` permissão. Os nomes secretos diferenciam maiúsculas de minúsculas. ### AWS Conexão com o provedor de credenciais da carga de trabalho recusada O provedor de credenciais de AWS carga de trabalho pode não estar em execução. Isso não é fatal — vai até `asm-exec` o endpoint do SigV4-signed MCP. Certifique-se de que AWS as credenciais estejam disponíveis para que o back-end possa se autenticar. ### Erros de “Falha na resolução” Ambos os back-ends estavam inacessíveis. Verifique se o AWS Workload Credentials Provider está em execução ou se AWS as credenciais são válidas (`aws sts get-caller-identity`), se a região do segredo está correta e se sua identidade está `secretsmanager:GetSecretValue` no segredo. ### A resolução produz uma string vazia A chave JSON pode não existir no valor secreto. Verifique a estrutura secreta no AWS console ou peça ao proprietário do segredo que confirme as chaves disponíveis. ### Hook não bloqueia uma chamada Os ganchos são carregados no início da sessão do agente. Se você instalou o plug-in no meio da sessão, reinicie a sessão do agente para que o gancho seja ativado.