Best practice di sicurezza per AgentCore Runtime

• Comprendi il limite dell'isolamento: ogni sessione utente viene eseguita in una microVM dedicata con CPU, memoria e file system isolati. I comandi e il codice dell'agente non possono accedere ai carichi di lavoro di altri clienti o sfuggire ai confini della VM. Al termine della sessione, l'intera MicroVM viene terminata e la memoria viene disinfettata.

• Applica le mappature sessione-utente nel backend, ma non le mappature sessione-utente. AgentCore Il backend del cliente deve mantenere la relazione tra gli utenti e i relativi ID di sessione e implementare la gestione del ciclo di vita, ad esempio il numero massimo di sessioni per utente.

• Fai attenzione al comportamento delle autorizzazioni del file system: quando usi file system persistenti, le autorizzazioni vengono archiviate ma non applicate all'interno della sessione. chmode stat funzionano correttamente, ma i controlli di accesso hanno sempre esito positivo perché l'agente viene eseguito come unico utente nella MicroVM.

• Comprendi l'esposizione delle credenziali all'interno della VM: qualsiasi codice o attore in esecuzione all'interno della microVM può accedere alle credenziali del ruolo di esecuzione chiamando l'endpoint dei metadati (MMDS). Definisci attentamente le autorizzazioni del ruolo di esecuzione. Per ulteriori informazioni, consulta Gestione delle credenziali.

• Non utilizzare CLI-generated le policy in produzione: le policy IAM create dalla AgentCore CLI sono progettate per scopi di sviluppo e test. Queste autorizzazioni garantiscono un ampio accesso e non sono adatte alla produzione. Crea policy IAM personalizzate che limitino le autorizzazioni solo alle risorse e alle azioni specifiche richieste. Per il riferimento completo, consulta IAM Permissions for AgentCore Runtime.

• Ambito delle autorizzazioni per ARN di runtime specifici: evita le dichiarazioni di risorse con caratteri jolly. Usa l'ARN completo delle tue risorse di runtime nei campi delle policy IAM. Resource

• Limita InvokeAgentRuntimeForUser: solo i committenti fidati dovrebbero avere questa autorizzazione. Applicalo a risorse di runtime specifiche utilizzando le condizioni delle risorse IAM.

• Nega la delega dell'ID utente dove non è necessaria: per i runtime in cui la delega dell'ID utente non è richiesta, nega esplicitamente l'azione:

  {
     "Statement": [
        {
           "Sid": "DenyUserIdDelegation",
           "Effect": "Deny",
           "Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
           "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/*"
        }
     ]
  }

• Impedisci l'escalation dei privilegi: assicurati che il ruolo di esecuzione associato al tuo runtime disponga di privilegi uguali o inferiori rispetto ai principali che possono richiamarlo. Per ulteriori informazioni, consulta Gestione delle credenziali. Comprendere la gestione delle credenziali in Amazon Bedrock AgentCore

• Usa le chiavi di condizione IAM per applicare le distribuzioni VPC: le chiavi di bedrock-agentcore:securityGroups condizione bedrock-agentcore:subnets e di condizione richiedono che tutti i runtime siano distribuiti in VPC approvati. Per esempi, consulta Utilizzare le chiavi di condizione VPC con Runtime. AgentCore

• Usa IAM Access Analyzer: convalida le tue policy IAM per assicurarti che aderiscano alle best practice e ai principi del privilegio minimo.

• Comprendi l'autorizzazione gerarchica: per operazioni API in fase di esecuzione comeInvokeAgentRuntime, e InvokeAgentRuntimeCommandInvokeAgentRuntimeCommandShell, AWS valuta le politiche sia sul runtime dell'agente che sull'endpoint dell'agente. Entrambi devono consentire l'azione.

• Configura entrambe le risorse per l'accesso tra account: per concedere l'accesso su più account, crea policy basate sulle risorse sia sul runtime dell'agente che sull'endpoint dell'agente. Se una delle risorse non dispone di un'autorizzazione esplicita, la richiesta viene rifiutata.

• Ricorda che il rifiuto esplicito vince sempre: se una policy (basata sull'identità o basata sulle risorse) nega esplicitamente un'azione, l'accesso viene negato indipendentemente dalle altre politiche.

• Usa aws:SourceArn e aws:SourceAccount: aggiungi queste condizioni alla tua politica di attendibilità del ruolo di esecuzione per limitare AgentCore le risorse che possono assumere il ruolo:

  {
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Service": "bedrock-agentcore.amazonaws.com"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {
            "aws:SourceAccount": "123456789012"
          },
          "ArnLike": {
            "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
          }
        }
      }
    ]
  }

