샌드박싱

Claude Code의 샌드박스된 bash 도구가 파일 시스템 및 네트워크 격리를 통해 더 안전하고 자율적인 에이전트 실행을 제공하는 방법을 알아보세요.

개요

Claude Code는 에이전트 실행을 위한 더 안전한 환경을 제공하고 지속적인 권한 프롬프트의 필요성을 줄이기 위해 네이티브 샌드박싱을 제공합니다. 각 bash 명령에 대해 권한을 요청하는 대신, 샌드박싱은 Claude Code가 위험을 줄이면서 더 자유롭게 작업할 수 있는 명확한 경계를 사전에 정의합니다.

샌드박스된 bash 도구는 OS 수준의 프리미티브를 사용하여 파일 시스템과 네트워크 격리를 모두 적용합니다.

샌드박싱이 중요한 이유

전통적인 권한 기반 보안은 bash 명령에 대해 지속적인 사용자 승인을 필요로 합니다. 이는 제어를 제공하지만 다음과 같은 문제로 이어질 수 있습니다:

승인 피로: 반복적으로 "승인"을 클릭하면 사용자가 승인하는 내용에 대한 주의력이 떨어질 수 있습니다
생산성 저하: 지속적인 중단이 개발 워크플로우를 느리게 합니다
제한된 자율성: Claude Code가 승인을 기다리는 동안 효율적으로 작업할 수 없습니다

샌드박싱은 다음과 같은 방법으로 이러한 문제를 해결합니다:

명확한 경계 정의: Claude Code가 접근할 수 있는 디렉터리와 네트워크 호스트를 정확히 지정합니다
권한 프롬프트 감소: 샌드박스 내의 안전한 명령은 승인이 필요하지 않습니다
보안 유지: 샌드박스 외부의 리소스에 접근하려는 시도는 즉시 알림을 트리거합니다
자율성 활성화: Claude Code가 정의된 한도 내에서 더 독립적으로 실행될 수 있습니다

주의: 효과적인 샌드박싱은 파일 시스템과 네트워크 격리를 모두 필요로 합니다. 네트워크 격리가 없으면 침해된 에이전트가 SSH 키와 같은 민감한 파일을 유출할 수 있습니다. 파일 시스템 격리가 없으면 침해된 에이전트가 시스템 리소스에 백도어를 설치하여 네트워크 접근 권한을 얻을 수 있습니다. 샌드박싱을 구성할 때 구성된 설정이 이러한 시스템에 우회 경로를 만들지 않도록 하는 것이 중요합니다.

작동 방식

파일 시스템 격리

샌드박스된 bash 도구는 파일 시스템 접근을 특정 디렉터리로 제한합니다:

기본 쓰기 동작: 현재 작업 디렉터리와 해당 하위 디렉터리에 대한 읽기 및 쓰기 접근
기본 읽기 동작: 특정 거부된 디렉터리를 제외한 전체 컴퓨터에 대한 읽기 접근
차단된 접근: 명시적 허가 없이 현재 작업 디렉터리 외부의 파일을 수정할 수 없음
구성 가능: 설정을 통해 사용자 정의 허용 및 거부 경로를 정의할 수 있음

설정에서 sandbox.filesystem.allowWrite를 사용하여 추가 경로에 대한 쓰기 접근 권한을 부여할 수 있습니다. 이러한 제한은 OS 수준(macOS의 Seatbelt, Linux의 bubblewrap)에서 적용되므로, Claude의 파일 도구뿐만 아니라 kubectl, terraform, npm과 같은 도구를 포함한 모든 하위 프로세스 명령에 적용됩니다.

네트워크 격리

네트워크 접근은 샌드박스 외부에서 실행되는 프록시 서버를 통해 제어됩니다:

도메인 제한: 승인된 도메인만 접근할 수 있음
사용자 확인: 새로운 도메인 요청이 권한 프롬프트를 트리거함 (allowManagedDomainsOnly가 활성화된 경우 허용되지 않은 도메인을 자동으로 차단)
사용자 정의 프록시 지원: 고급 사용자는 나가는 트래픽에 대한 사용자 정의 규칙을 구현할 수 있음
포괄적 적용: 명령으로 생성된 모든 스크립트, 프로그램 및 하위 프로세스에 제한이 적용됨

OS 수준 적용

샌드박스된 bash 도구는 운영 체제 보안 프리미티브를 활용합니다:

macOS: 샌드박스 적용에 Seatbelt 사용
Linux: 격리에 bubblewrap 사용
WSL2: Linux와 동일하게 bubblewrap 사용

