A sandbox is only useful if it actually keeps the agent inside the fence. Claude Code 2.1.216 tightens several gaps that could let a background task, subagent, or resumed session wander outside its assigned directory. This release introduces a new configuration switch, but the more important work is under the hood: smarter handling of Git worktrees, symlinks, and agent restarts. If you run Claude Code locally or in CI, these changes deserve more than a quick skim of the changelog.

함부로 건드려서는 안 될 파일 시스템 토글

Version 2.1.216에는 sandbox.filesystem.disabled가 추가되었습니다. 이 설정이 활성화되면 Claude Code는 네트워크 샌드박스는 유지하면서 자체 파일 시스템 격리는 건너뜁니다. 언뜻 보기에는 권한 오류를 방지하거나 파일 작업을 가속화하는 방법처럼 보일 수 있습니다. 하지만 그렇지 않습니다. 이 설정은 다른 계층에서 이미 디스크를 보호하고 있는 경우에만 활성화해야 합니다.

즉, 실행 후 삭제되는 일회성 컨테이너나 홈 디렉터리 또는 프로덕션 볼륨에 접근할 수 없는 전용 가상 머신(VM)을 의미합니다. macOS, Windows 또는 베어 리눅스 호스트에서 Claude Code를 직접 실행하는 경우 파일 시스템 격리를 켜두십시오. 네트워크 샌드박스는 파일 시스템 제어를 대체할 수 없으며, 샌드박스된 파일 액세스로 인한 약간의 불편함이 실수로 파일을 덮어쓰거나 프로젝트 폴더를 벗어나는 악의적인 프롬프트 인젝션으로부터 복구하는 비용보다 훨씬 저렴합니다.

이 토글을 성능 조절 장치가 아닌 호환성 심(shim)으로 생각하십시오. 이는 운영 체제나 오케스트레이터가 이미 격리를 처리하고 있어 Claude의 자체 샌드박스가 불필요한 복잡성을 더하는 환경을 위해 존재합니다.

이번 업데이트가 실제로 수정하는 사항

새로운 설정 외에도 2.1.216은 에이전트가 허용되지 않은 곳에 접근할 수 있게 만드는 몇 가지 실질적인 허점을 차단합니다.

Worktree isolation. 서브에이전트는 더 이상 Git 명령을 자신의 워크트리 외부의 상위 또는 형제 디렉터리로 리다이렉션할 수 없습니다. 이전에는 프로젝트 내부에서 실행되는 서브에이전트가 공유 체크아웃이나 인접한 저장소를 대상으로 Git 작업을 수행할 수 있었습니다. 많은 개발자가 공통 부모 폴더 아래에 여러 프로젝트를 보관하기 때문에 이는 중요한 문제입니다. 이제 이러한 경계를 넘나드는 명령은 실패합니다.

Symlink hardening at the .claude path. 워크플로 정의 및 예약된 작업이 설정을 작성할 때 심볼릭 링크를 따라가는 경우가 있었습니다. .claude에서 셸 프로필이나 SSH 디렉터리 등으로 심볼릭 링크를 생성할 수 있는 공격자는 에이전트가 프로젝트 외부로 파일을 쓰도록 유도할 수 있었습니다. 이번 업데이트는 해당 경로에서 심볼릭 링크를 따르는 것을 거부함으로써 이를 방지합니다.

Safer rewinds. 최근 변경 사항을 되돌릴 수 있는 /rewind 명령은 이제 심볼릭 링크 및 하드 링크된 경로를 건너뜁니다. 이 보호 장치가 없다면 리와인드 작업이 심볼릭 링크를 따라가 저장소에서 멀리 떨어진 파일을 덮어쓸 수 있습니다. Claude는 이제 이러한 건너뛴 경로를 명시적으로 보고하여 경계가 유지되었음을 알 수 있게 합니다.