• Usa l'ARN completo quando possibile: se conosci la risorsa di runtime specifica, utilizza l'ARN completo aws:SourceArn anziché i caratteri jolly.

• Applica il tipo di stringa nel campo del prompt: l'elemento ricevuto dal punto di ingresso viene payload analizzato da un JSON arbitrario. Un chiamante può inviare un valore non stringa (ad esempio un elenco o un oggetto) nel campo. prompt Se il framework dell'agente accetta blocchi di contenuto non contenenti stringhe, in particolare toolUse blocchi, il framework potrebbe inviare direttamente uno strumento. Ciò aggira il ragionamento del modello, i guardrail e l'applicazione dei prompt di sistema. Verifica sempre che il prompt sia una stringa prima di passarlo all'agente:

  @app.entrypoint
  def invoke(payload, context):
      user_message = payload.get("prompt", "")
      if not isinstance(user_message, str) or not user_message.strip():
          return {"error": "Invalid input: 'prompt' must be a non-empty string"}
      result = agent(user_message)
      return {"response": result.message}

• Rifiuta o elimina toolUse i blocchi di contenuto: se il tuo agente accetta array di messaggi strutturati (per conversazioni a più turni), filtra tutti i blocchi di toolUse contenuto dai messaggi forniti dall'utente. Un toolUse blocco nella cronologia dei messaggi può far sì che il ciclo di eventi del framework dell'agente esegua immediatamente lo strumento indicato senza la valutazione del modello.

• Convalida la struttura del payload con uno schema: usa Pydantic, Zod o una libreria di schemi equivalente per far sì che il corpo della richiesta sia conforme alla struttura prevista. Definisci prompt come (non) nel tuo schema: str Any

  from pydantic import BaseModel
  
  class InvocationRequest(BaseModel):
      prompt: str  # Enforces string type at the schema level

• Non fare affidamento sui valori predefiniti per la convalida: un pattern like payload.get("prompt", "Hello") fornisce un valore predefinito ma non rifiuta input non di tipo stringa. Il valore restituito è quello inviato dal chiamante, che potrebbe essere un dict o un elenco contenente blocchi di contenuto.

• Policy-based autorizzazione: utilizza il motore di policy del gateway per controllare quali chiamanti possono richiamare quali destinazioni e in quali condizioni. Per ulteriori informazioni, consulta Utilizzare le politiche per controllare l'accesso alle destinazioni del gateway.

• Guardrails: applica Amazon Bedrock Guardrails tramite il policy engine per esaminare richieste e risposte. Per ulteriori informazioni, consulta Usare i guardrail nelle policy.

• Intercettatori di richieste e risposte: ispeziona o trasforma il traffico con le funzioni Lambda di intercettazione configurate sul gateway.

• Runtime IAM (Sigv4): allega una policy basata sulle risorse che limiti l'invocazione al ruolo di esecuzione del gateway. Consulta Limita l'invocazione in entrata di IAM (Sigv4) al tuo gateway.

• Runtime OAuth (JWT): configura in base all'autorizzatore del runtime. allowedWorkloadConfiguration Vedi Limita l'invocazione al tuo gateway.

• Scegli il metodo di autenticazione giusto: utilizza IAM Sigv4 per le chiamate da servizio a servizio all'interno. AWS Usa l'autenticazione con token al portatore JWT quando gli utenti finali si autenticano direttamente tramite un provider di identità. Un runtime può supportare un metodo alla volta; creare versioni separate per diversi tipi di autenticazione.

• Preferisci JWT-based l'identificazione dell'utente per la produzione: quando il tuo agente recupera i token OAuth per conto degli utenti finali, preferisci il percorso del token portante JWT (GetWorkloadAccessTokenForJWT), che convalida l'emittente, la firma e la scadenza del token. Il UserId percorso (GetWorkloadAccessTokenForUserId/X-Amzn-Bedrock-AgentCore-Runtime-User-Idheader) considera l'identificatore utente come una stringa opaca senza verifica IdP: utilizzalo solo per lo sviluppo, gli scenari di avvio rapido o le architetture aziendali che risolvono l'identità dell'utente a monte. Per ulteriori informazioni, consulta Get workload access token. Ottieni il token di accesso al carico di lavoro

• Configura completamente gli autorizzatori JWT: quando utilizzi l'autenticazione JWT, configura tutti i campi di convalida disponibili: URL di scoperta, destinatari consentiti, client consentiti, ambiti consentiti e attestazioni personalizzate richieste.

