Claude Code 2.1.221: 샌드박스 명령어가 읽기 전에 자격 증명 (credential) 파일 마스킹하기

빠른 답변

Claude Code 2.1.221은 Linux 및 WSL2 환경의 샌드박스 자격 증명 (credential) 파일에 대해 mode: "mask"를 추가했습니다. 샌드박스화된 명령어는 실제 자격 증명 대신 파수꾼 (sentinel) 복사본을 읽습니다. 명령어가 허용된 요청을 보낼 때, 샌드박스 프록시 (proxy)가 송신 (egress) 시 실제 값을 대체할 수 있습니다. macOS의 경우, 파일 마스킹은 deny로 대체되므로 명령어가 자격 증명 파일을 읽을 수 없습니다.

이를 투명한 토글 (toggle)로 취급하지 마십시오. 2.1.221 버전 이상으로 고정하고, 규칙을 신뢰할 수 있는 설정 범위 (settings scope)에 배치하며, 일회용 자격 증명 (disposable credential)을 사용하고, injectHosts 범위를 좁히며, 자격 증명 치환에 필요한 TLS 종료 프록시 (TLS-terminating proxy)를 활성화하고, 추출 실패 시 카나리 (canary)를 중단시키십시오. 롤아웃 (rollout)은 명령어가 실제 값을 절대 보거나 로그에 남기지 않고, 승인된 요청이 인증되며, 모든 승인되지 않은 경로가 실패할 때만 통과됩니다.

발행 시점에 Anthropic의 일반 샌드박스 가이드에는 파일 항목이 deny만 지원한다고 여전히 명시되어 있었으나, 태그가 지정된 2.1.221 릴리스 및 패키징된 설정 스키마 (settings schema)는 파일 마스킹을 노출했습니다. 이러한 문서의 지연을 운영 환경 롤아웃 전에 정확한 설치 빌드와 유효한 스키마를 확인해야 하는 이유로 간주하십시오.

대상 사용자

이 가이드는 Claude Code가 Bash 샌드박스 내부에서 gh, npm, 클라우드 CLI 또는 내부 API 클라이언트를 실행하도록 허용하는 개발자 및 플랫폼 팀을 위한 것입니다. 명령어가 인증된 액세스가 필요하지만 에이전트가 기반이 되는 토큰 (token)을 절대 받아서는 안 되는 경우에 가장 유용합니다.

자격 증명 마스킹은 엄격한 네트워크 허용 목록 체크리스트 (strict network allowlist checklist)를 보완합니다. 허용 목록 (allowlist)은 샌드박스화된 명령어가 연결할 수 있는 위치를 제어하며, 마스킹은 명령어가 실제 자격 증명을 보유할지 여부를 제어합니다. 파일 시스템 및 세션 경계에 대해서는 더 광범위한 샌드박스 및 워크트리 회귀 테스트 (sandbox and worktree regression checks)를 유지하십시오.

변경된 사항 및 변경되지 않은 사항

2.1.221 버전 이전의 Claude Code는 두 가지 실용적인 자격 증명 경로를 문서화했습니다: 자격 증명 파일을 완전히 거부(deny)하거나, 환경 변수를 마스킹(mask)하고 프록시(proxy)가 값을 주입하도록 하는 방식입니다. 이번 새 릴리스는 이러한 센티넬-및-프록시(sentinel-and-proxy) 패턴을 Linux 및 WSL2의 파일로 확장합니다.

패키징된 2.1.221 스키마(schema)는 extract를 캡처 그룹 1(capture group 1)이 각 자격 증명 값을 식별하는 전역 정규 표현식(regular expression)으로 설명합니다. extract가 없으면 파일 전체가 하나의 센티넬(sentinel)로 대체됩니다. 또한 onExtractNoMatch, maskDuplicates, injectHosts 제어 기능도 제공합니다.

마스킹(Masking)이 허용된 호스트를 안전하게 만들거나, 요청의 의미를 검사하거나, MCP 도구를 제한하거나, Claude의 내장 파일 도구를 보호하는 것은 아닙니다. 이는 샌드박스(sandboxed) 명령어에만 적용됩니다. 중대한 작업에 대해서는 최소 권한 토큰(least-privilege tokens), 리포지토리 규칙(repository rules), 결정론적 테스트(deterministic tests) 및 인간의 승인을 계속 사용하십시오.

실패 시 차단되는(fail-closed) 롤아웃 워크플로

1. 런타임 및 플랫폼 동결

정확한 Claude Code 버전, 설치 채널, OS, 해당되는 경우 WSL 버전 및 설정 소스를 기록하십시오. 업그레이드 후에는 장시간 실행 중인 세션을 재시작하십시오. 패키지 락(package lock)이나 다른 터미널을 통해 활성 버전을 추측하지 마십시오.

2. 일회용 자격 증명 파일로 시작

해롭지 않은 카나리 엔드포인트(canary endpoint)에만 액세스할 수 있고 즉시 취소 가능한 토큰을 생성하십시오. 디렉터리가 아닌 정확한 파일 경로 하나를 사용하십시오. 개발자의 GitHub, npm, 클라우드 또는 운영(production) 자격 증명으로 테스트하지 마십시오.

3. 파일 전체 마스킹 또는 구조화된 마스킹 선택

파일에 단일 자격 증명만 포함되어 있고 클라이언트가 해당 형식을 수용하는 경우에만 파일 전체 마스킹을 사용하십시오. .netrc, JSON, YAML 또는 키-값(key-value) 파일의 경우, 클라이언트가 여전히 유효한 구문을 볼 수 있도록 extract를 사용하십시오. 그룹 1에서 비밀 값(secret)만 캡처하십시오.

