Distribuzione sicura di agenti AI

Claude Code e l’Agent SDK sono strumenti potenti che possono eseguire codice, accedere a file e interagire con servizi esterni per conto vostro. Come qualsiasi strumento con queste capacità, distribuirli con attenzione garantisce di ottenere i vantaggi mantenendo controlli appropriati. A differenza del software tradizionale che segue percorsi di codice predeterminati, questi strumenti generano le loro azioni dinamicamente in base al contesto e agli obiettivi. Questa flessibilità è ciò che li rende utili, ma significa anche che il loro comportamento può essere influenzato dal contenuto che elaborano: file, pagine web o input dell’utente. Questo è talvolta chiamato prompt injection. Ad esempio, se il README di un repository contiene istruzioni insolite, Claude Code potrebbe incorporarle nelle sue azioni in modi che l’operatore non aveva anticipato. Questa guida copre modi pratici per ridurre questo rischio. La buona notizia è che proteggere una distribuzione di agenti non richiede infrastrutture esotiche. Gli stessi principi che si applicano all’esecuzione di qualsiasi codice semi-affidabile si applicano qui: isolamento, privilegio minimo e difesa in profondità. Claude Code include diverse funzionalità di sicurezza che aiutano con le preoccupazioni comuni, e questa guida le esamina insieme a opzioni di hardening aggiuntive per chi ne ha bisogno. Non ogni distribuzione ha bisogno della massima sicurezza. Uno sviluppatore che esegue Claude Code sul proprio laptop ha requisiti diversi da un’azienda che elabora dati dei clienti in un ambiente multi-tenant. Questa guida presenta opzioni che vanno dalle funzionalità di sicurezza integrate di Claude Code alle architetture di produzione indurizzate, in modo che possiate scegliere ciò che si adatta alla vostra situazione.

Modello di minaccia

Gli agenti possono intraprendere azioni indesiderate a causa di prompt injection (istruzioni incorporate nel contenuto che elaborano) o errore del modello. I modelli Claude sono progettati per resistere a questo; consultate la panoramica del modello e la scheda di sistema per il modello che distribuite per i dettagli di valutazione. La difesa in profondità è comunque una buona pratica. Ad esempio, se un agente elabora un file dannoso che gli istruisce di inviare dati dei clienti a un server esterno, i controlli di rete possono bloccare completamente quella richiesta.

Funzionalità di sicurezza integrate

Claude Code include diverse funzionalità di sicurezza che affrontano le preoccupazioni comuni. Consultate la documentazione sulla sicurezza per i dettagli completi.

Sistema di autorizzazioni: Ogni strumento e comando bash può essere configurato per consentire, bloccare o richiedere l’approvazione dell’utente. Utilizzate i pattern glob per creare regole come “consenti tutti i comandi npm” o “blocca qualsiasi comando con sudo”. Le organizzazioni possono impostare politiche che si applicano a tutti gli utenti. Consultate autorizzazioni.
Analisi dei comandi per le autorizzazioni: Prima di eseguire i comandi bash, Claude Code li analizza in un AST e confronta il risultato con le vostre regole di autorizzazione. I comandi che non possono essere analizzati correttamente, o che non corrispondono a una regola di consentimento, richiedono approvazione esplicita. Un piccolo insieme di costrutti come eval richiedono sempre approvazione indipendentemente dalle regole di consentimento. Questo è un gate di autorizzazione, non una sandbox; non deduce se un comando è pericoloso dal suo percorso di destinazione o effetti.
Riepilogo della ricerca web: I risultati della ricerca vengono riepilogati piuttosto che passare il contenuto grezzo direttamente nel contesto, riducendo il rischio di prompt injection da contenuto web dannoso.
Modalità sandbox: I comandi Bash possono essere eseguiti in un ambiente sandbox che limita l’accesso al filesystem e alla rete. Consultate la documentazione del sandboxing per i dettagli.

Principi di sicurezza

Per le distribuzioni che richiedono hardening aggiuntivo oltre ai valori predefiniti di Claude Code, questi principi guidano le opzioni disponibili.

Confini di sicurezza

