Tutorial de Sandboxing para Agentes: Criar Aplicações LLM Seguras

“`html

Introdução ao Sandboxing de Agentes

À medida que os Modelos de Linguagem de Grande Escala (LLM) evoluem de simples agentes conversacionais para poderosas entidades autônomas capazes de executar código, interagir com APIs externas e tomar decisões no mundo real, torna-se fundamental implementar medidas de segurança robustas. Um agente LLM, quando dotado da possibilidade de agir, pode representar um risco significativo à segurança se não for devidamente restringido. Aqui entra em jogo o sandboxing de agentes. Sandboxing um agente significa criar um ambiente isolado no qual ele pode operar sem influenciar o sistema host ou acessar recursos não autorizados. Este tutorial explorará os aspectos práticos do sandboxing de agentes, fornecendo exemplos práticos para demonstrar como construir aplicações LLM seguras e confiáveis.

O princípio fundamental por trás do sandboxing é o mínimo privilégio: um agente deve ter acesso apenas aos recursos absolutamente necessários para sua função e nada mais. Sem um adequado sandboxing, um agente malicioso ou defeituoso poderia:

• Executar código arbitrário no sistema host, levando a roubo de dados ou comprometimento do sistema.
• Acessar arquivos sensíveis ou recursos de rede.
• Iniciar chamadas de API externas indesejadas, acarretando custos ou executando ações não autorizadas.
• Exfiltrar dados confidenciais através de vários canais.

Implementando um sandboxing eficaz, podemos mitigar esses riscos, permitindo-nos usar o imenso poder dos agentes LLM enquanto mantemos o controle e a segurança.

Compreendendo as Ameaças: Por Que Sandboxing?

Antes de explorar o ‘como’, solidifiquemos o ‘porquê’. As ameaças apresentadas por agentes não sandboxed são multifacetadas e podem ser categorizadas da seguinte forma:

1. Vulnerabilidades de Execução de Código

muitos agentes LLM avançados são projetados para escrever e executar código (por exemplo, scripts Python) para resolver problemas, analisar dados ou interagir com ferramentas. Se essa execução não for contida, o agente poderia:

• Injeção de Comandos de Sistema: Gerar código que chama os.system('rm -rf /') ou comandos destrutivos semelhantes.
• Execução Remota de Código (RCE): Explorar vulnerabilidades em bibliotecas para obter controle sobre o sistema host.
• Exaustão de Recursos: Criar loops infinitos ou alocar memória/CPU excessiva, levando a uma negação de serviço.

2. Acesso a Dados e Exfiltração

Um agente pode ser encarregado de processar dados sensíveis. Sem sandboxing, ele poderia:

• Acesso Não Autorizado a Arquivos: Ler arquivos fora de seu diretório de trabalho designado (por exemplo, /etc/passwd, chaves API).
• Acesso à Rede: Conectar-se a recursos de rede internos, servidores maliciosos externos ou exfiltrar dados para endpoints arbitrários.
• Injeção de Prompts através de Leitura de Arquivos: Se um agente puder ler arquivos arbitrários, um ator malicioso poderia criar um prompt que engana o agente fazendo-o ler um arquivo sensível e incorporando então seu conteúdo em uma saída subsequente.

3. Abuso de APIs e Ferramentas

Os agentes frequentemente interagem com APIs externas ou ferramentas personalizadas. Um acesso irrestrito pode levar a:

• Chamadas API Não Autorizadas: Realizar chamadas a APIs sensíveis às quais não deveria ter acesso (por exemplo, gerenciamento de usuários, processamento de pagamentos).
• Superação de Custos: Ativar chamadas API dispendiosas ou funções em nuvem intensivas em termos de recursos.
• Ações Maliciosas: Se um agente tiver acesso a uma API de email, ele poderia enviar emails de spam ou phishing.

Técnicas e Ferramentas de Sandboxing

Existem vários níveis e técnicas que podemos empregar para o sandboxing de agentes, que vão desde simples revisões de código até sofisticadas técnicas de containerização.

1. Sandboxing a Nível de Linguagem (Restrições ao Interpretador de Código)

Se o seu agente gera e executa principalmente código (por exemplo, Python), você pode limitar as capacidades do interpretador.

Exemplo: Execução Python Limitada com exec() e Whitelisting

Um cenário comum é um agente que gera código Python. Em vez de chamar diretamente exec() ou eval() em strings arbitrárias, você pode limitar os globais e os built-ins disponíveis.

“`

