Tutorial sobre o Agent Sandboxing: Criando Aplicações LLM Seguras

Introdução à Isolamento de Agentes

À medida que os Modelos de Linguagem de Grande Escala (LLMs) evoluem de agentes de conversação simples para entidades autônomas poderosas capazes de executar código, interagir com APIs externas e tomar decisões no mundo real, a necessidade de medidas de segurança fortes torna-se primordial. Um agente LLM, ao ser dotado da capacidade de agir, pode representar um risco de segurança significativo se não for corretamente contido. É aqui que entra a isolamento de agentes. A isolação de um agente significa criar um ambiente isolado onde ele pode operar sem afetar o sistema host ou acessar recursos não autorizados. Este tutorial explorará os aspectos práticos da isolação de agentes, fornecendo exemplos concretos para demonstrar como construir aplicações LLM seguras e confiáveis.

O princípio fundamental por trás do isolamento é o menor privilégio: um agente deve ter acesso apenas aos recursos absolutamente necessários para seu funcionamento, e nada mais. Sem um isolamento adequado, um agente malicioso ou impreciso poderia:

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

Ao implementar um isolamento eficaz, podemos atenuar esses riscos, permitindo-nos aproveitar o imenso poder dos agentes LLM enquanto mantemos o controle e a segurança.

Compreendendo as Ameaças: Por que Isolar?

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

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

Instrutores 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 Comando do Sistema: Gerar código que chama os.system('rm -rf /') ou comandos destrutivos similares.
• Execução de Código Remoto (RCE): Explorar vulnerabilidades em bibliotecas para assumir o controle do host.
• Exaustão de Recursos: Criar loops infinitos ou alocar memória/CPU excessiva, resultando em negação de serviço.

2. Acesso a Dados e Exfiltração

Um agente pode ser encarregado de processar dados sensíveis. Sem isolamento, 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 externos maliciosos ou exfiltrar dados para pontos finais arbitrários.
• Injeção de Prompt por Leituras de Arquivos: Se um agente pode ler arquivos arbitrários, um ator malicioso poderia preparar um prompt que engana o agente fazendo-o ler um arquivo sensível, e então incorporar 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 resultar em:

• Chamadas API Não Autorizadas: Fazer chamadas a APIs sensíveis às quais não deveria ter acesso (por exemplo, gerenciamento de usuários, processamento de pagamentos).
• Excessos de Custos: Acionar chamadas API caras ou funções de nuvem que consomem muitos recursos.
• Ações Maliciosas: Se um agente tiver acesso a uma API de mensagens, ele poderia enviar spam ou e-mails de phishing.

Técnicas e Ferramentas de Isolamento

Existem várias camadas e técnicas que podemos empregar para a isolação de agentes, desde a simples revisão de código até a containerização sofisticada.

1. Isolamento no Nível da Linguagem (Restrições do Interpretador de Código)

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

Exemplo: Execução Python Restrita com exec() e Listas Brancas

Um cenário comum é um agente gerando código Python. Em vez de chamar diretamente exec() ou eval() em cadeias arbitrárias, você pode restringir os globals e 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 branca dos módulos seguros

 # Criar 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__'
 }

 # Importar 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"Aviso: Não foi possível importar o módulo permitido {module_name}")

 try:
 # Usar subprocess para executar em um processo isolado para melhor isolamento
 # Isso é mais sólido do que simplesmente usar `exec` no processo atual
 # e permite limites de tempo e 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 ao executar: {e.stderr}"
 except subprocess.TimeoutExpired:
 return "Erro: A 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 do código seguro: {safe_execute_python_code(agent_code_safe)}")

# Tentativa de código malicioso (será bloqueada pelo isolamento subprocess e as restrições de built-in se exec direto fosse usado)
# Com subprocess, a importação de 'os' falharia no processo filho, a menos que fosse especificamente autorizada.
agent_code_malicious_os = "import os; print(os.listdir('/'))"
print(f"Saída do 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 do código de leitura de arquivo malicioso: {safe_execute_python_code(agent_code_malicious_file)}")

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

Explicação:

• Definimos uma função safe_execute_python_code.
• Ela recebe o código gerado pelo agente como entrada.
• Em vez de executar diretamente no processo atual, usamos subprocess.run. Este é um passo crucial para um verdadeiro isolamento, pois isso executa o código em um processo interpretador Python separado. Este processo herda privilégios mínimos e não é o mesmo que o processo pai executando sua aplicação principal.
• A lista allowed_modules atua como uma lista branca. Mesmo que o agente tente importar os ou sys, isso não estará disponível no ambiente restrito do subprocess, a menos que seja explicitamente autorizado (o que não deve ser o caso para o código do agente geral).
• timeout impede a exaustão de recursos devido a loops infinitos.
• capture_output=True e text=True nos permitem capturar a saída do agente.
• check=True aciona uma exceção se o subprocess retornar um código de saída diferente de zero (indicando um erro).