WSL1은 bubblewrap이 WSL2에서만 사용 가능한 커널 기능을 필요로 하기 때문에 지원되지 않습니다.

이러한 OS 수준 제한은 Claude Code의 명령으로 생성된 모든 자식 프로세스가 동일한 보안 경계를 상속하도록 보장합니다.

시작하기

사전 요구 사항

macOS에서는 내장 Seatbelt 프레임워크를 사용하여 샌드박싱이 바로 작동합니다.

Linux 및 WSL2에서는 먼저 필요한 패키지를 설치하세요:

Ubuntu/Debian

sudo apt-get install bubblewrap socat

Fedora

sudo dnf install bubblewrap socat

샌드박싱 활성화

/sandbox 명령을 실행하여 샌드박싱을 활성화할 수 있습니다:

/sandbox

이 명령은 샌드박스 모드를 선택할 수 있는 메뉴를 엽니다. 필요한 의존성이 누락된 경우(Linux의 bubblewrap 또는 socat 등) 해당 플랫폼에 대한 설치 지침이 메뉴에 표시됩니다.

샌드박스 모드

Claude Code는 두 가지 샌드박스 모드를 제공합니다:

자동 허용 모드: Bash 명령이 샌드박스 내에서 실행을 시도하며 권한 요청 없이 자동으로 허용됩니다. 샌드박스할 수 없는 명령(허용되지 않은 호스트에 대한 네트워크 접근이 필요한 경우 등)은 일반 권한 흐름으로 대체됩니다. 구성한 명시적 허용/거부 규칙은 항상 준수됩니다.

일반 권한 모드: 모든 bash 명령이 샌드박스 내에서도 표준 권한 흐름을 거칩니다. 이는 더 많은 제어를 제공하지만 더 많은 승인이 필요합니다.

두 모드 모두 동일한 파일 시스템 및 네트워크 제한을 적용합니다. 차이점은 샌드박스된 명령이 자동 승인되는지 또는 명시적 권한이 필요한지에만 있습니다.

참고: 자동 허용 모드는 권한 모드 설정과 독립적으로 작동합니다. "편집 수락" 모드가 아니더라도 자동 허용이 활성화되면 샌드박스된 bash 명령이 자동으로 실행됩니다. 이는 파일 편집 도구가 일반적으로 승인을 필요로 하는 경우에도 샌드박스 경계 내에서 파일을 수정하는 bash 명령이 프롬프트 없이 실행됨을 의미합니다.

샌드박싱 구성

settings.json 파일을 통해 샌드박스 동작을 사용자 정의하세요. 전체 구성 참조는 설정을 확인하세요.

하위 프로세스에 특정 경로 쓰기 접근 권한 부여

기본적으로 샌드박스된 명령은 현재 작업 디렉터리에만 쓸 수 있습니다. kubectl, terraform 또는 npm과 같은 하위 프로세스 명령이 프로젝트 디렉터리 외부에 쓰기가 필요한 경우 sandbox.filesystem.allowWrite를 사용하여 특정 경로에 대한 접근 권한을 부여하세요:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "//tmp/build"]
    }
  }
}

이러한 경로는 OS 수준에서 적용되므로 자식 프로세스를 포함하여 샌드박스 내에서 실행되는 모든 명령이 이를 준수합니다. 이는 excludedCommands로 도구를 샌드박스에서 완전히 제외하는 것보다 특정 위치에 쓰기 접근이 필요한 도구에 권장되는 접근 방식입니다.

allowWrite(또는 denyWrite/denyRead)가 여러 설정 범위에서 정의된 경우 배열이 병합됩니다. 즉, 모든 범위의 경로가 대체되지 않고 결합됩니다. 예를 들어, 관리형 설정이 //opt/company-tools에 대한 쓰기를 허용하고 사용자가 개인 설정에서 ~/.kube를 추가하면 두 경로 모두 최종 샌드박스 구성에 포함됩니다. 이는 사용자와 프로젝트가 상위 우선순위 범위에서 설정된 경로를 복제하거나 재정의하지 않고도 목록을 확장할 수 있음을 의미합니다.

경로 접두사는 경로가 해석되는 방식을 제어합니다:

접두사	의미	예시
`//`	파일 시스템 루트에서의 절대 경로	`//tmp/build`는 `/tmp/build`가 됨
`~/`	홈 디렉터리 기준 상대 경로	`~/.kube`는 `$HOME/.kube`가 됨
`/`	설정 파일 디렉터리 기준 상대 경로	`/build`는 `$SETTINGS_DIR/build`가 됨
`./` 또는 접두사 없음	상대 경로 (샌드박스 런타임에 의해 해석됨)	`./output`

