Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # 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](https://github.com/aws/agent-toolkit-for-aws) 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. **Importante** Si tratta di una difesa ottimale, non di un limite di sicurezza. Impedisce il percorso di fuga più comune ma non può fermare tutti i vettori di evasione. Combinalo con le policy IAM in materia di privilegi minimi CloudTrail , monitoraggio e endpoint VPC. ## Come funziona L'abilità di sicurezza segreta offre due livelli di protezione: 1. **Guida alle competenze**: insegna all'agente a utilizzare i riferimenti `{{resolve:secretsmanager:...}}` dinamici con `asm-exec` uno script wrapper che risolve i riferimenti in fase di esecuzione. Il valore di testo in chiaro esiste solo nel processo secondario e non entra mai nella finestra di contesto dell'agente. 1. **Imposizione strutturale (hook)**: un `PreToolUse` hook blocca automaticamente qualsiasi tentativo di chiamata `get-secret-value` o `batch-get-secret-value` tramite SDK AWS CLI, strumenti MCP o accesso diretto al daemon AWS Workload Credentials Provider. Non è richiesta alcuna configurazione manuale. ## Prerequisiti + [Un agente di codifica AI che supporta plugin, come [Claude Code o](https://docs.anthropic.com/en/docs/claude-code) OpenAI Codex.](https://openai.com/index/codex/) + Il plugin [Agent Toolkit for è installato.AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-core` + Uno dei seguenti backend di risoluzione segreti: + **AWS Workload Credentials Provider** in esecuzione su. `localhost:2773` Per informazioni, consulta [Utilizzo di AWS Fornitore di credenziali per il carico di lavoro](workload-credentials-provider.md). + **AWS credenziali** in grado di firmare le richieste all'endpoint MCP.AWS + Autorizzazioni IAM: `secretsmanager:GetSecretValue` sui segreti che vuoi risolvere. ## 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](https://github.com/aws/agent-toolkit-for-aws).AWS ## Il `{{resolve:...`}} sintassi Quando l'agente deve passare un segreto a un comando, utilizza un riferimento dinamico invece di chiamare`get-secret-value`: ``` {{resolve:secretsmanager::::}} ``` | Componente | Obbligatorio | Predefinita | Description | | --- | --- | --- | --- | | secret-id | Sì | – | Nome segreto o ARN completo | | field-type | No | SecretString | Deve essere SecretString | | json-key | No | (valore completo) | Chiave da estrarre dal valore segreto JSON | | version-stage | No | AWSCURRENT | Etichetta della fase della versione | ## 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 -- [arguments with {{resolve:...}} references] ``` `asm-exec`risolve i riferimenti tramite il primo backend disponibile: 1. **AWS Workload Credentials Provider** attivo, memorizzato nella cache locale. `localhost:2773` 1. **AWS Endpoint MCP: richiesta utilizzando** le credenziali disponibili SigV4-signed .AWS **Example Connect a un database 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 Effettua una chiamata API con un token bearer** ``` asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \ https://api.example.com/data ``` **Example Connect a MySQL con più segreti** ``` 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 Passa un segreto come variabile di ambiente a un contenitore Docker** ``` 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 + **Isolamento dei sottoprocessi**: il comando target viene eseguito tramite. `subprocess.run` I valori segreti esistono solo nella memoria del `asm-exec` processo e negli argomenti del processo secondario. ## 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: + `aws secretsmanager get-secret-value`e `batch-get-secret-value` tramite CLI + `get_secret_value`e `batch_get_secret_value` tramite chiamate SDK negli script + Accesso diretto al daemon path del AWS Workload Credentials Provider () `localhost:2773/secretsmanager/get` + `GetSecretValue`operazioni tramite strumenti MCP o chiamate API strutturate AWS 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-exec`endpoint 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.