Claude Code sandbox.credentials: 비밀 파일 읽기부터 막는 보안 설정 | DAKER 커뮤니티

Claude Code sandbox.credentials: 비밀 파일 읽기부터 막는 보안 설정

Claude Code sandbox.credentials란, 샌드박스 안에서 실행되는 명령이 자격 증명 파일과 비밀 환경 변수를 읽지 못하게 막는 설정입니다. 2026년 6월 24일 기준 최신 changelog 2.1.187에 추가된 항목이라, auto mode나 장시간 agent 작업을 쓰는 팀은 지금 설정 범위를 확인해야 합니다.

클로드 코드 sandbox.credentials로 자격 증명 파일과 비밀 환경 변수를 먼저 막는 보안 카드.

Claude Code sandbox.credentials는 왜 지금 확인해야 하나요?

한 줄 요약: agent가 명령을 실행하기 전에 "읽으면 안 되는 비밀"을 운영 체제 샌드박스 경계에서 먼저 줄이는 설정입니다.

AI 코딩 agent는 테스트, 빌드, 패키지 설치, 배포 점검을 위해 Bash 명령을 자주 실행합니다. 문제는 같은 명령이 홈 디렉터리의 credential 파일이나 secret 환경 변수를 우연히 읽을 수도 있다는 점입니다. Claude Code 2.1.187은 sandbox.credentials 설정을 추가해, sandboxed command가 credential files와 secret environment variables를 읽는 것을 차단할 수 있게 했습니다.

DAKER의 Claude Code auto mode git 안전장치는 자동 실행 중 파괴적 git 명령을 막는 흐름을 다뤘습니다. Claude Code MCP 재연결 점검은 외부 도구 장애를 분류하는 법을 정리했습니다. 오늘 글은 그보다 앞단인 "명령이 비밀을 읽을 수 있는가"를 줄이는 보안 설정에 집중합니다.

sandbox.credentials와 denyRead는 어떻게 다르게 쓰나요?

sandbox.credentials는 2.1.187 changelog에 새로 올라온 credential 차단 설정입니다. 반면 sandbox.filesystem.denyRead는 특정 경로를 읽지 못하게 하는 일반 파일시스템 규칙입니다. 둘은 경쟁 관계가 아니라 함께 쓰는 방어선입니다.

항목	쓰는 목적	팀에서 볼 질문
`sandbox.enabled`	Bash 명령을 샌드박스 안에서 실행	이 프로젝트에서 sandbox가 켜져 있는가
`sandbox.credentials`	credential 파일과 secret 환경 변수 읽기 차단	agent가 토큰을 읽을 필요가 정말 있는가
`sandbox.filesystem.denyRead`	특정 경로 읽기 금지	`.env`, `~/.aws/credentials`, `~/.ssh`를 막았는가
`sandbox.filesystem.allowRead`	denyRead 안에서 필요한 경로만 예외 허용	repo 내부 read만 열어도 충분한가
`sandbox.network.allowedDomains`	외부 통신 도메인 제한	패키지 레지스트리와 내부 API만 열었는가

중요한 한계도 있습니다. sandbox 설정은 Bash 하위 프로세스의 경계를 줄이는 장치입니다. Claude의 파일 도구 접근은 permission rule의 Read, Edit, WebFetch 규칙과 함께 관리해야 합니다.

단계별 사용법: 팀 저장소에 어떻게 적용하나요?

먼저 Claude Code 버전을 확인합니다. 이 글의 기준은 2.1.187입니다.
개인 실험은 user settings에서 시작하고, 팀 정책은 managed settings나 project settings로 분리합니다.
sandbox.enabled를 켜고 sandbox가 실제로 동작하는지 봅니다.
sandbox.credentials를 적용해 credential files와 secret environment variables 읽기를 막습니다.
sandbox.filesystem.denyRead에 .env, ~/.aws/credentials, ~/.ssh, cloud provider credential 경로를 추가합니다.
repo 내부 read가 필요하면 allowRead로 필요한 범위만 다시 엽니다.
배포 도구, Docker, 브라우저 인증처럼 sandbox 밖 실행이 필요한 명령은 별도 승인 규칙으로 분리합니다.

sandbox.credentials, denyRead, allowRead, 네트워크 제한을 순서대로 점검하는 팀 보안 워크플로.

짧은 예시: 보안 리뷰 프롬프트는 어떻게 쓰나요?

이 저장소의 Claude Code sandbox 설정을 리뷰해줘.

확인할 것:
- sandbox.enabled가 켜져 있는지
- credential 파일과 secret 환경 변수를 읽을 수 있는 경로가 남아 있는지
- .env, ~/.aws/credentials, ~/.ssh가 denyRead에 들어가 있는지
- allowRead가 너무 넓게 열려 있지 않은지
- 배포 명령은 sandbox 예외가 아니라 별도 승인 흐름인지

결과는 위험도 순서로 정리하고, 실제로 바꿀 설정은 diff로 제안해줘.

이 프롬프트의 목적은 "보안 설정을 알아서 다 바꿔줘"가 아닙니다. 먼저 읽기 경계, 예외 경계, 승인 경계를 나눠 보게 만드는 것입니다.

팀 적용 체크리스트는 무엇인가요?

Claude Code 2.1.187 이상에서 테스트했는가
sandbox가 켜져 있을 때와 꺼져 있을 때를 구분해 문서화했는가
credential 차단과 파일 경로 차단을 둘 다 검토했는가
.env, cloud credential, SSH key, package token 경로를 샘플로 점검했는가
allowRead가 홈 전체나 루트 전체를 열지 않는가
자동 실행 모드에서 비밀이 필요한 작업은 별도 human approval로 남겼는가
보안 설정 변경 후 빌드, 테스트, 패키지 설치가 여전히 되는지 확인했는가

공식 출처는 어디에서 확인했나요?

2026년 6월 24일 기준 Claude Code CHANGELOG.md 2.1.187과 settings documentation의 sandbox settings 섹션을 확인했습니다. 공개 본문에는 DAKER 운영 정책에 맞춰 DAKER 내부 링크만 연결했습니다.

FAQ

sandbox.credentials만 켜면 모든 비밀이 안전한가요?

아닙니다. credential 차단은 중요한 방어선이지만, 파일 도구 접근과 네트워크 접근은 permission rule과 sandbox filesystem/network 설정으로 함께 관리해야 합니다.

project settings에 보안 설정을 넣어도 되나요?

팀 저장소에서 공유해야 하는 기본값은 project settings에 둘 수 있습니다. 다만 강제 정책이 필요하면 사용자가 쉽게 우회할 수 없는 managed settings가 더 적합합니다.

auto mode와 sandbox.credentials는 같은 기능인가요?

아닙니다. auto mode는 권한 요청과 자동 실행 경계를 다루고, sandbox.credentials는 sandboxed command가 비밀을 읽는 경계를 줄입니다.

이미 denyRead를 쓰고 있으면 새 설정이 필요 없나요?

그렇게 단정하면 안 됩니다. denyRead는 경로 기반 차단이고, sandbox.credentials는 credential/secret 차단이라는 목적이 더 직접적입니다. 둘을 함께 검토하는 편이 안전합니다.

다음 agent 자동화 전에, 먼저 "이 명령이 비밀을 읽을 수 있는가"를 기준으로 sandbox 설정을 한 번 점검해 보세요.

대표 이미지: 클로드 코드 sandbox.credentials 보안 설정 만화 카드

워크플로 이미지: 자격 증명 파일 차단 설정 적용 순서