sandbox.filesystem.denyWrite 및 sandbox.filesystem.denyRead를 사용하여 쓰기 또는 읽기 접근을 거부할 수도 있습니다. 이는 Edit(...) 및 Read(...) 권한 규칙의 경로와 병합됩니다.

팁: 모든 명령이 기본적으로 샌드박싱과 호환되는 것은 아닙니다. 샌드박스를 최대한 활용하는 데 도움이 될 수 있는 몇 가지 참고 사항:

많은 CLI 도구는 특정 호스트에 접근해야 합니다. 이러한 도구를 사용할 때 특정 호스트에 대한 접근 권한을 요청합니다. 권한을 부여하면 현재와 이후에 이러한 호스트에 접근할 수 있어 샌드박스 내에서 안전하게 실행할 수 있습니다.

watchman은 샌드박스 내에서 실행하는 것과 호환되지 않습니다. jest를 실행하는 경우 jest --no-watchman 사용을 고려하세요

docker는 샌드박스 내에서 실행하는 것과 호환되지 않습니다. excludedCommands에 docker를 지정하여 샌드박스 외부에서 실행되도록 하는 것을 고려하세요.

참고: Claude Code에는 필요한 경우 명령이 샌드박스 외부에서 실행될 수 있도록 하는 의도적인 탈출 메커니즘이 포함되어 있습니다. 명령이 샌드박스 제한(네트워크 연결 문제나 호환되지 않는 도구 등)으로 인해 실패하면, Claude는 실패를 분석하도록 프롬프트를 받고 dangerouslyDisableSandbox 매개변수로 명령을 재시도할 수 있습니다. 이 매개변수를 사용하는 명령은 일반 Claude Code 권한 흐름을 거쳐 실행에 사용자 권한이 필요합니다. 이를 통해 Claude Code는 특정 도구나 네트워크 작업이 샌드박스 제약 내에서 작동할 수 없는 엣지 케이스를 처리할 수 있습니다.

샌드박스 설정에서 "allowUnsandboxedCommands": false를 설정하여 이 탈출 메커니즘을 비활성화할 수 있습니다. 비활성화되면 dangerouslyDisableSandbox 매개변수가 완전히 무시되며 모든 명령은 샌드박스 내에서 실행되거나 excludedCommands에 명시적으로 나열되어야 합니다.

보안 이점

프롬프트 인젝션에 대한 보호

공격자가 프롬프트 인젝션을 통해 Claude Code의 동작을 성공적으로 조작하더라도 샌드박스가 시스템의 안전을 보장합니다:

파일 시스템 보호:

~/.bashrc와 같은 중요한 설정 파일을 수정할 수 없음
/bin/에 있는 시스템 수준 파일을 수정할 수 없음
Claude 권한 설정에서 거부된 파일을 읽을 수 없음

네트워크 보호:

공격자가 제어하는 서버로 데이터를 유출할 수 없음
인가되지 않은 도메인에서 악성 스크립트를 다운로드할 수 없음
승인되지 않은 서비스에 예상치 못한 API 호출을 할 수 없음
명시적으로 허용되지 않은 도메인에 연결할 수 없음

모니터링 및 제어:

샌드박스 외부의 모든 접근 시도가 OS 수준에서 차단됨
경계가 테스트될 때 즉시 알림을 받음
거부, 한 번 허용 또는 구성을 영구적으로 업데이트하도록 선택할 수 있음

공격 표면 축소

샌드박싱은 다음으로부터의 잠재적 피해를 제한합니다:

악성 의존성: 유해한 코드가 포함된 NPM 패키지 또는 기타 의존성
침해된 스크립트: 보안 취약점이 있는 빌드 스크립트 또는 도구
소셜 엔지니어링: 사용자를 속여 위험한 명령을 실행하게 하는 공격
프롬프트 인젝션: Claude를 속여 위험한 명령을 실행하게 하는 공격

투명한 운영

Claude Code가 샌드박스 외부의 네트워크 리소스에 접근하려고 할 때:

OS 수준에서 작업이 차단됨
즉시 알림을 받음
다음을 선택할 수 있음:
- 요청 거부
- 한 번 허용
- 샌드박스 구성을 업데이트하여 영구적으로 허용

보안 제한 사항

네트워크 샌드박싱 제한 사항: 네트워크 필터링 시스템은 프로세스가 연결할 수 있는 도메인을 제한하는 방식으로 작동합니다. 프록시를 통과하는 트래픽을 별도로 검사하지 않으며, 사용자는 정책에서 신뢰할 수 있는 도메인만 허용하도록 해야 합니다.

