샌드박스 & 보안 저장소

Claude Code의 샌드박스 시스템은 AI가 실행하는 모든 Bash 명령을 OS 수준에서 격리합니다. SSH 키, API 토큰, 시스템 설정 같은 민감한 리소스에 대한 접근을 커널 수준 메커니즘으로 차단하며, 보안 저장소는 시크릿을 안전하게 관리합니다.

핵심 구성 요소:

• 샌드박스 아키텍처: macOS Seatbelt / Linux bubblewrap + seccomp
• 3가지 모드: disabled, regular, auto-allow
• 네트워크 & 파일시스템 제어: 도메인 허용/거부, 민감 파일 차단
• 보안 저장소: macOS Keychain + 30초 TTL 캐시 + 평문 폴백

샌드박스는 OS별로 다른 커널 수준 격리 메커니즘을 사용합니다. macOS에서는 Apple의 Seatbelt(sandbox-exec)을, Linux에서는 bubblewrap(bwrap) + seccomp을 사용합니다.

macOS — Seatbelt

// sandbox/seatbelt.ts — macOS 샌드박스 프로파일 생성
function buildSeatbeltProfile(config: SandboxConfig): string {
  return `
(version 1)
(deny default)

;; 기본 읽기 허용 (프로젝트 디렉토리)
(allow file-read*
  (subpath "${config.projectRoot}"))

;; 쓰기 허용 (프로젝트 디렉토리만)
(allow file-write*
  (subpath "${config.projectRoot}"))

;; 민감 파일 항상 거부
(deny file-read*
  (subpath "/Users/\${USER}/.ssh")
  (subpath "/Users/\${USER}/.gnupg")
  (subpath "/Users/\${USER}/.aws/credentials"))

;; 네트워크: 허용된 도메인만
(allow network-outbound
  (remote tcp "${config.allowedDomains.join('" "')}"))`
}

Linux — bubblewrap + seccomp

// sandbox/bubblewrap.ts — Linux 샌드박스 구성
function buildBwrapArgs(config: SandboxConfig): string[] {
  return [
    '--ro-bind', '/usr', '/usr',       // 시스템 바이너리 읽기 전용
    '--ro-bind', '/bin', '/bin',
    '--ro-bind', '/lib', '/lib',
    '--bind', config.projectRoot, config.projectRoot,  // 프로젝트만 RW
    '--tmpfs', '/tmp',                  // 격리된 /tmp
    '--unshare-net',                    // 기본 네트워크 격리
    '--seccomp', seccompFilterFd,       // syscall 필터
    '--die-with-parent',                // 부모 종료 시 함께 종료
  ]
}

샌드박스는 사용자 환경과 보안 요구사항에 따라 3가지 모드로 운영됩니다.

// sandbox/index.ts — 3가지 샌드박스 모드
type SandboxMode = 'disabled' | 'regular' | 'auto-allow'

function resolveSandboxMode(): SandboxMode {
  // 명시적 비활성화
  if (config.sandbox === false) return 'disabled'

  // auto-allow: 신뢰된 프로젝트에서 자동 승인
  if (config.permissionMode === 'auto') return 'auto-allow'

  // 기본: 모든 작업에 사용자 승인 필요
  return 'regular'
}

• disabled: 샌드박스가 완전히 비활성화됩니다. Docker 컨테이너 내부 등 이미 격리된 환경에서 사용합니다.
• regular: 기본 모드. 모든 Bash 명령 실행 전에 사용자에게 승인을 요청하며, 커널 수준 격리가 적용됩니다.
• auto-allow: 신뢰된 프로젝트에서 안전한 명령은 자동으로 승인됩니다. 단, 민감 파일 접근과 네트워크는 여전히 제한됩니다.

네트워크 제어는 도메인 기반 허용/거부 목록으로 관리됩니다. 기본적으로 모든 외부 네트워크 접근이 차단되며, 명시적으로 허용된 도메인만 접근 가능합니다.

// sandbox/network.ts — 도메인 기반 네트워크 제어
const DEFAULT_ALLOWED_DOMAINS = [
  'api.anthropic.com',       // Claude API
  'github.com',              // git 작업
  'registry.npmjs.org',      // npm 패키지
  'pypi.org',                // pip 패키지
]

