Noções básicas sobre políticas de sistema de arquivos para área restrita local em GitHub Copilot CLI

Introdução

Quando você habilita o sandboxing local, Copilot CLI executa os comandos que ele invoca em seu nome dentro de uma área restrita do sistema operacional. A sandbox impõe uma política de sistema de arquivos: um conjunto de regras que determina quais caminhos um processo ou operação em sandbox pode ler, quais pode gravar e quais não pode acessar de forma alguma.

A maior parte dessa política é montada automaticamente, para que os comandos diários continuem funcionando sem configuração. Este artigo explica como Copilot chega à política e como verificar o acesso que ela concede em um diretório específico.

Para obter uma visão geral do isolamento em sandbox local, incluindo como ativá-lo e desativá-lo, consulte Sobre a nuvem e as áreas restritas locais para GitHub Copilot e Usando o sandbox local. Para obter detalhes sobre como configurar o sandboxing local, consulte Configurando as configurações locais da sandbox.

A que a política se aplica

A política do sistema de arquivos abrange o trabalho que Copilot realiza em seu nome, mas é aplicada de maneiras diferentes, dependendo do tipo de trabalho:

• Os comandos do Shell e as pesquisas internas são executados como processos filho em área restrita, de modo que o sistema operacional impõe a política diretamente. As ferramentas grep e glob, por exemplo, executam o ripgrep como um processo filho isolado.
• O MCP local e os processos de servidor de idioma (LSP) são executados dentro da área restrita por padrão, de modo que o sistema operacional impõe a política a eles também. Você pode alterar isso nas configurações de sandbox, a menos que uma política gerenciada exija isso.
• As ferramentas integradas de leitura e edição de arquivos são executadas como parte do próprio Copilot CLI, e não como um processo filho em sandbox. Eles verificam a mesma política do sistema de arquivos antes de ler ou gravar um arquivo, mas, como o sandbox do sistema operacional nunca vê essas operações, essa verificação é um mecanismo de proteção apenas em software, em vez de ser aplicada pelo sistema operacional.
• Servidores MCP remotos são executados fora do computador, portanto, não há nenhum processo filho local para área restrita e a política do sistema de arquivos não os restringe. Suas conexões da CLI ainda podem ser restritas pela política de rede quando Sandbox MCP servers está habilitado.
• Os subagentes usam outras ferramentas para realizar seu trabalho. Se a política se aplica e como, depende da ferramenta que um subagente invoca.

Portanto, um processo em área restrita é restringido pelo sistema operacional, enquanto uma operação em processo impõe a mesma política no software, razão pela qual este artigo se refere a um processo ou operação em área restrita, em vez de apenas a comandos.

Níveis de permissão

A sandbox é nega por padrão: a menos que um caminho seja explicitamente concedido, um comando não pode usá-lo. Cada caminho na política tem um dos três níveis de permissão:

• Leitura/gravação – o comando pode ler e modificar arquivos nesse caminho.
• Somente leitura – o comando pode ler arquivos neste caminho, mas não alterá-los.
• Negado – o comando não pode ler ou gravar neste caminho, mesmo que uma regra mais ampla o permita de outra forma.

Como o acesso é negado, a menos que seja concedido, Copilot deve conceder a um comando tudo o que ele precisa legitimamente, seus arquivos de projeto, as ferramentas executadas e locais de suporte, como diretórios temporários, mantendo todo o resto fora dos limites.

Como a política é criada

Antes de cada processo em sandbox ser iniciado, Copilot CLI resolve a política efetiva desse processo usando o diretório de trabalho atual, o ambiente, as configurações e as concessões automáticas. Isso inclui locais comuns necessários para as ferramentas, para que você não precise conceder acesso a cada um deles individualmente. As ferramentas também podem receber acesso aos arquivos de sessão selecionados e às skills instaladas que precisam usar.

Seu diretório de trabalho

Quando Incluir diretório de trabalho está habilitado nas configurações do sistema de arquivos para área restrita local, como é por padrão, o diretório de trabalho atual recebe acesso de leitura/gravação. Em um repositório Git, Copilot também adiciona as concessões do Git associadas. Desativar essa configuração suprime todas essas concessões automáticas, portanto, você deve adicionar regras de permissão para o projeto necessário e os caminhos do Git manualmente. Consulte Configurando as configurações locais da sandbox.

Ferramentas no seu PATH

Para executar um programa como python ou git, a área restrita precisa permitir que o comando veja o diretório em que o programa reside. Quando Permitir acesso à ferramenta de desenvolvimento está habilitado, como é por padrão,Copilot concede acesso somente leitura aos diretórios listados em sua PATH variável de ambiente, juntamente com diretórios nomeados por variáveis de ferramenta relacionadas, como GOPATH, JAVA_HOMEe PYTHONPATH. Somente leitura é o nível correto para ferramentas externas: um comando precisa executar git, não modificá-lo. Se você desativar Permitir acesso à ferramenta de desenvolvimento , esses diretórios não serão mais concedidos automaticamente e deverão vir de suas próprias regras de permissão. Para obter a lista completa das variáveis de ambiente PATH e da cadeia de ferramentas que o sandbox inspeciona e como cada uma é interpretada, consulte referência de comando da CLI GitHub Copilot.