주의: 사용자는 github.com과 같은 광범위한 도메인을 허용할 때 데이터 유출이 가능할 수 있는 잠재적 위험을 인지해야 합니다. 또한 일부 경우에는 도메인 프론팅을 통해 네트워크 필터링을 우회할 수 있습니다.

Unix 소켓을 통한 권한 상승: allowUnixSockets 구성은 의도치 않게 샌드박스 우회로 이어질 수 있는 강력한 시스템 서비스에 대한 접근을 부여할 수 있습니다. 예를 들어, /var/run/docker.sock에 대한 접근을 허용하면 docker 소켓을 악용하여 호스트 시스템에 대한 접근을 효과적으로 부여하게 됩니다. 사용자는 샌드박스를 통해 허용하는 Unix 소켓을 신중하게 고려하는 것이 좋습니다.
파일 시스템 권한 상승: 지나치게 광범위한 파일 시스템 쓰기 권한은 권한 상승 공격을 가능하게 할 수 있습니다. $PATH에 있는 실행 파일이 포함된 디렉터리, 시스템 구성 디렉터리 또는 사용자 셸 구성 파일(.bashrc, .zshrc)에 대한 쓰기를 허용하면 다른 사용자나 시스템 프로세스가 이러한 파일에 접근할 때 다른 보안 컨텍스트에서 코드 실행이 발생할 수 있습니다.
Linux 샌드박스 강도: Linux 구현은 강력한 파일 시스템 및 네트워크 격리를 제공하지만 권한이 부여된 네임스페이스 없이 Docker 환경 내에서 작동할 수 있도록 하는 enableWeakerNestedSandbox 모드를 포함합니다. 이 옵션은 보안을 상당히 약화시키며 추가 격리가 별도로 적용되는 경우에만 사용해야 합니다.

샌드박싱과 권한의 관계

샌드박싱과 권한은 함께 작동하는 상호 보완적인 보안 계층입니다:

권한은 Claude Code가 사용할 수 있는 도구를 제어하며 도구가 실행되기 전에 평가됩니다. Bash, Read, Edit, WebFetch, MCP 등 모든 도구에 적용됩니다.
샌드박싱은 Bash 명령이 파일 시스템 및 네트워크 수준에서 접근할 수 있는 것을 제한하는 OS 수준 적용을 제공합니다. Bash 명령과 해당 자식 프로세스에만 적용됩니다.

파일 시스템 및 네트워크 제한은 샌드박스 설정과 권한 규칙 모두를 통해 구성됩니다:

sandbox.filesystem.allowWrite를 사용하여 작업 디렉터리 외부 경로에 하위 프로세스 쓰기 접근 권한을 부여
sandbox.filesystem.denyWrite 및 sandbox.filesystem.denyRead를 사용하여 특정 경로에 대한 하위 프로세스 접근을 차단
Read 및 Edit 거부 규칙을 사용하여 특정 파일이나 디렉터리에 대한 접근을 차단
WebFetch 허용/거부 규칙을 사용하여 도메인 접근을 제어
샌드박스 allowedDomains를 사용하여 Bash 명령이 연결할 수 있는 도메인을 제어

sandbox.filesystem 설정과 권한 규칙의 경로가 최종 샌드박스 구성으로 함께 병합됩니다.

이 저장소에는 샌드박스 관련 예시를 포함하여 일반적인 배포 시나리오를 위한 초기 설정 구성이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정하세요.

고급 사용법

사용자 정의 프록시 구성

고급 네트워크 보안이 필요한 조직의 경우 사용자 정의 프록시를 구현하여 다음을 수행할 수 있습니다:

HTTPS 트래픽 복호화 및 검사
사용자 정의 필터링 규칙 적용
모든 네트워크 요청 로깅
기존 보안 인프라와 통합

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

기존 보안 도구와의 통합

샌드박스된 bash 도구는 다음과 함께 작동합니다:

권한 규칙: 권한 설정과 결합하여 심층 방어를 구현
개발 컨테이너: devcontainer와 함께 사용하여 추가 격리를 제공
엔터프라이즈 정책: 관리형 설정을 통해 샌드박스 구성을 적용

모범 사례

제한적으로 시작: 최소한의 권한으로 시작하고 필요에 따라 확장
로그 모니터링: 샌드박스 위반 시도를 검토하여 Claude Code의 요구 사항을 파악
환경별 구성 사용: 개발 환경과 프로덕션 컨텍스트에 서로 다른 샌드박스 규칙을 적용
권한과 결합: 포괄적인 보안을 위해 IAM 정책과 함께 샌드박싱을 사용
구성 테스트: 샌드박스 설정이 정상적인 워크플로우를 차단하지 않는지 확인