Embora essa abordagem melhore consideravelmente a segurança em relação ao uso direto de exec(), ela não é infalível. Um agente altamente sofisticado ainda poderia encontrar maneiras de explorar chamadas de sistema subjacentes se o próprio ambiente Python estiver vulnerável ou se muitos módulos forem colocados na lista branca.

2. Isolamento no Nível do Sistema Operacional (Containers e Máquinas Virtuais)

Para um isolamento realmente sólido, especialmente quando os agentes podem gerar código em várias linguagens ou interagir com o sistema de arquivos/rede, o isolamento em nível de sistema operacional é indispensável.

a. Containers Docker

Docker é uma excelente escolha para isolamento. Cada execução de agente pode ocorrer em seu próprio container de curta duração com limites de recursos e políticas de acesso à rede estritamente definidas.

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

Etapa 1: Criar um Dockerfile para o ambiente de execução do agente.

# Dockerfile
FROM python:3.9-slim-buster

WORKDIR /app

# Criar um usuário não-root por motivos de segurança
RUN useradd --no-create-home --shell /bin/bash agentuser
USER agentuser

# Copiar um script simples que o agente pode gerar e que desejamos executar
COPY run_agent_code.py .

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

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

# run_agent_code.py
import sys
import os

# Simular a recepção de código do agente (por exemplo, via stdin ou um arquivo)
# Para este exemplo, vamos supor 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] # Permitir a passagem do código como argumento

 try:
 # Executar o código. Nota: o contêiner Docker em si é o sandbox.
 # Podemos querer impor ainda mais restrições no nível da linguagem *neste* script
 # para uma camada adicional, mas o isolamento principal é o contêiner.
 exec(agent_code)
 except Exception as e:
 print(f"A execução do código do agente falhou: {e}", file=sys.stderr)
 sys.exit(1)

 # Demonstrar o acesso restrito
 try:
 print(f"Tentando listar a raiz: {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}")

Etapa 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:
 # Construir a imagem se ela não existir (pode ser feito uma vez)
 # client.images.build(path='.', tag='agent-sandbox-env')

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

 container = client.containers.run(
 'agent-sandbox-env',
 command=['python', 'run_agent_code.py', agent_code], # Passar o código como arg
 detach=False, # Executar em primeiro plano, aguardar a conclusão
 remove=True, # Remover automaticamente o contêiner 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 no sistema de arquivos (raiz em modo somente leitura, sem montagens vinculadas para o código do agente)
 read_only=True, # Torna o sistema de arquivos do contêiner somente leitura após a configuração inicial
 # Opções de segurança (por exemplo, desativar o modo privilegiado, remover capacidades)
 security_opt=['no-new-privileges'],
 cap_drop=['ALL'], # Remove todas as capacidades para o contêiner
 # 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 com escopo
 # }
 )
 return container.decode('utf-8')
 except docker.errors.ContainerError as e:
 return f"Erro de contêiner: {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"Um erro inesperado do Docker ocorreu: {e}"

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

# Exemplo 1: Execução de código seguro
safe_code = "print('Hello from sandboxed agent!')"
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 bloqueada por read_only=True e permissões de usuário)
malicious_fs_code = "import os; print(os.listdir('/'))"
print("\n--- Tentativa de Acesso Malicioso ao Sistema de Arquivos ---")
print(execute_agent_in_docker(malicious_fs_code))

# Exemplo 3: Tentativa de criação de um arquivo (deve falhar)
malicious_write_code = "with open('/app/evil.txt', 'w') as f: f.write('malicious')"
print("\n--- Tentativa de Escrita Maliciosa ---")
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 Malicioso à Rede (desativada) ---")
print(execute_agent_in_docker(malicious_network_code, network_enabled=False))

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

Explicação:

• Dockerfile: Cria um ambiente Python mínimo. Crucialmente, cria e muda para um usuário non-root (agentuser) para minimizar os privilégios no contêiner.
• run_agent_code.py: É o ponto de entrada no contêiner. Ele executa o código fornecido pelo agente. Inclui tentativas de acesso a recursos restritos para demonstrar a eficácia do sandbox.
• Script Python (execute_agent_in_docker):
• client.containers.run(...): É aí que a mágica acontece.
• remove=True: Garante que os contêineres sejam limpos após a execução.
• cpu_quota, mem_limit: Essencial para prevenir a exaustão dos recursos.
• network_mode='none': Crítico para desativar o acesso à rede. Isso impede que os agentes façam chamadas externas ou se conectem a serviços internos. Ative apenas se o agente realmente precisar de acesso à rede para APIs externas específicas e em lista branca.
• read_only=True: Torna o sistema de arquivos do contêiner somente leitura após a inicialização. Isso impede que o agente escreva arquivos ou modifique as configurações do sistema.
• security_opt=['no-new-privileges'], cap_drop=['ALL']: Opções de segurança avançadas para restringir ainda mais as capacidades no contêiner.

