Execução de Código em Sandbox

A crate adk-sandbox fornece execução isolada de código para agentes ADK, com dois níveis de isolamento:

1. Isolamento de processos — processos filhos com isolamento de ambiente e imposição de tempo limite
2. Perfis de sandbox em nível de SO — restrições em nível de kernel para sistema de arquivos, rede e criação de processos

Backends

Qual isolamento você está obtendo?

ProcessBackend::isolation() informa isso, portanto não é algo a ser inferido pelo nome do crate:

Duas coisas sobre o backend de processos que vale a pena conhecer:

• Os programas são resolvidos antes que o ambiente seja limpo. Um python3, node ou rustc sem caminho é procurado no PATH do chamador e passado ao processo filho como um caminho absoluto. Isso significa que o processo filho não precisa de um PATH próprio para iniciar — anteriormente, o chamador precisava colocar PATH em ExecRequest::env, o que também permitia que o código executado iniciasse qualquer outra coisa disponível nele.
• A compilação passa pelo mesmo limite que a execução. O código-fonte Rust costumava ser compilado por um comando criado fora do caminho compartilhado, portanto a compilação não tinha um wrapper de enforcement, um tempo limite nem um grupo de processos. Isso é importante porque a compilação não é inerte: include_str! lê arquivos e macros procedurais executam código arbitrário antes que o binário produzido exista. A fase de compilação recebe uma lista de permissões de ferramentas específica da plataforma; no Windows, isso inclui os caminhos do MSVC e do Windows SDK, descobertos a partir da toolchain instalada quando o chamador ainda não está em um shell de desenvolvedor. A compilação usa o linker rust-lld da toolchain do Rust, portanto um link.exe não relacionado que apareça antes no PATH não pode ser selecionado. Um mecanismo de enforcement do sistema operacional é o que restringe essa fase.

Precedência do Ambiente

SandboxPolicy::env fornece valores padrão para cada execução e ExecRequest::env os substitui por chamada. As variáveis da política eram anteriormente ignoradas por completo.

Perfis de Sandbox do Sistema Operacional

O enforcement de sandbox no nível do sistema operacional restringe os processos filhos no nível do kernel. Isso vai além do isolamento do ambiente — o próprio sistema operacional bloqueia o acesso não autorizado ao sistema de arquivos, as conexões de rede e a criação de processos.

Suporte à Plataforma

Início rápido

use adk_sandbox::{
    ProcessBackend, ProcessConfig, SandboxBackend,
    SandboxPolicyBuilder, get_enforcer,
};

// 1. Define what the sandboxed process can do
let policy = SandboxPolicyBuilder::new()
    .allow_read("/usr")           // Read system libraries
    .allow_read_write("/tmp/work") // Write to work directory
    .allow_process_spawn()         // Python needs to exec
    // Network is denied by default
    .env("PATH", "/usr/bin:/usr/local/bin")
    .build();

// 2. Get the platform-appropriate enforcer
let enforcer = get_enforcer()?;

// 3. Create a sandboxed backend
let backend = ProcessBackend::with_sandbox(
    ProcessConfig::default(),
    enforcer,
    policy,
);

// 4. Execute code — network is blocked, writes restricted
let result = backend.execute(request).await?;

Sinalizadores de recursos

[dependencies]
# Auto-detect platform enforcer
adk-sandbox = { version = "2.1.0", features = ["process", "sandbox-native"] }

# Or pick a specific platform
adk-sandbox = { version = "2.1.0", features = ["process", "sandbox-macos"] }
adk-sandbox = { version = "2.1.0", features = ["process", "sandbox-linux"] }

SandboxPolicy

A política define o que um processo em sandbox tem permissão para fazer:

Diferenças entre plataformas

macOS (Seatbelt): Usa “permitir por padrão, negar operações perigosas” — começa com acesso total e, em seguida, bloqueia a rede, as gravações em arquivos e a criação de processos. Uma abordagem baseada exclusivamente em lista de permissões não funciona porque o Python precisa de dezenas de categorias de chamadas de sistema específicas do macOS na inicialização.

Linux (bubblewrap): Usa uma lista de permissões baseada em namespaces — nada existe por padrão; você monta somente o que é necessário. Instale com apt install bubblewrap ou dnf install bubblewrap.

Windows (AppContainer): Não implementado. O design é baseado em ACLs de tokens — um SID restrito sem acesso por padrão e, em seguida, ACLs concedidas em caminhos específicos — mas a criação de contêineres, as ACLs, os recursos e a limpeza de objetos de trabalho estão ausentes; portanto, probe() retorna EnforcerUnavailable. Execute sem um aplicador de políticas no Windows ou use macOS ou Linux, onde a aplicação das políticas é real.

Exemplo

Consulte examples/sandbox_agent/ para ver um exemplo completo orientado por LLM que executa código Python em um ambiente isolado, com o acesso à rede bloqueado pelo kernel do sistema operacional.