Un confine di sicurezza separa i componenti con diversi livelli di fiducia. Per le distribuzioni ad alta sicurezza, potete posizionare le risorse sensibili (come le credenziali) al di fuori del confine che contiene l’agente. Se qualcosa va storto nell’ambiente dell’agente, le risorse al di fuori di quel confine rimangono protette. Ad esempio, piuttosto che dare a un agente accesso diretto a una chiave API, potreste eseguire un proxy al di fuori dell’ambiente dell’agente che inietta la chiave nelle richieste. L’agente può effettuare chiamate API, ma non vede mai la credenziale stessa. Questo pattern è utile per le distribuzioni multi-tenant o quando si elabora contenuto non affidabile.

Privilegio minimo

Quando necessario, potete limitare l’agente solo alle capacità richieste per il suo compito specifico:

Risorsa	Opzioni di restrizione
Filesystem	Montare solo le directory necessarie, preferire la sola lettura
Rete	Limitare a endpoint specifici tramite proxy
Credenziali	Iniettare tramite proxy piuttosto che esporre direttamente
Capacità di sistema	Eliminare le capacità Linux nei container

Difesa in profondità

Per gli ambienti ad alta sicurezza, stratificare più controlli fornisce protezione aggiuntiva. Le opzioni includono:

Isolamento dei container
Restrizioni di rete
Controlli del filesystem
Convalida delle richieste presso un proxy

La giusta combinazione dipende dal vostro modello di minaccia e dai requisiti operativi.

Tecnologie di isolamento

Diverse tecnologie di isolamento offrono diversi compromessi tra forza di sicurezza, prestazioni e complessità operativa.

In tutte queste configurazioni, Claude Code (o la vostra applicazione Agent SDK) viene eseguito all’interno del confine di isolamento (la sandbox, il container o la VM). I controlli di sicurezza descritti di seguito limitano ciò che l’agente può accedere da quel confine.

Tecnologia	Forza di isolamento	Overhead di prestazioni	Complessità
Sandbox runtime	Buona (impostazioni predefinite sicure)	Molto bassa	Bassa
Container (Docker)	Dipende dalla configurazione	Bassa	Media
gVisor	Eccellente (con configurazione corretta)	Media/Alta	Media
VM (Firecracker, QEMU)	Eccellente (con configurazione corretta)	Alta	Media/Alta

Sandbox runtime

Per l’isolamento leggero senza container, sandbox-runtime applica restrizioni di filesystem e rete a livello del sistema operativo. Il vantaggio principale è la semplicità: non è richiesta alcuna configurazione Docker, immagini di container o configurazione di rete. Il proxy e le restrizioni del filesystem sono integrati. Fornite un file di configurazione che specifica i domini e i percorsi consentiti. Come funziona:

Filesystem: Utilizza primitive del sistema operativo (bubblewrap su Linux, sandbox-exec su macOS) per limitare l’accesso in lettura/scrittura ai percorsi configurati
Rete: Rimuove lo spazio dei nomi di rete (Linux) o utilizza i profili Seatbelt (macOS) per instradare il traffico di rete attraverso un proxy integrato
Configurazione: Allowlist basate su JSON per domini e percorsi del filesystem

Configurazione:

npm install @anthropic-ai/sandbox-runtime

Quindi create un file di configurazione che specifica i percorsi e i domini consentiti. Considerazioni sulla sicurezza:

Kernel dello stesso host: A differenza delle VM, i processi in sandbox condividono il kernel dell’host. Una vulnerabilità del kernel potrebbe teoricamente abilitare un’evasione. Per alcuni modelli di minaccia questo è accettabile, ma se avete bisogno di isolamento a livello di kernel, utilizzate gVisor o una VM separata.
Nessuna ispezione TLS: Il proxy consente i domini in base al nome host fornito dal client e non termina o ispeziona il traffico crittografato. Il codice in esecuzione all’interno della sandbox può potenzialmente utilizzare domain fronting o tecniche simili per raggiungere host al di fuori dell’allowlist. Se il vostro modello di minaccia richiede garanzie più forti, configurate un proxy che termina TLS. Consultate le limitazioni di sicurezza del sandboxing per ulteriori dettagli. Separatamente, se l’agente ha credenziali permissive per un dominio consentito, assicuratevi che non possa utilizzare quel dominio per attivare altre richieste di rete o per estrarre dati.

