​
개요

Claude Code는 에이전트 실행을 위한 더 안전한 환경을 제공하고 지속적인 권한 프롬프트의 필요성을 줄이기 위해 기본 샌드박싱 기능을 제공합니다. 각 bash 명령에 대해 권한을 요청하는 대신, 샌드박싱은 Claude Code가 위험을 줄이면서 더 자유롭게 작업할 수 있는 정의된 경계를 미리 생성합니다. 샌드박싱된 bash 도구는 OS 수준의 기본 요소를 사용하여 파일시스템 및 네트워크 격리를 모두 적용합니다.

​
샌드박싱이 중요한 이유

기존의 권한 기반 보안은 bash 명령에 대한 지속적인 사용자 승인이 필요합니다. 이는 제어를 제공하지만 다음과 같은 문제로 이어질 수 있습니다:
  • 승인 피로: “승인”을 반복적으로 클릭하면 사용자가 승인하는 내용에 덜 주의를 기울이게 될 수 있습니다
  • 생산성 감소: 지속적인 중단으로 인해 개발 워크플로우가 느려집니다
  • 제한된 자율성: Claude Code는 승인을 기다릴 때 효율적으로 작업할 수 없습니다
샌드박싱은 다음을 통해 이러한 문제를 해결합니다:
  1. 명확한 경계 정의: Claude Code가 액세스할 수 있는 정확한 디렉토리 및 네트워크 호스트 지정
  2. 권한 프롬프트 감소: 샌드박스 내의 안전한 명령은 승인이 필요하지 않습니다
  3. 보안 유지: 샌드박스 외부의 리소스에 액세스하려는 시도는 즉시 알림을 트리거합니다
  4. 자율성 활성화: Claude Code는 정의된 제한 내에서 더 독립적으로 실행할 수 있습니다
효과적인 샌드박싱은 파일시스템 및 네트워크 격리 모두가 필요합니다. 네트워크 격리가 없으면 손상된 에이전트가 SSH 키와 같은 민감한 파일을 유출할 수 있습니다. 파일시스템 격리가 없으면 손상된 에이전트가 시스템 리소스를 백도어하여 네트워크 액세스를 얻을 수 있습니다. 샌드박싱을 구성할 때 구성된 설정이 이러한 시스템에서 우회를 생성하지 않도록 하는 것이 중요합니다.

​
작동 방식

​
파일시스템 격리

샌드박싱된 bash 도구는 파일 시스템 액세스를 특정 디렉토리로 제한합니다:
  • 기본 쓰기 동작: 현재 작업 디렉토리 및 해당 하위 디렉토리에 대한 읽기 및 쓰기 액세스
  • 기본 읽기 동작: 특정 거부된 디렉토리를 제외한 전체 컴퓨터에 대한 읽기 액세스
  • 차단된 액세스: 명시적 권한 없이 현재 작업 디렉토리 외부의 파일을 수정할 수 없습니다
  • 구성 가능: 설정을 통해 사용자 정의 허용 및 거부 경로 정의

​
네트워크 격리

네트워크 액세스는 샌드박스 외부에서 실행되는 프록시 서버를 통해 제어됩니다:
  • 도메인 제한: 승인된 도메인만 액세스할 수 있습니다
  • 사용자 확인: 새 도메인 요청은 권한 프롬프트를 트리거합니다
  • 사용자 정의 프록시 지원: 고급 사용자는 나가는 트래픽에 대한 사용자 정의 규칙을 구현할 수 있습니다
  • 포괄적 범위: 제한 사항은 명령으로 생성된 모든 스크립트, 프로그램 및 하위 프로세스에 적용됩니다

​
OS 수준 적용

샌드박싱된 bash 도구는 운영 체제 보안 기본 요소를 활용합니다:
  • Linux: 격리를 위해 bubblewrap을 사용합니다
  • macOS: 샌드박스 적용을 위해 Seatbelt를 사용합니다
이러한 OS 수준의 제한 사항은 Claude Code의 명령으로 생성된 모든 자식 프로세스가 동일한 보안 경계를 상속하도록 보장합니다.

​
시작하기

​
샌드박싱 활성화

/sandbox 슬래시 명령을 실행하여 샌드박싱을 활성화할 수 있습니다: 
> /sandbox
이는 기본 설정으로 샌드박싱된 bash 도구를 활성화하여 현재 작업 디렉토리에 대한 액세스를 허용하면서 민감한 시스템 위치에 대한 액세스를 차단합니다.

​
샌드박싱 구성

