Implantação segura de agentes de IA

Um guia para proteger implantações do Claude Code e Agent SDK com isolamento, gerenciamento de credenciais e controles de rede

Claude Code e o Agent SDK podem executar código, acessar arquivos e interagir com serviços externos em seu nome.

Ao contrário do software tradicional que segue caminhos de código predeterminados, essas ferramentas geram suas ações dinamicamente com base no contexto e nos objetivos. Essa flexibilidade é o que as torna úteis, mas também significa que seu comportamento pode ser influenciado pelo conteúdo que processam: arquivos, páginas da web ou entrada do usuário. Isso às vezes é chamado de injeção de prompt. Por exemplo, se o README de um repositório contiver instruções incomuns, Claude Code pode incorporar essas instruções em suas ações de maneiras que o operador não antecipou. Este guia aborda maneiras práticas de reduzir esse risco.

Nem toda implantação precisa de segurança máxima. Um desenvolvedor executando Claude Code em seu laptop tem requisitos diferentes de uma empresa processando dados de clientes em um ambiente multi-tenant. Este guia apresenta opções que variam desde os recursos de segurança integrados do Claude Code até arquiteturas de produção endurecidas, para que você possa escolher o que se adequa à sua situação.

Modelo de ameaça

Agentes podem tomar ações não intencionais devido a injeção de prompt (instruções incorporadas no conteúdo que processam) ou erro do modelo. Os modelos Claude são projetados para resistir a isso; consulte a visão geral do modelo e o cartão do sistema para o modelo que você implanta para detalhes de avaliação.

A defesa em profundidade ainda é uma boa prática. Por exemplo, se um agente processa um arquivo malicioso que o instrui a enviar dados de clientes para um servidor externo, controles de rede podem bloquear essa solicitação completamente.

Recursos de segurança integrados

Claude Code inclui vários recursos de segurança que abordam preocupações comuns. Consulte a documentação de segurança para detalhes completos.

• Sistema de permissões: As regras de permissão decidem se uma chamada de ferramenta é executada, bloqueada ou solicita aprovação primeiro. Para as formas que uma regra de Bash não captura e como as regras se combinam com os modos de permissão, consulte O que uma regra de Bash não corresponde e Configurar permissões. Os administradores também podem definir regras em configurações gerenciadas.
• Remoções de caminho crítico: Com o modo de permissão definido como default, um comando rm ou rmdir reconhecido como removendo seu diretório de trabalho ou outro caminho crítico requer aprovação. Uma regra de permissão allow correspondente não dispensa essa aprovação. Esta é uma porta de permissão, não um sandbox. Para controlar o que o agente pode gravar, use controles do sistema de arquivos.
• Resumo de pesquisa na web: Os resultados da pesquisa são resumidos em vez de passar o conteúdo bruto diretamente para o contexto, reduzindo o risco de injeção de prompt de conteúdo web malicioso.
• Modo sandbox: Comandos Bash podem ser executados em um ambiente sandboxed que restringe acesso ao sistema de arquivos e rede. Consulte a documentação de sandboxing para detalhes.

Princípios de segurança

Para implantações que requerem endurecimento adicional além dos padrões do Claude Code, esses princípios guiam as opções disponíveis.

Limites de segurança

Um limite de segurança separa componentes com diferentes níveis de confiança. Para implantações de alta segurança, você pode colocar recursos sensíveis (como credenciais) fora do limite contendo o agente. Se algo der errado no ambiente do agente, recursos fora desse limite permanecem protegidos.

Por exemplo, em vez de dar a um agente acesso direto a uma chave de API, você poderia executar um proxy fora do ambiente do agente que injeta a chave em solicitações. O agente pode fazer chamadas de API, mas nunca vê a credencial em si. Esse padrão é útil para implantações multi-tenant ou ao processar conteúdo não confiável.

Privilégio mínimo

Quando necessário, você pode restringir o agente apenas às capacidades necessárias para sua tarefa específica:

Defesa em profundidade

Para ambientes de alta segurança, camadas de múltiplos controles fornecem proteção adicional. As opções incluem:

• Isolamento de contêiner
• Restrições de rede
• Controles de sistema de arquivos
• Validação de solicitação em um proxy

A combinação correta depende do seu modelo de ameaça e requisitos operacionais.

Tecnologias de isolamento

Diferentes tecnologias de isolamento oferecem diferentes compensações entre nível de segurança, desempenho e complexidade operacional.

[!NOTE]

Em todas essas configurações, o Claude Code (ou sua aplicação do Agent SDK) é executado dentro da fronteira de isolamento (o sandbox, o contêiner ou a VM). Os controles de segurança descritos abaixo restringem o que o agente pode acessar a partir dessa fronteira.