• Non inserire mai i token nel codice di produzione: utilizza meccanismi sicuri di recupero dei token. I token codificati rappresentano un rischio per la sicurezza nel controllo del codice sorgente e negli artefatti implementati.

• Ricava l'ID utente dall'entità autenticata: se utilizzi l'X-Amzn-Bedrock-AgentCore-Runtime-User-Idintestazione, il valore deve essere derivato dal contesto dell'entità autenticata (identità del chiamante IAM o attestazioni del token utente), non da valori arbitrari forniti dal client. Ciò impedisce agli utenti autenticati di impersonare altri utenti.

• Nega ForUserId dove non è necessario: per i carichi di lavoro che hanno sempre un JWT disponibile, nega esplicitamente e nelle politiche IAM. bedrock-agentcore:GetWorkloadAccessTokenForUserId bedrock-agentcore:InvokeAgentRuntimeForUser Ciò garantisce che tutte le identificazioni degli utenti passino attraverso il percorso JWT verificato crittograficamente.

• Configura le politiche degli endpoint VPC per il tuo metodo di autenticazione: le politiche degli endpoint VPC possono limitare i chiamanti solo in base ai principali IAM, non agli utenti OAuth. Per OAuth-based le richieste, impostalo nella policy degli endpoint. Principal * Per SigV4-based l'autenticazione, specifica le identità IAM consentite.

• Usa AgentCore Identity per l'autenticazione in uscita: AgentCore Identity gestisce le credenziali OAuth e le chiavi API in modo sicuro, prevenendo l'esposizione delle credenziali nel codice o nei log dell'agente. Usalo per tutti gli accessi ai servizi di terze parti (Slack, Zoom). GitHub

• Comprendi l'esposizione delle credenziali MMDS: MicroVM Metadata Service (MMDS) fornisce le credenziali del ruolo di esecuzione a qualsiasi codice in esecuzione nella VM, in modo simile all'IMDS di EC2. Ambita le autorizzazioni dei ruoli di esecuzione solo per ciò che l'agente richiede.

• Abilita MMDSv2: a partire dal 30 giugno 2026, i runtime dell'agente devono avere MMDSv2 abilitato. I runtime senza MMDSv2 abilitato non possono essere richiamati e restituiscono un. ValidationException Per abilitare, chiama UpdateAgentRuntime con set to in. requireMMDSV2 true metadataConfiguration Per ulteriori informazioni sulla risoluzione di questo errore, vedi Risoluzione dei problemi MMDSv2 ValidationException .

• Esegui i contenitori come utenti non root: quando crei immagini personalizzate dei contenitori, configurali per l'esecuzione come utente non root. Questo limita l'impatto delle potenziali vulnerabilità legate all'esecuzione del codice.

• Credenziali separate delegate dall'utente e autonome: utilizzate l'autenticazione delegata dall'utente (Authorization Code Grant) quando il vostro agente agisce per conto di un utente specifico. Utilizza l'autenticazione autonoma (Client Credentials Grant) quando l'agente opera in modo indipendente.

• Implementa i runtime in un VPC per l'accesso privato alle risorse: configura la connettività VPC per accedere a database privati, API interne e servizi senza esporli a Internet. Per i dettagli sulla configurazione, consulta Configure Runtime for VPC. AgentCore

• Usa AWS PrivateLink per l'accesso alle API: crea endpoint VPC di interfaccia per il piano AgentCore dati (com.amazonaws.region.bedrock-agentcore) e il piano di controllo () per evitare l'com.amazonaws.region.bedrock-agentcore-controlattraversamento di Internet. Per ulteriori informazioni, consulta Uso. AWS PrivateLink

• Applica il privilegio minimo ai gruppi di sicurezza: definisci regole in uscita che consentano solo il traffico minimo richiesto. Non aprite un ampio accesso in uscita a meno che non sia necessario.

• Configura gli endpoint VPC richiesti per gli agenti container: per gli agenti VPC-mode container, configura gli endpoint VPC per ECR (com.amazonaws.region.ecr.dkr,com.amazonaws.region.ecr.api), S3 (endpoint com.amazonaws.region.s3 gateway) e Logs (). CloudWatch com.amazonaws.region.logs L'endpoint del gateway S3 elimina i costi di elaborazione dei dati del gateway NAT per i pull del livello di immagine ECR.

