Claude Code 공식문서 리뷰-Deployment[8] : Sandboxing

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Deployment 섹션의 내용 중 [Sandboxing]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/sandboxing

Sandboxing - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

Claude Code 샌드박싱

• 기능: OS 수준 프리미티브를 사용한 격리 환경
• 격리 범위: 파일시스템 + 네트워크
• 적용: Linux (bubblewrap), macOS (Seatbelt)
• 활성화: /sandbox 명령

용어 설명: 샌드박싱
프로그램을 격리된 환경에서 실행하여 시스템의 다른 부분에 영향을 주지 못하도록 하는 보안 메커니즘이다. Claude Code의 샌드박싱은 파일시스템 접근과 네트워크 접근을 모두 제한한다.

 

샌드박싱이 왜 중요한가?

실제 상황을 생각해보자

Claude Code에게 "프로젝트를 빌드해줘"라고 요청했다고 가정해보자.
기존 권한 방식이라면? 매번 npm install, npm run build, rm -rf dist 같은 각 명령어마다 "이 명령어를 실행할까요?" 승인을 받아야 한다.

결과:  승인 버튼을 10번 넘게 눌러야 하고, 집중력은 떨어지고, 생산성도 떨어진다.

 

전통적인 권한 방식의 한계

문제	설명	실제 영향
승인 피로	사용자가 승인하는 내용에 덜 주의를 기울임	"또 승인이야? 그냥 다 허용하자" → 위험한 명령어도 무심코 승인
생산성 저하	지속적인 중단이 워크플로우를 느리게 함	간단한 작업도 승인 대기로 5분이 10분으로 늘어남
제한된 자율성	Claude Code가 승인을 기다리며 효율적으로 작업할 수 없음	연속 작업이 불가능 - 각 단계마다 멈춰서 승인 기다림

 

샌드박싱의 혁신적 해결 방법

"한 번만 신뢰하면, 안전하게 자유롭게"

1. 명확한 경계를 미리 정의
   "이 프로젝트 폴더 안에서만 작업하자" - 한 번 설정하면 끝
2. 안전한 작업에 대한 권한 프롬프트 감소
   프로젝트 내 파일 읽고 쓰기? 승인 없이 자동 진행
3. OS 수준 적용을 통한 보안 유지
   Linux bubblewrap / macOS Seatbelt이 시스템 레벨에서 차단
4. 정의된 한계 내에서 더 큰 자율성 활성화
   프로젝트 폴더에서는 자유롭게, 벗어나면 즉시 알림 → 최고의 균형

중요
효과적인 샌드박싱은 파일시스템과 네트워크 격리 모두 필요하다. 네트워크 격리 없이는 민감한 파일(SSH 키)이 유출될 수 있다. 파일시스템 격리 없이는 시스템 리소스가 백도어될 수 있다.

 

작동 방식

파일시스템 격리

기본 쓰기 동작:    현재 작업 디렉토리 및 하위 디렉토리에 읽기/쓰기 접근
기본 읽기 동작:    전체 컴퓨터 읽기 접근 (거부된 디렉토리 제외)
차단된 접근:       권한 없이 현재 작업 디렉토리 외부 파일 수정 불가
구성 가능:         설정을 통해 커스텀 허용/거부 경로 정의

 

네트워크 격리

• 도메인 제한: 승인된 도메인만 접근 가능
• 사용자 확인: 새 도메인 요청 시 권한 프롬프트 트리거
• 커스텀 프록시 지원: 고급 사용자는 커스텀 필터링 규칙 구현 가능
• 포괄적 범위: 모든 스크립트, 프로그램, 하위 프로세스에 제한 적용

 

OS 수준 적용

OS	적용 메커니즘
Linux	bubblewrap 사용
macOS	Seatbelt 샌드박스 적용

모든 자식 프로세스는 동일한 보안 경계를 상속한다.

 

시작하기 - 5분

1단계: 샌드박싱 활성화

프로젝트 디렉토리에서 Claude Code를 열고 다음 명령을 입력하자:

> /sandbox

샌드박스 모드를 선택하는 메뉴가 열린다.

 

2단계: 모드 선택하기