Sandbox runtime

Para um isolamento leve sem contêineres, o sandbox-runtime aplica restrições de sistema de arquivos e de rede no nível do sistema operacional.

A principal vantagem é a simplicidade: não é necessária configuração do Docker, imagens de contêiner nem configuração de rede. O proxy e as restrições de sistema de arquivos já vêm integrados.

Como funciona:

• Sistema de arquivos: usa primitivas do sistema operacional (bubblewrap no Linux, sandbox-exec no macOS) para restringir o acesso de leitura/gravação aos caminhos configurados
• Rede: executa os comandos em seu próprio namespace de rede (Linux) ou sob um perfil Seatbelt (macOS) e roteia o tráfego deles por um proxy integrado que permite os domínios configurados. Uma conexão com um host externo que ignora o proxy falha.
• Configuração: allowlists baseadas em JSON para domínios e caminhos do sistema de arquivos

Configuração inicial:

Para as etapas de instalação, configuração e inicialização, consulte Configurar e iniciar o runtime.

Considerações de segurança:

1. Kernel do mesmo host: diferentemente das VMs, os processos em sandbox compartilham o kernel do host. Uma vulnerabilidade no kernel poderia, teoricamente, permitir uma fuga. Para alguns modelos de ameaça isso é aceitável, mas se você precisar de isolamento no nível do kernel, use gVisor ou uma VM separada.

2. Sem inspeção de TLS: por padrão, o proxy filtra os domínios com base na allowlist usando o nome de host fornecido pelo cliente e não encerra nem inspeciona o tráfego criptografado. O código executado dentro do sandbox pode potencialmente usar domain fronting ou técnicas semelhantes para alcançar hosts fora da allowlist. Se o seu modelo de ameaça exigir garantias mais fortes, use um proxy que encerre o TLS e inspecione o tráfego, conforme descrito em Encaminhamento de tráfego. Para mais informações, consulte as limitações de segurança do sandboxing.

3. Credenciais para domínios permitidos: se o agente tiver credenciais permissivas para um domínio permitido, certifique-se de que ele não possa usar esse domínio para disparar outras requisições de rede ou para exfiltrar dados.

Para muitos casos de uso de desenvolvedor individual e de CI/CD, o sandbox-runtime eleva significativamente o nível de segurança com configuração mínima. As seções abaixo abordam contêineres e VMs para implantações que exigem um isolamento mais forte.

Contêineres

Os contêineres oferecem isolamento por meio de namespaces do Linux. Cada contêiner tem sua própria visão do sistema de arquivos, da árvore de processos e da pilha de rede, enquanto compartilha o kernel do host.

Uma configuração de contêiner com segurança reforçada pode ser assim:

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

Veja o que cada opção faz:

Arquitetura de socket Unix:

Com --network none, uma consulta DNS ou uma conexão direta com outro host falha dentro do contêiner. Para permitir que o código no contêiner alcance outros hosts, execute um proxy no host e monte o socket Unix dele no contêiner. Se você apontar ANTHROPIC_BASE_URL ou HTTP_PROXY para uma porta em localhost, como mostrado em Configurar o Claude Code para usar um proxy, retransmita essa porta dentro do contêiner para o socket.

Você pode configurar esse proxy para aplicar allowlists de domínios, injetar credenciais e registrar todo o tráfego em log.

[!WARNING]

Dentro da allowlist do seu proxy, o agente pode enviar dados para qualquer domínio permitido. Permita apenas os domínios de que o agente precisa.

Opções adicionais de reforço de segurança:

gVisor

Contêineres padrão compartilham o kernel do host: quando o código dentro de um contêiner faz uma chamada de sistema, ela vai diretamente para o mesmo kernel que executa o host. Isso significa que uma vulnerabilidade no kernel poderia permitir a fuga do contêiner. O gVisor resolve isso interceptando as chamadas de sistema no espaço do usuário antes que cheguem ao kernel do host, implementando sua própria camada de compatibilidade que trata a maioria das syscalls sem envolver o kernel real.

Se um agente executar código malicioso (talvez devido a uma injeção de prompt), esse código será executado no contêiner e poderá tentar explorar o kernel. Com o gVisor, a superfície de ataque é muito menor: o código malicioso precisaria primeiro explorar a implementação do gVisor no espaço do usuário e teria acesso limitado ao kernel real.

Para usar o gVisor com o Docker, instale o runtime runsc e configure o daemon:

{
  "runtimes": {
    "runsc": {
      "path": "/usr/local/bin/runsc"
    }
  }
}

Em seguida, execute os contêineres com:

docker run --runtime=runsc agent-image