Resumed agents keep their restrictions. 중단되었다가 나중에 재개된 백그라운드 세션이 기본 도구 권한으로 되돌아가는 문제가 있었습니다. 에이전트가 읽기만 가능하고 쓰기는 불가능하도록 의도적으로 제한했더라도, 재시작 시 광범위한 권한이 조용히 복구될 수 있었습니다. 이제 원래의 제한 사항이 세션과 함께 유지되고 복구됩니다.

보안 프로필 선택하기

Claude Code 2.1.216은 이러한 제어 기능을 세 가지 프로필로 구성합니다. 도구가 가장 빠르게 느껴지는 방식이 아니라, 도구를 실행하는 위치에 따라 선택하십시오.

Default. 파일 시스템 및 네트워크 샌드박스가 모두 활성화된 상태로 유지됩니다. 노트북이나 워크스테이션에서 로컬 개발을 하는 경우에 적합한 선택입니다. 컨테이너를 관리할 필요 없이 홈 디렉터리, 시스템 파일 및 인접 프로젝트를 보호합니다.

Compatibility. 파일 시스템 격리는 꺼지지만 네트워크 샌드박스는 유지됩니다. 파일 시스템이 이미 일시적이거나 엄격하게 범위가 지정된 일회성 컨테이너 또는 VM으로 이 프로필을 제한하십시오. 에이전트가 보호된 폴더에 접근할 때 비밀번호를 입력하는 것이 귀찮다는 이유로 이 프로필을 사용해서는 안 됩니다.

Managed Hard Gate. 두 가지 샌드박스 계층이 모두 켜져 있으며, 오케스트레이터나 보안 팀이 시행하는 추가적인 컨테이너 정책을 요구합니다. 이는 심층 방어가 필수적인 CI 파이프라인, 원격 개발 환경 및 엔터프라이즈 설정에 맞게 구축되었습니다.

어떤 것이 적합한지 확실하지 않다면 Default로 시작하십시오. 런타임 환경이 자체적으로 파일 시스템을 진정으로 격리하고 있음을 확인한 후에만 보호 수준을 낮출 수 있습니다.

Upgrading Without Breaking Your Workflow

이 업데이트를 금요일 오후에 설치하는 일상적인 패치처럼 가볍게 다루지 마십시오. 2.1.216의 업그레이드 경로는 간단하지만, 설정 오류로 인한 결과는 결코 간단하지 않습니다.

먼저, 평소 사용하는 패키지 관리자나 설치 프로그램을 통해 2.1.216으로 업그레이드하십시오. 그런 다음 에이전트 작업을 시작하기 전에 세 가지 격리 프로필 중 하나를 선택하십시오. 어떤 프로필이 우선권을 갖는지 이해하지 못한 채 실행 중인 세션 간에 프로필을 혼용하지 마십시오.

다음으로, 아래에 설명된 다섯 가지 비파괴적 경계 테스트(non-destructive boundary tests)를 실행하십시오. 이는 샌드박스가 프로필에서 약속한 대로 작동하는지 증명하는 빠르고 스크립트화된 점검 방식입니다. 테스트 중에 일회용 테스트 저장소 외부에 있는 파일에 대한 센티넬 해시(sentinel hash)를 생성하십시오. 센티넬 해시는 보호하려는 민감한 파일이나 디렉터리의 체크섬일 뿐입니다. 테스트를 실행한 후 해시를 비교하십시오. 만약 변경된 사항이 있다면, 격리가 제대로 이루어지지 않고 유출되고 있는 것입니다.

로그도 함께 비교하십시오. Claude Code는 거부(denials) 및 샌드박스 이벤트를 로컬 로그에 기록합니다. 차단된 호스트에 접속을 시도하거나 서브에이전트(subagent)가 워크트리(worktree)를 벗어날 때 명시적인 거부 메시지가 있는지 확인하십시오. 조용한 실패(silent failures)는 명시적인 실패보다 더 위험하므로, 로그에 가드레일(guardrails)이 작동하고 있는지 확인하십시오.

마지막으로, 변경 사항을 점진적으로 적용하십시오. 단일 프로젝트나 비운영(non-production) 브랜치에서 시작하십시오. 전체 팀이나 CI 플릿(fleet)에 배포하기 전에 새 버전을 하루 이틀 정도 실행해 보십시오.

