Descripción de las directivas del sistema de archivos para el entorno de pruebas local en GitHub Copilot CLI

Introduction

Al habilitar el espacio aislado local, Copilot CLI ejecuta los comandos que invoca en su nombre dentro de un espacio aislado del sistema operativo. El espacio aislado impone una política del sistema de archivos: un conjunto de reglas que determina qué rutas puede leer un proceso u operación en entorno aislado, cuáles puede escribir y a cuáles no puede acceder en absoluto.

La mayoría de esta directiva se ensambla automáticamente, de modo que los comandos diarios sigan funcionando sin configurar. En este artículo se explica cómo Copilot llega a la directiva y cómo comprobar el acceso que concede en un directorio determinado.

Para obtener una visión general del aislamiento local, incluida la forma de activarlo y desactivarlo, consulte Información sobre los entornos de pruebas en la nube y locales para GitHub Copilot y Uso del entorno aislado local. Para más información sobre cómo configurar el espacio aislado local, consulte Configuración de los ajustes del entorno aislado local.

¿A qué se aplica la directiva?

La política del sistema de archivos abarca el trabajo que Copilot realiza en su nombre, pero se aplica de distintas maneras según el tipo de trabajo:

• Los comandos de Shell y las búsquedas integradas se ejecutan como procesos secundarios de espacio aislado, por lo que el sistema operativo aplica la directiva directamente. Las herramientas grep y glob, por ejemplo, ejecutan ripgrep como un proceso hijo en entorno aislado.
• Los procesos locales de MCP y del servidor de lenguaje (LSP) se ejecutan dentro del espacio aislado de forma predeterminada, por lo que el sistema operativo también aplica la directiva en ellos. Puede cambiarlo en la configuración del espacio aislado a menos que una directiva administrada lo requiera.
• Las herramientas integradas para leer y editar archivos se ejecutan como parte de Copilot CLI mismo, en lugar de hacerlo como un proceso hijo aislado. Comprueban la misma directiva del sistema de archivos antes de leer o escribir un archivo, pero dado que el espacio aislado del sistema operativo nunca ve estas operaciones, la comprobación es una protección solo de software en lugar de una que el sistema operativo aplica.
• Los servidores MCP remotos se ejecutan fuera de tu equipo, por lo que no hay ningún proceso secundario local que aislar y la directiva del sistema de archivos no los restringe. La directiva de red puede restringir sus conexiones desde la CLI cuando los servidores MCP Sandbox están habilitados.
• Los subagentes usan otras herramientas para realizar su trabajo. Si se aplica la directiva y cómo depende de la herramienta que invoca un subagente.

Por lo tanto, un proceso de espacio aislado está restringido por el sistema operativo, mientras que una operación en proceso aplica la misma directiva en el software, por lo que este artículo hace referencia a un proceso o operación de espacio aislado en lugar de solo a comandos.

Niveles de permisos

El espacio aislado es deny-by-default: a menos que se conceda explícitamente una ruta de acceso, un comando no puede usarlo. Cada ruta de la directiva tiene uno de estos tres niveles de permisos:

• Lectura y escritura : el comando puede leer y modificar archivos en esta ruta de acceso.
• Solo lectura : el comando puede leer archivos en esta ruta de acceso, pero no cambiarlos.
• Denegado : el comando no puede leer ni escribir en esta ruta de acceso, aunque una regla más amplia lo permita.

Dado que se deniega el acceso a menos que se conceda, Copilot debe conceder un comando todo lo que necesita legítimamente, los archivos del proyecto, las herramientas que ejecuta y las ubicaciones auxiliares, como directorios temporales, al tiempo que mantiene todo lo demás fuera de los límites.

Cómo se compila la directiva

Antes de que se inicie cada proceso aislado, Copilot CLI determina la política efectiva de ese proceso en función del directorio de trabajo actual, el entorno, la configuración y los permisos concedidos automáticamente. Esto incluye ubicaciones comunes necesarias para las herramientas, por lo que no es necesario conceder permisos a cada una de ellas. Las herramientas también pueden recibir acceso a los archivos de sesión seleccionados y a las habilidades instaladas que necesitan usar.