Considerações de desempenho:

Para ambientes multilocatário ou ao processar conteúdo não confiável, o isolamento adicional geralmente compensa a sobrecarga.

Máquinas virtuais

As VMs oferecem isolamento no nível de hardware por meio de extensões de virtualização da CPU. Cada VM executa seu próprio kernel, criando uma fronteira forte. Uma vulnerabilidade no kernel convidado não compromete diretamente o host. No entanto, as VMs não são automaticamente "mais seguras" do que alternativas como o gVisor. A segurança das VMs depende muito do hipervisor e do código de emulação de dispositivos.

O Firecracker foi projetado para isolamento leve com microVMs. Ele consegue inicializar VMs em menos de 125 ms com menos de 5 MiB de sobrecarga de memória RAM, eliminando a emulação de dispositivos desnecessária para reduzir a superfície de ataque.

Com essa abordagem, a VM do agente não tem interface de rede externa. Em vez disso, ela se comunica por meio de vsock (sockets virtuais). Todo o tráfego é roteado pelo vsock até um proxy no host, que aplica as allowlists e injeta credenciais antes de encaminhar as requisições.

Implantações em nuvem

Para implantações em nuvem, você pode combinar qualquer uma das tecnologias de isolamento acima com controles de rede nativos da nuvem:

1. Execute os contêineres do agente em uma sub-rede privada sem gateway de internet
2. Configure regras de firewall da nuvem (AWS Security Groups, firewall de VPC do GCP) para bloquear todo o tráfego de saída, exceto para o seu proxy
3. Execute um proxy (como o Envoy com seu filtro credential_injector) que valide as requisições, aplique allowlists de domínios, injete credenciais e encaminhe para APIs externas
4. Atribua permissões mínimas de IAM à conta de serviço do agente, roteando o acesso sensível pelo proxy sempre que possível
5. Registre todo o tráfego em log no proxy para fins de auditoria

Gerenciamento de credenciais

Agentes frequentemente precisam de credenciais para chamar APIs, acessar repositórios ou interagir com serviços em nuvem. O desafio é fornecer esse acesso sem expor as credenciais em si.

O padrão de proxy

A abordagem recomendada é executar um proxy fora do limite de segurança do agente que injeta credenciais em solicitações de saída. O agente envia solicitações sem credenciais, o proxy as adiciona e encaminha a solicitação para seu destino.

Este padrão tem vários benefícios:

1. O agente nunca vê as credenciais reais
2. O proxy pode impor uma lista de permissão de endpoints permitidos
3. O proxy pode registrar todas as solicitações para auditoria
4. Credenciais são armazenadas em um local seguro em vez de distribuídas para cada agente

Configurando Claude Code para usar um proxy

Claude Code suporta dois métodos para rotear solicitações de amostragem através de um proxy:

Opção 1: ANTHROPIC_BASE_URL (simples mas apenas para solicitações de API de amostragem)

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

Isso diz ao Claude Code e ao Agent SDK para enviar solicitações de amostragem para seu proxy em vez de diretamente para a API Claude. Seu proxy recebe solicitações HTTP em texto simples, pode inspecionar e modificá-las (incluindo injetar credenciais), então encaminha para a API real.

Opção 2: HTTP_PROXY / HTTPS_PROXY (em todo o sistema)

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

Claude Code e o Agent SDK respeitam essas variáveis de ambiente padrão, roteando todo o tráfego HTTP através do proxy. Para HTTPS, o proxy cria um túnel CONNECT criptografado: ele não pode ver ou modificar conteúdo de solicitação sem interceptação TLS.

Implementando um proxy

Você pode construir seu próprio proxy ou usar um existente:

• Envoy Proxy: proxy de nível de produção com filtro credential_injector para adicionar cabeçalhos de autenticação
• mitmproxy: proxy que termina TLS para inspecionar e modificar tráfego HTTPS
• Squid: proxy de cache com listas de controle de acesso
• LiteLLM: gateway LLM com injeção de credenciais e limitação de taxa

Credenciais para outros serviços

Além de amostragem da API Claude, agentes frequentemente precisam de acesso autenticado a outros serviços, como repositórios git, bancos de dados e APIs internas. Existem duas abordagens principais:

Ferramentas personalizadas

Forneça acesso através de um servidor MCP ou ferramenta personalizada que roteia solicitações para um serviço executado fora do limite de segurança do agente. O agente chama a ferramenta, mas a solicitação autenticada real acontece fora. As chamadas de ferramenta vão para um proxy que injeta as credenciais.

Por exemplo, um servidor MCP git poderia aceitar comandos do agente mas encaminhá-los para um proxy git executado no host, que adiciona autenticação antes de contatar o repositório remoto. O agente nunca vê as credenciais.

