새소식
300x250
AI/Claude Code Doc(공식문서) 번역본
Claude Code 공식문서 리뷰-Administration[3] : Claude Code 설정 - 보안(Security)
- -
728x90
안녕하세요! 갓대희입니다.
Claude Code Docs 공식 문서 >> [관리] 섹션의 내용 중 [Claude Code 설정 - 보안(Security)]를 살펴 보려고 합니다.
이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.
https://code.claude.com/docs/ko/security
보안 - Claude Code Docs
Claude Code의 보안 보호 기능과 안전한 사용을 위한 모범 사례에 대해 알아보세요.
code.claude.com
이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.
저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.
Claude Code 보안
보안 아키텍처, 내장 보호 기능, 모범 사례
보안 모델: Claude Code는 "명시적 승인" 원칙을 따른다. 기본적으로 읽기 전용이며, 파일 수정이나 명령어 실행 같은 민감한 작업은 사용자의 명시적 승인이 필요하다.
보안 설정 시작하기
Claude Code를 처음 사용하거나 보안 설정을 점검하려는 경우, 다음 단계를 따른다.
Step 1: 현재 권한 설정 확인
먼저 현재 설정된 권한을 확인한다:
# Claude Code 내에서 실행
/permissions
# 출력 예시:
# Allowed tools:
# - Read (always allowed)
# - Glob (always allowed)
# - Grep (always allowed)
#
# Allowed commands:
# - npm test
# - npm run build
# - git status
Step 2: 샌드박스 모드 활성화 (권장)
자율 작업 시 파일 시스템과 네트워크를 격리하려면 샌드박스를 활성화한다:
# 샌드박스 모드 활성화
/sandbox
# 특정 디렉토리로 작업 범위 제한
/sandbox /path/to/project
Step 3: 프로젝트별 설정 구성
민감한 프로젝트는 .claude/settings.json으로 별도 권한을 설정할 수 있다:
// .claude/settings.json
{
"permissions": {
"allow": [
"npm test",
"npm run lint"
],
"deny": [
"rm -rf",
"curl",
"wget"
]
}
}
Step 4: 정기적인 권한 감사
허용된 명령어 목록이 너무 많아지지 않도록 정기적으로 점검한다:
# 현재 권한 목록 확인
/permissions
# 불필요한 권한이 있다면 설정 파일에서 제거
# ~/.claude/settings.json 또는 .claude/settings.json 수정
핵심 보안 아키텍처
권한 기반 모델
Claude Code의 권한 시스템은 다음 원칙을 따른다:
사용자 책임: Claude Code는 사용자가 부여한 권한만 가진다. 제안된 코드와 명령어가 안전한지 승인 전에 반드시 검토해야 한다.
상황별 보안 설정 가이드
상황 1: 개인 프로젝트에서 사용
개인 학습이나 사이드 프로젝트에서는 기본 설정으로 충분하다.
상황 2: 팀 프로젝트에서 사용
팀원 간 일관된 보안 정책이 필요하다.
상황 3: 민감한 프로덕션 코드 작업
프로덕션 환경이나 보안이 중요한 코드는 더 엄격한 설정이 필요하다.
주의 (-p 플래그): 비대화형 모드(
claude -p "...")로 실행하면 Trust verification이 비활성화된다. 자동화 스크립트에서 사용할 때 특히 주의가 필요하다.
내장 보호 기능
1. 샌드박스 Bash 도구
- 파일 시스템과 네트워크 격리
- 보안을 유지하면서 권한 프롬프트 줄임
/sandbox명령으로 자율 작업 범위 정의
2. 쓰기 접근 제한
[쓰기 가능] Claude Code가 시작된 폴더와 하위 폴더
[쓰기 불가] 상위 디렉토리 (명시적 권한 없이)
[읽기 가능] 작업 디렉토리 외부 파일 (시스템 라이브러리/의존성용)
3. 권한 피로 완화
자주 사용하는 안전한 명령어를 허용 목록에 추가할 수 있다:
- 사용자별 설정 (
~/.claude/settings.json) - 코드베이스별 설정 (
.claude/settings.json) - 조직별 설정 (Enterprise)
4. Accept Edits 모드
- 여러 편집을 일괄 승인
- 부작용이 있는 명령어는 여전히 권한 프롬프트 유지
실전 팁: Accept Edits 모드는 리팩토링처럼 많은 파일을 수정할 때 유용하다. 하지만 외부 명령어 실행은 여전히 개별 승인이 필요하므로 안전하다.
5. 자연어 명령어 설명
복잡한 bash 명령어의 경우 Claude Code가 자연어로 설명을 제공한다. 예를 들어:
명령어: find . -name "*.log" -mtime +30 -delete
설명: "현재 디렉토리에서 30일 이상 된 .log 파일을 찾아 삭제합니다"
이를 통해 승인 전에 명령어가 어떤 동작을 하는지 이해할 수 있다.
프롬프트 인젝션 보호
핵심 보호 기능
추가 보호 장치
Privacy Safeguards (개인정보 보호)
Claude Code는 사용자 데이터 보호를 위해 다음 조치를 취한다:
자세한 내용은 다음 문서를 참조한다:
- Commercial Terms of Service (Team, Enterprise, API 사용자)
- Consumer Terms (Free, Pro, Max 사용자)
- Privacy Policy
MCP 보안
Model Context Protocol (MCP) 서버 관련 보안 고려사항:
주의: Anthropic은 MCP 서버를 관리하거나 감사하지 않는다. 신뢰할 수 있는 서버만 사용하거나 직접 작성하는 것을 권장한다.
IDE 보안
VS Code 등 IDE에서 Claude Code를 실행할 때의 보안 정보는 VS Code 보안 섹션을 참조한다.
클라우드 실행 보안
웹에서 Claude Code를 실행할 때의 보안 기능:
보안 모범 사례
민감한 코드 작업 시
- 모든 제안된 변경사항을 승인 전 검토
- 민감한 저장소에는 프로젝트별 권한 설정 사용
- 격리를 위해 devcontainer 사용 고려
/permissions로 정기적으로 권한 감사
팀 보안
- 엔터프라이즈 관리 설정으로 조직 표준 적용
- 버전 컨트롤을 통해 승인된 권한 설정 공유
- 팀원에게 보안 모범 사례 교육
- OpenTelemetry 메트릭으로 사용량 모니터링
신뢰할 수 없는 콘텐츠 작업 시
- 승인 전 제안된 명령어 검토
- 신뢰할 수 없는 콘텐츠를 Claude에 직접 파이프하지 않기
- 중요 파일에 대한 제안된 변경사항 검증
- 외부 웹 서비스가 포함된 스크립트는 가상 머신에서 실행
/bug로 의심스러운 동작 신고
트러블슈팅
문제 1: 명령어가 계속 차단됨
증상: 자주 사용하는 안전한 명령어인데도 매번 승인을 요청한다.
해결 방법:
// .claude/settings.json에 허용 명령어 추가
{
"permissions": {
"allow": [
"npm test",
"npm run build",
"python -m pytest"
]
}
}
문제 2: curl/wget이 필요한데 차단됨
증상: API 테스트 등을 위해 curl이 필요하지만 기본적으로 차단되어 있다.
해결 방법:
- 정말 필요한 경우에만 허용 목록에 추가
- 허용 시 권한 패턴 제한 사항을 이해하고 사용
// 특정 도메인으로 제한된 curl만 허용 (예시)
{
"permissions": {
"allow": [
"curl https://api.example.com/*"
]
}
}
주의: curl과 wget은 임의의 웹 콘텐츠를 가져올 수 있어 프롬프트 인젝션 위험이 있다. 꼭 필요한 경우에만 허용하고, 가능하면 특정 URL로 범위를 제한한다.
문제 3: MCP 서버를 신뢰할 수 있는지 판단이 어려움
증상: 외부 MCP 서버를 사용하고 싶은데 안전한지 확신이 없다.
해결 방법:
- 공식 또는 검증된 MCP 서버만 사용
- 소스 코드를 직접 검토
- 확실하지 않으면 직접 MCP 서버 작성
- MCP 서버별로 권한을 최소화하여 설정
문제 4: 파일 쓰기 권한 오류
증상: 특정 디렉토리에 파일을 쓰려는데 권한이 없다는 오류가 발생한다.
원인: Claude Code는 시작 디렉토리와 그 하위 폴더에만 쓰기 권한이 있다.
해결 방법:
- 작업할 프로젝트의 루트 디렉토리에서 Claude Code를 시작
- 상위 디렉토리 접근이 필요한 경우 명시적 권한 부여
중요 경고: Windows WebDAV
경고: WebDAV를 활성화하거나 Claude Code가
\\* 경로에 접근하도록 허용하지 않는다. WebDAV는 보안 위험으로 인해 Microsoft에서 사용 중단되었으며, 권한 시스템을 우회하는 네트워크 요청을 트리거할 수 있다.
보안 문제 신고
보안 취약점을 발견한 경우:
보안 점검 체크리스트
프로젝트 시작 전 또는 정기적으로 다음 항목을 확인한다:
관련 문서
300x250
'AI > Claude Code Doc(공식문서) 번역본' 카테고리의 다른 글
Contents
소중한 공감 감사합니다