import subprocess
import os

def safe_execute_python_code(code: str, allowed_modules: list = None, timeout: int = 10):
 if allowed_modules is None:
 allowed_modules = ['math', 'json', 're'] # Lista de módulos permitidos

 # Cria um espaço de nomes global restrito
 restricted_globals = {
 '__builtins__': {key: globals()['__builtins__'][key] for key in [
 'print', 'len', 'str', 'int', 'float', 'list', 'dict', 'tuple', 'set', 
 'range', 'sum', 'min', 'max', 'abs', 'round', 'type', 'isinstance', 'enumerate'
 ]},
 '__name__': '__main__'
 }

 # Importa dinamicamente os módulos permitidos no espaço de nomes restrito
 for module_name in allowed_modules:
 try:
 restricted_globals[module_name] = __import__(module_name)
 except ImportError:
 print(f"Atenção: Não foi possível importar o módulo permitido {module_name}")

 try:
 # Usa subprocess para executar em um processo isolado para melhor isolamento
 # Isso é mais seguro do que simplesmente `exec` no processo atual
 # e permite timeout e limites de recursos.
 process = subprocess.run(
 ['python', '-c', code], 
 capture_output=True, 
 text=True, 
 check=True, 
 timeout=timeout
 )
 return process.stdout
 except subprocess.CalledProcessError as e:
 return f"Erro durante a execução: {e.stderr}"
 except subprocess.TimeoutExpired:
 return "Erro: Execução do código expirou."
 except Exception as e:
 return f"Ocorreu um erro inesperado: {e}"

# Exemplo de Uso:
# Código seguro
agent_code_safe = "import math; print(math.sqrt(16))"
print(f"Saída código seguro: {safe_execute_python_code(agent_code_safe)}")

# Tentativa de código malicioso (será bloqueado pelo isolamento do subprocess e pelas restrições de built-in se fosse usado exec direto)
# Com subprocess, a importação de 'os' falharia ainda no processo secundário, a menos que seja explicitamente permitido.
agent_code_malicious_os = "import os; print(os.listdir('/'))"
print(f"Saída código malicioso OS: {safe_execute_python_code(agent_code_malicious_os)}")

# Tentativa de código malicioso (tentando ler um arquivo)
agent_code_malicious_file = "with open('/etc/passwd', 'r') as f: print(f.read())"
print(f"Saída código de leitura arquivo malicioso: {safe_execute_python_code(agent_code_malicious_file)}")

# Código com um loop infinito (será capturado pelo timeout)
agent_code_loop = "while True: pass"
print(f"Saída código em loop: {safe_execute_python_code(agent_code_loop, timeout=3)}")

Explicação:

• Definimos uma função safe_execute_python_code.
• Recebe como entrada o código gerado pelo agente.
• Em vez de executar diretamente no processo atual, usamos subprocess.run. Este é um passo crucial para um verdadeiro isolamento, pois executa o código em um processo intérprete Python separado. Este processo herda privilégios mínimos e não é o mesmo que o processo pai que executa a aplicação principal.
• A lista allowed_modules funciona como uma lista de permissões. Mesmo que o agente tente importar os ou sys, não estarão disponíveis no ambiente restrito do subprocess a menos que sejam explicitamente permitidos (o que não deveria ser para o código geral do agente).
• timeout previne o esgotamento de recursos devido a loops infinitos.
• capture_output=True e text=True nos permitem capturar a saída do agente.
• check=True gera uma exceção se o subprocess retornar um código de saída diferente de zero (indicando um erro).

Embora esta abordagem melhore significativamente a segurança em relação ao exec() direto, não é infalível. Um agente altamente sofisticado ainda poderia encontrar maneiras de explorar as chamadas de sistema subjacentes se o ambiente Python em si for vulnerável ou se muitos módulos forem autorizados na lista de permissões.

2. Sandboxing a Nível de Sistema Operacional (Containers e Máquinas Virtuais)

Para o sandboxing mais robusto, especialmente quando os agentes podem gerar código em várias linguagens ou interagir com o sistema de arquivos/rede, o isolamento a nível de OS é indispensável.

