읽는 시간: 8분 | 난이도: 중급자

Claude Code는 에이전트 실행을 위한 더 안전한 환경을 제공하는 네이티브 샌드박싱 기능을 지원합니다. 샌드박싱은 bash 명령마다 허가를 요청하는 대신, 사전에 명확한 경계를 정의하여 Claude Code가 그 범위 내에서 자유롭게 작업할 수 있도록 합니다.

샌드박싱이 필요한 이유

기존 권한 기반 보안 방식은 bash 명령마다 사용자 승인을 요구합니다. 이는 제어력을 제공하지만 다음과 같은 문제를 야기합니다:

• 승인 피로: 반복적인 클릭으로 인해 사용자가 승인 내용에 덜 주의를 기울이게 됩니다
• 생산성 저하: 지속적인 인터럽트가 개발 워크플로우를 느리게 만듭니다
• 제한된 자율성: 승인을 기다리는 동안 Claude Code가 효율적으로 작업할 수 없습니다

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

1. 명확한 경계 정의: Claude Code가 접근할 수 있는 디렉토리와 네트워크 호스트를 정확히 지정
2. 권한 프롬프트 감소: 샌드박스 내의 안전한 명령은 승인 불필요
3. 보안 유지: 샌드박스 외부 리소스 접근 시도 시 즉시 알림
4. 자율성 활성화: 정의된 범위 내에서 더 독립적으로 작업 가능

경고: 효과적인 샌드박싱은 파일시스템과 네트워크 격리 모두를 필요로 합니다. 네트워크 격리 없이는 공격받은 에이전트가 SSH 키 같은 민감한 파일을 외부로 유출할 수 있습니다. 파일시스템 격리 없이는 시스템 리소스를 백도어로 활용해 네트워크 접근을 얻을 수 있습니다.

동작 원리

파일시스템 격리

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

• 기본 쓰기 동작: 현재 작업 디렉토리와 하위 디렉토리에 읽기/쓰기 접근
• 기본 읽기 동작: 일부 거부된 디렉토리를 제외한 전체 컴퓨터에 읽기 접근
• 차단된 접근: 명시적 권한 없이 현재 작업 디렉토리 외부의 파일 수정 불가
• 설정 가능: 설정을 통해 허용/거부 경로를 커스터마이징 가능

네트워크 격리

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

• 도메인 제한: 승인된 도메인에만 접근 가능
• 사용자 확인: 새 도메인 요청 시 권한 프롬프트 표시
• 커스텀 프록시 지원: 고급 사용자는 발신 트래픽에 커스텀 규칙 적용 가능
• 포괄적 적용: 명령이 생성한 모든 스크립트, 프로그램, 서브프로세스에 제한 적용

OS 수준 적용

샌드박스 bash 도구는 운영 체제 보안 기능을 활용합니다:

참고: WSL1은 bubblewrap에 필요한 커널 기능이 없어 지원되지 않습니다.

시작하기

사전 요구사항

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 명령은 자동으로 실행됩니다.

샌드박싱 설정

settings.json 파일을 통해 샌드박스 동작을 커스터마이징합니다:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "npmjs.com"],
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    },
    "allowUnsandboxedCommands": false,
    "excludedCommands": ["docker"]
  }
}

보안 이점

프롬프트 인젝션으로부터 보호

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

파일시스템 보호:

• ~/.bashrc와 같은 중요한 설정 파일 수정 불가
• /bin/의 시스템 파일 수정 불가
• Claude 권한 설정에서 거부된 파일 읽기 불가

네트워크 보호:

• 공격자 제어 서버로 데이터 유출 불가
• 승인되지 않은 도메인에서 악성 스크립트 다운로드 불가
• 승인되지 않은 서비스에 예상치 못한 API 호출 불가

모니터링 및 제어:

• 샌드박스 외부의 모든 접근 시도는 OS 수준에서 차단됩니다
• 경계가 테스트될 때 즉시 알림을 받습니다
• 거부, 한 번 허용, 또는 설정을 영구적으로 업데이트할 수 있습니다

공격 표면 감소

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

• 악성 의존성: 해로운 코드가 있는 NPM 패키지 등
• 손상된 스크립트: 보안 취약점이 있는 빌드 스크립트나 도구
• 사회공학: 사용자를 속여 위험한 명령을 실행하도록 유도하는 공격
• 프롬프트 인젝션: Claude를 속여 위험한 명령을 실행하도록 하는 공격