어떤 모드를 선택해야 할까?

처음 사용한다면 → "자동 허용 모드(Auto-allow mode)" 권장.
대부분의 작업이 승인 없이 진행되어 생산성이 훨씬 좋다.

샌드박스 모드

모드	설명
자동 허용 모드	Bash 명령이 권한 요청 없이 자동으로 샌드박스 내에서 실행. 허용되지 않은 호스트에 네트워크 접근이 필요한 명령은 일반 권한 플로우로 폴백
일반 권한 모드	모든 bash 명령이 표준 권한 플로우를 거침. 더 많은 제어 가능하지만 더 많은 승인 필요. 동일한 파일시스템/네트워크 제한 적용

 

호환성 참고사항

• 많은 CLI 도구가 호스트 접근을 요구함 - 요청 시 권한을 부여하여 향후 샌드박스 실행 활성화
• watchman은 샌드박싱과 호환되지 않음 - Jest에서 jest --no-watchman 사용
• docker는 호환되지 않음 - excludedCommands에 지정하여 샌드박스 외부에서 실행

 

탈출구 메커니즘

샌드박스 제한으로 실패하는 명령은 dangerouslyDisableSandbox 매개변수를 사용할 수 있다. 다음으로 비활성화:

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

 

보안 이점

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

성공적인 프롬프트 인젝션에도 샌드박스가 시스템 보안을 보장한다:

 

파일시스템 보호

• 중요 구성 파일 수정 불가 (~/.bashrc)
• 시스템 파일 수정 불가 (/bin/)
• Claude 권한 설정에서 거부된 파일 읽기 불가

 

네트워크 보호

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

 

모니터링 및 제어

• 모든 샌드박스 외부 접근 시도가 OS 수준에서 차단
• 경계 테스트 시 즉각적인 알림
• 거부, 1회 허용, 또는 구성 업데이트 선택 가능

 

공격 표면 감소

다음으로 인한 피해 제한:

• 악성 의존성
• 손상된 스크립트
• 소셜 엔지니어링
• 프롬프트 인젝션 공격

 

보안 제한사항

중요: 이러한 제한사항을 이해해야 한다

네트워크 샌드박싱 제한

• 네트워크 필터링은 허용된 도메인을 제한하여 작동 - 트래픽을 검사하지 않음
• github.com 같은 광범위한 도메인은 데이터 유출 위험
• 도메인 프론팅을 통한 필터링 우회 가능

 

Unix 소켓을 통한 권한 상승

• allowUnixSockets 구성은 강력한 시스템 서비스에 대한 접근 권한을 부여할 수 있음
• 예: /var/run/docker.sock은 Docker를 통한 호스트 시스템 접근 권한 부여
• 허용되는 모든 unix 소켓을 신중하게 고려

 

파일시스템 권한 상승

• 과도하게 넓은 쓰기 권한은 권한 상승을 가능하게 함
• 다음에 쓰기 허용 피하기:
  • $PATH에 있는 실행 파일을 포함하는 디렉토리
  • 시스템 구성 디렉토리
  • 사용자 셸 구성 파일 (.bashrc, .zshrc)

 

Linux 샌드박스 강도

• Linux는 강력한 파일시스템/네트워크 격리 제공
• enableWeakerNestedSandbox 모드는 권한 있는 네임스페이스 없이 Docker 호환성 활성화
• 보안을 상당히 약화시킴 - 추가 격리와 함께만 사용

 

고급 사용법

커스텀 프록시 구성

고급 네트워크 보안을 위해 커스텀 프록시 구현:

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

활성화 기능:

• HTTPS 트래픽 복호화 및 검사
• 커스텀 필터링 규칙
• 네트워크 요청 로깅
• 엔터프라이즈 보안 인프라 통합

 

기존 보안 도구와 통합

도구	설명
IAM 정책	권한 설정 - 심층 방어
개발 컨테이너	devcontainers - 추가 격리
엔터프라이즈 정책	관리 설정을 통한 샌드박스 구성 적용

 

모범 사례

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

 

오픈 소스

샌드박스 런타임은 npm 패키지로 제공된다:

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