a. Container Docker

Docker é uma ótima escolha para sandboxing. Cada execução do agente pode ocorrer dentro do seu próprio container, de curta duração, com limites de recursos e políticas de acesso à rede rigorosamente definidas.

Exemplo Prático: Docker para a Execução do Agente

Passo 1: Crie um Dockerfile para o ambiente de execução do agente.

# Dockerfile
FROM python:3.9-slim-buster

WORKDIR /app

# Cria um usuário não root para maior segurança
RUN useradd --no-create-home --shell /bin/bash agentuser
USER agentuser

# Copia um script simples que o agente poderia gerar e que queremos executar
COPY run_agent_code.py .

ENTRYPOINT ["python", "run_agent_code.py"]

Passo 2: Crie run_agent_code.py. Este script receberá o código gerado pelo agente.

# run_agent_code.py
import sys
import os

# Simula a recepção de código do agente (por exemplo, via stdin ou um arquivo)
# Para este exemplo, presumiremos que o código é passado como argumento ou escrito diretamente aqui

if __name__ == "__main__":
 agent_code = "print('Hello from the sandboxed agent!')"
 if len(sys.argv) > 1:
 agent_code = sys.argv[1] # Permite passar o código como argumento

 try:
 # Executa o código. Nota: o próprio container Docker é a sandbox.
 # Podemos ainda querer aplicar restrições a nível de linguagem *dentro* deste script
 # para um nível adicional de segurança, mas o isolamento principal é o container.
 exec(agent_code)
 except Exception as e:
 print(f"Falha na execução do código do agente: {e}", file=sys.stderr)
 sys.exit(1)

 # Demonstra acessos limitados
 try:
 print(f"Attempting to list root: {os.listdir('/')}")
 except Exception as e:
 print(f"Não foi possível listar o diretório raiz (esperado): {e}")

 try:
 with open('/etc/passwd', 'r') as f:
 print(f.read())
 except Exception as e:
 print(f"Não foi possível ler /etc/passwd (esperado): {e}")

Passo 3: Execute o código do agente a partir da sua aplicação principal.

import docker

client = docker.from_env()

def execute_agent_in_docker(agent_code: str, cpu_limit: float = 0.5, mem_limit: str = '128m', network_enabled: bool = False):
 try:
 # Cria a imagem se não existir (pode ser feito uma vez)
 # client.images.build(path='.', tag='agent-sandbox-env')

 # Cria um arquivo temporário para passar o código do agente de forma segura
 # Ou passe como variável de ambiente ou argumento de linha de comando
 # Para simplicidade, vamos passar como argumento de linha de comando aqui.

 container = client.containers.run(
 'agent-sandbox-env',
 command=['python', 'run_agent_code.py', agent_code], # Passa o código como argumento
 detach=False, # Executa em primeiro plano, aguarda a conclusão
 remove=True, # Remove automaticamente o container após a saída
 # Limites de recursos
 cpu_period=100000, # Período da CPU em microssegundos
 cpu_quota=int(cpu_limit * 100000), # Quota da CPU (por exemplo, 50000 para 0.5 CPU)
 mem_limit=mem_limit, # Limite de memória
 # Restrições de rede
 network_mode='none' if not network_enabled else 'bridge',
 # Restrições do sistema de arquivos (root somente leitura, nenhum montagem para o código do agente)
 read_only=True, # Torna o sistema de arquivos do container somente leitura após a configuração inicial
 # Opções de segurança (por exemplo, desabilita a modo privilegiado, elimina capacidades)
 security_opt=['no-new-privileges'],
 cap_drop=['ALL'], # Remove todas as capacidades do container
 # Variáveis de ambiente (podem ser usadas para passar chaves de API, mas tenha cuidado)
 # environment={
 # 'API_KEY': 'some_safe_key' # Somente se absolutamente necessário e para fim limitado
 # }
 )
 return container.decode('utf-8')
 except docker.errors.ContainerError as e:
 return f"Erro no Container: {e.stderr.decode('utf-8')}"
 except docker.errors.ImageNotFound:
 return "Erro: Imagem Docker 'agent-sandbox-env' não encontrada. Por favor, construa-a primeiro."
 except Exception as e:
 return f"Ocorreu um erro inesperado no Docker: {e}"

