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
-
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
| 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) |
--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"
}
}
}
docker run --runtime=runsc agent-image
| 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 |
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"
export HTTP_PROXY="http://localhost:8080"
export HTTPS_PROXY="http://localhost:8080"
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.
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 |
.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
Letture ulteriori
