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 isolamento local.

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) também podem ser executados dentro da área restrita, de modo que o sistema operacional impõe a política a eles também.
• 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.
• Os subagentes não agem diretamente; eles orquestram outras ferramentas. 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 restringe o processo apenas ao acesso necessário e significa que você não precisa gerenciar esses locais comuns por conta própria.

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. Apenas leitura é o nível adequado para ferramentas externas: um comando precisa ser executado em 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 de PATH e da cadeia de ferramentas que a sandbox inspeciona, e como cada uma delas é 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 as configurações do sistema sem poder modificá-los. Os diretórios de aplicativo em seu perfil de usuário também são concedidos 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

Para permitir que instalações e compilações funcionem dentro do sandbox, Copilot também concede acesso aos caches e repositórios usados por gerenciadores de pacotes e cadeias de ferramentas comuns — somente leitura para a maioria dos locais e leitura e gravação para locais específicos com permissão de gravação, como caches de compilação e armazenamentos de dependências de gerenciadores de pacotes. /sandbox policy No relatório, isso aparece como acesso à ferramenta de desenvolvimento.

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 o fizerem, o caminho mais específico ganhará. Por exemplo, se /project for gravável, mas você marcar /project/secrets como somente leitura, tudo em /project permanecerá gravável, exceto /project/secrets. Essa é uma maneira útil de proteger uma subpasta confidencial.

Os casos de sobreposição também são resolvidos a seu favor quando uma permissão de conveniência, de outra forma, atrapalharia. 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 resolve isso para você: uma permissão adicionada automaticamente (como um diretório de ferramentas em PATH) é substituída por uma permissão de leitura e gravação mais ampla que já o abrange. Assim, um diretório local ao projeto node_modules/.bin, .venv ou semelhante permanece com permissão de gravação como parte do seu espaço de trabalho.

As regras configuradas são sempre mantidas. Se você marcar um caminho como somente leitura ou negá-lo, essa decisão será mantida mesmo que esse mesmo caminho, de outra forma, fosse detectado e autorizado automaticamente. Isso fornece uma maneira confiável de proteger um local confidencial, por exemplo, negando um .env arquivo para que nenhum comando em área restrita possa ler seus segredos.

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 exibe a política efetiva para o diretório atual: os caminhos com permissão de leitura/gravação, somente leitura e negados que um comando executado a partir daqui realmente receberia, juntamente com o acesso à rede e o acesso às ferramentas de desenvolvimento em vigor. Este é o resultado final após a combinação das concessões automáticas com suas configurações e a resolução de todas as sobreposições — não apenas uma cópia das suas configurações salvas.

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

• Isso reflete o diretório atual. Como as permissões são identificadas com base em cada diretório, as mesmas configurações podem ser resolvidas em caminhos diferentes, dependendo de onde forem executadas.
• Se um caminho que você configurou não existir no disco, ele será omitido da política e indicado em uma seção de Notas. Isso explica por que uma regra que você adicionou pode parecer não ter efeito.
• 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 isolamento local.

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 o sandbox, o usuário poderá desativar explicitamente o sandbox pelo restante da sessão atual a partir de um prompt ativo de permissão para ignorá-lo. Esta desativação da sessão não altera 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 isolamento local
• Configurando as configurações locais da sandbox