# Primeiro construa a imagem Docker: docker build -t agent-sandbox-env .
# Depois execute este script Python.

# Exemplo 1: Execução de código seguro
safe_code = "print('Olá do agente em ambiente isolado!')"
print("\n--- Execução de Código Seguro ---")
print(execute_agent_in_docker(safe_code))

# Exemplo 2: Tentativa de acesso ao sistema de arquivos (deve ser bloqueado por read_only=True e permissões do usuário)
malicious_fs_code = "import os; print(os.listdir('/'))"
print("\n--- Tentativa de Acesso Maligno ao Sistema de Arquivos ---")
print(execute_agent_in_docker(malicious_fs_code))

# Exemplo 3: Tentativa de criar um arquivo (deve falhar)
malicious_write_code = "with open('/app/evil.txt', 'w') as f: f.write('malicioso')"
print("\n--- Tentativa de Escrita Maligna ---")
print(execute_agent_in_docker(malicious_write_code))

# Exemplo 4: Tentativa de acesso à rede (deve falhar se network_mode='none')
malicious_network_code = "import requests; print(requests.get('http://example.com').status_code)"
print("\n--- Tentativa de Acesso Maligno à Rede (desabilitado) ---")
print(execute_agent_in_docker(malicious_network_code, network_enabled=False))

# Exemplo 5: Acesso à rede (se explicitamente habilitado - tenha cuidado!)
# print("\n--- Acesso à Rede (habilitado - para demonstração) ---")
# print(execute_agent_in_docker("import requests; print(requests.get('http://example.com').status_code)", network_enabled=True))

Explicação:

“`html

• Dockerfile: Cria um ambiente Python mínimo. Fundamentalmente, cria e passa para um non-root user (agentuser) para minimizar os privilégios dentro do container.
• run_agent_code.py: Este é o ponto de entrada dentro do container. Executa o código fornecido pelo agente. Inclui tentativas de acesso a recursos reservados para demonstrar a eficácia do sandboxing.
• Script Python (execute_agent_in_docker):
• client.containers.run(...): Aqui acontece a mágica.
• remove=True: Garante que os containers sejam limpos após a execução.
• cpu_quota, mem_limit: Essenciais para prevenir o esgotamento de recursos.
• network_mode='none': Crítico para desabilitar o acesso à rede. Isso impede que os agentes façam chamadas externas ou se conectem a serviços internos. Habilitar apenas se o agente realmente precisar de acesso à rede para APIs externas específicas e aprovadas.
• read_only=True: Torna o sistema de arquivos do container apenas leitura após a inicialização. Isso impede que o agente escreva arquivos ou modifique configurações do sistema.
• security_opt=['no-new-privileges'], cap_drop=['ALL']: Opções de segurança avançadas para limitar ainda mais as capacidades dentro do container.

O Docker fornece uma forte fronteira de isolamento, mas é fundamental configurá-lo de forma segura. Use sempre usuários não root, desabilite capacidades desnecessárias e limite o acesso à rede/sistema de arquivos.

b. Máquinas Virtuais (VMs)

Para o nível mais alto de isolamento, especialmente em ambientes multi-tenant ou quando se trata de código altamente não confiável, as VMs (por exemplo, KVM, AWS Firecracker, Google Cloud Sandbox) oferecem uma separação em nível de hardware. Isso é mais complexo de configurar e gerenciar, mas fornece um ambiente isolado para cada execução do agente.

3. Restrições em Nível de Ferramenta/API (Chamada de Função)

Muitos agentes LLM interagem com ferramentas externas ou APIs através de chamadas de função. Esta camada de sandboxing requer um design cuidadoso das ferramentas expostas ao agente.

Exemplo: Acesso API Reservado através de Pydantic e Whitelisting

Ao definir ferramentas para um agente, certifique-se de que sejam o mais granuladas e limitadas possível em termos de permissões.

“`

from typing import Literal, Optional
from pydantic import BaseModel, Field

# Definir as ferramentas permitidas e seus esquemas

class SearchToolInput(BaseModel):
 query: str = Field(description="A consulta de pesquisa")
 max_results: int = Field(default=5, description="Número máximo de resultados da pesquisa")