오픈 소스

샌드박스 런타임은 자체 에이전트 프로젝트에서 사용할 수 있도록 오픈 소스 npm 패키지로 제공됩니다. 이를 통해 더 넓은 AI 에이전트 커뮤니티가 더 안전하고 보안이 강화된 자율 시스템을 구축할 수 있습니다. 실행하려는 다른 프로그램을 샌드박스하는 데에도 사용할 수 있습니다. 예를 들어, MCP 서버를 샌드박스하려면 다음과 같이 실행할 수 있습니다:

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

구현 세부 사항과 소스 코드는 GitHub 저장소를 참조하세요.

제한 사항

성능 오버헤드: 최소한이지만 일부 파일 시스템 작업이 약간 느려질 수 있음
호환성: 특정 시스템 접근 패턴이 필요한 일부 도구는 구성 조정이 필요하거나 샌드박스 외부에서 실행해야 할 수 있음
플랫폼 지원: macOS, Linux 및 WSL2를 지원합니다. WSL1은 지원되지 않습니다. 네이티브 Windows 지원이 계획되어 있습니다.

샌드박싱

Claude Code의 샌드박스된 bash 도구가 파일 시스템 및 네트워크 격리를 통해 더 안전하고 자율적인 에이전트 실행을 제공하는 방법을 알아보세요.

개요

샌드박스된 bash 도구는 OS 수준의 프리미티브를 사용하여 파일 시스템과 네트워크 격리를 모두 적용합니다.

샌드박싱이 중요한 이유

전통적인 권한 기반 보안은 bash 명령에 대해 지속적인 사용자 승인을 필요로 합니다. 이는 제어를 제공하지만 다음과 같은 문제로 이어질 수 있습니다:

승인 피로: 반복적으로 "승인"을 클릭하면 사용자가 승인하는 내용에 대한 주의력이 떨어질 수 있습니다
생산성 저하: 지속적인 중단이 개발 워크플로우를 느리게 합니다
제한된 자율성: Claude Code가 승인을 기다리는 동안 효율적으로 작업할 수 없습니다

샌드박싱은 다음과 같은 방법으로 이러한 문제를 해결합니다:

명확한 경계 정의: Claude Code가 접근할 수 있는 디렉터리와 네트워크 호스트를 정확히 지정합니다
권한 프롬프트 감소: 샌드박스 내의 안전한 명령은 승인이 필요하지 않습니다
보안 유지: 샌드박스 외부의 리소스에 접근하려는 시도는 즉시 알림을 트리거합니다
자율성 활성화: Claude Code가 정의된 한도 내에서 더 독립적으로 실행될 수 있습니다

주의: 효과적인 샌드박싱은 파일 시스템과 네트워크 격리를 모두 필요로 합니다. 네트워크 격리가 없으면 침해된 에이전트가 SSH 키와 같은 민감한 파일을 유출할 수 있습니다. 파일 시스템 격리가 없으면 침해된 에이전트가 시스템 리소스에 백도어를 설치하여 네트워크 접근 권한을 얻을 수 있습니다. 샌드박싱을 구성할 때 구성된 설정이 이러한 시스템에 우회 경로를 만들지 않도록 하는 것이 중요합니다.

작동 방식

파일 시스템 격리

샌드박스된 bash 도구는 파일 시스템 접근을 특정 디렉터리로 제한합니다:

기본 쓰기 동작: 현재 작업 디렉터리와 해당 하위 디렉터리에 대한 읽기 및 쓰기 접근
기본 읽기 동작: 특정 거부된 디렉터리를 제외한 전체 컴퓨터에 대한 읽기 접근
차단된 접근: 명시적 허가 없이 현재 작업 디렉터리 외부의 파일을 수정할 수 없음
구성 가능: 설정을 통해 사용자 정의 허용 및 거부 경로를 정의할 수 있음

네트워크 격리

네트워크 접근은 샌드박스 외부에서 실행되는 프록시 서버를 통해 제어됩니다:

도메인 제한: 승인된 도메인만 접근할 수 있음
사용자 확인: 새로운 도메인 요청이 권한 프롬프트를 트리거함 (allowManagedDomainsOnly가 활성화된 경우 허용되지 않은 도메인을 자동으로 차단)
사용자 정의 프록시 지원: 고급 사용자는 나가는 트래픽에 대한 사용자 정의 규칙을 구현할 수 있음
포괄적 적용: 명령으로 생성된 모든 스크립트, 프로그램 및 하위 프로세스에 제한이 적용됨

