Gemini CLI의 샌드박싱

이 문서에서는 전제 조건, 빠른 시작 및 구성을 포함한 Gemini CLI의 샌드박싱 가이드를 제공합니다.

전제 조건

샌드박싱을 사용하기 전에 Gemini CLI를 설치하고 설정해야 합니다:

npm install -g @google/gemini-cli

설치를 확인하려면:

gemini --version

샌드박싱 개요

샌드박싱은 위험할 수 있는 작업(예: 셸 명령 또는 파일 수정)을 호스트 시스템에서 격리하여 AI 작업과 환경 사이에 보안 장벽을 제공합니다.

샌드박싱의 이점은 다음과 같습니다:

보안: 우발적인 시스템 손상이나 데이터 손실을 방지합니다.
격리: 파일 시스템 액세스를 프로젝트 디렉터리로 제한합니다.
일관성: 서로 다른 시스템에서 재현 가능한 환경을 보장합니다.
안전성: 신뢰할 수 없는 코드나 실험적인 명령으로 작업할 때 위험을 줄입니다.

샌드박싱 방법

이상적인 샌드박싱 방법은 플랫폼과 선호하는 컨테이너 솔루션에 따라 다를 수 있습니다.

1. macOS Seatbelt (macOS 전용)

sandbox-exec를 사용하는 가볍고 내장된 샌드박싱입니다.

기본 프로필: permissive-open - 프로젝트 디렉터리 외부 쓰기를 제한하지만 대부분의 다른 작업은 허용합니다.

2. 컨테이너 기반 (Docker/Podman)

완전한 프로세스 격리를 제공하는 크로스 플랫폼 샌드박싱입니다.

참고: 샌드박스 이미지를 로컬에서 빌드하거나 조직의 레지스트리에 게시된 이미지를 사용해야 합니다.

빠른 시작

# 명령 플래그로 샌드박싱 활성화
gemini -s -p "analyze the code structure"
 
# 환경 변수 사용
export GEMINI_SANDBOX=true
gemini -p "run the test suite"
 
# settings.json에서 구성
{
  "tools": {
    "sandbox": "docker"
  }
}

구성

샌드박싱 활성화 (우선순위 순)

명령 플래그: -s 또는 --sandbox
환경 변수: GEMINI_SANDBOX=true|docker|podman|sandbox-exec
설정 파일: settings.json 파일의 tools 객체에 "sandbox": true 설정 (예: {"tools": {"sandbox": true}}).

macOS Seatbelt 프로필

내장 프로필 (SEATBELT_PROFILE 환경 변수로 설정):

permissive-open (기본값): 쓰기 제한, 네트워크 허용
permissive-closed: 쓰기 제한, 네트워크 없음
permissive-proxied: 쓰기 제한, 프록시를 통한 네트워크
restrictive-open: 엄격한 제한, 네트워크 허용
restrictive-closed: 최대 제한

사용자 지정 샌드박스 플래그

컨테이너 기반 샌드박싱의 경우 SANDBOX_FLAGS 환경 변수를 사용하여 사용자 지정 플래그를 docker 또는 podman 명령에 주입할 수 있습니다. 이는 특정 사용 사례에 대해 보안 기능을 비활성화하는 등 고급 구성을 위해 유용합니다.

예시 (Podman):

볼륨 마운트에 대한 SELinux 레이블링을 비활성화하려면 다음과 같이 설정할 수 있습니다:

export SANDBOX_FLAGS="--security-opt label=disable"

여러 플래그는 공백으로 구분된 문자열로 제공할 수 있습니다:

export SANDBOX_FLAGS="--flag1 --flag2=value"

Linux UID/GID 처리

샌드박스는 Linux에서 사용자 권한을 자동으로 처리합니다. 다음을 사용하여 이 권한을 재정의하세요:

export SANDBOX_SET_UID_GID=true   # 호스트 UID/GID 강제 설정
export SANDBOX_SET_UID_GID=false  # UID/GID 매핑 비활성화

문제 해결

일반적인 문제

"Operation not permitted" (작업이 허용되지 않음)

작업이 샌드박스 외부 액세스를 필요로 합니다.
더 관대한 프로필을 시도하거나 마운트 지점을 추가하세요.

명령 누락

사용자 지정 Dockerfile에 추가하세요.
sandbox.bashrc를 통해 설치하세요.

네트워크 문제

샌드박스 프로필이 네트워크를 허용하는지 확인하세요.
프록시 구성을 확인하세요.

디버그 모드

DEBUG=1 gemini -s -p "debug command"

참고: 프로젝트의 .env 파일에 DEBUG=true가 있어도 자동 제외로 인해 gemini-cli에는 영향을 미치지 않습니다. gemini-cli 관련 디버그 설정에는 .gemini/.env 파일을 사용하세요.

샌드박스 검사

# 환경 확인
gemini -s -p "run shell command: env | grep SANDBOX"
 
# 마운트 목록
gemini -s -p "run shell command: mount | grep workspace"

보안 참고 사항

샌드박싱은 위험을 줄여주지만 모든 위험을 제거하지는 않습니다.
작업을 허용하는 가장 제한적인 프로필을 사용하세요.
컨테이너 오버헤드는 첫 번째 빌드 후에는 최소화됩니다.
GUI 애플리케이션은 샌드박스에서 작동하지 않을 수 있습니다.