El directorio de trabajo

Cuando Incluir directorio de trabajo está habilitado en la configuración del sistema de archivos para el aislamiento local, como ocurre de forma predeterminada, se le concede acceso de lectura y escritura al directorio de trabajo actual. En un repositorio de Git, Copilot también agrega las concesiones de Git asociadas. Al desactivar esta configuración, se suprimen todas esas autorizaciones automáticas, por lo que debe agregar manualmente reglas de permiso para las rutas de Git y del proyecto necesarias. Consulte Configuración de los ajustes del entorno aislado local.

Herramientas en tu PATH

Para ejecutar un programa como python o git, el espacio aislado tiene que permitir que el comando vea el directorio en el que reside el programa. Cuando Permitir el acceso a las herramientas de desarrollo está habilitado —como ocurre de forma predeterminada—, Copilot concede acceso de solo lectura a los directorios enumerados en la variable de entorno PATH, junto con los directorios especificados por variables de herramientas relacionadas, como GOPATH, JAVA_HOME y PYTHONPATH. Solo lectura es el nivel adecuado para las herramientas externas: un comando debe ejecutar git, no modificarlo. Si desactiva la opción Permitir acceso a las herramientas de desarrollo, estos directorios ya no se autorizan automáticamente y deben estar contemplados en sus propias reglas de permiso. Para obtener la lista completa de las variables de entorno de PATH y de la cadena de herramientas que inspecciona el entorno aislado, así como la forma en que se interpreta cada una de ellas, consulte Referencia de comandos de la CLI de GitHub Copilot.

Ubicaciones del sistema y del perfil

En macOS, a las ubicaciones del sistema estándar se les concede permiso de solo lectura para que los comandos puedan cargar bibliotecas compartidas y leer la configuración del sistema sin poder cambiarlas. Los directorios de aplicación del perfil de usuario (por ejemplo, los subdirectorios de %LOCALAPPDATA%\Programs en Windows, o los ~/.local/bin directorios y ~/.local/lib en macOS y Linux) también se conceden permisos de solo lectura cuando se habilita permitir el acceso a la herramienta de desarrollo, de modo que los comandos puedan leer las herramientas que ha instalado allí sin poder modificarlas.

Cachés del administrador de paquetes

Cuando Permitir el acceso a las herramientas de desarrollo está habilitado, Copilot concede acceso a las memorias caché y los registros usados por administradores de paquetes y cadenas de herramientas comunes. La mayoría de las ubicaciones son de solo lectura. Las ubicaciones seleccionadas, como la memoria caché de npm, las cachés de compilación y algunos almacenes de dependencias, tienen permiso de escritura para que las instalaciones y compilaciones puedan funcionar.

Estos permisos dependen del comando y de las herramientas detectadas en el proyecto. Pueden seguir las ubicaciones de caché configuradas fuera de los directorios habituales. Algunos archivos de configuración concedidos contienen credenciales del registro y las cachés grabables se pueden compartir con comandos que se ejecutan fuera del espacio aislado. Desactive Permitir el acceso a la herramienta de desarrollo si prefiere conceder estas ubicaciones usted mismo.

En el informe /sandbox policy, en la sección Herramientas de desarrollo se enumeran las herramientas detectadas y sus rutas de acceso. Las memorias caché grabables seleccionadas se crean cuando un comando los necesita, por lo que es posible que no aparezcan en el informe antes del primer uso.

Repositorios Git

Cuando se trabaja en un subdirectorio de un repositorio Git, Copilot otorga acceso de lectura a todo el repositorio para que los comandos puedan ver el proyecto completo, al tiempo que limita el acceso de escritura al directorio de trabajo actual y al directorio .git de metadatos Git del repositorio. Esto permite que un comando lea todo el repositorio, pero mantiene los cambios limitados a la parte en la que estás trabajando.