OS 수준 적용

샌드박스된 bash 도구는 운영 체제 보안 프리미티브를 활용합니다:

macOS: 샌드박스 적용에 Seatbelt 사용
Linux: 격리에 bubblewrap 사용
WSL2: Linux와 동일하게 bubblewrap 사용

WSL1은 bubblewrap이 WSL2에서만 사용 가능한 커널 기능을 필요로 하기 때문에 지원되지 않습니다.

이러한 OS 수준 제한은 Claude Code의 명령으로 생성된 모든 자식 프로세스가 동일한 보안 경계를 상속하도록 보장합니다.

시작하기

사전 요구 사항

macOS에서는 내장 Seatbelt 프레임워크를 사용하여 샌드박싱이 바로 작동합니다.

Linux 및 WSL2에서는 먼저 필요한 패키지를 설치하세요:

Ubuntu/Debian

sudo apt-get install bubblewrap socat

Fedora

sudo dnf install bubblewrap socat

샌드박싱 활성화

/sandbox 명령을 실행하여 샌드박싱을 활성화할 수 있습니다:

/sandbox

샌드박스 모드

Claude Code는 두 가지 샌드박스 모드를 제공합니다:

일반 권한 모드: 모든 bash 명령이 샌드박스 내에서도 표준 권한 흐름을 거칩니다. 이는 더 많은 제어를 제공하지만 더 많은 승인이 필요합니다.

참고: 자동 허용 모드는 권한 모드 설정과 독립적으로 작동합니다. "편집 수락" 모드가 아니더라도 자동 허용이 활성화되면 샌드박스된 bash 명령이 자동으로 실행됩니다. 이는 파일 편집 도구가 일반적으로 승인을 필요로 하는 경우에도 샌드박스 경계 내에서 파일을 수정하는 bash 명령이 프롬프트 없이 실행됨을 의미합니다.

샌드박싱 구성

settings.json 파일을 통해 샌드박스 동작을 사용자 정의하세요. 전체 구성 참조는 설정을 확인하세요.

하위 프로세스에 특정 경로 쓰기 접근 권한 부여

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "//tmp/build"]
    }
  }
}

경로 접두사는 경로가 해석되는 방식을 제어합니다:

접두사	의미	예시
`//`	파일 시스템 루트에서의 절대 경로	`//tmp/build`는 `/tmp/build`가 됨
`~/`	홈 디렉터리 기준 상대 경로	`~/.kube`는 `$HOME/.kube`가 됨
`/`	설정 파일 디렉터리 기준 상대 경로	`/build`는 `$SETTINGS_DIR/build`가 됨
`./` 또는 접두사 없음	상대 경로 (샌드박스 런타임에 의해 해석됨)	`./output`

팁: 모든 명령이 기본적으로 샌드박싱과 호환되는 것은 아닙니다. 샌드박스를 최대한 활용하는 데 도움이 될 수 있는 몇 가지 참고 사항:

많은 CLI 도구는 특정 호스트에 접근해야 합니다. 이러한 도구를 사용할 때 특정 호스트에 대한 접근 권한을 요청합니다. 권한을 부여하면 현재와 이후에 이러한 호스트에 접근할 수 있어 샌드박스 내에서 안전하게 실행할 수 있습니다.

watchman은 샌드박스 내에서 실행하는 것과 호환되지 않습니다. jest를 실행하는 경우 jest --no-watchman 사용을 고려하세요

docker는 샌드박스 내에서 실행하는 것과 호환되지 않습니다. excludedCommands에 docker를 지정하여 샌드박스 외부에서 실행되도록 하는 것을 고려하세요.

참고: Claude Code에는 필요한 경우 명령이 샌드박스 외부에서 실행될 수 있도록 하는 의도적인 탈출 메커니즘이 포함되어 있습니다. 명령이 샌드박스 제한(네트워크 연결 문제나 호환되지 않는 도구 등)으로 인해 실패하면, Claude는 실패를 분석하도록 프롬프트를 받고 dangerouslyDisableSandbox 매개변수로 명령을 재시도할 수 있습니다. 이 매개변수를 사용하는 명령은 일반 Claude Code 권한 흐름을 거쳐 실행에 사용자 권한이 필요합니다. 이를 통해 Claude Code는 특정 도구나 네트워크 작업이 샌드박스 제약 내에서 작동할 수 없는 엣지 케이스를 처리할 수 있습니다.

