Claude Code 2.1.216 샌드박스(sandbox) 및 워크트리(worktree) 보안 체크리스트

빠른 답변

2026년 7월 20일에 출시된 Claude Code v2.1.216은 네트워크 송신(network egress) 제어는 유지하면서 Claude Code의 파일 시스템 격리(filesystem isolation)를 건너뛸 수 있는 sandbox.filesystem.disabled 설정을 추가했습니다. 동일한 릴리스에서는 워크트리(worktree)로 격리된 서브 에이전트(subagents), 심볼릭 링크(symlinked)된 .claude 경로, 되감기(rewind) 작업, 그리고 재개된 백그라운드 에이전트(background-agent) 제한과 관련된 여러 경계 실패(boundary failures) 사항을 수정했습니다.

해당 경계 보안 기능에 의존하기 전에 업그레이드하십시오. 하지만 단순히 마찰을 줄이기 위해 파일 시스템 격리를 꺼서는 안 됩니다. Anthropic의 샌드박스(sandbox) 문서에 따르면 효과적인 격리를 위해서는 파일 시스템과 네트워크 제어가 모두 필요합니다. 새로운 예외 사항은 일회용 컨테이너(disposable container)나 VM과 같은 다른 계층이 이미 파일 시스템 접근을 제한하고 있는 경우에만 사용하십시오.

다음 릴리스 게이트(release gate)를 사용하십시오:

2.1.216으로 업그레이드
-> 격리 프로필(isolation profile) 선택
-> 5가지 비파괴적 경계 테스트(non-destructive boundary tests) 실행
...

대상 사용자

이 가이드는 로컬, CI, 또는 백그라운드 에이전트(background agents)를 통해 Claude Code를 실행하는 개발자, 특히 워크트리(worktrees), 예약된 작업(scheduled tasks), 워크플로(workflows), 사용자 정의 샌드박스(sandbox) 설정 또는 장기 세션(long-lived sessions)을 사용하는 개발자를 위한 것입니다.

이 가이드는 더 광범위한 untrusted-repository 샌드박스 체크리스트를 보완합니다. 해당 가이드는 신뢰 경계(trust boundary)를 정의하며, 본 가이드는 v2.1.216에서의 구체적인 변경 사항을 검증합니다. 환경이 안전해진 후에는 출력 품질을 위해 명시적인 /verify 및 /code-review 종료 게이트(finish gate)를 사용하십시오.

변경 사항

릴리스 노트는 회귀 테스트(regression coverage)가 필요한 다섯 가지 변경 사항을 확인해 줍니다:

이러한 사항들은 Claude Code의 강제 적용 (enforcement) 및 상태 복구 (state restoration)에 대한 수정 사항입니다. 이것이 모든 명령어를 안전하게 만들거나, 암호화된 트래픽을 검사하거나, 내장된 파일 도구 (file tools)를 격리하는 것은 아닙니다. Anthropic은 샌드박싱 (sandboxing)을 Bash 및 그 자식 프로세스 (child processes)를 위한 OS 레벨의 경계 (boundary)로 문서화하고 있습니다. Read, Edit, Write, computer use, 그리고 MCP 도구들은 별도의 제어 (controls)를 가집니다.

적절한 격리 프로필 (isolation profile) 선택하기

기본 프로필의 경우, 전체 명령어를 제외하기보다는 좁은 범위의 sandbox.filesystem.allowWrite 항목을 사용하는 것을 권장합니다. 엄격한 차단 (hard gate)을 위해서는 sandbox.failIfUnavailable을 활성화하고, allowUnsandboxedCommands: false를 통해 샌드박스 미적용 탈출구 (unsandboxed escape hatch)를 비활성화하십시오.

v2.1.216에서의 호환성 프로필 (compatibility profile)은 다음과 같을 수 있습니다:

{
  "sandbox": {
    "enabled": true,
...

해당 설정을 보안 개선이 아닌, 책임의 이전 (transfer of responsibility)으로 취급하십시오. 컨테이너 (container) 또는 VM이 호스트 자격 증명 (host credentials), 셸 시작 파일 (shell startup files), 다른 리포지토리 (repositories), 그리고 배포 설정 (deployment configuration)에 대한 쓰기 작업을 방지해야 합니다.

5가지 사례 회귀 매트릭스 (Five-case regression matrix)

가짜 데이터가 포함된 일회용 리포지토리 (disposable repository)에서 테스트를 실행하십시오. 보안 피스처 (security fixture)를 실제 자격 증명이나 운영 환경의 체크아웃 (production checkout)에 연결하지 마십시오.

Claude Code 버전, 운영 체제 (operating system), 설정 범위 (settings scopes), 피스처 커밋 (fixture commit), 명령어 (commands), 프롬프트 (prompts), 종료 상태 (exit status), 표시된 프롬프트 (prompts shown), 그리고 센티넬 해시 (sentinel hashes)를 기록하십시오. 증거 없는 통과는 의도한 경로에 도달하지 못한 테스트와 구별하기 어렵습니다.

업그레이드 워크플로 (Upgrade workflow)

1. 현재 정책을 캡처하고 claude --version을 실행하십시오. 설명되지 않은 변경 사항 내에서 샌드박스 규칙을 편집하고 바이너리 (binary)를 동시에 업그레이드하지 마십시오.
2. v2.1.216 또는 그 이상의 안정적인 릴리스 (stable release)로 업그레이드한 다음, 세션을 다시 열어 새로운 코드와 설정이 로드되도록 하십시오.
3. 먼저 기본 전체 샌드박스 (full sandbox) 환경에서 5가지 피스처 (fixtures)를 실행하십시오. 도구가 호환되지 않는 경우, 파일 시스템 격리 (filesystem isolation)를 비활성화하기 전에 좁은 범위의 allowWrite 경로를 먼저 시도하십시오.
4. 호환성 예외가 불가피한 경우, 일회용 컨테이너 (disposable container) 또는 VM 내부에서 Claude Code를 실행하고, 네트워크 허용 목록 (allowlist)을 좁게 유지하며, 모든 피스처를 반복하십시오.
5. 하나의 저위험 리포지토리 (low-risk repository)에서 구성을 카나리 (Canary) 테스트하십시오. 광범위한 배포 (rollout)를 진행하기 전에 거부된 작업, 예상치 못한 프롬프트, 리포지토리 외부의 쓰기, 네트워크 목적지, 그리고 재개된 에이전트 (resumed-agent) 동작을 모니터링하십시오.

다음의 간결한 증거 기록을 사용하십시오:

Claude Code 격리 증거 (isolation evidence)
- 버전 / OS:
- 설정 범위 및 프로필 (settings scope and profile):
...

일반적인 실수 (Common mistakes)

• filesystem.disabled를 호환성을 위한 탈출구 (escape hatch)가 아닌 권장되는 기본값으로 오해하는 것.
• 네트워크 필터링을 유지하면서도 임의의 업로드된 데이터를 수신할 수 있는 광범위한 도메인을 허용하는 것.
• 실제 공유된 체크아웃 (checkout)이나 히스토리를 수정하는 명령어를 사용하여 워크트리 (worktree) 격리를 테스트하는 것.
• Bash 샌드박스 (sandbox) 규칙이 읽기 (Read), 편집 (Edit), 쓰기 (Write), 컴퓨터 사용 (computer use), 그리고 모든 MCP 도구 (tool)를 규제한다고 가정하는 것.
• 프롬프트 및 도구 제한 사항이 복구되었는지 확인하지 않고 오래된 백그라운드 세션을 재개하는 것.
• 성공적인 업그레이드를 기존의 관리되는 설정 (settings), 훅 (hooks), 컨테이너 (containers)가 여전히 안전하게 구성되어 있다는 증거로 취급하는 것.

FAQ

sandbox.filesystem.disabled를 true로 설정해야 하나요?

일반적으로는 아닙니다. 별도의 파일 시스템 경계 (filesystem boundary)가 이미 강제되고 있으며 구체적인 호환성 문제가 있는 경우에만 사용하십시오. 일반적인 로컬 개발의 경우, 파일 시스템 (filesystem) 및 네트워크 격리 (network isolation)를 모두 유지하십시오.

네트워크 격리가 모든 데이터 유출 경로를 차단하나요?

아니요. Anthropic은 내장된 프록시 (proxy)가 도메인별로 필터링하며 암호화된 트래픽을 검사하지 않는다고 명시했습니다. 광범위하게 허용된 도메인과 강력한 유닉스 소켓 (Unix sockets)은 경계를 약화시킬 수 있습니다. 위협 모델 (threat model)에서 요구하는 경우, TLS 검사 프록시 (TLS-inspecting proxy) 또는 더 강력한 외부 격리를 사용하십시오.

워크트리 (worktree) 수정 사항이 부모 저장소 (parent repository)를 자동으로 보호하나요?

해당 수정 사항은 릴리스 (release)에 명시된 특정 리디렉션 경로를 차단합니다. 여전히 관련 없는 워크트리 변경 사항, 자격 증명 (credentials), Git 설정 (configuration), 훅 (hooks), 그리고 배포 작업 (deployment actions)은 신뢰할 수 없는 에이전트 (agent)의 권한 밖에 두어야 합니다.

v2.1.216 버전이면 무인 코딩 에이전트 (unattended coding agents)를 위해 충분한가요?

이는 유용한 보안 업그레이드이지만, 완전한 무인 실행 정책 (unattended-run policy)은 아닙니다. 결정론적 테스트 (deterministic tests), 범위가 제한된 자격 증명 (scoped credentials), 네트워크 제어 (network controls), 되돌릴 수 없는 작업 게이트 (irreversible-action gate), 그리고 기록된 증거를 유지하십시오.

Sources

출처 (Sources)

• Claude Code GitHub 릴리스 v2.1.216: https://github.com/anthropics/claude-code/releases/tag/v2.1.216
• Claude Code 문서: 샌드박싱 (Sandboxing): https://code.claude.com/docs/en/sandboxing
• Claude Code 문서: 설정 (Settings): https://code.claude.com/docs/en/settings
• Claude Code 문서: 조직 설정 (Organization setup): https://code.claude.com/docs/en/admin-setup
• Claude Code 문서: 개발 컨테이너 (Development containers): https://code.claude.com/docs/en/devcontainer