Dado que el acceso de lectura abarca todo el repositorio, un comando de espacio aislado puede leer archivos fuera del subdirectorio actual, incluida cualquier información confidencial almacenada en otro lugar del proyecto. Para mantener las rutas de acceso específicas fuera de alcance, puede agregar reglas de denegación. Consulte Configuración de los ajustes del entorno aislado local.

Cuando las reglas de acceso se superponen

Dado que Copilot concede permisos para varias ubicaciones y puedes añadir las tuyas propias, las reglas pueden solaparse. Cuando las concesiones de solo lectura y de lectura y escritura se superponen, gana la ruta de acceso más específica. Por ejemplo, si /project es editable, pero se marca /project/secrets como de solo lectura, todo en /project permanece editable excepto /project/secrets. Las rutas de acceso denegadas tienen prioridad sobre ambos tipos de permiso.

Las concesiones de directorio de herramientas detectadas dan paso a un acceso de lectura y escritura que ya las cubre. Considere un proyecto de Python con un entorno virtual local (.venv) que aparece en PATH. Tratar ese directorio como una ubicación normal para herramientas de solo lectura haría que fuera de solo lectura, a pesar de que está dentro de tu proyecto con permiso de escritura, y un comando como pip install podría entonces fallar al intentar actualizar el entorno. Copilot lo deja editable como parte del área de trabajo. Otras reglas de solo lectura, incluidas las que configure usted mismo, no se descartan de esta manera.

Las reglas que usted configure no se quitan solo porque la misma ruta de acceso se detectó automáticamente. Puede usarlos para restringir el acceso a una ubicación confidencial, como un archivo .env existente. Las rutas de acceso que faltan y los vínculos simbólicos necesitan atención adicional, como se describe en Solución de problemas de acceso al sistema de archivos.

Comprobación de lo que permite la directiva actual

Dado que la directiva se ensambla para cada directorio y comando, la manera más sencilla de ver el acceso que tiene es preguntar Copilot CLI. En una sesión, escriba:

/sandbox policy

/sandbox policy

Copilot imprime la directiva efectiva para el directorio actual. Las rutas de acceso se agrupan por origen, como las rutas de acceso configuradas por el usuario y las herramientas de desarrollo, y por nivel de acceso. El informe también incluye la configuración de red y una sección Capacidades que abarca la configuración, como bypass, el espacio aislado MCP/LSP y la autenticación. Este es el resultado después de que se hayan combinado las concesiones automáticas, la configuración y las restricciones administradas, no solo una copia de la configuración guardada.

Para inspeccionar el acceso de la herramienta de desarrollador para un comando determinado, agregue el comando después de policy. Por ejemplo:

/sandbox policy npm install

/sandbox policy npm install

Esto no se ejecuta npm install. Muestra el acceso a la herramienta que recibiría el comando. La vista previa no crea directorios, incluidas las rutas denegadas o inexistentes y las memorias caché de herramientas.

Algunas cosas que debe tener en cuenta al leer el informe:

• Refleja el directorio actual. Dado que los permisos se determinan por directorio, una misma configuración puede corresponder a rutas diferentes dependiendo de dónde se ejecute.
• Consulte Notas para ver las rutas de acceso configuradas que no se pudieron incluir. Se omiten los permisos de lectura y escritura o de solo lectura que faltan. En Linux, las rutas de acceso denegadas que faltan se omiten en esta versión preliminar, pero la preparación de inicio las crea antes de aplicar la directiva. La versión preliminar los conserva en macOS y en hosts Windows que admiten rutas de acceso denegadas.
• Si el aislamiento está desactivado, /sandbox policy se lo indica en lugar de mostrar una política, porque no hay restricciones en vigor.

Para comprobar únicamente si el aislamiento está activado en este momento, use /sandbox status. Para obtener más información sobre estos comandos, consulte Uso del entorno aislado local.

Solución de problemas de acceso al sistema de archivos

