Claude Code 샌드박스 적용 범위 공백: 셸 밖 파일 도구·MCP 경계를 설계하는 법
홈랩 구축 체크리스트 — 로컬 LLM을 세우고 Tailscale로 안전하게 잇는 20단계를 A4 한 장으로 정리했습니다.
체크리스트 받기 →
Claude Code의 샌드박스는 OS 수준의 강한 격리를 제공하지만, 공식 문서 기준으로 그 대상은 셸 명령과 그 하위 프로세스로 한정된다. 파일 도구와 MCP 서버는 다른 통제 계층에 속하므로, 셸·파일·네트워크 권한을 함께 가진 에이전트에서 통제가 한 경로에만 걸리면 우회 지점이 생긴다. 이 글은 Anthropic 공식 샌드박스 문서를 근거로 적용 범위를 정리하고, 도구별 권한 경계를 설계하는 절차를 제시한다.
샌드박스가 덮는 범위와 덮지 않는 범위
공식 문서에 따르면 샌드박스는 Bash, PowerShell, Monitor 명령과 그 자식 프로세스에 대한 OS 강제 경계이며 macOS, Linux, WSL2에서 동작한다. 네이티브 Windows는 샌드박스 없이 실행된다.
| 경로 | 샌드박스 적용 | 통제 수단 |
|---|---|---|
| Bash 등 셸 명령과 자식 프로세스 | 적용 | 파일시스템·네트워크 경계 |
| Read, Edit, Write, WebFetch, WebSearch | 미적용 | 권한 규칙 |
| MCP 서버, 명령 훅, 플러그인 모니터, LSP 서버, 상태줄, apiKeyHelper | 미적용 | 사용자 전체 권한으로 실행 |
! 셸 모드 직접 입력 |
대개 미적용 | 사용자 책임 |
문서는 denyRead 항목이 Read 도구를 막지 못하고, allowedDomains가 WebFetch를 제한하지 않는다고 명시한다. 기본 읽기 범위도 ~/.ssh 등 머신 대부분을 포함한다. 샌드박스는 "위험을 줄이지만 완전한 격리 경계는 아니다"라고 문서 스스로 밝힌다.
공백이 만드는 우회 지점
- 셸에서 차단된 경로 읽기가 파일 도구로는 허용 규칙만 맞으면 가능할 수 있다.
- 도메인 허용 목록은 셸 네트워크에만 걸리고 웹 도구와 MCP 서버의 외부 통신에는 걸리지 않는다.
- MCP 서버와 훅은 전체 권한으로 돌아 한 번 침해되면 샌드박스 밖에서 모든 동작이 가능하다.
- 탈출구 설정(
dangerouslyDisableSandbox재시도,excludedCommands,filesystem.disabled, 유닉스 소켓 허용)이 경계를 약화시킨다. - 쓰기 가능한
$PATH디렉터리나 셸 시작 파일은 샌드박스 밖 코드 실행으로 이어질 수 있다고 문서가 경고한다.
도구별 경계 설계 구조
flowchart TB
A["에이전트 요청"] --> B{"경로 유형"}
B -->|"셸"| C["샌드박스 경계"]
B -->|"파일 도구"| D["권한 규칙"]
B -->|"웹 도구"| E["권한 규칙"]
B -->|"MCP·훅"| F["전체 권한 실행"]
C --> G["감사 로그"]
D --> G
E --> G
F --> H["추가 격리: 컨테이너·VM"]
H --> G
G --> I["설정 변경 감시"]
1단계: 도구별 권한 경계 목록화
- 에이전트가 쓸 수 있는 경로를 셸, 파일 도구, 웹 도구, MCP 서버, 훅, LSP, 상태줄, 인증 헬퍼로 나누어 목록화한다.
- 각 경로마다 어떤 통제가 실제로 적용되는지(샌드박스, 권한 규칙, 없음)를 표로 기록한다. "없음"으로 표시된 칸이 우선 보완 대상이다.
2단계: 샌드박스 밖 경로의 최소 권한 정책
- 파일 도구는
deny권한 규칙으로 민감 경로(자격 증명, 키, 설정 파일)를 명시 차단한다. 샌드박스의denyRead에만 의존하지 않는다. - MCP 서버는 도구 단위 허용(
mcp__서버__도구)으로 최소화하고, 신뢰할 수 있는 서버만 등록한다. allowUnsandboxedCommands: false로 비샌드박스 재시도를 끄고,failIfUnavailable로 샌드박스 불가 시 실행을 중단한다.- 훅과 MCP 서버처럼 전체 권한으로 도는 구성요소는 컨테이너나 VM 같은 별도 격리 안에서 실행한다.
- 관리자는 managed settings로 이들 설정을 잠근다.
3단계: 설정 파일 변경 감시와 신뢰 경계 점검
- 설정 파일, 훅 정의, MCP 서버 목록의 변경을 버전 관리와 해시 비교로 감시하고, 변경 시 검토 절차를 거치게 한다.
- 문서상
.claude/settings.json과.git/hooks는 샌드박스 내 쓰기가 막혀 있지만, 파일 도구 경로의 쓰기는 권한 규칙이 책임지므로 해당 경로에 대한 쓰기 규칙도 별도로 확인한다. - 주기 점검 항목: 허용 도메인의 폭, 유닉스 소켓 허용 여부, 제외 명령 목록, 약화 옵션 사용 여부.
- 도구 호출 로그와 실제 파일·네트워크 변화를 대조해 한 경로로만 통제가 걸린 지점을 찾는다.
마무리
Claude Code 샌드박스는 셸 명령에 대해서는 강력한 OS 격리를 주지만, 파일 도구·웹 도구·MCP·훅은 별도의 통제가 필요하다. 통제가 한 경로에만 걸리면 나머지 경로가 우회로가 되므로, 경로별 적용 통제를 목록화하고 샌드박스 밖 경로에 최소 권한과 추가 격리를 적용해야 한다. 설정 파일 변경 감시와 주기적 신뢰 경계 점검을 운영 절차로 고정하는 것이 마지막 요건이다.
Keywords
sandbox, permission rules, MCP, trust boundary, least privilege, 샌드박스, 권한 규칙, 신뢰 경계, 최소 권한, 설정 감시
Sources
'IT Professional Engineering > AI.ML' 카테고리의 다른 글
| Claude 이미지 스테가노그래피 분석: 모델 출력에 숨은 은닉 채널을 탐지하는 설계 (0) | 2026.10.24 |
|---|---|
| OpenAI 내부 코딩 에이전트의 모니터링 약화: 감시 체계 공백 대응 설계 (0) | 2026.10.24 |
| 에이전트 명령 검사·접근 통제 도구: 실행 전 검사 계층의 설계 기준 (0) | 2026.10.23 |
| Agent Skills의 AAIF 이관: 중립 재단 거버넌스 기반 스킬 표준 설계 (0) | 2026.10.23 |
| PyTorch 2.15 Mac GPU FP8·MoE 가속: 로컬 추론 경로의 정밀도와 이식 기준 설계 (0) | 2026.10.23 |
홈랩 구축 체크리스트를 A4 한 장으로 드립니다
로컬 LLM을 세우고 Tailscale로 안전하게 잇는 20단계. 이메일을 남기면 바로 보내드립니다. 광고 없이, 언제든 수신거부.
체크리스트 받기 →