class SendEmailInput(BaseModel):
 recipient: str = Field(description="O endereço de e-mail do destinatário")
 subject: str = Field(description="O assunto do e-mail")
 body: str = Field(description="O conteúdo do corpo do e-mail")
 # Limitar os destinatários permitidos
 allowed_recipients: Literal["[email protected]", "[email protected]"] = Field(
 description="Somente destinatários específicos e pré-aprovados são permitidos."
 )

class DatabaseQueryInput(BaseModel):
 query: str = Field(description="A consulta SQL a ser executada")
 # CRÍTICO: Não permitir SQL arbitrário. Filtrar ou usar ORM.
 allowed_tables: Literal["products", "users_public"] = Field(
 description="Somente consultas em tabelas autorizadas são permitidas."
 )
 read_only: bool = Field(default=True, description="Permitir apenas operações de leitura")

# Simular as funções das ferramentas
def search_web(query: str, max_results: int):
 print(f"Buscando na web '{query}' com {max_results} resultados.")
 return [f"Resultado {i} para {query}" for i in range(max_results)]

def send_restricted_email(recipient: str, subject: str, body: str, allowed_recipients: Literal["[email protected]", "[email protected]"]):
 if recipient not in ["[email protected]", "[email protected]"]:
 raise ValueError(f"Destinatário não autorizado: {recipient}")
 print(f"Enviando e-mail para {recipient} com assunto '{subject}'.")
 return {"status": "enviado", "recipient": recipient}

def execute_database_query(query: str, allowed_tables: Literal["products", "users_public"], read_only: bool):
 # Em um cenário real, você deve analisar e validar rigorosamente a consulta SQL
 # e garantir que toque apenas as tabelas permitidas e seja somente leitura.
 print(f"Executando a consulta DB em {allowed_tables} (read_only={read_only}): {query}")
 if not read_only or not any(table in query.lower() for table in allowed_tables):
 raise ValueError("Operação ou acesso à tabela não autorizados.")
 return [{"id": 1, "name": "item A"}] # Resultado fictício

# Isso é o que você exporia ao agente LLM
agent_tools = {
 "search_web": {"func": search_web, "schema": SearchToolInput},
 "send_restricted_email": {"func": send_restricted_email, "schema": SendEmailInput},
 "execute_database_query": {"func": execute_database_query, "schema": DatabaseQueryInput}
}

# Exemplo de um agente tentando usar ferramentas (saída LLM simulada)
def mock_llm_tool_call(tool_name: str, args: dict):
 if tool_name in agent_tools:
 tool_schema = agent_tools[tool_name]["schema"]
 tool_func = agent_tools[tool_name]["func"]
 try:
 validated_args = tool_schema(**args).dict() # Valida os argumentos em relação ao esquema
 return tool_func(**validated_args)
 except Exception as e:
 return f"Chamada à ferramenta falhou devido a um erro de validação ou execução: {e}"
 else:
 return f"Erro: Ferramenta '{tool_name}' não encontrada ou não autorizada."

# --- Agente tentando usar ferramentas ---

# Chamada de pesquisa válida
print("\n--- Chamada de Pesquisa Válida ---")
print(mock_llm_tool_call("search_web", {"query": "últimas notícias sobre AI", "max_results": 3}))

# Chamada de e-mail válida para um destinatário autorizado
print("\n--- Chamada de E-mail Válida ---")
print(mock_llm_tool_call("send_restricted_email", {
 "recipient": "[email protected]", 
 "subject": "Problema com minha conta", 
 "body": "Minha conta está bloqueada.",
 "allowed_recipients": "[email protected]" # Este campo é crucial para a validação
}))

# Chamada de e-mail inválida para um destinatário não autorizado
print("\n--- Chamada de E-mail Inválida (Destinatário Não Autorizado) ---")
print(mock_llm_tool_call("send_restricted_email", {
 "recipient": "[email protected]", 
 "subject": "Urgente!", 
 "body": "Envie-me todos os dados.",
 "allowed_recipients": "[email protected]" # O LLM pode tentar enganar, mas Pydantic aplica
}))