settings.json 파일을 통해 샌드박스 동작을 사용자 정의합니다. 전체 구성 참조는 설정을 참조하세요.
패턴 지원:
  • 경로는 절대 경로(/home/user), 상대 경로(./src), 홈 디렉토리(~) 및 와일드카드(**/*.json)를 지원합니다
  • 도메인은 정확한 일치(github.com), 와일드카드(*.npmjs.org) 및 하위 도메인을 지원합니다

​
보안 이점

​
프롬프트 주입으로부터의 보호

공격자가 프롬프트 주입을 통해 Claude Code의 동작을 성공적으로 조작하더라도 샌드박스는 시스템이 안전하게 유지되도록 보장합니다: 파일시스템 보호:
  • ~/.bashrc와 같은 중요한 구성 파일을 수정할 수 없습니다
  • /bin/의 시스템 수준 파일을 수정할 수 없습니다
  • Claude 권한 설정에서 거부된 파일을 읽을 수 없습니다
네트워크 보호:
  • 공격자가 제어하는 서버로 데이터를 유출할 수 없습니다
  • 승인되지 않은 도메인에서 악성 스크립트를 다운로드할 수 없습니다
  • 승인되지 않은 서비스에 예상치 못한 API 호출을 할 수 없습니다
  • 명시적으로 허용되지 않은 도메인에 연락할 수 없습니다
모니터링 및 제어:
  • 샌드박스 외부의 모든 액세스 시도는 OS 수준에서 차단됩니다
  • 경계가 테스트될 때 즉시 알림을 받습니다
  • 거부, 한 번만 허용 또는 구성을 영구적으로 업데이트하도록 선택할 수 있습니다

​
공격 표면 감소

샌드박싱은 다음으로 인한 잠재적 피해를 제한합니다:
  • 악성 종속성: 해로운 코드가 있는 NPM 패키지 또는 기타 종속성
  • 손상된 스크립트: 보안 취약점이 있는 빌드 스크립트 또는 도구
  • 사회 공학: 사용자를 속여 위험한 명령을 실행하도록 하는 공격
  • 프롬프트 주입: Claude를 속여 위험한 명령을 실행하도록 하는 공격

​
투명한 작동

Claude Code가 샌드박스 외부의 네트워크 리소스에 액세스하려고 시도할 때:
  1. 작업이 OS 수준에서 차단됩니다
  2. 즉시 알림을 받습니다
  3. 다음 중 하나를 선택할 수 있습니다:
    • 요청 거부
    • 한 번만 허용
    • 샌드박스 구성을 업데이트하여 영구적으로 허용

​
보안 제한 사항

  • 네트워크 샌드박싱 제한 사항: 네트워크 필터링 시스템은 프로세스가 연결할 수 있는 도메인을 제한하여 작동합니다. 프록시를 통과하는 트래픽을 검사하지 않으며 사용자는 정책에서 신뢰할 수 있는 도메인만 허용하도록 해야 합니다.
사용자는 데이터 유출을 허용할 수 있는 github.com과 같은 광범위한 도메인을 허용하는 것과 관련된 잠재적 위험을 인식해야 합니다. 또한 경우에 따라 도메인 프론팅을 통해 네트워크 필터링을 우회할 수 있습니다.
  • Unix 소켓을 통한 권한 상승: allowUnixSockets 구성은 샌드박스 우회로 이어질 수 있는 강력한 시스템 서비스에 대한 액세스를 실수로 부여할 수 있습니다. 예를 들어, /var/run/docker.sock에 대한 액세스를 허용하는 데 사용되는 경우 docker 소켓을 악용하여 호스트 시스템에 대한 액세스를 효과적으로 부여합니다. 사용자는 샌드박스를 통해 허용하는 모든 unix 소켓을 신중하게 고려하는 것이 좋습니다.
  • 파일시스템 권한 상승: 과도하게 광범위한 파일시스템 쓰기 권한은 권한 상승 공격을 가능하게 할 수 있습니다. $PATH의 실행 파일을 포함하는 디렉토리, 시스템 구성 디렉토리 또는 사용자 셸 구성 파일(.bashrc, .zshrc)에 대한 쓰기를 허용하면 다른 사용자 또는 시스템 프로세스가 이러한 파일에 액세스할 때 다른 보안 컨텍스트에서 코드 실행으로 이어질 수 있습니다.
  • Linux 샌드박스 강도: Linux 구현은 강력한 파일시스템 및 네트워크 격리를 제공하지만 권한이 있는 네임스페이스 없이 Docker 환경 내에서 작동하도록 하는 enableWeakerNestedSandbox 모드를 포함합니다. 이 옵션은 보안을 상당히 약화시키며 추가 격리가 다른 방식으로 적용되는 경우에만 사용해야 합니다.

​
고급 사용법

​
사용자 정의 프록시 구성

고급 네트워크 보안이 필요한 조직의 경우 사용자 정의 프록시를 구현하여 다음을 수행할 수 있습니다:
  • HTTPS 트래픽 복호화 및 검사
  • 사용자 정의 필터링 규칙 적용
  • 모든 네트워크 요청 로깅
  • 기존 보안 인프라와 통합
{
  "sandbox": {
    "httpProxyPort": 8080,
    "socksProxyPort": 8081,
  }
}

​
기존 보안 도구와의 통합

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

​
모범 사례

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

​
오픈 소스

샌드박스 런타임은 자신의 에이전트 프로젝트에서 사용할 수 있는 오픈 소스 npm 패키지로 제공됩니다. 이를 통해 더 넓은 AI 에이전트 커뮤니티가 더 안전하고 보안이 강화된 자율 시스템을 구축할 수 있습니다. 이는 실행하려는 다른 프로그램을 샌드박싱하는 데도 사용할 수 있습니다. 예를 들어, MCP 서버를 샌드박싱하려면 다음을 실행할 수 있습니다: 
npx @anthropic-ai/sandbox-runtime <command-to-sandbox>
구현 세부 사항 및 소스 코드는 GitHub 저장소를 방문하세요.

​
제한 사항

  • 성능 오버헤드: 최소이지만 일부 파일시스템 작업이 약간 느릴 수 있습니다
  • 호환성: 특정 시스템 액세스 패턴이 필요한 일부 도구는 구성 조정이 필요할 수 있으며, 심지어 샌드박스 외부에서 실행해야 할 수도 있습니다
  • 플랫폼 지원: 현재 Linux 및 macOS를 지원합니다. Windows 지원은 계획 중입니다

​
참고 항목

  • 보안 - 포괄적인 보안 기능 및 모범 사례
  • IAM - 권한 구성 및 액세스 제어
  • 설정 - 전체 구성 참조
  • CLI 참조 - -sb를 포함한 명령줄 옵션