const ALWAYS_DENIED_DOMAINS = [
  '*.onion',                  // Tor 네트워크
  'metadata.google.internal', // 클라우드 메타데이터
  '169.254.169.254',          // AWS 메타데이터
]

특정 파일과 디렉토리는 샌드박스 모드와 관계없이 항상 접근이 거부됩니다.

// sandbox/filesystem.ts — 항상 거부 목록
const ALWAYS_DENIED: string[] = [
  // Claude Code 내부 설정 (변조 방지)
  'settings.json',           // 권한 설정 변경 방지
  '.claude/skills/*',         // 스킬 주입 방지

  // Git 보안
  '.git/hooks/*',             // git hook 변조 방지
  '.bare-git-sentinel',       // bare repo 감지 우회 방지

  // 민감한 시크릿
  '~/.ssh/*',                 // SSH 키
  '~/.gnupg/*',               // GPG 키
  '~/.aws/credentials',       // AWS 자격 증명
  '~/.config/gcloud/*',       // GCP 자격 증명
]

function isPathDenied(path: string): boolean {
  return ALWAYS_DENIED.some(pattern =>
    minimatch(normalizePath(path), pattern)
  )
}

settings.json이 항상 거부 목록에 포함되는 이유는 특히 중요합니다. Claude가 자신의 권한 설정을 수정할 수 있다면, 보안 메커니즘 전체가 무력화될 수 있기 때문입니다.

보안 저장소는 API 키, OAuth 토큰 등의 시크릿을 안전하게 관리합니다. macOS에서는 시스템 Keychain을, 지원되지 않는 환경에서는 평문 폴백을 사용합니다.

macOS Keychain + hex 인코딩

// security/keychain.ts — macOS Keychain 통합
async function storeSecret(key: string, value: string): Promise<void> {
  // hex 인코딩: Keychain이 특수 문자를 안전하게 처리하도록
  const hexValue = Buffer.from(value).toString('hex')

  await execFile('security', [
    'add-generic-password',
    '-a', 'claude-code',
    '-s', key,
    '-w', hexValue,
    '-U',  // 기존 항목 업데이트
  ])
}

async function readSecret(key: string): Promise<string | null> {
  const hexValue = await execFile('security', [
    'find-generic-password',
    '-a', 'claude-code',
    '-s', key,
    '-w',
  ])

  return Buffer.from(hexValue.trim(), 'hex').toString()
}

30초 TTL 캐시

Keychain 접근은 서브프로세스 호출이 필요하므로 20~40ms가 소요됩니다. 빈번한 API 호출을 위해 30초 TTL(Time-to-Live) 인메모리 캐시를 사용합니다.

// 30초 TTL 캐시
const secretCache = new Map<string, { value: string; expires: number }>()
const TTL_MS = 30_000  // 30초

async function getCachedSecret(key: string): Promise<string | null> {
  const cached = secretCache.get(key)
  if (cached && cached.expires > Date.now()) {
    return cached.value
  }

  const value = await readSecret(key)
  if (value) {
    secretCache.set(key, { value, expires: Date.now() + TTL_MS })
  }
  return value
}

평문 폴백

Linux 또는 Keychain이 사용 불가한 환경에서는 ~/.claude/credentials에 평문으로 저장됩니다. 파일 권한은 0o600(소유자만 읽기/쓰기)으로 설정됩니다.

샌드박스 위반이 발생하면 사용자에게 명확한 피드백을 제공하고, 위반 이벤트를 분석 시스템에 기록합니다.

// 위반 감지 & 보고
function handleSandboxViolation(violation: Violation): void {
  // UI에 위반 사항 표시
  displayWarning({
    type: violation.type,     // 'file_access' | 'network' | 'syscall'
    path: violation.path,     // 접근 시도된 경로/도메인
    command: violation.cmd,   // 실행된 명령
  })

  // 분석 이벤트 기록 (PII 제외)
  logEvent('sandbox_violation', {
    type: violation.type,
    // 경로는 해싱하여 기록 (PII 방지)
    pathHash: hashPath(violation.path),
  })
}