O Docker fornece uma forte barreira de isolamento, mas é vital configurá-lo de forma segura. Sempre use usuários não-root, desative capacidades desnecessárias e restringa o acesso à rede/sistema de arquivos.

b. Máquinas Virtuais (VMs)

Para o mais alto nível de isolamento, especialmente em ambientes multi-inquilinos ou ao lidar com 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 de agente.

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

Muitos agentes LLM interagem com ferramentas externas ou APIs por meio de chamadas de função. Esta camada de sandbox envolve um design cuidadoso das ferramentas expostas ao agente.

Exemplo: Acesso API Restrito via Pydantic e Lista Branca

Ao definir ferramentas para um agente, certifique-se de que elas sejam o mais granulares e limitadas possível por 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 de 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")
 # Restringir os destinatários permitidos
 allowed_recipients: Literal["[email protected]", "[email protected]"] = Field(
 description="Apenas 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="Apenas consultas contra tabelas na lista branca são permitidas."
 )
 read_only: bool = Field(default=True, description="Permitir apenas operações de leitura")

# Simular as funções da ferramenta
def search_web(query: str, max_results: int):
 print(f"Pesquisando na web por '{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 o e-mail para {recipient} com o 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ê parseria e validaria rigorosamente a consulta SQL
 # e garantiria que ela só afetasse tabelas permitidas e fosse 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 autorizado.")
 return [{"id": 1, "name": "artigo A"}] # Resultado fictício

# Aqui está 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() # Validar os argumentos de acordo com o esquema
 return tool_func(**validated_args)
 except Exception as e:
 return f"A chamada da 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 IA", "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]" # LLM pode tentar enganar, mas Pydantic impõe
}))

# 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", # LLM pode tentar enganar, mas a função valida
 "read_only": False # LLM pode tentar definir como False
}))

# Consulta DB inválida (tentativa de acesso a 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:

• Definição estrita do esquema: Use 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.
• Lista branca dos valores: Para parâmetros sensíveis (como destinatários de e-mail, tabelas de banco de dados), utilize tipos Literal ou uma validação explícita para restringir o agente a um conjunto predefinido de valores autorizados.
• Permissões granulares: Projete ferramentas para realizar uma coisa específica. Em vez de um execute_sql(query) genérico, crie get_product_info(product_id) ou update_user_profile(user_id, new_data) com uma validação rigorosa.
• Somente leitura por padrão: Para ferramentas de banco de dados ou sistemas de arquivos, por padrão, limite o acesso a leitura e exija uma autorização explícita, aprovada por um humano, para operações de escrita.
• Validação das entradas: Sempre valide os argumentos passados para suas funções de ferramenta, mesmo que tenham passado pela validação Pydantic. O LLM ainda pode construir entradas válidas, mas maliciosas (por exemplo, uma string de injeção SQL que se parece com um ID de produto válido).

Melhores Práticas para o Sandboxing de Agentes

1. Princípio do Menor 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 de OS, nível de ferramenta) para uma proteção sólida. Nenhuma camada única é infalível.
3. Ambientes Efêmeros: Para execução de código, priorize a execução de agentes em contêineres ou máquinas virtuais descartáveis de curta duração que são destruídas após cada tarefa.
4. Validação Rigorosa das Entradas: Sempre valide e sanitize qualquer entrada proveniente 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 de ferramentas e uso de recursos. Isso é crucial para detectar comportamentos anormais e para análise pós-incidente.
6. Timeouts e Limites de Recursos: Implemente prazos rigorosos para execução de código e chamadas de API, e estabeleça limites de CPU/memória para prevenir ataques de negação de serviço.
7. Isolamento de Rede: Por padrão, desative o acesso à rede para os agentes. Ative-o somente para endpoints e protocolos específicos e na lista branca se absolutamente necessário.
8. Sistemas de Arquivos Somente Leitura: Configure os ambientes de agentes com sistemas de arquivos somente leitura sempre que possível para evitar modificação ou exfiltração não autorizada de dados.
9. Usuários Não-Raiz: Sempre execute os processos de agentes como usuários não-raiz com permissões limitadas dentro do sandbox.
10. Auditorias 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 uma exigência fundamental para implantar agentes LLM de forma segura. À medida que esses agentes se tornam mais capazes e autônomos, o potencial para uso indevido ou danos acidentais aumenta consideravelmente. Ao empregar uma combinação de restrições em nível de linguagem, contêinerização sólida e interfaces de ferramentas meticulosamente projetadas, os desenvolvedores podem criar aplicações LLM poderosas que são novas e seguras. Os exemplos fornecidos neste tutorial mostram etapas práticas para construir esses ambientes seguros, permitindo que você integre agentes LLM em seus sistemas com confiança, minimizando os riscos.

🕒 Published: March 31, 2026