샌드박스 설정에서 "allowUnsandboxedCommands": false를 설정하여 이 탈출 메커니즘을 비활성화할 수 있습니다. 비활성화되면 dangerouslyDisableSandbox 매개변수가 완전히 무시되며 모든 명령은 샌드박스 내에서 실행되거나 excludedCommands에 명시적으로 나열되어야 합니다.

보안 이점

프롬프트 인젝션에 대한 보호

공격자가 프롬프트 인젝션을 통해 Claude Code의 동작을 성공적으로 조작하더라도 샌드박스가 시스템의 안전을 보장합니다:

파일 시스템 보호:

~/.bashrc와 같은 중요한 설정 파일을 수정할 수 없음
/bin/에 있는 시스템 수준 파일을 수정할 수 없음
Claude 권한 설정에서 거부된 파일을 읽을 수 없음

네트워크 보호:

공격자가 제어하는 서버로 데이터를 유출할 수 없음
인가되지 않은 도메인에서 악성 스크립트를 다운로드할 수 없음
승인되지 않은 서비스에 예상치 못한 API 호출을 할 수 없음
명시적으로 허용되지 않은 도메인에 연결할 수 없음

모니터링 및 제어:

샌드박스 외부의 모든 접근 시도가 OS 수준에서 차단됨
경계가 테스트될 때 즉시 알림을 받음
거부, 한 번 허용 또는 구성을 영구적으로 업데이트하도록 선택할 수 있음

공격 표면 축소

샌드박싱은 다음으로부터의 잠재적 피해를 제한합니다:

악성 의존성: 유해한 코드가 포함된 NPM 패키지 또는 기타 의존성
침해된 스크립트: 보안 취약점이 있는 빌드 스크립트 또는 도구
소셜 엔지니어링: 사용자를 속여 위험한 명령을 실행하게 하는 공격
프롬프트 인젝션: Claude를 속여 위험한 명령을 실행하게 하는 공격

투명한 운영

Claude Code가 샌드박스 외부의 네트워크 리소스에 접근하려고 할 때:

OS 수준에서 작업이 차단됨
즉시 알림을 받음
다음을 선택할 수 있음:
- 요청 거부
- 한 번 허용
- 샌드박스 구성을 업데이트하여 영구적으로 허용

보안 제한 사항

네트워크 샌드박싱 제한 사항: 네트워크 필터링 시스템은 프로세스가 연결할 수 있는 도메인을 제한하는 방식으로 작동합니다. 프록시를 통과하는 트래픽을 별도로 검사하지 않으며, 사용자는 정책에서 신뢰할 수 있는 도메인만 허용하도록 해야 합니다.

주의: 사용자는 github.com과 같은 광범위한 도메인을 허용할 때 데이터 유출이 가능할 수 있는 잠재적 위험을 인지해야 합니다. 또한 일부 경우에는 도메인 프론팅을 통해 네트워크 필터링을 우회할 수 있습니다.

Unix 소켓을 통한 권한 상승: allowUnixSockets 구성은 의도치 않게 샌드박스 우회로 이어질 수 있는 강력한 시스템 서비스에 대한 접근을 부여할 수 있습니다. 예를 들어, /var/run/docker.sock에 대한 접근을 허용하면 docker 소켓을 악용하여 호스트 시스템에 대한 접근을 효과적으로 부여하게 됩니다. 사용자는 샌드박스를 통해 허용하는 Unix 소켓을 신중하게 고려하는 것이 좋습니다.
파일 시스템 권한 상승: 지나치게 광범위한 파일 시스템 쓰기 권한은 권한 상승 공격을 가능하게 할 수 있습니다. $PATH에 있는 실행 파일이 포함된 디렉터리, 시스템 구성 디렉터리 또는 사용자 셸 구성 파일(.bashrc, .zshrc)에 대한 쓰기를 허용하면 다른 사용자나 시스템 프로세스가 이러한 파일에 접근할 때 다른 보안 컨텍스트에서 코드 실행이 발생할 수 있습니다.
Linux 샌드박스 강도: Linux 구현은 강력한 파일 시스템 및 네트워크 격리를 제공하지만 권한이 부여된 네임스페이스 없이 Docker 환경 내에서 작동할 수 있도록 하는 enableWeakerNestedSandbox 모드를 포함합니다. 이 옵션은 보안을 상당히 약화시키며 추가 격리가 별도로 적용되는 경우에만 사용해야 합니다.

샌드박싱과 권한의 관계

샌드박싱과 권한은 함께 작동하는 상호 보완적인 보안 계층입니다:

권한은 Claude Code가 사용할 수 있는 도구를 제어하며 도구가 실행되기 전에 평가됩니다. Bash, Read, Edit, WebFetch, MCP 등 모든 도구에 적용됩니다.
샌드박싱은 Bash 명령이 파일 시스템 및 네트워크 수준에서 접근할 수 있는 것을 제한하는 OS 수준 적용을 제공합니다. Bash 명령과 해당 자식 프로세스에만 적용됩니다.

파일 시스템 및 네트워크 제한은 샌드박스 설정과 권한 규칙 모두를 통해 구성됩니다:

sandbox.filesystem.allowWrite를 사용하여 작업 디렉터리 외부 경로에 하위 프로세스 쓰기 접근 권한을 부여
sandbox.filesystem.denyWrite 및 sandbox.filesystem.denyRead를 사용하여 특정 경로에 대한 하위 프로세스 접근을 차단
Read 및 Edit 거부 규칙을 사용하여 특정 파일이나 디렉터리에 대한 접근을 차단
WebFetch 허용/거부 규칙을 사용하여 도메인 접근을 제어
샌드박스 allowedDomains를 사용하여 Bash 명령이 연결할 수 있는 도메인을 제어

sandbox.filesystem 설정과 권한 규칙의 경로가 최종 샌드박스 구성으로 함께 병합됩니다.

고급 사용법

사용자 정의 프록시 구성

고급 네트워크 보안이 필요한 조직의 경우 사용자 정의 프록시를 구현하여 다음을 수행할 수 있습니다:

HTTPS 트래픽 복호화 및 검사
사용자 정의 필터링 규칙 적용
모든 네트워크 요청 로깅
기존 보안 인프라와 통합

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

기존 보안 도구와의 통합

샌드박스된 bash 도구는 다음과 함께 작동합니다:

권한 규칙: 권한 설정과 결합하여 심층 방어를 구현
개발 컨테이너: devcontainer와 함께 사용하여 추가 격리를 제공
엔터프라이즈 정책: 관리형 설정을 통해 샌드박스 구성을 적용

모범 사례

제한적으로 시작: 최소한의 권한으로 시작하고 필요에 따라 확장
로그 모니터링: 샌드박스 위반 시도를 검토하여 Claude Code의 요구 사항을 파악
환경별 구성 사용: 개발 환경과 프로덕션 컨텍스트에 서로 다른 샌드박스 규칙을 적용
권한과 결합: 포괄적인 보안을 위해 IAM 정책과 함께 샌드박싱을 사용
구성 테스트: 샌드박스 설정이 정상적인 워크플로우를 차단하지 않는지 확인

오픈 소스

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

구현 세부 사항과 소스 코드는 GitHub 저장소를 참조하세요.

제한 사항

성능 오버헤드: 최소한이지만 일부 파일 시스템 작업이 약간 느려질 수 있음
호환성: 특정 시스템 접근 패턴이 필요한 일부 도구는 구성 조정이 필요하거나 샌드박스 외부에서 실행해야 할 수 있음
플랫폼 지원: macOS, Linux 및 WSL2를 지원합니다. WSL1은 지원되지 않습니다. 네이티브 Windows 지원이 계획되어 있습니다.

15. 샌드박싱

샌드박싱

개요

샌드박싱이 중요한 이유

작동 방식

파일 시스템 격리

네트워크 격리

OS 수준 적용

시작하기

사전 요구 사항

샌드박싱 활성화

샌드박스 모드

샌드박싱 구성

하위 프로세스에 특정 경로 쓰기 접근 권한 부여

보안 이점

프롬프트 인젝션에 대한 보호

공격 표면 축소

투명한 운영

보안 제한 사항

샌드박싱과 권한의 관계

고급 사용법

사용자 정의 프록시 구성

기존 보안 도구와의 통합

모범 사례

오픈 소스

제한 사항

관련 문서

15. 샌드박싱

샌드박싱

개요

샌드박싱이 중요한 이유

작동 방식

파일 시스템 격리

네트워크 격리

OS 수준 적용

시작하기

사전 요구 사항

샌드박싱 활성화

샌드박스 모드

샌드박싱 구성

하위 프로세스에 특정 경로 쓰기 접근 권한 부여

보안 이점

프롬프트 인젝션에 대한 보호

공격 표면 축소

투명한 운영

보안 제한 사항

샌드박싱과 권한의 관계

고급 사용법

사용자 정의 프록시 구성

기존 보안 도구와의 통합

모범 사례

오픈 소스

제한 사항

관련 문서