보안 제한사항

샌드박싱을 사용할 때 알아야 할 중요한 제한사항들이 있습니다:

네트워크 샌드박싱 제한: 네트워크 필터링 시스템은 프로세스가 연결할 수 있는 도메인을 제한하지만, 프록시를 통과하는 트래픽을 검사하지는 않습니다. 신뢰할 수 있는 도메인만 허용하도록 주의하세요.

주의: github.com과 같이 광범위한 도메인을 허용하면 데이터 유출 위험이 있습니다. 또한 일부 경우에는 도메인 프론팅(domain fronting)을 통해 네트워크 필터링을 우회할 수 있습니다.

Unix 소켓을 통한 권한 상승: allowUnixSockets 설정은 강력한 시스템 서비스에 대한 접근을 허용해 샌드박스 우회로 이어질 수 있습니다. 예를 들어 /var/run/docker.sock에 접근을 허용하면 도커 소켓을 통해 호스트 시스템에 접근할 수 있게 됩니다.

파일시스템 권한 상승: 과도하게 넓은 파일시스템 쓰기 권한은 권한 상승 공격을 가능하게 합니다. $PATH의 실행 파일이 있는 디렉토리, 시스템 설정 디렉토리, 또는 사용자 쉘 설정 파일(.bashrc, .zshrc)에 대한 쓰기를 허용하지 마세요.

샌드박싱과 권한의 관계

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

• 권한(Permissions): Claude Code가 사용할 수 있는 도구를 제어하며, 도구 실행 전에 평가됩니다. Bash, Read, Edit, WebFetch, MCP 등 모든 도구에 적용됩니다.
• 샌드박싱: bash 명령이 파일시스템과 네트워크 수준에서 접근할 수 있는 것을 OS 수준에서 제한합니다. bash 명령과 그 하위 프로세스에만 적용됩니다.

파일시스템과 네트워크 제한은 샌드박스 설정이 아닌 권한 규칙을 통해 설정합니다:

• Read 및 Edit 거부 규칙으로 특정 파일이나 디렉토리 접근 차단
• WebFetch 허용/거부 규칙으로 도메인 접근 제어
• 샌드박스 allowedDomains로 bash 명령이 접근할 수 있는 도메인 제어

고급 사용법

커스텀 프록시 설정

고급 네트워크 보안이 필요한 조직을 위해 커스텀 프록시를 구현할 수 있습니다:

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

커스텀 프록시로 가능한 것들:

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

탈출 구멍(Escape Hatch) 메커니즘

Claude Code는 필요할 때 명령을 샌드박스 외부에서 실행할 수 있는 의도적인 탈출 구멍 메커니즘을 포함합니다. 명령이 샌드박스 제한으로 실패하면, Claude는 실패를 분석하고 dangerouslyDisableSandbox 파라미터로 명령을 재시도할 수 있습니다.

이 탈출 구멍을 비활성화하려면 샌드박스 설정에서 allowUnsandboxedCommands를 false로 설정하세요:

{
  "sandbox": {
    "allowUnsandboxedCommands": false
  }
}

모범 사례

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

제한사항

• 성능 오버헤드: 최소화되어 있지만 일부 파일시스템 작업이 약간 느릴 수 있습니다
• 호환성: 특정 시스템 접근 패턴이 필요한 일부 도구는 설정 조정이 필요할 수 있습니다
• 플랫폼 지원: macOS, Linux, WSL2 지원. WSL1은 지원되지 않습니다. Windows 네이티브 지원은 계획 중입니다.

오픈 소스

샌드박스 런타임은 오픈 소스 npm 패키지로 제공되어 자체 에이전트 프로젝트에서 사용할 수 있습니다. MCP 서버를 샌드박싱하는 예시:

npx @anthropic-ai/sandbox-runtime <샌드박싱할-명령>

다음 단계

• 보안 가이드 — 포괄적인 보안 기능 및 모범 사례
• 권한 설정 — 권한 설정 및 접근 제어
• 설정 파일 가이드 — 전체 설정 옵션 참조
• 개발 컨테이너 — 추가 격리를 위한 devcontainer 사용