카나리(canary)의 경우 onExtractNoMatch를 error로 설정하십시오. 패키징된 스키마(schema)에 따르면, 기본값인 warn 동작은 매칭되지 않는 파일이 샌드박스(sandbox) 내부에서 읽기 가능한 상태로 남을 수 있다고 명시되어 있습니다. 변경된 파일 형식은 시작을 차단해야 하며, 원래 파일을 조용히 노출해서는 안 됩니다. maskDuplicates는 길고 엔트로피(entropy)가 높은 값에만 사용하십시오. 짧고 반복되는 텍스트를 교체하면 관련 없는 필드가 손상될 수 있기 때문입니다.

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

예시 호스트(host)와 패턴(pattern)을 제어 가능한 카나리로 교체하십시오. 자격 증명 주입(credential-injection) 규칙은 리포지토리(repository)가 제어하는 파일이 아닌, 사용자(user), 관리형(managed) 또는 명시적인 CLI 설정에 유지하십시오.

4. 송출(egress)을 제한하기 위한 바인드 치환(Bind substitution)

모든 injectHosts 항목은 network.allowedDomains를 통해서도 도달 가능해야 합니다. 광범위한 와일드카드(wildcard)보다는 정확한 API 호스트네임(hostname)을 선호하십시오. 자격 증명 치환(credential substitution)을 위해서는 프록시(proxy)가 요청 콘텐츠를 볼 수 있어야 하므로, network.tlsTerminate를 구성하십시오. 이 설정이 없으면 센티넬(sentinel)이 변경되지 않은 상태로 서버에 도달하게 되어 인증에 실패해야 합니다.

5. 6가지 부정 및 긍정 테스트 실행

제어 가능한 싱크(sink)를 사용하고 편집(redacted)된 증거만 보존하십시오:

1. 샌드박스 내부에서 파일을 읽었을 때 유효한 구조와 센티넬은 나타나지만, 일회용 토큰(disposable token)은 절대 나타나지 않아야 합니다.
2. 로그(logs), 트레이스(traces), 프로세스 인자(process arguments) 및 에러 메시지에 일회용 토큰이 포함되지 않아야 합니다.
3. 정확히 허용된 호스트로의 요청이 프록시 치환을 통해 인증되어야 합니다.
4. 다른 호스트로 보내는 동일한 요청은 실제 토큰을 받지 않아야 합니다.
5. 파일을 변경하여 extract가 아무것도 매칭하지 못하게 만듭니다. 이때 샌드박스 설정이 중단되어야 합니다.
6. 지원되는 모든 실행 표면(execution surface)에서 반복합니다. macOS는 마스킹(masking)이 작동하는 척하는 대신 파일 접근을 거부해야 합니다.

6. 거부 폴백(deny fallback)과 함께 배포

하나의 비프로덕션(non-production) 워크플로로 시작하십시오. 빌드, 플랫폼, TLS 프록시(proxy), 스키마(schema) 또는 편집된 증거(redacted evidence)를 증명할 수 없는 경우, 파일 항목을 deny로 전환하고 인증된 작업을 좁은 범위의 MCP/커스텀 도구 또는 외부 자격 증명 주입 프록시(external credential-injecting proxy)를 통해 라우팅하십시오. 신뢰할 수 없는 리포지토리 샌드박스 체크리스트는 외부 경계로 유지됩니다.

8가지 배포 게이트 (Eight rollout gates)

일반적인 실수 (Common mistakes)

실제 계정 토큰으로 테스트하기. 카나리(canary)는 로그, 정규 표현식(regex) 또는 프록시 규칙이 잘못되었을 때 안전해야 합니다.

일치하지 않는 동작을 fail-open 기본값으로 남겨두기. 자격 증명 파일 형식은 변경됩니다. 일치하지 않는 추출(extraction)이 발생하면 배포를 차단하도록 만드십시오.

광범위한 허용 도메인 사용하기. 마스킹(masking)은 토큰을 보유하는 주체를 제한하는 것이지, 인증된 요청이 수행할 수 있는 작업을 제한하는 것이 아닙니다. 호스트와 토큰 범위 모두를 좁게 유지하십시오.

macOS와의 동일성 가정하기. 버전 2.1.221은 macOS에서 명시적으로 deny로 폴백(fallback)합니다. 해당 환경에서의 인증 실패는 예상된 동작이지, 대체(substitution)의 증거가 아닙니다.

FAQ

마스킹이 Claude Code가 자격 증명을 아예 보지 못하게 방지하나요?

구성된 파일, 프록시 및 호스트 경로가 예상대로 작동할 때, 샌드박스화된 Bash 명령어로부터 실제 값을 보호합니다. 하지만 내장 도구, MCP 서버, 기타 샌드박스화되지 않은 프로세스 또는 목록에 기재하지 않은 곳에 저장된 자격 증명은 보호하지 않습니다.

파일 거부(deny) 규칙을 즉시 교체해야 하나요?

아니요. 명령에 자격 증명이 필요하지 않을 때는 deny를 유지하십시오. mask는 센티널(sentinel), 추출(extraction), 이그레스(egress), TLS, 로깅 및 롤백(rollback) 게이트를 통과하는 인증된 워크플로에 대해서만 사용하십시오.

출처 (Sources)

출처 (Sources)

• Claude Code v2.1.221 릴리스
• Claude Code 샌드박싱 문서
• Anthropic 보안 에이전트 배포 가이드
• Claude Code 2.1.221 패키지