Sandbox da Cortex Code CLI¶

A Cortex Code CLI pode executar comandos shell em sandbox para restringir o acesso ao sistema de arquivos e à rede e processar os recursos. O sandbox adiciona uma camada de isolamento para que o agente não modifique arquivos nem acesse recursos fora do seu projeto acidentalmente.

Importante

O suporte para este recurso é experimental e pode estar sujeito a alterações.

Suporte à plataforma¶

O sandbox usa os recursos de isolamento integrados do sistema operacional para restringir os comandos.


Plataforma	Implementação	Dependências
macOS	`sandbox-exec` (interno)	`ripgrep`
Linux	`bubblewrap`	`bubblewrap`, `socat` e `ripgrep`
Windows	Tokens nativos restritos	Nenhum

Instalando dependências¶

macOS:

brew install ripgrep

Debian/Ubuntu:

sudo apt-get install bubblewrap socat ripgrep

Fedora/RHEL:

sudo dnf install bubblewrap socat ripgrep

Habilitando o sandbox¶

Use o comando de barra /sandbox na Cortex Code CLI:

/sandbox                          # Interactive selector
/sandbox runtime on               # Enable sandbox
/sandbox runtime off              # Disable sandbox
/sandbox runtime status           # Show sandbox status
/sandbox status                   # Show current sandbox status

Você também pode habilitar o sandbox no arquivo de configurações. Adicione um objeto sandbox a ~/.snowflake/cortex/settings.json (nível do usuário) ou a .snowflake/cortex/settings.json (nível do projeto):

{
  "sandbox": {
    "enabled": true
  }
}

O modo de permissão padrão é "regular". Para usar o modo de permissão automática, defina "mode": "autoAllow" explicitamente. Consulte Modos de permissão.

Modos de permissão¶

O sandbox tem dois modos de permissão que controlam como os comandos são aprovados:


Modo	Valor de configuração	Comportamento
Permissão automática	`"autoAllow"`	Os comandos que podem ser colocados em sandbox são executados automaticamente sem um aviso. Os comandos que não podem ser colocados em sandbox (por exemplo, aqueles que exigem acesso de rede a domínios não permitidos) são revertidos ao fluxo normal de permissão.
Regular	`"regular"`	Todos os comandos solicitam aprovação, mesmo quando executados dentro do sandbox.

Defina o modo com o comando /sandbox ou nas configurações:

/sandbox mode auto                # Set auto-allow mode
/sandbox mode regular             # Set regular mode

Restrições de sistema de arquivos¶

O sandbox controla os caminhos em que os comandos podem ler e gravar.

Comportamento padrão¶

Diretório de trabalho: sempre permitido para leitura e gravação.
Diretório de habilidades (~/.snowflake/cortex/skills): permitido.
Diretório de contexto (~/.snowflake/cortex/.ctx): permitido quando ctxAvailable está habilitado.

Caminhos protegidos (sempre negados para gravação)¶

Os seguintes caminhos sempre são protegidos, seja qual for a sua configuração:

Arquivos de configuração shell: ~/.bashrc, ~/.bash_profile, ~/.zshrc, ~/.zprofile, ~/.profile, ~/.bash_login, ~/.bash_logout
Ganchos do Git: ~/.git/hooks, .git/hooks
Configuração de SSH: ~/.ssh/authorized_keys, ~/.ssh/config
Diretórios e arquivos de configurações gerenciadas: /Library/Application Support/Cortex/ (macOS), /etc/cortex/ (Linux), %ProgramData%\Cortex\ (Windows)

Regras personalizadas de sistema de arquivos¶

Defina o acesso ao sistema de arquivos nas configurações:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowRead": [],
      "denyRead": ["/private/secrets"],
      "allowWrite": ["/tmp", "~/projects"],
      "denyWrite": ["/etc", "/var"]
    }
  }
}


Configuração	Padrão	Descrição
`allowRead`	`[]` (permitir todos)	Caminhos que o sandbox pode ler. Uma matriz vazia significa que todos os caminhos são permitidos (exceto aqueles em `denyRead`).
`denyRead`	`[]`	Caminhos que o sandbox não pode ler. Tem precedência sobre `allowRead`.
`allowWrite`	`[]` (somente diretório de trabalho)	Caminhos em que o sandbox pode gravar.
`denyWrite`	`[]`	Caminhos em que o sandbox não pode gravar. Tem precedência sobre `allowWrite`.

