클로드코드 09-sandboxing

1. Sandboxing

참고: Claude Code의 sandboxed bash tool이 파일시스템과 네트워크를 격리하여 더 안전하고 자율적인 에이전트 실행을 제공하는 방법

1.1. 개요

Claude Code의 sandboxing은 OS 수준의 파일시스템 및 네트워크 격리를 제공한다. 미리 정의된 경계를 설정하면 Claude Code가 더 자유롭게 작업하면서도 위험을 줄일 수 있다.

1.2. 왜 Sandboxing이 중요한가?

기존의 권한 기반 보안은 각 bash 명령어에 대해 사용자 승인을 요구한다. 이는 통제를 제공하지만 다음과 같은 문제를 야기한다.

- 승인 피로: 반복적으로 "승인"을 클릭하면 사용자가 무엇을 승인하는지 덜 주의하게 된다.
- 생산성 저하: 끊임없는 인터럽션이 개발 워크플로우를 느리게 한다.
- 자율성 제한: 승인을 기다려야 하므로 Claude Code가 효율적으로 작업할 수 없다.

Sandboxing은 다음으로 이 문제를 해결한다.

명확한 경계 설정: Claude Code가 접근할 수 있는 디렉토리와 네트워크 호스트를 정확히 지정
권한 프롬프트 감소: sandbox 내의 안전한 명령어는 승인 없이 실행
보안 유지: sandbox 외부 접근 시도는 즉시 알림
자율성 활성화: 정의된 한계 내에서 Claude Code가 더 독립적으로 작업

참고: 효과적인 sandboxing은 파일시스템과 네트워크 격리 둘 다 필요하다.

1.3. 작동 방식

1.3.1. 파일시스템 격리

- 기본 쓰기: 현재 작업 디렉토리와 하위 디렉토리에 대한 읽기/쓰기
- 기본 읽기: 컴퓨터 전체 읽기 (특정 거부 디렉토리 제외)
- 차단된 접근: 명시적 허가 없이 작업 디렉토리 외부 수정 불가
- 설정 가능: sandbox.filesystem.allowWrite로 추가 경로 지정

1.3.2. 네트워크 격리

- 도메인 제한: 승인된 도메인만 접근 가능
- 사용자 확인: 새로운 도메인 요청 시 권한 프롬프트
- 포괄적 커버리지: 명령어가 생성하는 모든 스크립트, 프로그램, 하위 프로세스에 적용

1.3.3. OS 수준 집행

- macOS: Seatbelt framework 사용
- Linux/WSL2: bubblewrap 사용
- WSL1: 지원하지 않음 (필요한 Linux namespace 기능 부재)
- Native Windows: 계획 중

1.4. 시작하기

1.4.1. 전제조건

macOS: 별도 설치 없이 작동한다.

Linux/WSL2:

# Ubuntu/Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

Ubuntu 24.04+: 기본 AppArmor 정책이 bubblewrap의 user namespace 생성을 차단할 수 있다.

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
sudo systemctl reload apparmor

1.4.2. 활성화

세션 중 /sandbox 명령어로 메뉴를 열어 활성화한다.

1.4.3. Sandbox 모드

Auto-allow mode: sandbox 내에서 bash 명령어를 자동으로 허가한다. sandboxing할 수 없는 명령어는 일반 권한 흐름으로 fallback한다.

Regular permissions mode: sandboxed 명령어도 표준 권한 흐름을 거친다. 더 많은 통제를 제공하지만 더 많은 승인이 필요하다.

1.5. 설정

1.5.1. 특정 경로 쓰기 허용

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

경로 접두사:

- 접두사: 의미: 예시
- /: 파일시스템 루트 기준 절대 경로: /tmp/build
- ~/: 홈 디렉토리 기준: ~/.kube
- ./ 또는 접두사 없음: 프로젝트 루트 기준: ./output

1.5.2. 읽기/쓰기 거부

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

참고: allowRead는 denyRead보다 우선한다.

1.6. 보안 이점

1.6.1. Prompt injection 방어

공격자가 prompt injection으로 Claude Code의 행동을 조작하더라도 sandbox는 시스템을 안전하게 유지한다.

- ~/.bashrc 등 중요 설정 파일 수정 불가
- /bin/ 등 시스템 파일 수정 불가
- 허가되지 않은 서버로 데이터 유출 불가
- 허가되지 않은 도메인에서 악성 스크립트 다운로드 불가

1.7. 보안 제한사항

- 네트워크 필터링: 내장 프록시는 TLS 트래픽을 종료하거나 검사하지 않는다. 도메인 기반으로만 제한한다.
- Unix 소켓: allowUnixSockets 설정이 /var/run/docker.sock 등 강력한 시스템 서비스 접근을 우회할 수 있다.
- 권한 상승: $PATH의 실행 파일 디렉토리, 시스템 설정 디렉토리, 셸 설정 파일(.bashrc) 등에 대한 쓰기 권한은 권한 상승 공격을 가능하게 할 수 있다.
- Docker 환경: enableWeakerNestedSandbox는 Docker 내부에서 작동하도록 하지만 보안을 상당히 약화시킨다.

1.8. Permission과의 관계

- Permissions: Claude Code가 어떤 도구를 사용할 수 있는지 제어. 모든 도구에 적용.
- Sandboxing: Bash 명령어와 하위 프로세스의 파일시스템/네트워크 접근을 OS 수준에서 제한. Bash에만 적용.

둘을 함께 사용하는 defense-in-depth 전략:

- Permission deny 규칙으로 제한된 리소스 접근 시도 자체를 차단
- Sandbox 제한으로 prompt injection이 Claude의 의사결정을 우회하더라도 Bash 명령어가 경계 밖에 도달하지 못하도록 방지