샌드박스 작동을 증명하는 다섯 가지 경계 테스트

항상 가짜 데이터가 가득 찬 일회용 저장소 내부에서 이 테스트를 실행하십시오. 운영 코드, 실제 자격 증명 또는 실제 인프라를 대상으로 테스트하지 마십시오.

네트워크 경계. 명시적으로 허용한 엔드포인트와 차단한 엔드포인트, 두 곳에 접속을 시도하십시오. httpbin.org와 같은 공개 테스트 서비스에 대한 간단한 HTTP 요청은 허용된 대상으로 사용할 수 있으며, 로컬 메타데이터 엔드포인트나 내부 IP에 대한 요청은 실패해야 합니다. 차단된 요청이 성공한다면 네트워크 샌드박스가 잘못 설정된 것입니다.

워크트리 격리. 서브에이전트 내부에서 상위 디렉터리를 대상으로 하는 Git 명령을 실행하십시오. 예를 들어, git -C .. status를 시도하거나 에이전트에게 체크아웃 영역 외부의 파일을 설명하도록 시키십시오. 2.1.216의 수정 사항이 적용되었다면 이는 반드시 실패해야 합니다. 서브에이전트는 자신의 워크트리만 볼 수 있어야 합니다.

심볼릭 링크 트랩. 프로젝트 내부에 /tmp/sentinel-target과 같이 저장소 외부의 디렉터리를 가리키는 심볼릭 링크를 생성하십시오. 그런 다음 해당 링크를 통해 쓰기가 수행될 수 있는 작업을 .claude 경로 아래에 저장해 보십시오. 저장 후 외부 디렉터리를 확인하십시오. 여전히 비어 있다면 심볼릭 링크 강화(hardening)가 제대로 작동하고 있는 것입니다.

리와인드 건너뛰기(Rewind skip). 저장소 내부에 시스템 파일이나 다른 디렉터리로 연결되는 심볼릭 링크를 포함하는 폴더를 만듭니다. 해당 폴더에서 /rewind를 실행하십시오. Claude는 해당 경로를 따라가는 대신 건너뛴 심볼릭 링크 또는 하드 링크 경로를 목록으로 표시해야 합니다. 저장소 외부의 대상이 그대로 유지되는지 확인하십시오.

세션 재개(Session resurrection). 파일 쓰기 도구를 비활성화하는 것과 같은 엄격한 제한을 걸고 백그라운드 에이전트를 실행하십시오. 세션을 일시 중지하거나 중단한 다음 다시 재개하십시오. 즉시 에이전트가 파일을 쓰도록 시도하십시오. 제한 사항이 여전히 활성 상태라면 재개된 에이전트에 대한 수정 사항이 작동하고 있는 것입니다. 에이전트가 갑자기 다시 모든 도구에 접근할 수 있게 된다면 여전히 보안 취약점이 있는 상태입니다.

마치며

Claude Code 2.1.216은 이전 버전보다 더 많은 유연성을 제공하지만, 그 유연성에는 명확한 명령이 따릅니다. 바로 '신뢰하기 전에 검증하라'는 것입니다. 새로운 파일 시스템 토글은 안전을 희생하면서 사용자의 편의를 돕기 위해 만들어진 것이 아닙니다. 이는 이미 도구 아래에 견고한 기반을 구축한 엔지니어들을 위한 것입니다. 이번 릴리스의 진정한 개선 사항은 서브에이전트가 상위 디렉터리로 침투하는 것을 막고, 설정 쓰기 중에 심볼릭 링크를 따르는 것을 거부하며, 긴 일시 중지 후에도 규칙을 기억하는 조용한 가드레일입니다.

다섯 가지 테스트를 실행하십시오. 센티넬 해시를 확인하십시오. 로그를 읽으십시오. 그러고 나서, 오직 그 후에만 새 버전이 실제 작업을 처리하도록 하십시오.

Source: Claude Code v2.1.216 Release Notes

Optional learning community: GyaanSetu on Telegram