Localizações do sistema e do perfil

No macOS, os locais padrão do sistema recebem permissão de somente leitura para que os comandos possam carregar bibliotecas compartilhadas e ler a configuração do sistema sem poder alterá-los. Os diretórios de aplicativo em seu perfil de usuário (por exemplo, os subdiretórios de %LOCALAPPDATA%\Programs no Windows ou os ~/.local/bin diretórios ~/.local/lib no macOS e linux) também recebem permissão somente leitura quando Permitir acesso à ferramenta de desenvolvimento está habilitado, para que os comandos possam ler as ferramentas que você instalou lá sem poder modificá-las.

Caches do gerenciador de pacotes

Quando Permitir acesso às ferramentas de desenvolvimento está habilitado, Copilot concede acesso aos caches e repositórios usados por gerenciadores de pacotes comuns e cadeias de ferramentas. A maioria dos locais está em modo somente leitura. Locais selecionados, como o cache do npm, caches de build e alguns armazenamentos de dependências, são graváveis para que instalações e builds possam funcionar.

Essas permissões dependem do comando e das ferramentas detectadas em seu projeto. Eles podem acessar os locais de cache que você configurou fora dos diretórios usuais. Alguns arquivos de configuração concedidos contêm credenciais de registro, e caches graváveis podem ser compartilhados com comandos executados fora da área restrita. Desative Permitir acesso às ferramentas de desenvolvedor se preferir conceder essas pastas por conta própria.

No /sandbox policy relatório, a seção Ferramentas de Desenvolvimento lista as ferramentas detectadas e seus caminhos. Os caches graváveis selecionados são criados quando um comando precisa deles, por isso eles podem não aparecer no relatório antes do primeiro uso.

Repositórios do Git;

Quando você trabalha em um subdiretório de um repositório Git, Copilot concede acesso de leitura a todo o repositório para que os comandos possam ver o projeto completo, enquanto limita as operações de gravação ao seu diretório de trabalho atual e aos metadados Git do repositório (seu diretório .git). Isso permite que um comando seja lido no repositório, mas mantém as alterações focadas no local em que você está trabalhando.

Como o acesso de leitura abrange todo o repositório, um comando em área restrita pode ler arquivos fora do subdiretório atual, incluindo qualquer coisa confidencial armazenada em outro lugar do projeto. Para manter caminhos específicos fora de alcance, você pode adicionar regras de negação. Consulte Configurando as configurações locais da sandbox.

Quando as regras de acesso se sobrepõem

Como Copilot concede vários locais e você pode adicionar seus próprios, as regras podem se sobrepor. Quando as permissões somente leitura e leitura/gravação se sobrepõem, o caminho mais específico vence. Por exemplo, se /project for gravável, mas você marcar /project/secrets como somente leitura, tudo em /project permanecerá gravável, exceto /project/secrets. Os caminhos negados têm precedência sobre ambos os tipos de permissão concedida.

As permissões descobertas do diretório de ferramentas são substituídas pelo acesso de leitura/gravação que já as abrange. Considere um projeto Python com um ambiente virtual local (.venv) que aparece em seu PATH. Tratar esse diretório como um local comum de ferramentas somente para leitura o tornaria somente para leitura, mesmo que ele esteja dentro do seu projeto com permissão de gravação, e um comando como pip install poderia falhar ao tentar atualizar o ambiente. Copilot o deixa gravável como parte do workspace. Outras regras somente leitura, incluindo as que você mesmo configura, não são descartadas dessa forma.

As regras que você configura não são removidas apenas porque o mesmo caminho foi descoberto automaticamente. Você pode usá-los para restringir o acesso a um local confidencial, como um arquivo .env existente. Caminhos ausentes e links simbólicos precisam de cuidados adicionais, conforme descrito na solução de problemas de acesso ao sistema de arquivos.

Verificando o que a política atual permite

Como a política é montada para cada diretório e comando, a maneira mais simples de ver o acesso que você tem é perguntar Copilot CLI. Em uma sessão, digite:

/sandbox policy

/sandbox policy

Copilot imprime a política efetiva para o diretório atual. Os caminhos são agrupados por origem, como caminhos configurados pelo usuário e ferramentas de desenvolvimento e por nível de acesso. O relatório também inclui configurações de rede e uma seção Capacidades que abrange configurações como bypass, isolamento em sandbox de MCP/LSP e autenticação. Esse é o resultado após concessões automáticas, suas configurações e restrições gerenciadas terem sido combinadas, não apenas uma cópia de suas configurações salvas.

Para inspecionar o acesso à ferramenta de desenvolvedor para um comando específico, adicione o comando após policy. Por exemplo:

/sandbox policy npm install

/sandbox policy npm install

