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. 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.

Como funciona

A habilidade secreta de segurança fornece duas camadas de proteção:

Pré-requisitos

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.

O {{resolve:...}} sintaxe

Quando o agente precisa passar um segredo para um comando, ele usa uma referência dinâmica em vez de chamarget-secret-value:

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

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 -- <command> [arguments with {{resolve:...}} references]

asm-execresolve referências por meio do primeiro back-end disponível:

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 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

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:

Quando uma chamada é bloqueada, o agente recebe uma mensagem de negação que o direciona a usar {{resolve:...}} referências comasm-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.