Per molti casi di uso a sviluppatore singolo e CI/CD, sandbox-runtime aumenta significativamente la barra con una configurazione minima. Le sezioni seguenti coprono container e VM per le distribuzioni che richiedono un isolamento più forte.

Container

I container forniscono isolamento attraverso i namespace di Linux. Ogni container ha la sua propria vista del filesystem, dell’albero dei processi e dello stack di rete, mentre condivide il kernel dell’host. Una configurazione di container con hardening di sicurezza potrebbe assomigliare a questa:

docker run \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --security-opt seccomp=/path/to/seccomp-profile.json \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /home/agent:rw,noexec,nosuid,size=500m \
  --network none \
  --memory 2g \
  --cpus 2 \
  --pids-limit 100 \
  --user 1000:1000 \
  -v /path/to/code:/workspace:ro \
  -v /var/run/proxy.sock:/var/run/proxy.sock:ro \
  agent-image

Ecco cosa fa ogni opzione:

Opzione	Scopo
`--cap-drop ALL`	Rimuove le capacità Linux come `NET_ADMIN` e `SYS_ADMIN` che potrebbero abilitare l’escalation dei privilegi
`--security-opt no-new-privileges`	Impedisce ai processi di ottenere privilegi attraverso i binari setuid
`--security-opt seccomp=...`	Limita le syscall disponibili; il valore predefinito di Docker blocca ~44, i profili personalizzati possono bloccare di più
`--read-only`	Rende il filesystem root del container immutabile, impedendo all’agente di persistere i cambiamenti
`--tmpfs /tmp:...`	Fornisce una directory temporanea scrivibile che viene cancellata quando il container si ferma
`--network none`	Rimuove tutte le interfacce di rete; l’agente comunica attraverso il socket Unix montato di seguito
`--memory 2g`	Limita l’utilizzo della memoria per prevenire l’esaurimento delle risorse
`--pids-limit 100`	Limita il conteggio dei processi per prevenire fork bomb
`--user 1000:1000`	Viene eseguito come utente non root
`-v ...:/workspace:ro`	Monta il codice in sola lettura in modo che l’agente possa analizzarlo ma non modificarlo. Evitate di montare directory host sensibili come `~/.ssh`, `~/.aws` o `~/.config`
`-v .../proxy.sock:...`	Monta un socket Unix connesso a un proxy in esecuzione al di fuori del container (vedi sotto)

Architettura del socket Unix: Con --network none, il container non ha alcuna interfaccia di rete. L’unico modo per l’agente di raggiungere il mondo esterno è attraverso il socket Unix montato, che si connette a un proxy in esecuzione sull’host. Questo proxy può applicare allowlist di domini, iniettare credenziali e registrare tutto il traffico. Questa è la stessa architettura utilizzata da sandbox-runtime. Anche se l’agente è compromesso tramite prompt injection, non può estrarre dati a server arbitrari. Può solo comunicare attraverso il proxy, che controlla quali domini sono raggiungibili. Per ulteriori dettagli, consultate il post del blog sul sandboxing di Claude Code. Opzioni di hardening aggiuntive:

Opzione	Scopo
`--userns-remap`	Mappa il root del container a un utente host senza privilegi; richiede la configurazione del daemon ma limita i danni dall’evasione del container
`--ipc private`	Isola la comunicazione tra processi per prevenire attacchi tra container

gVisor

I container standard condividono il kernel dell’host: quando il codice all’interno di un container effettua una chiamata di sistema, va direttamente allo stesso kernel che esegue l’host. Questo significa che una vulnerabilità del kernel potrebbe consentire l’evasione del container. gVisor affronta questo intercettando le chiamate di sistema nello spazio utente prima che raggiungano il kernel dell’host, implementando il suo proprio livello di compatibilità che gestisce la maggior parte delle syscall senza coinvolgere il kernel reale. Se un agente esegue codice dannoso (forse a causa di prompt injection), quel codice viene eseguito nel container e potrebbe tentare exploit del kernel. Con gVisor, la superficie di attacco è molto più piccola: il codice dannoso dovrebbe prima sfruttare l’implementazione dello spazio utente di gVisor e avrebbe accesso limitato al kernel reale. Per utilizzare gVisor con Docker, installate il runtime runsc e configurate il daemon:

// /etc/docker/daemon.json
{
  "runtimes": {
    "runsc": {
      "path": "/usr/local/bin/runsc"
    }
  }
}

Quindi eseguite i container con:

docker run --runtime=runsc agent-image

Considerazioni sulle prestazioni:

Carico di lavoro	Overhead
Calcolo CPU-bound	~0% (nessuna intercettazione di syscall)
Syscall semplici	~2× più lento
I/O file intensivo	Fino a 10-200× più lento per pattern di apertura/chiusura pesanti

Per gli ambienti multi-tenant o quando si elabora contenuto non affidabile, l’isolamento aggiuntivo spesso vale l’overhead.

Macchine virtuali

Le VM forniscono isolamento a livello hardware attraverso le estensioni di virtualizzazione della CPU. Ogni VM esegue il suo proprio kernel, creando un confine forte. Una vulnerabilità nel kernel guest non compromette direttamente l’host. Tuttavia, le VM non sono automaticamente “più sicure” di alternative come gVisor. La sicurezza della VM dipende molto dall’hypervisor e dal codice di emulazione dei dispositivi. Firecracker è progettato per l’isolamento leggero di microVM. Può avviare VM in meno di 125ms con meno di 5 MiB di overhead di memoria, eliminando l’emulazione dei dispositivi non necessaria per ridurre la superficie di attacco. Con questo approccio, la VM dell’agente non ha alcuna interfaccia di rete esterna. Invece, comunica attraverso vsock (socket virtuali). Tutto il traffico viene instradato tramite vsock a un proxy sull’host, che applica allowlist e inietta credenziali prima di inoltrare le richieste.

Distribuzioni cloud

Per le distribuzioni cloud, potete combinare qualsiasi tecnologia di isolamento di cui sopra con controlli di rete nativi del cloud:

Eseguite i container dell’agente in una subnet privata senza gateway internet
Configurate le regole del firewall cloud (AWS Security Groups, GCP VPC firewall) per bloccare tutto l’egress tranne verso il vostro proxy
Eseguite un proxy (come Envoy con il suo filtro credential_injector) che convalida le richieste, applica allowlist di domini, inietta credenziali e inoltra alle API esterne
Assegnate autorizzazioni IAM minime all’account di servizio dell’agente, instradando l’accesso sensibile attraverso il proxy dove possibile
Registrate tutto il traffico presso il proxy a scopo di audit

Gestione delle credenziali

Gli agenti spesso hanno bisogno di credenziali per chiamare API, accedere a repository o interagire con servizi cloud. La sfida è fornire questo accesso senza esporre le credenziali stesse.

Il pattern del proxy

L’approccio consigliato è eseguire un proxy al di fuori del confine di sicurezza dell’agente che inietta le credenziali nelle richieste in uscita. L’agente invia richieste senza credenziali, il proxy le aggiunge e inoltra la richiesta alla sua destinazione. Questo pattern ha diversi vantaggi:

L’agente non vede mai le credenziali effettive
Il proxy può applicare un allowlist di endpoint consentiti
Il proxy può registrare tutte le richieste per l’audit
Le credenziali vengono archiviate in un’unica posizione sicura piuttosto che distribuite a ogni agente

Configurazione di Claude Code per utilizzare un proxy

Claude Code supporta due metodi per instradare le richieste di sampling attraverso un proxy: Opzione 1: ANTHROPIC_BASE_URL (semplice ma solo per le richieste API di sampling)

export ANTHROPIC_BASE_URL="http://localhost:8080"

Questo dice a Claude Code e all’Agent SDK di inviare le richieste di sampling al vostro proxy invece che direttamente all’API Claude. Il vostro proxy riceve richieste HTTP in testo semplice, può ispezionarle e modificarle (incluso l’iniezione di credenziali), quindi inoltra all’API reale. Opzione 2: HTTP_PROXY / HTTPS_PROXY (a livello di sistema)