Si no existe una ruta de acceso de lectura/escritura o de solo lectura configurada, créela fuera del espacio aislado antes de volver a iniciar el comando. Un proceso secundario en ejecución mantiene la directiva que recibió al iniciarse. La creación de una ruta de acceso más adelante no agrega un permiso que falta a ese proceso. Reinicie un servidor de larga duración si necesita los permisos de acceso actualizados.

Antes de que se inicie un proceso de espacio aislado, Copilot CLI crea las rutas denegadas que faltan y sus directorios padre en la máquina. Esto incluye las rutas de acceso destinadas a los archivos, por lo que la ausencia de .env hace que se convierta en un directorio. Los directorios permanecen después de que el proceso finalice.

Si no se puede preparar una ruta de acceso denegada, el proceso no se inicia. La versión preliminar de solo /sandbox policy lectura no realiza esta preparación, por lo que se omiten allí las rutas denegadas ausentes en Linux. Para solucionar problemas, consulte Uso del entorno aislado local.

Un vínculo simbólico dentro de un directorio permitido no garantiza el acceso a un destino fuera de ese directorio. Si un mensaje de denegación menciona ese destino, inspecciónelo y conceda acceso solo si está previsto. Agregar un vínculo simbólico que se puede resolver mediante /sandbox config también agrega su destino actual para acceso de lectura y escritura o de solo lectura. Las reglas de ruta de acceso escritas a mano y las concesiones de herramientas de desarrollador detectadas automáticamente no agregan automáticamente ese objetivo.

Las rutas de acceso denegadas se gestionan de forma diferente a los permisos concedidos: la CLI resuelve su ruta de acceso escrita y el destino actual. En Linux, un vínculo simbólico denegado protege su destino, pero no impide que el propio vínculo se reemplace de forma confiable. Prefiere denegar el directorio confidencial real en lugar de confiar solo en una regla de vínculo simbólico.

Para ver fallos de red, restricciones administradas y opciones de omisión, consulte Solución de problemas de comandos bloqueados.

Personalizar la directiva

Puede conceder rutas de acceso adicionales de lectura y escritura o de solo lectura, denegar rutas de acceso y cambiar otro comportamiento del sistema de archivos, ya sea desde el cuadro de diálogo o en el /sandbox config archivo de configuración. Después de realizar un cambio, ejecute /sandbox policy para confirmar el resultado. Para obtener instrucciones paso a paso, consulte Configuración de los ajustes del entorno aislado local.

Directivas administradas por la empresa

Si obtiene Copilot a través de una organización propiedad de una empresa, un administrador puede imponer una directiva del sistema de archivos mediante la configuración administrada. La configuración administrada actúa como una base de referencia restrictiva: puede exigir el uso de un entorno aislado, añadir rutas denegadas y limitar las rutas que se te permite autorizar. Cuando se aplica una configuración administrada, el /sandbox config cuadro de diálogo lo muestra como un valor bloqueado (administrado) y /sandbox policy lo refleja en la directiva resuelta. Si la directiva efectiva permite la omisión del espacio aislado, un usuario puede deshabilitar explícitamente el espacio aislado para el resto de la sesión actual, ya sea desde un aviso de permisos de omisión activo o ejecutando /sandbox disable. La exclusión voluntaria de esta sesión no modifica la política guardada.

A diferencia de la mayoría de los ajustes, donde prevalece un único origen, la directiva de espacio aislado se compone a partir de todos los orígenes vigentes al mismo tiempo. Los ajustes administrados pueden llegar simultáneamente a través de más de un canal —gestionados por el servidor, por MDM y basados en archivos— y se combinan entre sí, y con tus propios ajustes, aplicando el criterio más restrictivo en lugar de que una fuente prevalezca sobre otra: un interruptor obligatorio permanece activado, las rutas denegadas de todas las fuentes se acumulan y las rutas que se te permite autorizar solo pueden restringirse más. Para obtener más información, vea Configuración administrada por la empresa.

Lectura adicional

• Información sobre los entornos de pruebas en la nube y locales para GitHub Copilot
• Uso del entorno aislado local
• Configuración de los ajustes del entorno aislado local