Isso não executa npm install. Mostra o acesso à ferramenta que o comando receberia. A visualização não cria diretórios, nem mesmo para caminhos negados ou ausentes e caches de ferramentas.

Algumas coisas para ter em mente ao ler o relatório:

• Isso reflete o diretório atual. Como as concessões são descobertas por diretório, as mesmas configurações podem ser resolvidas para caminhos diferentes, dependendo de onde você as executa.
• Verifique Notas para caminhos configurados que não puderam ser incluídos. As permissões de leitura/gravação ou somente leitura ausentes não são incluídas. No Linux, os caminhos negados ausentes são omitidos dessa versão prévia, mas a preparação de inicialização os cria antes de aplicar a política. A Pré-visualização os mantém no macOS e em hosts Windows com suporte a caminhos negados.
• Se o isolamento (sandboxing) estiver desativado, /sandbox policy informa isso em vez de exibir uma política, porque nenhuma restrição está em vigor.

Para verificar apenas se o sandboxing está ativado no momento, use /sandbox status. Para obter mais informações sobre esses comandos, consulte Usando o sandbox local.

Solução de problemas de acesso ao sistema de arquivos

Se um caminho de leitura/gravação ou somente leitura configurado não existir, crie-o fora da área restrita antes de iniciar o comando novamente. Um processo filho em execução mantém a política recebida no início. Criar um caminho posteriormente não adiciona uma permissão ausente a esse processo. Reinicie um servidor que está em execução há muito tempo se precisar do acesso atualizado.

Antes do início de um processo em área restrita, Copilot CLI cria caminhos com acesso negado ausentes e seus diretórios pai em seu computador. Isso inclui caminhos destinados a arquivos, portanto, um ausente .env se torna um diretório. Os diretórios permanecem após o processo ser encerrado.

Se um caminho negado não puder ser preparado, o processo não será iniciado. A visualização de somente leitura /sandbox policy não executa essa preparação, e é por isso que os caminhos negados que estão ausentes são omitidos no Linux. Para solucionar problemas, consulte Usando o sandbox local.

Um link simbólico dentro de um diretório permitido não garante o acesso a um destino fora desse diretório. Se uma mensagem de negação nomeia esse destino, inspecione-o e conceda acesso somente se for intencional. Adicionar um link simbólico resolvível por meio de /sandbox config também adiciona seu destino atual para acesso de leitura/gravação ou somente leitura. As regras de caminho definidas manualmente e as concessões da ferramenta do desenvolvedor descobertas automaticamente não adicionam automaticamente esse destino.

Os caminhos negados são tratados de forma diferente das permissões concedidas: a CLI resolve seu caminho como escrito e o destino atual. No Linux, um link simbólico negado protege seu alvo, mas não impede de forma confiável que o link em si seja substituído. Prefira negar o diretório confidencial real em vez de depender apenas de uma regra de vínculo simbólico.

Para falhas de rede, restrições gerenciadas e opções de bypass, consulte Solução de problemas de comandos bloqueados.

Personalizando a política

Você pode conceder caminhos adicionais de leitura/gravação ou somente leitura, negar caminhos e alterar outros comportamentos do sistema de arquivos, seja na caixa de diálogo /sandbox config ou no arquivo de configurações. Depois de fazer uma alteração, execute /sandbox policy para confirmar o resultado. Para obter instruções passo a passo, consulte Configurando as configurações locais da sandbox.

Políticas gerenciadas pela empresa

Se você receber Copilot por meio de uma organização pertencente à empresa, um administrador poderá aplicar uma política do sistema de arquivos por meio de configurações gerenciadas. As configurações gerenciadas atuam como uma base restritiva: elas podem exigir isolamento em sandbox, adicionar caminhos bloqueados e limitar quais caminhos você pode autorizar. Quando uma configuração gerenciada se aplica, a /sandbox config caixa de diálogo mostra-a como um valor bloqueado (gerenciado) e /sandbox policy reflete-a na política resolvida. Se a política efetiva permitir ignorar a sandbox, um usuário poderá desativar explicitamente o sandboxing durante o restante da sessão atual, seja a partir de um prompt ativo de permissão para ignorar a sandbox ou executando /sandbox disable. Esta desativação da sessão não flexibiliza a política salva.

Ao contrário da maioria das configurações, em que uma única fonte prevalece, a política de sandbox é composta por todas as fontes vigentes ao mesmo tempo. As configurações gerenciadas podem chegar simultaneamente por mais de um canal — gerenciadas pelo servidor, por MDM e baseadas em arquivos — e elas se combinam entre si e com suas próprias configurações seguindo o critério mais restritivo, em vez de uma fonte se sobrepor à outra: um controle obrigatório permanece ativado, os caminhos negados de todas as fontes são acumulados, e os caminhos que você pode autorizar só podem ser ainda mais restringidos. Para obter mais informações, consulte Configurações gerenciadas pela empresa.

Leitura adicional

• Sobre a nuvem e as áreas restritas locais para GitHub Copilot
• Usando o sandbox local
• Configurando as configurações locais da sandbox