Implantação segura de agentes de IA

Claude Code e o Agent SDK são ferramentas poderosas que podem executar código, acessar arquivos e interagir com serviços externos em seu nome. Como qualquer ferramenta com essas capacidades, implantá-las com cuidado garante que você obtenha os benefícios mantendo controles apropriados.

Diferentemente 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 incorporá-las em suas ações de maneiras que o operador não antecipou. Este guia aborda maneiras práticas de reduzir esse risco.

A boa notícia é que proteger uma implantação de agente não requer infraestrutura exótica. Os mesmos princípios que se aplicam à execução de qualquer código semi-confiável se aplicam aqui: isolamento, privilégio mínimo e defesa em profundidade. Claude Code inclui vários recursos de segurança que ajudam com preocupações comuns, e este guia percorre esses recursos junto com opções de endurecimento adicionais para quem precisar delas.

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.

O que estamos protegendo?

Agentes podem executar 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, e conforme analisamos em nosso cartão de modelo, acreditamos que Claude Opus 4.5 é o modelo de fronteira mais robusto disponível.

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: Cada ferramenta e comando bash pode ser configurado para permitir, bloquear ou solicitar aprovação do usuário. Use padrões glob para criar regras como "permitir todos os comandos npm" ou "bloquear qualquer comando com sudo". As organizações podem definir políticas que se aplicam a todos os usuários. Consulte controle de acesso e permissões.
• Análise estática: Antes de executar comandos bash, Claude Code executa análise estática para identificar operações potencialmente arriscadas. Comandos que modificam arquivos do sistema ou acessam diretórios sensíveis são sinalizados e requerem aprovação explícita do usuário.
• 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 sandbox 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 força de segurança, desempenho e complexidade operacional.

Runtime sandbox

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

A principal vantagem é a simplicidade: nenhuma configuração Docker, imagens de contêiner ou configuração de rede necessária. O proxy e as restrições de sistema de arquivos são integrados. Você fornece um arquivo de configurações especificando domínios e caminhos permitidos.

Como funciona:

• Sistema de arquivos: Usa primitivos do SO (bubblewrap no Linux, sandbox-exec no macOS) para restringir acesso de leitura/escrita a caminhos configurados
• Rede: Remove namespace de rede (Linux) ou usa perfis Seatbelt (macOS) para rotear tráfego de rede através de um proxy integrado
• Configuração: Listas de permissão baseadas em JSON para domínios e caminhos do sistema de arquivos

Configuração:

npm install @anthropic-ai/sandbox-runtime

Em seguida, crie um arquivo de configuração especificando caminhos e domínios permitidos.

Considerações de segurança:

1. Kernel no mesmo host: Diferentemente de VMs, processos em sandbox compartilham o kernel do host. Uma vulnerabilidade de kernel poderia teoricamente permitir escape. 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 TLS: O proxy lista domínios permitidos mas não inspeciona tráfego criptografado. Se o agente tiver credenciais permissivas para um domínio permitido, certifique-se de que não seja possível usar esse domínio para disparar outras solicitações de rede ou exfiltrar dados.

Para muitos casos de uso de desenvolvedor único e CI/CD, sandbox-runtime aumenta significativamente a barra com configuração mínima. As seções abaixo cobrem contêineres e VMs para implantações que requerem isolamento mais forte.

Contêineres

Contêineres fornecem isolamento através de namespaces Linux. Cada contêiner tem sua própria visualização do sistema de arquivos, árvore de processos e pilha de rede, enquanto compartilha o kernel do host.

Uma configuração de contêiner endurecida por segurança pode parecer 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

Aqui está o que cada opção faz:

Arquitetura de socket Unix:

Com --network none, o contêiner não tem interfaces de rede. A única maneira do agente alcançar o mundo externo é através do socket Unix montado, que se conecta a um proxy executando no host. Este proxy pode impor listas de permissão de domínio, injetar credenciais e registrar todo o tráfego.

Esta é a mesma arquitetura usada por sandbox-runtime. Mesmo se o agente for comprometido via injeção de prompt, ele não pode exfiltrar dados para servidores arbitrários—ele só pode se comunicar através do proxy, que controla quais domínios são alcançáveis. Para mais detalhes, consulte o post do blog de sandboxing do Claude Code.

Opções de endurecimento adicional:

gVisor

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

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

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

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

Em seguida, execute contêineres com:

docker run --runtime=runsc agent-image

Considerações de desempenho:

Para ambientes multi-tenant ou ao processar conteúdo não confiável, o isolamento adicional geralmente vale a sobrecarga.

Máquinas virtuais

VMs fornecem isolamento no nível de hardware através de extensões de virtualização de CPU. Cada VM executa seu próprio kernel, criando um limite forte—uma vulnerabilidade no kernel convidado não compromete diretamente o host. No entanto, VMs não são automaticamente "mais seguras" que alternativas como gVisor. A segurança de VM depende muito do hipervisor e do código de emulação de dispositivo.

Firecracker é projetado para isolamento leve de microVM—pode inicializar VMs em menos de 125ms com menos de 5 MiB de sobrecarga de memória, removendo emulação de dispositivo 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 através de vsock (sockets virtuais). Todo o tráfego é roteado através de vsock para um proxy no host, que impõe listas de permissão e injeta credenciais antes de encaminhar solicitaçõ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 contêineres de agente em uma sub-rede privada sem gateway de internet
2. Configure regras de firewall em nuvem (AWS Security Groups, firewall VPC do GCP) para bloquear toda saída exceto para seu proxy
3. Execute um proxy (como Envoy com seu filtro credential_injector) que valida solicitações, impõe listas de permissão de domínio, injeta credenciais e encaminha para APIs externas
4. Atribua permissões IAM mínimas à conta de serviço do agente, roteando acesso sensível através do proxy quando possível
5. Registre todo o tráfego 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 da API Anthropic diretamente. 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 Anthropic, agentes frequentemente precisam de acesso autenticado a outros serviços—repositórios git, bancos de dados, 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 executando fora do limite de segurança do agente. O agente chama a ferramenta, mas a solicitação autenticada real acontece fora—a ferramenta chama um proxy que injeta as credenciais.

Por exemplo, um servidor MCP git poderia aceitar comandos do agente mas encaminhá-los para um proxy git executando 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 da API Anthropic, 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ê roteá-lo 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 manipula qualquer serviço baseado em HTTP sem escrever ferramentas personalizadas, mas adiciona complexidade em torno do gerenciamento de certificado.

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 cobertura abrangente, você pode usar proxychains para interceptar chamadas de rede, ou configurar iptables para redirecionar tráfego de saída para um proxy transparente.

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

Locais graváveis

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

Para espaços de trabalho efêmeros em contêineres, use montagens tmpfs que existem apenas em 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—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
• Manipulando permissões
• Sandbox runtime
• The Lethal Trifecta for AI Agents
• OWASP Top 10 for LLM Applications
• Docker Security Best Practices
• gVisor Documentation
• Firecracker Documentation

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