Importante

As regras de negação sempre têm precedência sobre as regras de permissão. Se um caminho corresponder a ambos allowWrite e denyWrite, o caminho será negado.

Restrições de rede¶

O sandbox pode restringir os comandos de domínio que ele pode acessar pela rede.

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["*.internal.company.com"],
      "allowLocalBinding": false
    }
  }
}


Configuração	Padrão	Descrição
`allowedDomains`	`[]` (permitir todos)	Domínios que o sandbox pode acessar. Uma matriz vazia significa que todos os domínios são permitidos (exceto aqueles em `deniedDomains`). Suporte para curingas (`*.example.com`).
`deniedDomains`	`[]`	Domínios que o sandbox não pode acessar. Tem precedência sobre `allowedDomains`. Suporte para curingas.
`allowLocalBinding`	`false`	Se os comandos em sandbox podem ser vinculados a portas locais.

Fallback de comando fora do sandbox¶

Alguns comandos podem não ser compatíveis com sandbox. A configuração allowUnsandboxedCommands controla o que acontece quando um comando não pode ser executado dentro do sandbox.


Configuração	Comportamento
`true` (padrão)	O agente pode solicitar a execução do comando no host. Você será solicitado a aprovar.
`false`	Os comandos devem ser executados dentro do sandbox ou listados em `excludedCommands`. Se nenhum dos dois ocorrer, haverá falha no comando.

Comandos excluídos¶

Você pode especificar comandos que sempre devem ser executados no host, fora do sandbox:

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": true,
    "excludedCommands": ["docker", "kubectl"]
  }
}

Os comandos excluídos ignoram o sandbox e seguem o fluxo normal de permissão.

Referência de configurações¶

O objeto de configurações de sandbox completo:

{
  "sandbox": {
    "enabled": false,
    "mode": "regular",
    "allowUnsandboxedCommands": true,
    "excludedCommands": [],
    "permissions": {
      "allow": [],
      "deny": []
    },
    "network": {
      "allowedDomains": [],
      "deniedDomains": [],
      "allowLocalBinding": false
    },
    "filesystem": {
      "allowRead": [],
      "denyRead": [],
      "allowWrite": [],
      "denyWrite": []
    },
    "ctxAvailable": true
  }
}


Configuração	Padrão	Descrição
`enabled`	`false`	Habilite ou desabilite o sandbox.
`mode`	`"regular"`	Modo de permissão: `"regular"` ou `"autoAllow"`.
`allowUnsandboxedCommands`	`true`	Permitir o fallback para execução no host quando um comando não pode ser colocado em sandbox.
`excludedCommands`	`[]`	Comandos que sempre são executados no host, fora do sandbox.
`permissions.allow`	`[]`	Regras de permissão de alto nível. Compatível com padrões como `WebFetch(domain:example.com)`, `Edit(path)`, `Read(path)`, `Bash(command)`.
`permissions.deny`	`[]`	Regras de negação de permissão de alto nível. Mesma sintaxe de padrão que `permissions.allow`. Tem precedência sobre as regras de permissão.
`network.allowedDomains`	`[]`	Lista de permissão de domínios de rede (vazia = permitir tudo). Suporte para curingas.
`network.deniedDomains`	`[]`	Lista de negação de domínios de rede. Tem precedência sobre a lista de permissão.
`network.allowLocalBinding`	`false`	Permitir que comandos em sandbox sejam vinculados a portas locais.
`filesystem.allowRead`	`[]`	Lista de permissão de leitura (vazia = permitir tudo, exceto negação).
`filesystem.denyRead`	`[]`	Lista de negação de leitura. Tem precedência.
`filesystem.allowWrite`	`[]`	Lista de permissão de gravação.
`filesystem.denyWrite`	`[]`	Lista de negação de gravação. Tem precedência.
`ctxAvailable`	`true`	Permitir o acesso do sandbox ao diretório de contexto (`~/.snowflake/cortex/.ctx` ), usado para armazenar contexto de conversa e dados de sessão.

Escopos de configuração¶

As configurações de sandbox seguem a mesma precedência que as outras configurações do Cortex Code:

Nível do projeto (prioridade mais alta): .snowflake/cortex/settings.json
Nível do usuário: ~/.snowflake/cortex/settings.json
Gerenciado/aplicado: os administradores podem aplicar a política de sandbox por meio do arquivo de configurações gerenciadas. Consulte Configurações gerenciadas (política da organização).