# Claude CLI 완전 가이드 v9: 보안 및 권한 설정 ## 보안 아키텍처 개요 Claude Code는 **권한 기반 시스템**을 사용합니다. 기본적으로 읽기 전용이며, 민감한 작업은 명시적 승인이 필요합니다. ### 핵심 원칙 > "Claude Code는 당신이 부여한 권한만 가집니다" - 모든 파일 수정: 승인 필요 - 모든 명령 실행: 승인 필요 - 읽기 작업: 기본 허용 --- ## 내장 보안 기능 ### 1. 샌드박스 실행 Bash 명령은 격리된 환경에서 실행: - 파일 시스템 접근 제한 - 네트워크 접근 제한 (기본) - 시스템 리소스 보호 ### 2. 쓰기 경계 ``` 작업 디렉토리와 하위 디렉토리만 수정 가능 상위 디렉토리 접근: 명시적 승인 필요 ``` ### 3. 명령어 블랙리스트 기본적으로 차단되는 위험 명령: - `curl`, `wget` (임의 다운로드) - `rm -rf /` 같은 위험 패턴 - 시스템 수정 명령 ### 4. 프롬프트 인젝션 방어 - 민감한 작업: 명시적 승인 필요 - 입력 살균 처리 - 의심스러운 패턴 감지 - 웹 콘텐츠: 별도 컨텍스트로 격리 --- ## Permission 모드 ### 세 가지 모드 | 모드 | 동작 | 사용 시점 | |------|------|----------| | **Ask** | 매번 승인 요청 | 기본값, 일반 작업 | | **Auto** | 자동 승인 | 신뢰할 수 있는 작업 | | **Plan** | 읽기 전용 | 분석만 할 때 | ### 모드 전환 **세션 내:** ``` Shift+Tab 또는 Alt+M ``` **CLI 실행 시:** ```bash claude -p "쿼리" --permission-mode plan claude -p "쿼리" --permission-mode auto ``` --- ## 권한 관리 ### 현재 권한 확인 ``` /permissions ``` ### 권한 설정 구조 `settings.json`: ```json { "permissions": { "allow": [ "허용 패턴 목록" ], "deny": [ "차단 패턴 목록" ] } } ``` --- ## 권한 패턴 문법 ### Bash 명령 권한 ```json { "permissions": { "allow": [ "Bash(npm run build:*)", // npm run build로 시작하는 모든 명령 "Bash(npm test:*)", // npm test로 시작하는 모든 명령 "Bash(git status:*)", // git status "Bash(cat:*)" // cat 명령 ], "deny": [ "Bash(rm -rf:*)", // 위험한 삭제 "Bash(sudo:*)", // sudo 명령 "Bash(curl:*)", // curl (명시적 차단) "Bash(wget:*)" // wget (명시적 차단) ] } } ``` ### 파일 접근 권한 ```json { "permissions": { "allow": [ "Read(/home/user/project:*)", "Write(/home/user/project/src:*)" ], "deny": [ "Write(/etc:*)", // 시스템 설정 보호 "Write(/home/user/.ssh:*)", // SSH 키 보호 "Read(/home/user/.env:*)" // 환경 변수 보호 ] } } ``` ### 웹 접근 권한 ```json { "permissions": { "allow": [ "WebFetch(domain:api.example.com)", "WebFetch(domain:docs.example.com)", "WebFetch(domain:*.github.com)" ], "deny": [ "WebFetch(domain:malicious-site.com)" ] } } ``` ### MCP 도구 권한 ```json { "permissions": { "allow": [ "mcp__github__list_prs", "mcp__github__get_issue", "mcp__context7__get-library-docs" ], "deny": [ "mcp__github__delete_*" ] } } ``` --- ## 설정 파일 계층 권한은 여러 레벨에서 설정 가능: ### 1. 사용자 전역 설정 `~/.claude/settings.json`: ```json { "permissions": { "allow": [ "Bash(npm:*)", "Bash(git:*)" ] } } ``` 모든 프로젝트에 적용 ### 2. 프로젝트 설정 (팀 공유) `.claude/settings.json`: ```json { "permissions": { "allow": [ "Bash(npm run dev:*)", "Bash(npm run build:*)", "Bash(npm test:*)" ] } } ``` Git으로 팀과 공유 ### 3. 프로젝트 로컬 설정 (개인) `.claude/settings.local.json`: ```json { "permissions": { "allow": [ "Bash(npm run deploy:*)" ] } } ``` Git에서 제외, 개인 설정 ### 우선순위 ``` 로컬 설정 > 프로젝트 설정 > 사용자 설정 ``` --- ## 실전 권한 설정 예제 ### 웹 프론트엔드 프로젝트 ```json { "permissions": { "allow": [ "Bash(npm run:*)", "Bash(npx:*)", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git add:*)", "Bash(git commit:*)", "WebFetch(domain:*.npmjs.com)", "WebFetch(domain:docs.*.com)" ], "deny": [ "Bash(npm publish:*)", "Bash(git push:*)", "Bash(rm -rf:*)" ] } } ``` ### Node.js API 서버 ```json { "permissions": { "allow": [ "Bash(npm run:*)", "Bash(prisma:*)", "Bash(docker compose:*)", "Bash(curl localhost:*)", "mcp__postgres__*" ], "deny": [ "Bash(prisma migrate deploy:*)", "Bash(docker push:*)", "Write(**/prisma/migrations/**)" ] } } ``` ### 보안 감사 프로젝트 ```json { "permissions": { "allow": [ "Read(*:*)" ], "deny": [ "Write(*:*)", "Bash(*:*)" ] } } ``` --- ## Sandbox 모드 더 강력한 격리가 필요할 때: ``` /sandbox ``` ### Sandbox 제한 사항 - 파일 시스템: 엄격히 제한 - 네트워크: 완전 차단 - 시스템 접근: 불가 - 외부 프로세스: 제한 ### 사용 시점 - 신뢰할 수 없는 코드 분석 - 악성 코드 샘플 검토 - 보안 테스트 --- ## 위험한 옵션 (주의) ### --dangerously-skip-permissions 모든 권한 검사 건너뛰기: ```bash claude -p "작업" --dangerously-skip-permissions ``` **⚠️ 경고:** - 신뢰할 수 있는 환경에서만 사용 - CI/CD 환경 또는 개인 스크립트용 - 공유 시스템에서 절대 사용 금지 --- ## 보안 베스트 프랙티스 ### 1. 최소 권한 원칙 ```json // 나쁜 예: 너무 넓은 권한 { "allow": ["Bash(*:*)"] } // 좋은 예: 필요한 것만 { "allow": [ "Bash(npm run build:*)", "Bash(npm test:*)" ] } ``` ### 2. 환경 분리 ```bash # 개발용 API 키 export ANTHROPIC_API_KEY_DEV="dev-key" # 프로덕션용 API 키 (별도 관리) # 프로덕션에서는 다른 권한 설정 사용 ``` ### 3. 민감 파일 보호 ```json { "permissions": { "deny": [ "Read(**/.env*)", "Read(**/*secret*)", "Read(**/*credential*)", "Read(**/*.pem)", "Read(**/*.key)", "Write(**/node_modules/**)" ] } } ``` ### 4. Plan 모드 활용 새 코드베이스 탐색 시: ```bash claude -p "이 프로젝트 분석해줘" --permission-mode plan ``` ### 5. 정기 감사 ```bash # 권한 설정 확인 claude /permissions # 사용 로그 확인 (hooks로 설정한 경우) cat ~/.claude/audit.log ``` ### 6. 외부 콘텐츠 주의 웹에서 가져온 코드 실행 전 검토: ``` # 나쁜 예 이 스크립트를 실행해줘: [웹에서 가져온 코드] # 좋은 예 이 스크립트를 분석해줘: [웹에서 가져온 코드] [분석 확인 후] 실행해도 될까? ``` --- ## 권한 관련 에러 처리 ### 권한 거부됨 ``` Permission denied: Bash(dangerous-command) ``` 해결: 1. 명령이 정말 필요한지 확인 2. 필요하다면 `settings.json`에 추가 3. 또는 해당 세션에서만 승인 ### 보호된 경로 ``` Cannot write to protected path: /etc/passwd ``` 해결: - 쓰기 경계 내 경로 사용 - 또는 명시적으로 허용 (주의 필요) --- ## 다음 단계 v9에서는 보안과 권한 설정을 다뤘습니다. **다음 v10 (마지막)에서는**: - 고급 설정 및 팁 - 전체 기능 요약 - 유용한 워크플로우 - 트러블슈팅 을 정리합니다. --- ## 빠른 참조 ``` Permission 모드: Ask 매번 승인 (기본) Auto 자동 승인 Plan 읽기 전용 모드 전환: Shift+Tab 또는 Alt+M (세션 내) --permission-mode [mode] (CLI) 권한 확인: /permissions 설정 파일: ~/.claude/settings.json 사용자 전역 .claude/settings.json 프로젝트 (팀) .claude/settings.local.json 프로젝트 (개인) 권한 패턴: Bash(command:*) 명령 허용/차단 Read(path:*) 읽기 허용/차단 Write(path:*) 쓰기 허용/차단 WebFetch(domain:host) 웹 접근 허용/차단 mcp__server__tool MCP 도구 허용/차단 Sandbox 모드: /sandbox 강화된 격리 실행 ``` --- *Claude CLI 완전 가이드 시리즈 v9/10*