Usa i segreti in modo sicuro con gli agenti di codifica AI

Quando gli agenti di codifica AI hanno accesso alla shell o all'AWS API, possono chiamare get-secret-value e ricevere segreti in testo semplice nella loro finestra di contesto. Ciò crea molteplici rischi: i valori segreti possono penetrare nella cronologia delle conversazioni, nei log o nelle chiamate agli strumenti a valle.

Per evitare che ciò accada, usa l'abilità di sicurezza segreta di Agent Toolkit for.AWS L'abilità insegna agli agenti di intelligenza artificiale a utilizzare riferimenti dinamici risolti in fase di esecuzione, in modo che l'agente gestisca l'utilizzo segreto senza mai visualizzare il valore del testo in chiaro.

Come funziona

L'abilità di sicurezza segreta offre due livelli di protezione:

Prerequisiti

Installazione del plug-in

Installa il aws-core plugin per la tua piattaforma di agenti. L'abilità di sicurezza segreta e il gancio si attivano automaticamente.

Per Claude Code:

claude plugin add ./plugins/aws-core

Per OpenAI Codex:

codex plugin add ./plugins/aws-core

Per altre piattaforme supportate, consulta Agent Toolkit for README.AWS

Il {{resolve:...}} sintassi

Quando l'agente deve passare un segreto a un comando, utilizza un riferimento dinamico invece di chiamareget-secret-value:

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

Usa asm-exec per eseguire comandi con segreti

asm-execè uno script wrapper che risolve i {{resolve:...}} riferimenti negli argomenti dei comandi, quindi esegue il comando target. Il valore segreto esiste solo nel processo secondario.

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

asm-execrisolve i riferimenti tramite il primo backend disponibile:

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 segreti

Per i segreti archiviati in una regione diversa da quella predefinita, usa l'ARN completo (che include la regione) o imposta la variabile di 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

Considerazioni relative alla sicurezza

In che modo l'hook blocca l'accesso segreto diretto

Quando il aws-core plugin è abilitato, un PreToolUse hook intercetta le chiamate allo strumento prima dell'esecuzione. Blocca:

Quando una chiamata viene bloccata, l'agente riceve un messaggio di rifiuto che lo invita a utilizzare invece i {{resolve:...}} riferimenti con. asm-exec

Risoluzione dei problemi

Errori «Segreto non trovato»

Verifica che il segreto esista e che il tuo ruolo IAM disponga secretsmanager:GetSecretValue dell'autorizzazione. I nomi segreti fanno distinzione tra maiuscole e minuscole.

AWS Connessione al Workload Credentials Provider rifiutata

Il AWS Workload Credentials Provider potrebbe non essere in esecuzione. Ciò non è fatale: passa all'asm-execendpoint MCP. SigV4-signed Assicurati che AWS le credenziali siano disponibili in modo che il backend possa autenticarsi.

Errori «Risoluzione non riuscita»

Entrambi i backend erano irraggiungibili. Verifica che il AWS Workload Credentials Provider sia in esecuzione o che AWS le credenziali siano valide (aws sts get-caller-identity), che l'area del segreto sia corretta e che la tua identità sia inclusa nel segreto. secretsmanager:GetSecretValue

La risoluzione produce una stringa vuota

La chiave JSON potrebbe non esistere nel valore segreto. Verifica la struttura segreta nella AWS console o chiedi al proprietario segreto di confermare le chiavi disponibili.

Hook non blocca una chiamata

Gli hook vengono caricati all'inizio della sessione dell'agente. Se hai installato il plugin a metà sessione, riavvia la sessione dell'agente per attivare l'hook.