다른 프로그램(예: MCP 서버)도 샌드박스할 수 있다. 구현 세부 사항은 GitHub 저장소를 참조한다.

 

제한사항

제한	설명
성능 오버헤드	최소, 일부 파일시스템 작업이 약간 느려질 수 있음
호환성	특정 시스템 접근 패턴이 필요한 일부 도구는 구성 조정 필요
플랫폼 지원	Linux와 macOS 지원, Windows 지원 계획 중

 

관련 문서 - 더 알아보기

샌드박싱을 더 깊이 이해하고 효과적으로 활용하려면 다음 문서들을 참고하자.

문서	언제 유용한가?
보안	이런 경우 유용: 샌드박싱 외 다른 보안 기능도 알고 싶을 때 전체 보안 아키텍처를 이해하고 싶을 때 다층 보안 전략을 수립할 때 핵심 내용: IAM, 권한, 감사 로깅, 보안 모범 사례
IAM	이런 경우 유용: 샌드박싱과 IAM 정책을 함께 사용하고 싶을 때 팀별로 다른 권한을 부여하고 싶을 때 세밀한 접근 제어가 필요할 때 핵심 내용: 권한 구성, 역할 기반 접근 제어, 심층 방어
설정 레퍼런스	이런 경우 유용: 샌드박스 설정을 커스터마이징하고 싶을 때 특정 디렉토리나 도메인 예외를 추가할 때 고급 옵션을 찾고 있을 때 핵심 내용: allowWrite, denyRead, allowedDomains, excludedCommands
CLI 레퍼런스	이런 경우 유용: CLI에서 샌드박스를 직접 제어하고 싶을 때 스크립트로 샌드박스 활성화를 자동화할 때 -sb 플래그 같은 명령줄 옵션이 궁금할 때 핵심 내용: CLI 옵션, 플래그, 자동화 스크립트 예시

 

빠른 시작 체크리스트

샌드박싱 도입을 위한 단계별 가이드

다음 체크리스트를 따라하면 5분 안에 샌드박싱을 시작할 수 있다.

단계 1: 기본 설정 (필수)

1. ☐ 프로젝트 디렉토리에서 Claude Code 열기
2. ☐ /sandbox 명령 실행
3. ☐ "자동 허용 모드(Auto-allow mode)" 선택 (권장)
4. ☐ 첫 명령어 실행해보기 (예: "간단한 파일 만들어줘")

단계 2: 이해하기

1. ☐ 격리 범위 확인: 파일시스템 + 네트워크 양쪽 모두
2. ☐ 기본 규칙 이해: 현재 프로젝트 폴더는 읽기/쓰기 자유, 외부는 승인 필요
3. ☐ OS 적용 확인: Linux(bubblewrap) 또는 macOS(Seatbelt) 사용 중
4. ☐ 제한사항 숙지: Windows는 아직 미지원, 일부 도구 호환성 이슈 존재

단계 3: 호환성 확인 (선택)

1. ☐ Jest 사용 시: --no-watchman 플래그 추가
2. ☐ Docker 사용 시: 설정에서 excludedCommands에 "docker" 추가
3. ☐ 프록시 설정이 필요하면 httpProxyPort, socksProxyPort 설정

단계 4: 고급 설정 (필요 시)

1. ☐ IAM 정책과 함께 사용하여 심층 방어 구현
2. ☐ devcontainer에서 실행하여 추가 격리 계층 적용
3. ☐ 설정 파일에서 커스텀 허용/거부 경로 정의
4. ☐ 샌드박스 위반 시도 로그 모니터링 설정

다음 단계

기본 설정만으로도 충분하지만, 더 깊이 알고 싶다면:
보안 문서에서 전체 보안 아키텍처 확인
설정 레퍼런스에서 상세 옵션 탐색
모범 사례 섹션 다시 읽기

핵심 요약

활성화:	/sandbox 명령
격리 범위:	파일시스템 + 네트워크 (양쪽 모두 필수!)
권장 모드:	자동 허용 모드 (처음 사용자에게 최적)
OS 지원:	Linux, macOS (Windows 계획 중)
핵심 이점:	승인 피로 감소 + 생산성 향상 + 보안 유지