• Ambito di applicazione della policy sugli endpoint del gateway S3 per gli agenti container: limita la policy degli endpoint del gateway S3 al solo bucket utilizzato da Amazon ECR per lo storage a livello di immagine:

  {
    "Statement": [
      {
        "Sid": "AllowECRLayerAccess",
        "Principal": "*",
        "Action": [
          "s3:GetObject"
        ],
        "Effect": "Allow",
        "Resource": ["arn:aws:s3:::prod-region-starport-layer-bucket/*"]
      }
    ]
  }

  Sostituiscila region con l'identificatore AWS della tua regione (ad esempio,). us-east-2

• Definisci la policy degli endpoint del gateway S3 per gli agenti di distribuzione diretta del codice: per le implementazioni basate su zip, limita la policy al bucket interno di codice di proprietà del servizio. Aggiungi una aws:PrincipalServiceName condizione per garantire che solo il responsabile del servizio possa accedere ai bucket tramite questa policy sugli endpoint: AgentCore

  {
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": "*",
        "Action": "s3:GetObject",
        "Resource": [
          "arn:aws:s3:::acr-code-*-region-an",
          "arn:aws:s3:::acr-code-*-region-an/*"
        ],
        "Condition": {
          "StringEquals": {
            "aws:PrincipalServiceName": "bedrock-agentcore.amazonaws.com"
          }
        }
      }
    ]
  }

  Sostituiscilo region con l'identificatore AWS della tua regione (ad esempio,). us-west-2 I bucket degli artefatti del AgentCore codice vengono creati nei bucket generici dello spazio dei nomi regionali dell'Account. AWS Può essere proprietario solo dei nomi effettivi dei bucket utilizzati dal servizio. La aws:PrincipalServiceName condizione garantisce che solo il responsabile del AgentCore servizio possa accedere ai bucket tramite questa policy sugli endpoint. Se utilizzi anche file system permanenti, aggiungi il bucket di archiviazione delle sessioni a questa policy. Per ulteriori informazioni, consulta Configure AgentCore Runtime for VPC.

• Usa sottoreti private con gateway NAT: le sottoreti pubbliche non forniscono l'accesso a Internet per Runtime. AgentCore Posiziona sempre gli ENI di runtime in sottoreti private con un percorso verso un gateway NAT per l'accesso a Internet in uscita.

• Sicurezza dei trasporti: tutte le connessioni utilizzano TLS 1.2 o versioni successive. WebSocket le connessioni, tra cuiInvokeAgentRuntimeCommandShell, utilizzano esclusivamente WSS (WebSocket Secure) su HTTPS. Le ws:// connessioni in chiaro non sono supportate.

• Applica i limiti delle intestazioni: le intestazioni personalizzate sono limitate a 4 KB per valore e 20 intestazioni per runtime. L'Authorizationintestazione è riservata agli agenti con accesso in entrata OAuth.

• Crittografia in transito: tutte le comunicazioni tra client e AgentCore Runtime e tra AgentCore Runtime e le sue dipendenze sono protette tramite TLS 1.2 o versioni successive. Questa è configurata di default e non richiede alcuna configurazione aggiuntiva.

• Crittografia inattiva: per impostazione predefinita, i dati inattivi vengono crittografati utilizzando le chiavi di crittografia AWS possedute dal AWS AWS Key Management Service (KMS).

• Usa TLS 1.3 laddove possibile: sebbene TLS 1.2 sia il minimo, AWS consiglia TLS 1.3 per migliorare sicurezza e prestazioni.

• Abilita la CloudTrail registrazione: AWS CloudTrail registra le chiamate API incluseInvokeAgentRuntime, InvokeAgentRuntimeCommandInvokeAgentRuntimeCommandShell, e le operazioni del piano di controllo. Ogni record include l'identità del chiamante, il timestamp, l'indirizzo IP di origine e lo stato della risposta.

• Usa CloudWatch i log per il controllo dei comandi: AgentCore Runtime invia l'ID della richiesta e il comando di input al gruppo di log Logs dell' CloudWatch agente. Utilizza questi registri per mantenere una traccia di controllo dei comandi eseguiti nelle tue sessioni.

• Correla i log utilizzando gli ID di richiesta: utilizza l'ID della richiesta per correlare CloudTrail i record (chi ha chiamato l'API) con CloudWatch i log (quale comando è stato eseguito).

• Imposta filtri metrici e allarmi: configura i filtri metrici di CloudWatch Logs per rilevare modelli di comando imprevisti o tentativi di accesso non autorizzati. Crea allarmi per notificare al tuo team eventuali anomalie.

• Registra le relazioni di delega degli ID utente: quando usi l'X-Amzn-Bedrock-AgentCore-Runtime-User-Idintestazione, registra la relazione tra il principale IAM autenticato e il valore dell'ID utente a fini di controllo.

