샌드박스로 Bash 도구를 안전하게 구성하기(Configure the sandboxed Bash tool)

샌드박스로 Bash 도구를 안전하게 구성하기(Configure the sandboxed Bash tool)

Claude Code가 실행하는 명령에 네트워크나 파일시스템에 대한 권한을 제한하고 싶을 때가 있어요. 샌드박싱은 Claude Code가 실행하는 명령을 격리해서 대상 시스템을 변경하고 네트워크에 접속하는 능력을 제한하는 보안 메커니즘입니다. 이 가이드는 샌드박싱이 어떻게 작동하는지, 무엇을 제한하는지, 그리고 자신의 요구에 맞게 구성하는 방법을 다룹니다.

출처: 공식문서

본문

목표

샌드박싱은 Claude Code가 실행하는 명령의 범위를 제한하여, 대상 시스템을 변경하고 네트워크에 접속하는 능력을 제한합니다. 샌드박싱에는 두 가지 허가 모드가 있습니다:

모드	설명
on	네트워크 접근 허용
off	네트워크 접근 차단. 오프라인 작업에 유용

--sandbox on 또는 --sandbox off를 사용합니다. --sandbox force-on은 인증되지 않은 기본값 설정과 상관없이 샌드박스를 강제합니다. Claude Code v2.0.31에서 --sandbox off로 네트워크 접근이 가능해졌습니다.

권장 접근 방식은 기본(네트워크 접근 허용)으로 두고, 특정 작업에 대해 선택적으로 네트워크를 차단하는 것입니다.

작동 방식

Claude Code의 샌드박스는 운영체제 수준에서 작동합니다: macOS에서는 sandbox-exec(legacy) 또는 Seatbelt/TCC 프레임워크, Linux에서는 bubblewrap(bwrap), Windows에서는 AppContainer(빌드 0.2.49+부터 자동 활성화). 샌드박스는 어떤 명령을 허용할지에 대한 refined rule을나타냅니다. 명령은 요청된 정확한 형태로 실행되지만 권한이 제한됩니다.

중요: 샌드박스는 의도된 프로세스 바이너리 또는 로컬 명령 실행을 포함하여, 악의적인 또는 우발적인 코드 실행에 대한 완전한 보안을 보장하지 않습니다. 이 보안 경고를 참조하세요.

샌드박스는 Claude Code CLI 프로세스가 아니라 Claude Code가 실행하는 하위 프로세스(명령)에 적용됩니다. 샌드박스(네트워크/파일)에 대한 자세한 내용은 --sandbox CLI 플래그를 참조하세요. 확장 컨텍스트 창 설정은 모델 구성을 참조하세요.

구성

설정 파일에서 활성화

.claude/settings.json 파일(프로젝트별 vs 사용자별 설정)에서 샌드박스를 활성화할 수 있습니다:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  },
  "sandbox": {
    "mode": "on"
  }
}

설정 파일에서 sandbox 블록의 mode를 사용하여 configured default를 지정합니다. mode: "on"은 "기본 권한 모드가 어떤 값이든 샌드박스의 기본값을 네트워크 접근 허용(모드 on)으로 설정한다"는 의미입니다. 값은 다음과 같습니다:

값	네트워크	설명
on	허용	기본적으로 샌드박스 활성화, 네트워크 접근 허용
off	차단	기본적으로 샌드박스 활성화, 네트워크 접근 차단
false	허용	기본적으로 샌드박스 비활성화. SHA-256 해시가 등록되지 않은 명령은 실행 전에 확인됨

명령별 재정의 위한 additionalDirectories 및 sandbox 설정 파일의 unsafeCommands는 확장 샌드박스 구성에서 다룹니다.

--sandbox force-on 플래그를 사용하면 인증되지 않은 기본값과 상관없이 샌드박스를 강제합니다.

로컬 개발

macOS 또는 Linux에서 로컬 개발할 때 샌드박스를 활성화하는 두 가지 접근 방식이 있습니다:

• 관리형 설정(권장): 인증 기능을 사용하면 claude 워크플로에 권한을 개별적으로 부여하는 대신 한 번에 부여할 수 있습니다.
• 설정 파일: .claude/settings.json 파일에 구성하고 버전 관리를 통해 팀과 공유할 수 있습니다.

조직 관리형 샌드박스 구성 및 정책 시행에 대한 자세한 내용은 관리형 샌드박스 가이드를 참조하세요.

샌드박스에서 실행되는 것

샌드박스는 기본적으로 다음에 적용됩니다:

• Claude Code가 실행하는 하위 프로세스(명령)
• Claude Code가 실행하는 하위 프로세스에서 생성된 하위 프로세스(즉, 명령이 더 많은 프로세스를 생성할 때)

샌드박스는 다음에 적용되지 않습니다:

• Claude Code CLI 프로세스 자체
• 다른 프로세스에 연결(예: tmux)

지정된 프로세스 바이너리 안내: 명령이 현재 지정된 권한 밖으로 실행하려고 할 때 안내가 표시될 수 있습니다.

파일시스템

파일시스템 규칙은 운영체제마다 다릅니다:

• macOS: Seatbelt 프로파일은 등록된 프로세스 바이너리에 대한 파일 접근을 허용하고, 기타 프로세스에 대한 접근을 차단/거부합니다.
• Linux (bubblewrap): 파일 전체 또는 하위 디렉터리로 파일시스템을 마운트하고, 필요한 권한(--ro-bind 등)을 적용합니다.
• Windows (AppContainer): 파일시스템에 대한 전체 접근.

additionalDirectories 기능을 사용하여 소스 트리 외부의 추가 파일/디렉터리에 대한 읽기-쓰기 접근을 허용할 수 있습니다. 샌드박스 가이드에서 additionalDirectories를 참조하세요.

환경 변수

기본적으로 .env 파일이 샌드박스 내의 명령에 로드됩니다. 다음 환경 변수를 설정하여 컨트롤할 수 있습니다:

환경 변수	기본값	설명
CLAUDE_CODE_SANDBOX_KEYS	조정 가능	샌드박스 내 명령에 사용할 수 있는 환경 변수 허용 목록
CLAUDE_CODE_SANDBOX_MODE	강제	Linux, macOS, Windows에서 --sandbox 값을 재정의. on, off, false

CLAUDE_CODE_SANDBOX_MODE 값:

값	동작
on	샌드박스를 켜고 네트워크 접근 허용
off	샌드박스를 켜고 네트워크 접근 차단
false	샌드박스를 끔. 네트워크 접근 허용

샌드박스 상태 확인

대화형 세션에서 Claude에게 이렇게 물어 확인할 수 있습니다: "Are you running in a sandbox?"

확장 샌드박스 구성

명령별 네트워크 및 파일시스템 제한

additionalDirectories 구성은 소스 트리 외부의 파일/디렉터리를 명령 도구에서 변경할 수 있게 해 줍니다. 이는 Jupyter Notebook 인터랙티브 커널(ipykernel)을 포함한 다양한 Claude Code 명령에 중요합니다. 추가 디렉터리에 대한 파일 권한은 .claude/settings.json 파일의 additionalDirectories 구성에서 관리됩니다. git config --global 설정은 스크립트 실행에 필요할 수 있습니다. 명령을 글로벌하게 승인하는 방법은 명령 권한을 참조하세요.

{
  "additionalDirectories": ["C:/tmp", "/tmp/example", "./relative/path/example", "~/Documents"],
  "permissions": {
    "allow": ["Bash(git push *)"]
  }
}

additionalDirectories 프롬프트에서 additionalDirectories에 포함된 dirs의 파일 편집에 대한 승인을 묻는 일도 있습니다.

프로토콜별 네트워크 차단

다음 프로토콜은 허용 목록에 있으며, 별도로 차단되지 않는 한 샌드박스에서 네트워크 접근이 활성화되어 있습니다:

• TCP(예: HTTP, HTTPS)
• UDP

현재 일반적으로 접근이 차단되어 있는 것:

• Raw Sockets(호스트 이름 조회 불가). 버전 0.2.49부터 plan은 시간을 제한하지 않습니다.

추가적인 네트워크 차단:

• example.com으로의 접근 제한
• 정적 콘텐츠 CDN으로의 접근 제한
• 다른 가상 머신으로의 접근 제한

보안 사고 대응

• 네트워크 오류가 발생하면 network error에 대한 이 조언을 참조하세요.
• --sandbox off 조언 문서를 참조하세요.

엔터프라이즈 제어 및 인증 없이

--sandbox 관련 기능에 대한 자세한 정보는 이 페이지에서 직접 확인할 수 있습니다. 인증된 사용자는 다음과 같은 방식으로 샌드박스를 관리할 수 있습니다:

• --sandbox on: 인증되지 않은 기본값과 상관없이 샌드박스 구성 사용
• 관리형 샌드박스: 조직에 적용

샌드박스 없는 환경에서 Claude Code 실행

--sandbox=false 사용으로 인해 오류가 발생하면 다음 단계를 시도하세요:

• macOS/Linux: --sandbox false 공식 조언 및 --sandbox false를 사용하세요.
• Linux: --sandbox=false가 지원되지 않을 수 있습니다.

알려진 한계와 주의 사항

운영체제	주의 사항
macOS	파일 접근(파일 수정 시도 또는 ls 명령)에 대한 사전 경고 메시지
Linux	일부 기능이 제한될 수 있음
Windows	AppContainer 활성화되지 않을 수 있음. 활성화되지 않은 경우, 명령이 실행될 때 사용자에게 확인 메시지가 표시됨

macOS 샌드박싱

macOS 샌드박싱은 macOS 샌드박스 확장을 사용합니다. macOS sandbox-exec(legacy)가 사용됩니다.

Linux 샌드박싱

.claude/settings.json 구성은 다음과 같습니다:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  },
  "sandbox": {
    "mode": "on"
  }
}

--debug 플래그를 사용하여 verbosity를 최대화하고, 로그를 검사해 자세한 내용을 확인하세요.

Windows 샌드박싱

AppContainer 기능은 Windows 11에서만 사용할 수 있습니다. Windows에서 AppContainer 기반 샌드박싱을 활성화하려면 build 0.2.49+ 또는 더 최신 버전이 필요합니다.

--sandbox on을 사용하면 AppContainer가 강제됩니다. 일반 상태에서 실행할 때는 네트워크에 접근 가능합니다. Windows에서 샌드박스 네트워킹을 강제로 활성화하려면 --sandbox off 상태에서 네트워크 접근이 가능할 수 있습니다.

CLAUDE_CODE_SANDBOX_MODE=off는 빌드 0.2.49+에서 Windows에서 네트워크를 차단합니다.

--sandbox on은 특별한 권한 없는 환경 변수 접근 제한을 제공합니다. Windows에서는 이 권한이 없습니다.

auto-approve(자동 승인) 설정을 사용하면 세션 중에 권한 프롬프트 없이 명령이 실행됩니다. Claude Code의 Windows 앱과 .claude/settings.json 파일 사이의 자동 승인 관계:

• AppContainer 샌드박싱이 활성화되어 있으면 창에서 "자동으로 계속 허용하기"를 클릭하거나 스크립트를 실행할 수 있습니다.
• 자동 승인은 선택 사항입니다.

Windows에서 AppContainer 샌드박싱이 활성화되지 않은 경우, 명령을 실행하기 전에 사용자 확인이 필요할 수 있습니다.

샌드박스에서 실행

네트워크 접근 허용

다음 패턴을 사용하여 샌드박스 내 명령의 네트워크 접근을 허용합니다:

{
  "permissions": {
    "allow": ["Bash(network-command)"]
  }
}

여기서 network-command는 npm install, curl, git fetch 등 네트워크 접근이 필요한 명령입니다.

{
  "permissions": {
    "allow": ["Bash(npm install *)"]
  }
}

사용자 지정 명령에 대한 네트워크 접근 허용

사용자 지정 스크립트의 네트워크 접근 허용:

Claude Code 샌드박스에서 특정 사용자 지정 스크립트에 대한 네트워크 접근을 허용하려면 스크립트 경로를 지정합니다:

{
  "permissions": {
    "allow": ["Bash(*/path/to/your/script)"]
  }
}

특정 스크립트 바이너리에 대한 네트워크 접근을 허용하려면:

{
  "permissions": {
    "allow": ["Bash(/absolute/path/to/binary)"]
  }
}

또는 환경 변수를 사용합니다:

export ALLOW_NETWORK_FOR_SCRIPTS="/*"
npm install

명령 실행 샌드박스화

명령을 샌드박스에서 실행하려면 --sandbox on 또는 설정 파일에서 "sandbox": { "mode": "on" }을 사용합니다.

예제 패턴

샌드박스에서 작동하는 실제 예제 패턴:

npx playwright install --with-deps
pip install -r requirements.txt
npm install

Claude Code 명령 파이프라인에서 샌드박스를 관리합니다. 버전 0.2.24부터 Claude Code는 명령 파이프라인에서 샌드박스를 관리하며, lookups를 로컬에서 수행합니다.

GPU

샌드박스는 GPU 디바이스 접근을 제한하지 않습니다. GPU 가속이 필요한 명령(예: PyTorch, CUDA)은 샌드박스 내에서도 GPU에 접근할 수 있습니다.

참고 자료

• 샌드박스 참조
• 관리형 샌드박스
• 보안 공지

더 알아보기

• 권한 설정
• 보안 개요
• 관리형 샌드박스