Claude Code 샌드박스와 권한: 파일·네트워크를 안전하게 여는 법

설정 파일 위치부터 고릅니다

팀 전체에 적용할 설정은 저장소의 `.claude/settings.json`에 둡니다. 개인에게만 필요한 예외는 `~/.claude/settings.json`, 저장소별 개인 설정은 Git에 올라가지 않는 `.claude/settings.local.json`에 둡니다. 아래 JSON 예시는 세 위치 중 목적에 맞는 파일의 최상위 객체에 합쳐 넣습니다.

보안 경계는 개인 로컬 예외보다 프로젝트 설정을 우선합니다. 팀이 반드시 지켜야 하는 거부 규칙을 개인 파일에만 두면 다른 개발자와 CI에는 적용되지 않습니다.

샌드박스와 권한은 같은 기능이 아닙니다

샌드박스는 Bash 명령과 그 자식 프로세스가 접근할 수 있는 파일 경로와 네트워크 도메인을 제한합니다. 명령이 실행된 뒤에도 운영체제 수준의 경계가 적용됩니다.

권한은 그보다 앞 단계입니다. Claude Code가 파일 편집, Bash 실행, 웹 요청 같은 도구를 사용하려 할 때 허용할지, 매번 물을지, 막을지를 정합니다. 샌드박스 안에서 실행 가능한 명령도 권한 모드와 규칙에 따라 승인이 필요할 수 있습니다.

작은 수정도 두 질문으로 나누면 됩니다. 이 명령을 실행해도 되는지는 권한의 문제입니다. 실행한다면 어디까지 닿게 할지는 샌드박스의 문제입니다.

지원 환경과 기본 파일 범위를 먼저 확인합니다

Claude Code의 Bash 샌드박스는 macOS, Linux, WSL2에서 지원됩니다. 네이티브 Windows는 지원하지 않으므로 Windows에서는 WSL2 배포판 안에서 실행해야 합니다.

기본 쓰기 범위는 현재 작업 디렉터리와 그 하위 폴더, 세션 임시 디렉터리입니다. 반면 기본 읽기 범위는 일부 차단 경로를 제외한 컴퓨터 전체입니다. 자격 증명 파일을 읽지 못하게 하려면 `sandbox.credentials`나 `denyRead`를 별도로 설정해야 합니다.

테스트 결과를 저장소 밖에 써야 한다면 전체 홈 디렉터리를 열지 않습니다. 도구가 실제로 쓰는 경로 하나만 추가하고, 다른 프로젝트나 비밀 파일과 섞이지 않는지 사람이 확인합니다.

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/project-test-output"],
      "denyRead": ["~/.ssh", "~/.aws"]
    }
  }
}

새 도메인은 실패 원인을 읽은 뒤 승인합니다

샌드박스 안 명령이 새 네트워크 도메인에 처음 연결하려 하면 Claude Code는 승인을 요청합니다. `auto` 모드에서는 같은 요청을 안전 분류기가 판단합니다. 아무 도메인도 미리 허용하지 않은 상태가 기본입니다.

`npm test`가 패키지를 내려받으려 한다고 해서 모든 인터넷 연결을 열 필요는 없습니다. 실패 출력에서 막힌 호스트를 확인하고, 작업에 필요한 공식 레지스트리인지 확인한 뒤 필요한 도메인만 허용합니다.

명령이 알 수 없는 분석 서버나 파일 공유 주소에 연결하려 하면 멈춥니다. 왜 필요한지, 어떤 데이터가 전송되는지, 로컬 대체 방법이 있는지 확인하기 전에는 목록에 넣지 않습니다.

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["registry.npmjs.org"]
    }
  }
}

`deny`, `ask`, `allow` 순서가 결과를 정합니다

권한 규칙은 `deny`, `ask`, `allow` 순서로 평가됩니다. 같은 명령이 허용 규칙에도 맞더라도 거부 규칙에 맞으면 실행되지 않습니다. 확인 규칙에 맞으면 더 구체적인 허용 규칙이 있어도 확인을 요청합니다.

반복해도 위험이 작은 검사 명령은 허용할 수 있습니다. 원격 변경은 확인 대상으로 남기고, 비밀 파일 읽기는 거부합니다. 넓은 거부 규칙 안의 예외를 작은 허용 규칙으로 되살릴 수 있다고 기대하면 안 됩니다.

{
  "permissions": {
    "allow": ["Bash(npm test -- orders)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"]
  }
}

자동 허용은 안전 판정이 아닙니다

샌드박스에는 `auto-allow`와 `regular permissions` 모드가 있습니다. 둘은 같은 파일·네트워크 경계를 사용하지만, 샌드박스 안 명령을 자동 승인할지에 차이가 있습니다.

`auto-allow`에서는 경계 안에서 실행 가능한 명령이 승인 없이 실행될 수 있습니다. 명시적 거부 규칙과 `git push`처럼 내용을 지정한 확인 규칙은 계속 적용됩니다. `regular permissions`에서는 샌드박스 안 Bash 명령도 일반 승인 절차를 거칩니다.

처음 업무 저장소에 적용할 때는 `regular permissions`로 실제 명령을 살펴보는 편이 낫습니다. `auto-allow`는 반복되는 로컬 검사처럼 범위와 복구 방법을 이미 아는 작업에만 씁니다.

샌드박스 밖 재실행 요청은 경고로 읽습니다

명령이 샌드박스 경계 때문에 실패하면 Claude Code는 막힌 경로나 호스트를 출력에 붙입니다. `allowUnsandboxedCommands`가 켜져 있으면 샌드박스 밖 재실행을 요청할 수 있습니다.

샌드박스 밖 명령은 일반 권한 절차를 거치지만 파일·네트워크 격리는 사라집니다. 막힌 대상의 필요성을 설명할 수 없거나 비밀 파일, 고객 데이터, 운영 변경에 닿을 수 있으면 실행하지 않습니다.

샌드박스를 보안 관문으로 쓰는 환경은 `allowUnsandboxedCommands`를 `false`로 둡니다. 이때 명령은 샌드박스 안에서 실행되거나 관리자가 정한 제외 명령으로 명시되어야 합니다.

샌드박스를 못 열면 작업도 멈추게 합니다

지원하지 않는 플랫폼이거나 필요한 구성 요소가 없으면 기본 동작은 경고 뒤 샌드박스 없이 명령을 실행하는 것입니다. 조직이 샌드박스를 필수 보안 장치로 쓴다면 이 기본값은 맞지 않습니다.

`sandbox.failIfUnavailable`을 `true`로 두면 보호 장치를 열지 못한 상태에서 명령을 실행하지 않습니다. WSL1처럼 지원하지 않는 환경을 발견하면 WSL2로 바꾸거나 관리자가 예외를 판단할 때까지 멈춥니다.

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

경계를 넓히기 전과 결과를 반영하기 전에 검토합니다

시작할 때 수정할 폴더, 읽지 말아야 할 파일, 필요한 테스트와 허용할 도메인을 적습니다. 실행 중 새 쓰기 경로, 새 도메인, 샌드박스 밖 재시도 요청이 나오면 대상과 목적을 확인합니다. 테스트가 실패했다는 이유만으로 범위를 넓히지 않습니다.

마지막에는 변경 파일 목록, 테스트 결과와 `git diff`를 확인합니다. 합의한 범위 밖 파일이 바뀌지 않았는지 보고, 커밋·푸시·배포·운영 데이터 변경은 별도 승인으로 남깁니다.