• Abilita i log di flusso VPC: per i VPC-connected runtime, abilita VPC Flow Logs per controllare il traffico a livello di rete e identificare modelli di comunicazione imprevisti.

• Rivedi CloudTrail i log regolarmente: esamina periodicamente i log per individuare eventuali tentativi di accesso non autorizzati, in particolare per carichi di lavoro sensibili.

AWS responsabilità:

• Infrastruttura sicura e isolamento delle microVM a livello hardware

• Patching del kernel del sistema operativo per tutte le modalità di distribuzione

• Applicazione di patch in fase di esecuzione del linguaggio per distribuzioni dirette di codice

• Sicurezza dell'infrastruttura di rete

• Disponibilità e resilienza del servizio

Le tue responsabilità:

• Sicurezza del codice dell'agente e gestione delle dipendenze

• Controlli di accesso e politiche delle risorse IAM

• Sicurezza dei comandi eseguiti nelle sessioni di runtime

• Session-to-user applicazione della mappatura

• aggiornamenti dell'immagine del contenitore (per le implementazioni dei container): ricostruisci regolarmente con l'immagine di base sicura più recente

• Convalida degli input e prevenzione delle iniezioni tempestive, inclusa la convalida dell'InvokeHarnessinput quando si utilizza l'harness gestito (vedi Harness condivide il limite di fiducia di Runtime) AgentCore

• Configurazione della rete (gruppi di sicurezza, endpoint VPC, tabelle di routing)

• InvokeAgentRuntimeCommand— One-shot, esecuzione di comandi non interattiva terminata. HTTP/2 Azione IAM:bedrock-agentcore:InvokeAgentRuntimeCommand.

• InvokeAgentRuntimeCommandShell— Sessione WebSocket shell interattiva con accesso PTY persistente. Azione IAM:bedrock-agentcore:InvokeAgentRuntimeCommandShell.

• Comprendi i limiti di sicurezza: i comandi hanno pieno accesso al filesystem del contenitore e a qualsiasi credenziale o segreto configurato all'interno della MicroVM. Il limite di isolamento è la microVM stessa. Secondo il modello di responsabilità condivisa, sei responsabile della sicurezza di qualsiasi codice eseguito nel tuo contenitore di runtime.

• Usa operazioni deterministiche per attività deterministiche: usa InvokeAgentRuntimeCommand o InvokeAgentRuntimeCommandShell per operazioni come tests, git e builds. Non indirizzare le operazioni deterministiche attraverso l'LLM tramite. InvokeAgentRuntime

• Limita chi può eseguire comandi: utilizza le politiche IAM per limitare i principali che possono chiamare o. InvokeAgentRuntimeCommand InvokeAgentRuntimeCommandShell Non tutti gli utenti che possono richiamare un agente dovrebbero essere in grado di eseguire comandi arbitrari. Esempio di risorsa ARN:. arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent

• WebSocket shell utilizza solo wss://: InvokeAgentRuntimeCommandShell le connessioni vengono stabilite esclusivamente tramite WSS (WebSocket Secure). Le ws:// connessioni in chiaro non sono supportate. I chiamanti si autenticano tramite SIGv4 al momento dell'aggiornamento. WebSocket

• Mantieni il traffico all'interno della tua rete: configura gli endpoint VPC per evitare l'attraversamento di Internet per le chiamate API di esecuzione dei comandi.

• Imposta i timeout appropriati: configura i timeout dei comandi in base alla durata prevista di esecuzione per evitare sprechi di risorse a causa di processi incontrollati.

• Limita l'accesso a localhost nel codice dell'agente: configura il tuo agente e tutti gli strumenti di rete per impedire l'accesso illimitato a localhost. Il codice dell'agente non deve effettuare chiamate HTTP arbitrarie a localhost a meno che non sia necessario per un'integrazione specifica.

• Inserisci nella lista consentita solo le porte richieste per le configurazioni sidecar: se la tua architettura utilizza un pattern container-in-container o sidecar su localhost, elenca esplicitamente solo le porte specifiche utilizzate dai tuoi servizi sidecar. Non aprite un ampio accesso a localhost.

• Verifica la portata di localhost degli strumenti di rete: controlla tutti gli strumenti forniti al tuo agente (ad esempio strumenti di richiesta HTTP o utilità di rete generiche) per assicurarti che non possa effettuare richieste indesiderate agli endpoint localhost. Applica il filtro degli URL o gli elenchi consentiti a livello di strumento.