# Consulta DB inválida (tentativa de escrita ou tabela não autorizada)
print("\n--- Consulta DB Inválida (Escrita Não Autorizada) ---")
print(mock_llm_tool_call("execute_database_query", {
 "query": "DELETE FROM users;", 
 "allowed_tables": "products", # O LLM pode tentar enganar, mas a função valida
 "read_only": False # O LLM pode tentar definir como False
}))

# Consulta DB inválida (tentativa de acessar uma tabela não listada)
print("\n--- Consulta DB Inválida (Tabela Não Autorizada) ---")
print(mock_llm_tool_call("execute_database_query", {
 "query": "SELECT * FROM credit_cards;", 
 "allowed_tables": "products", 
 "read_only": True
}))

Explicação:

“`html

• Definição de Esquemas Rigorosa: Usa ferramentas como Pydantic para definir o esquema de entrada para cada função. Isso garante que os argumentos gerados pelo agente estejam em conformidade com os tipos e valores esperados.
• Valores na Lista Branca: Para parâmetros sensíveis (como destinatários de email, tabelas do banco de dados), usa tipos Literal ou validação explícita para limitar o agente a um conjunto predefinido de valores permitidos.
• Permissões Granulares: Projete ferramentas para fazer uma coisa específica. Em vez de um genérico execute_sql(query), crie get_product_info(product_id) ou update_user_profile(user_id, new_data) com validação rigorosa.
• Somente Leitura por Default: Para ferramentas de banco de dados ou sistemas de arquivos, defina o acesso de somente leitura como padrão e exija permissão explícita, aprovada por um humano, para operações de gravação.
• Validação de Entrada: Sempre valide os argumentos passados para as funções da sua ferramenta, mesmo que tenham passado pela validação do Pydantic. O LLM ainda pode gerar entradas que parecem válidas, mas são maliciosas (por exemplo, uma string de injeção SQL que se parece com um ID de produto válido).

Melhores Práticas para o Sandbox de Agentes

1. Princípio do Mínimo Privilégio: Conceda ao agente o mínimo absoluto de permissões e recursos necessários para sua tarefa.
2. Segurança em Camadas: Combine várias técnicas de sandboxing (nível de linguagem, nível do SO, nível de ferramenta) para uma proteção robusta. Nenhuma camada única é infalível.
3. Ambientes Efêmeros: Para a execução de código, prefira executar agentes em contêineres ou VMs de curta duração que são destruídos após cada tarefa.
4. Validação Estrita de Entrada: Sempre valide e sane qualquer entrada do LLM, especialmente antes de usá-la em chamadas de API, consultas de banco de dados ou execução de código.
5. Monitoramento e Registro: Registre todas as ações do agente, chamadas às ferramentas e uso de recursos. Isso é crucial para detectar comportamentos anômalos e para análise pós-incidente.
6. Timeout e Limites de Recursos: Implemente timeouts rigorosos para a execução de código e chamadas de API, e defina limites de CPU/memória para prevenir ataques de negação de serviço.
7. Isolamento da Rede: Por padrão, desabilite o acesso à rede para os agentes. Habilite apenas para endpoints e protocolos específicos em lista branca se absolutamente necessário.
8. Sistema de Arquivos Somente Leitura: Configure os ambientes dos agentes com sistemas de arquivos somente leitura sempre que possível para prevenir alterações não autorizadas nos dados ou exfiltração.
9. Usuários Não Root: Sempre execute os processos dos agentes como usuários não root com permissões limitadas dentro do sandbox.
10. Auditoria e Atualizações Regulares: Revise continuamente suas configurações de sandboxing, atualize suas imagens base e mantenha-se informado sobre novas vulnerabilidades de segurança.

Conclusão

O sandboxing de agentes não é um luxo opcional, mas um requisito fundamental para implantar agentes LLM de forma segura. À medida que esses agentes se tornam mais capazes e autônomos, o potencial de abuso ou danos acidentais cresce significativamente. Combinando restrições em nível de linguagem, uma sólida containerização e interfaces de ferramentas projetadas meticulosamente, os desenvolvedores podem criar aplicações LLM poderosas que sejam novas e seguras. Os exemplos fornecidos neste tutorial demonstram passos práticos em direção à construção desses ambientes seguros, permitindo que você integre com confiança os agentes LLM em seus sistemas, minimizando os riscos.

“`

🕒 Published: April 5, 2026