export HTTP_PROXY="http://localhost:8080"
export HTTPS_PROXY="http://localhost:8080"

Claude Code e l’Agent SDK rispettano queste variabili di ambiente standard, instradando tutto il traffico HTTP attraverso il proxy. Per HTTPS, il proxy crea un tunnel CONNECT crittografato: non può vedere o modificare il contenuto delle richieste senza l’intercettazione TLS.

Implementazione di un proxy

Potete costruire il vostro proxy o utilizzarne uno esistente:

Envoy Proxy: proxy di livello produzione con filtro credential_injector per aggiungere header di autenticazione
mitmproxy: proxy che termina TLS per ispezionare e modificare il traffico HTTPS
Squid: proxy di caching con liste di controllo di accesso
LiteLLM: gateway LLM con iniezione di credenziali e rate limiting

Credenziali per altri servizi

Oltre al sampling dall’API Claude, gli agenti spesso hanno bisogno di accesso autenticato ad altri servizi, come repository git, database e API interne. Ci sono due approcci principali:

Strumenti personalizzati

Fornire accesso attraverso un server MCP o uno strumento personalizzato che instrada le richieste a un servizio in esecuzione al di fuori del confine di sicurezza dell’agente. L’agente chiama lo strumento, ma la richiesta autenticata effettiva avviene all’esterno. Le chiamate dello strumento vanno a un proxy che inietta le credenziali. Ad esempio, un server MCP git potrebbe accettare comandi dall’agente ma inoltrarli a un proxy git in esecuzione sull’host, che aggiunge l’autenticazione prima di contattare il repository remoto. L’agente non vede mai le credenziali. Vantaggi:

Nessuna intercettazione TLS: Il servizio esterno effettua richieste autenticate direttamente
Le credenziali rimangono all’esterno: L’agente vede solo l’interfaccia dello strumento, non le credenziali sottostanti

Inoltro del traffico

Per le chiamate all’API Claude, ANTHROPIC_BASE_URL vi consente di instradare le richieste a un proxy che può ispezionarle e modificarle in testo semplice. Ma per altri servizi HTTPS (GitHub, registri npm, API interne), il traffico è spesso crittografato end-to-end. Anche se lo instradate attraverso un proxy tramite HTTP_PROXY, il proxy vede solo un tunnel TLS opaco e non può iniettare credenziali. Per modificare il traffico HTTPS verso servizi arbitrari, senza utilizzare uno strumento personalizzato, avete bisogno di un proxy che termina TLS che decrittografa il traffico, lo ispeziona o lo modifica, quindi lo ricripta prima di inoltrarlo. Questo richiede:

Esecuzione del proxy al di fuori del container dell’agente
Installazione del certificato CA del proxy nell’archivio di fiducia dell’agente (in modo che l’agente si fidi dei certificati del proxy)
Configurazione di HTTP_PROXY/HTTPS_PROXY per instradare il traffico attraverso il proxy

Questo approccio gestisce qualsiasi servizio basato su HTTP senza scrivere strumenti personalizzati, ma aggiunge complessità attorno alla gestione dei certificati. Notate che non tutti i programmi rispettano HTTP_PROXY/HTTPS_PROXY. La maggior parte degli strumenti (curl, pip, npm, git) lo fa, ma alcuni potrebbero bypassare queste variabili e connettersi direttamente. Ad esempio, fetch() di Node.js ignora queste variabili per impostazione predefinita; in Node 24+ potete impostare NODE_USE_ENV_PROXY=1 per abilitare il supporto. Per una copertura completa, potete utilizzare proxychains per intercettare le chiamate di rete, o configurare iptables per reindirizzare il traffico in uscita a un proxy trasparente.

Un proxy trasparente intercetta il traffico a livello di rete, quindi il client non ha bisogno di essere configurato per utilizzarlo. I proxy regolari richiedono ai client di connettersi esplicitamente e parlare HTTP CONNECT o SOCKS. I proxy trasparenti (come Squid o mitmproxy in modalità trasparente) possono gestire connessioni TCP grezze reindirizzate.

Entrambi gli approcci richiedono ancora il proxy che termina TLS e il certificato CA affidabile. Assicurano semplicemente che il traffico raggiunga effettivamente il proxy.