Vantagens:

• Sem interceptação TLS: O serviço externo faz solicitações autenticadas diretamente
• Credenciais ficam fora: O agente apenas vê a interface da ferramenta, não as credenciais subjacentes

Encaminhamento de tráfego

Para chamadas de API Claude, ANTHROPIC_BASE_URL permite rotear solicitações para um proxy que pode inspecionar e modificá-las em texto simples. Mas para outros serviços HTTPS (GitHub, registros npm, APIs internas), o tráfego geralmente é criptografado de ponta a ponta. Mesmo se você o rotear através de um proxy via HTTP_PROXY, o proxy apenas vê um túnel TLS opaco e não pode injetar credenciais.

Para modificar tráfego HTTPS para serviços arbitrários, sem usar uma ferramenta personalizada, você precisa de um proxy que termina TLS que descriptografa tráfego, inspeciona ou modifica, então re-criptografa antes de encaminhar. Isso requer:

1. Executar o proxy fora do contêiner do agente
2. Instalar o certificado CA do proxy no armazenamento de confiança do agente (para que o agente confie nos certificados do proxy)
3. Configurar HTTP_PROXY/HTTPS_PROXY para rotear tráfego através do proxy

Esta abordagem lida com qualquer serviço baseado em HTTP sem escrever ferramentas personalizadas, mas adiciona complexidade em torno do gerenciamento de certificados.

Note que nem todos os programas respeitam HTTP_PROXY/HTTPS_PROXY. A maioria das ferramentas (curl, pip, npm, git) respeita, mas algumas podem contornar essas variáveis e conectar diretamente. Por exemplo, fetch() do Node.js ignora essas variáveis por padrão; no Node 24+ você pode definir NODE_USE_ENV_PROXY=1 para habilitar suporte. Para cobrir ferramentas que ignoram essas variáveis, você pode usar proxychains para interceptar chamadas de rede, ou configurar iptables para redirecionar tráfego de saída para um proxy transparente.

[!NOTE]

Um proxy transparente intercepta tráfego no nível de rede, então o cliente não precisa ser configurado para usá-lo. Proxies regulares requerem que clientes se conectem explicitamente e falem HTTP CONNECT ou SOCKS. Proxies transparentes (como Squid ou mitmproxy em modo transparente) podem lidar com conexões TCP brutas redirecionadas.

Ambas as abordagens ainda requerem o proxy que termina TLS e certificado CA confiável. Elas apenas garantem que o tráfego realmente alcance o proxy.

Configuração do sistema de arquivos

Controles de sistema de arquivos determinam quais arquivos o agente pode ler e escrever.

Montagem de código somente leitura

Quando o agente precisa analisar código mas não modificá-lo, monte o diretório somente leitura:

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

[!WARNING]

Mesmo acesso somente leitura a um diretório de código pode expor credenciais. Arquivos comuns para excluir ou sanitizar antes de montar:

Arquivo	Risco
.env, .env.local	Chaves de API, senhas de banco de dados, segredos
~/.git-credentials	Senhas/tokens git em texto simples
~/.aws/credentials	Chaves de acesso AWS
~/.config/gcloud/application_default_credentials.json	Tokens ADC do Google Cloud
~/.azure/	Credenciais da CLI Azure
~/.docker/config.json	Tokens de autenticação de registro Docker
~/.kube/config	Credenciais de cluster Kubernetes
.npmrc, .pypirc	Tokens de registro de pacotes
*-service-account.json	Chaves de conta de serviço do GCP
*.pem, *.key	Chaves privadas

Considere copiar apenas os arquivos de origem necessários, ou usar filtragem no estilo .dockerignore.

Locais graváveis

Se o agente precisa escrever arquivos, você tem algumas opções dependendo se você quer que as mudanças persistam:

Para espaços de trabalho efêmeros em contêineres, use montagens tmpfs que existem apenas na memória e são limpas quando o contêiner para:

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

Se você quer revisar mudanças antes de persistir, um sistema de arquivos overlay permite que o agente escreva sem modificar arquivos subjacentes. As mudanças são armazenadas em uma camada separada que você pode inspecionar, aplicar ou descartar. Para saída totalmente persistente, monte um volume dedicado mas mantenha-o separado de diretórios sensíveis.

Leitura adicional

• Documentação de segurança do Claude Code
• Hospedando o Agent SDK
• Tratando permissões
• Sandbox runtime
• The Lethal Trifecta for AI Agents
• OWASP Top 10 for LLM Applications
• Docker Security Best Practices
• gVisor Documentation
• Firecracker Documentation