로컬 샌드박스는 GitLab Duo 에이전트가 사용자의 컴퓨터에서 실행될 때 읽고, 쓰고, 네트워크로 접근할 수 있는 범위를 제한합니다. 에디터의 에이전트와 GitLab Duo CLI의 에이전트에 적용됩니다.

샌드박스는 기본적으로 꺼져 있습니다. 샌드박스를 켜기 전에는 에디터 확장 및 CLI 도구의 보안 고려 사항에 설명된 위험이 적용됩니다.

GitLab Runner에서 실행되는 플로는 원격 실행 환경 샌드박스를 참고합니다.

샌드박스 작동 방식#

샌드박스가 켜져 있으면 GitLab Duo는 운영 체제가 제한하는 별도의 워커 프로세스에서 에이전트 작업을 실행합니다. 에이전트 작업에는 셸 명령, 파일 읽기와 쓰기, 파일 검색, 디렉터리 목록 조회가 포함됩니다.

stdio 전송을 사용하는 로컬 MCP 서버도 같은 종류의 샌드박스에서 실행됩니다.

샌드박스는 GITLAB_TOKEN, GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, SSH_AUTH_SOCK 같은 알려진 자격 증명 환경 변수를 샌드박스 안 프로세스의 환경에서 제거합니다. 그 밖의 환경 변수는 제거하지 않습니다.

기본적으로 샌드박스는 다음도 차단합니다:

• 일반적인 자격 증명 디렉터리와 개인 디렉터리 읽기.
• 워크스페이스와 임시 디렉터리 밖에 쓰기.
• GitLab 인스턴스를 제외한 모든 호스트로의 네트워크 접근.

전체 목록은 기본 샌드박스 규칙을 참고합니다.

이 샌드박스는 프로세스 샌드박스이며 컨테이너나 가상 머신이 아닙니다. 다음은 샌드박스 밖에서 실행됩니다:

• 에디터와 GitLab Duo 자체.
• http 또는 sse 전송을 사용하는 MCP 서버와의 연결.
• "sandboxEnabled": false 가 설정된 MCP 서버.
• GitLab Duo CLI 훅.

샌드박스는 에이전트를 로컬에서 실행할 때의 위험을 줄이지만 없애지는 못합니다. 에이전트는 여전히 워크스페이스의 파일을 읽고 변경할 수 있으며, 샌드박스가 허용하는 호스트로 데이터를 보낼 수 있습니다.

샌드박스가 켜져 있지만 시작할 수 없는 경우(예: 의존성이 없는 경우) 에이전트 작업과 로컬 MCP 서버는 오류와 함께 실패합니다. 샌드박스 없이 실행되지 않습니다. 이 동작은 샌드박스 없이 플로를 실행하고 경고를 표시하는 원격 실행 환경 샌드박스와 다릅니다.

지원 플랫폼#

사전 요구 사항#

Linux에서는 bubblewrap과 socat을 설치합니다. 예를 들면 다음과 같습니다:

• Debian 또는 Ubuntu에서:

  sudo apt-get install bubblewrap socat
  

• Fedora에서:

  sudo dnf install bubblewrap socat
  

macOS에서는 추가 소프트웨어가 필요하지 않습니다.

샌드박스 켜기#

샌드박스를 켜려면 다음과 같이 합니다:

duo --sandbox true

export DUO_SANDBOX_ENABLED=true

샌드박스 상태 확인#

샌드박스가 켜져 있고 사용할 수 있는지 확인하려면 다음과 같이 합니다:

각 상태 확인은 다음 항목을 보고합니다:

• 설정에서 프로세스 샌드박싱이 활성화되어 있는지 여부.
• 이 플랫폼에서 프로세스 샌드박싱이 지원되는지 여부.
• 프로세스 샌드박싱에 필요한 시스템 의존성이 설치되어 있는지 여부.

기본 샌드박스 규칙#

이 규칙은 샌드박스가 켜져 있을 때 에이전트 작업과 로컬 MCP 서버에 적용됩니다.

네트워크#

샌드박스 안 프로세스는 GitLab 인스턴스 URL의 호스트와 포트에만 연결할 수 있습니다. 인스턴스 URL에 포트가 없으면 샌드박스는 https에 443을, http에 80을 사용합니다.

패키지 레지스트리를 포함한 다른 모든 호스트는 차단됩니다. 더 많은 호스트를 허용하려면 샌드박스 규칙을 사용자 지정합니다.

샌드박스는 각 연결의 호스트와 포트만 확인합니다. 요청 내용은 검사하지 않습니다. 에이전트는 샌드박스가 허용하는 호스트의 모든 프로젝트나 계정으로 데이터를 보낼 수 있습니다.

파일 시스템 읽기#

샌드박스 안 프로세스는 다음을 읽을 수 없습니다:

• ~/.ssh/, ~/.gnupg/, ~/.aws/, ~/.azure/, ~/.kube/config, ~/.docker/config.json, ~/.netrc, ~/.git-credentials, ~/.npmrc, ~/.pypirc 같은 자격 증명 파일과 디렉터리.
• ~/.config/. 단, ~/.config/git/은 제외됩니다.
• 개인 디렉터리: ~/Documents/, ~/Downloads/, ~/Desktop/, ~/Pictures/, ~/Movies/, ~/Music/.
• 셸 기록: ~/.bash_history와 ~/.zsh_history.
• macOS에서 ~/Library/Application Support/, ~/Library/Containers/, ~/Library/Group Containers/, ~/Library/Keychains/.

Linux와 VS Code의 macOS에서 샌드박스 안 프로세스는 허용된 경로 집합만 읽을 수 있습니다. 허용된 경로에는 워크스페이스, /usr/, /bin/, /etc/ 같은 시스템 디렉터리, 임시 디렉터리, GitLab Duo 구성 디렉터리, Git 구성, 일반적인 Node.js 버전 관리자 디렉터리가 포함됩니다.

JetBrains IDE와 GitLab Duo CLI의 macOS에서 샌드박스 안 프로세스는 차단 목록에 없는 모든 경로를 읽을 수 있습니다.

허용된 경로는 그 경로를 포함하는 차단된 경로보다 우선합니다. 예를 들어 워크스페이스가 ~/Documents/ 안에 있으면 샌드박스 안 프로세스는 그 워크스페이스를 읽을 수 있습니다.

파일 시스템 쓰기#

샌드박스 안 프로세스는 워크스페이스, 임시 디렉터리, 샌드박스 런타임이 사용하는 몇몇 로그 디렉터리에만 쓸 수 있습니다.

워크스페이스 안에서도 샌드박스 안 프로세스는 다음에 쓸 수 없습니다:

• .git/hooks/와 .git/config
• .gitlab-ci.yml과 .gitlab/
• .gitconfig와 .gitmodules
• .bashrc, .zshrc, .profile 같은 셸 시작 파일
• 에디터 구성 디렉터리: .vscode와 .idea

GitLab Duo CLI에서 --cwd 옵션으로 다른 디렉터리의 워크스페이스를 열면, .git/config, .gitmodules, 셸 시작 파일, 에디터 구성 디렉터리에 대한 규칙은 워크스페이스가 아니라 CLI를 시작한 디렉터리에 적용됩니다. 이 규칙을 워크스페이스에 적용하려면 워크스페이스 디렉터리에서 CLI를 시작합니다.

샌드박스 규칙 사용자 지정#

샌드박스 구성 파일에서 기본 규칙에 규칙을 추가할 수 있습니다. 추가한 규칙은 모든 워크스페이스에 적용됩니다.

샌드박스 규칙을 사용자 지정하려면 다음과 같이 합니다:

1. 파일 위치에 sandbox.json 파일을 만듭니다.

2. 필요한 규칙을 추가합니다. 예를 들어 에이전트가 npm 레지스트리에서 패키지를 설치하고 홈 디렉터리의 한 디렉터리를 읽도록 허용하려면 다음과 같이 합니다:

   {
     "network": {
       "allowedDomains": ["registry.npmjs.org"]
     },
     "filesystem": {
       "allowRead": ["~/reference-docs/"],
       "allowWrite": ["~/.npm/"]
     }
   }
   

   npm은 내려받은 패키지를 ~/.npm/에 저장하므로 이 예시는 그 위치에 대한 쓰기도 허용합니다.

3. 파일을 저장합니다.

4. IDE 또는 GitLab Duo CLI를 다시 시작합니다.

GitLab Duo CLI에서는 --sandbox-config 옵션이나 DUO_SANDBOX_CONFIG 환경 변수로 다른 파일을 사용할 수 있습니다. 절대 경로 또는 ~/로 시작하는 경로를 사용합니다. 샌드박스도 켜져 있어야 합니다:

duo --sandbox true --sandbox-config ~/sandbox-strict.json

파일 위치#

파일은 ~/.gitlab/duo/sandbox.json에 있습니다.

XDG_CONFIG_HOME 환경 변수를 설정한 경우 파일은 $XDG_CONFIG_HOME/gitlab/duo/sandbox.json에 있습니다.

구성 파일 참조#

이 파일은 다음 키를 지원합니다. 별도로 명시하지 않는 한 각 키는 문자열 목록을 값으로 받습니다.

추가한 규칙은 기본 규칙에 더해집니다. 다음은 제거할 수 없습니다:

• 워크스페이스와 임시 디렉터리에 대한 쓰기 접근.
• GitLab 인스턴스에 대한 네트워크 접근.
• 워크스페이스에서 차단된 쓰기 경로.

파일이 유효한 JSON이 아니거나 이 표에 없는 키가 포함되어 있으면 GitLab Duo는 파일 전체를 무시하고 기본 규칙을 사용합니다. 오류는 GitLab Duo 로그에 기록됩니다.

MCP 서버의 샌드박스 구성#

일부 로컬 MCP 서버는 기본 규칙이 차단하는 접근이 필요합니다. 예를 들어 자체 구성을 ~/.config/에서 읽는 MCP 서버는 시작할 수 없습니다.

MCP 서버 하나의 샌드박스 규칙을 변경하려면 다음과 같이 합니다:

1. 사용자 MCP 구성 파일을 엽니다.

2. 서버 구성에 sandbox 객체를 추가합니다. 예를 들면 다음과 같습니다:

   {
     "mcpServers": {
       "gitlab": {
         "type": "stdio",
         "command": "glab",
         "args": ["mcp", "serve"],
         "sandbox": {
           "allowRead": ["~/.config/glab-cli/"]
         }
       }
     }
   }
   

   이 예시는 Linux의 glab 구성 디렉터리를 사용합니다. macOS에서는 ~/Library/Application Support/glab-cli/를 사용합니다.

3. 파일을 저장합니다.

4. IDE 또는 GitLab Duo CLI를 다시 시작합니다.

샌드박스는 서버의 env 객체에 설정한 경우에도 MCP 서버에서 자격 증명 환경 변수를 제거합니다.

MCP 서버 샌드박스 설정#

sandbox 객체는 stdio 전송을 사용하는 MCP 서버에만 적용됩니다. 다음 키를 지원합니다:

sandbox 객체를 어디에 설정하느냐에 따라 적용되는 키가 달라집니다:

• 사용자 구성: 모든 키가 적용됩니다.
• 워크스페이스 구성(.gitlab/duo/mcp.json): denyRead만 적용됩니다. 프로젝트는 서버를 제한할 수는 있지만 더 많은 접근 권한을 부여할 수는 없습니다. GitLab Duo는 나머지 키를 무시하고 경고를 기록합니다.
• 플러그인: sandbox 객체는 무시됩니다.

문제 해결#

로컬 샌드박스를 사용할 때 다음 문제가 발생할 수 있습니다.

Error: Sandbox is enabled but sandbox provider is not available (missing_dependencies)#

샌드박스가 켜져 있고 필요한 소프트웨어가 설치되어 있지 않으면 이 오류가 발생할 수 있습니다. VS Code에서는 누락된 의존성을 나열하는 경고도 표시됩니다.

이 문제를 해결하려면 사전 요구 사항을 설치한 다음 IDE 또는 GitLab Duo CLI를 다시 시작합니다.

Error: Sandbox is enabled but sandbox provider is not available (unsupported_platform)#

샌드박스가 켜져 있고 운영 체제가 지원되지 않으면 이 오류가 발생할 수 있습니다.

이 문제를 해결하려면 샌드박스를 끕니다:

• VS Code에서는 설정에서 gitlab.duoAgentPlatform.sandbox.enabled를 검색한 다음 Enable Sandboxing 확인란의 선택을 해제합니다.
• GitLab Duo CLI에서는 DUO_SANDBOX_ENABLED와 DUO_SANDBOX_CONFIG 환경 변수를 해제한 다음 --sandbox와 --sandbox-config 옵션 없이 CLI를 시작합니다.

Error: Operation is blocked by sandbox.#

에이전트 작업이 샌드박스 규칙이 차단하는 대상을 읽거나 쓰거나 연결하려고 하면 이 오류가 발생할 수 있습니다.

이 문제를 해결하려면 에이전트에 해당 접근이 필요한 경우 샌드박스 구성 파일에 규칙을 추가합니다.

MCP 서버가 시작되지 않음#

샌드박스가 켜져 있으면 다음과 같은 이유로 로컬 MCP 서버가 시작되지 않을 수 있습니다:

• 샌드박스를 시작할 수 없습니다. 오류에 Sandbox is enabled but sandbox provider is not available가 포함됩니다. 이 문제를 해결하려면 사전 요구 사항을 설치합니다.
• 서버가 샌드박스가 차단하는 파일을 읽거나 호스트에 연결합니다. 이 문제를 해결하려면 MCP 서버의 샌드박스를 구성합니다.
• 서버에 샌드박스가 제거하는 자격 증명 환경 변수(예: GITHUB_TOKEN)가 필요합니다. 이 문제를 해결하려면 서버를 신뢰하는 경우 sandbox 객체에 "sandboxEnabled": false를 설정합니다.

프로젝트 MCP 샌드박스 설정이 무시됨#

sandbox settings from this project's committed config can only narrow, not widen이 포함된 경고가 표시될 수 있습니다.

이 경고는 워크스페이스의 .gitlab/duo/mcp.json 파일이 denyRead 외의 sandbox 키를 설정할 때 발생합니다.

이 문제를 해결하려면 해당 키를 사용자 MCP 구성 파일로 옮깁니다.

GitLab 인스턴스로의 요청이 차단됨#

샌드박스 안 프로세스는 인스턴스 URL의 호스트와 포트로만 GitLab 인스턴스에 연결할 수 있습니다. 다른 포트로의 요청은 차단됩니다. 예를 들어 인스턴스 URL이 https://gitlab.example.com이면 허용되는 포트는 443이므로, 포트 80의 http://gitlab.example.com으로 보내는 요청은 차단됩니다.

이 문제를 해결하려면 인스턴스 URL과 같은 포트를 사용하거나, 호스트와 포트를 샌드박스 구성 파일의 network.allowedDomains에 추가합니다. 예를 들어 gitlab.example.com:8080을 추가합니다.