Configurazione del filesystem

I controlli del filesystem determinano quali file l’agente può leggere e scrivere.

Montaggio del codice in sola lettura

Quando l’agente ha bisogno di analizzare il codice ma non modificarlo, montate la directory in sola lettura:

docker run -v /path/to/code:/workspace:ro agent-image

Anche l’accesso in sola lettura a una directory di codice può esporre le credenziali. File comuni da escludere o bonificare prima del montaggio:

File	Rischio
`.env`, `.env.local`	Chiavi API, password del database, segreti
`~/.git-credentials`	Password/token git in testo semplice
`~/.aws/credentials`	Chiavi di accesso AWS
`~/.config/gcloud/application_default_credentials.json`	Token ADC di Google Cloud
`~/.azure/`	Credenziali CLI di Azure
`~/.docker/config.json`	Token di autenticazione del registro Docker
`~/.kube/config`	Credenziali del cluster Kubernetes
`.npmrc`, `.pypirc`	Token del registro dei pacchetti
`*-service-account.json`	Chiavi dell’account di servizio GCP
`.pem`, `.key`	Chiavi private

Considerate di copiare solo i file sorgente necessari, o di utilizzare il filtraggio in stile .dockerignore.

Posizioni scrivibili

Se l’agente ha bisogno di scrivere file, avete alcune opzioni a seconda che vogliate che i cambiamenti persistano: Per gli spazi di lavoro effimeri nei container, utilizzate i montaggi tmpfs che esistono solo in memoria e vengono cancellati quando il container si ferma:

docker run \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /workspace:rw,noexec,size=500m \
  agent-image

Se volete rivedere i cambiamenti prima di renderli persistenti, un filesystem overlay consente all’agente di scrivere senza modificare i file sottostanti. I cambiamenti vengono archiviati in un livello separato che potete ispezionare, applicare o scartare. Per un output completamente persistente, montate un volume dedicato ma mantenetelo separato dalle directory sensibili.

Agent SDK

Concetti fondamentali

Input e output

Estendi con strumenti

Personalizza il comportamento

Controllo e osservabilità

Distribuzione

Riferimenti SDK

Distribuzione sicura di agenti AI

Modello di minaccia

Funzionalità di sicurezza integrate

Principi di sicurezza

Confini di sicurezza

Privilegio minimo

Difesa in profondità

Tecnologie di isolamento

Sandbox runtime

Container

gVisor

Macchine virtuali

Distribuzioni cloud

Gestione delle credenziali

Il pattern del proxy

Configurazione di Claude Code per utilizzare un proxy

Implementazione di un proxy

Credenziali per altri servizi

Strumenti personalizzati

Inoltro del traffico

Configurazione del filesystem

Montaggio del codice in sola lettura

Posizioni scrivibili

Letture ulteriori

​Modello di minaccia

​Funzionalità di sicurezza integrate

​Principi di sicurezza

​Confini di sicurezza

​Privilegio minimo

​Difesa in profondità

​Tecnologie di isolamento

​Sandbox runtime

​Container

​gVisor

​Macchine virtuali

​Distribuzioni cloud

​Gestione delle credenziali

​Il pattern del proxy

​Configurazione di Claude Code per utilizzare un proxy

​Implementazione di un proxy

​Credenziali per altri servizi

​Strumenti personalizzati

​Inoltro del traffico

​Configurazione del filesystem

​Montaggio del codice in sola lettura

​Posizioni scrivibili

​Letture ulteriori

Modello di minaccia

Funzionalità di sicurezza integrate

Principi di sicurezza

Confini di sicurezza

Privilegio minimo

Difesa in profondità

Tecnologie di isolamento

Sandbox runtime

Container

gVisor

Macchine virtuali

Distribuzioni cloud

Gestione delle credenziali

Il pattern del proxy

Configurazione di Claude Code per utilizzare un proxy

Implementazione di un proxy

Credenziali per altri servizi

Strumenti personalizzati

Inoltro del traffico

Configurazione del filesystem

Montaggio del codice in sola lettura

Posizioni scrivibili

Letture ulteriori