Claude Code 권한 시스템 전체 구조, settings.json allow/deny 설정, --dangerously-skip-permissions 사용 기준, 샌드박스 실행, MCP 보안까지 실무 보안 가이드.
Claude Code 가이드 #17 — Claude Code를 프로덕션 워크플로우나 CI/CD 파이프라인에 연결하려다 "어디까지 허용해야 하나"에서 막힌 경험이 있나요? 이 편에서는 Claude Code의 권한 시스템 전체 구조, 안전한 설정 방법, 그리고 실무에서 쓰는 보안 Best Practice를 정리합니다.
† 이 글은 2026년 3월 기준, Claude Code 공식 Permissions 문서 기반으로 작성됐습니다.
Claude Code는 실행 중에 파일 읽기/쓰기, 셸 명령 실행, 외부 API 호출 등 다양한 작업을 수행합니다. 이 모든 작업은 권한 시스템(Permission System)을 통해 제어됩니다.
권한 체계는 크게 세 레이어로 구성됩니다:
| 레이어 | 위치 | 적용 범위 |
|---|---|---|
| 글로벌 설정 | ~/.claude/settings.json | 모든 프로젝트에 기본 적용 |
| 프로젝트 설정 | .claude/settings.json | 해당 프로젝트에서만 적용 (글로벌 덮어쓰기) |
| 실행 플래그 | --dangerously-skip-permissions | 해당 세션 전체의 권한 확인 우회 |
권한 설정의 우선순위는 실행 플래그 > 프로젝트 설정 > 글로벌 설정 순입니다. 프로젝트 설정이 있으면 글로벌 설정보다 우선 적용됩니다.
.claude/settings.json은 레포지토리에 커밋할 수 있습니다. 팀 전체에 공통 권한 규칙을 적용할 때 유용하지만, 신뢰할 수 없는 레포를 클론한 뒤 Claude Code를 실행하면 레포의 settings.json이 자동으로 로드됩니다. 외부 레포 작업 시 반드시 이 파일을 먼저 확인하세요.Claude Code에는 실행 시 적용되는 4가지 권한 모드가 있습니다. 상황에 따라 맞는 모드를 선택해야 합니다.
| 모드 | 파일 수정 | 셸 실행 | 사용 시나리오 |
|---|---|---|---|
| Ask permissions (기본) | 승인 요청 | 승인 요청 | 일반 개발, 처음 사용 시 |
| Auto accept edits | 자동 승인 | 승인 요청 | 파일 작업이 많은 반복 작업 |
| Plan mode | 불가 | 불가 | 계획 수립, 코드 리뷰 전용 |
| dontAsk (skip-permissions) | 자동 승인 | 자동 승인 | 신뢰된 로컬 환경 자동화 |
실무에서는 대부분 Ask permissions(기본) 또는 allowedTools를 이용한 선택적 허용 조합으로 운영하는 것이 가장 균형 잡힌 선택입니다.
settings.json의 permissions 블록으로 도구별 허용/거부 규칙을 정밀하게 제어할 수 있습니다.
~/.claude/settings.json 또는 .claude/settings.json 기본 구조{ "permissions": { "allow": [ "Read", "Edit", "Write", "Bash(git status)", "Bash(git diff *)", "Bash(node --check *)" ], "deny": [ "Bash(rm *)", "Bash(curl *)", "Bash(wget *)" ] } }
allow와 deny 규칙은 다음 우선순위로 적용됩니다:
deny 목록에 있으면 무조건 차단allow 목록에 있으면 자동 승인도구 이름 패턴:
Read, Edit, Write — 파일 관련 도구Bash(명령어 패턴) — 셸 명령. *는 와일드카드WebFetch, WebSearch — 외부 네트워크 접근mcp__서버명__도구명 — MCP 서버 도구실전 예시 — 콘텐츠 생성 프로젝트용 설정// .claude/settings.json (프로젝트 레벨) { "permissions": { "allow": [ "Read", "Edit", "Write", "Bash(node --check *)", "Bash(git status)", "Bash(git diff *)", "Bash(git log *)" ], "deny": [ "Bash(rm *)", "Bash(git push *)", "Bash(git reset *)", "WebFetch", "WebSearch" ] } }
deny 목록에 Bash(rm *)를 추가해도 Bash(rm -rf /)까지 모두 막을 수 있는 것은 아닙니다. Bash(*) 전체 거부 후 필요한 명령만 allow에 추가하는 화이트리스트 방식이 보안상 더 안전합니다.--dangerously-skip-permissions는 Claude Code의 모든 권한 확인을 비활성화하는 플래그입니다. 이름에 "dangerously"가 붙은 이유는 실제로 위험하기 때문입니다.
rm, curl, git push 포함)이 플래그를 사용하면 Claude Code가 사용자 개입 없이 모든 작업을 자동으로 진행합니다.
| ✅ 사용해도 되는 상황 | ❌ 절대 사용 금지 |
|---|---|
| 로컬 개발 머신 개인 작업 | 프로덕션 서버 |
| 신뢰된 프로젝트 반복 유지보수 | CI/CD 자동화 파이프라인 |
| 광고 축소, H2 재작성 등 단순 수정 | 외부에서 받은 레포 |
| 검증 스크립트 일괄 실행 | 여러 사람이 접근하는 공유 환경 |
skip-permissions 실행 방법# 기본 사용 claude --dangerously-skip-permissions # Agent Teams와 함께 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --dangerously-skip-permissions # settings.json에서 팀 전체에 적용 (권장하지 않음) # 대신 allowedTools 방식 사용 권장
--dangerously-skip-permissions로 열면, 레포에 포함된 .claude/settings.json이나 .mcp.json의 악의적 설정이 자동 실행될 수 있습니다. 신뢰할 수 없는 레포에서는 이 플래그를 절대 사용하지 마세요. Claude Code를 열기 전에 .claude/ 디렉토리와 .mcp.json을 먼저 확인하세요.Claude Code 자체에는 OS 수준의 샌드박스가 없습니다. 즉, Claude Code가 실행하는 셸 명령은 현재 사용자의 권한으로 그대로 실행됩니다. 이를 보완하는 방법이 몇 가지 있습니다.
Claude Code를 Docker 컨테이너 내부에서 실행하면, 호스트 시스템과 격리됩니다.
Docker 컨테이너에서 Claude Code 실행# 프로젝트 디렉토리를 컨테이너에 마운트하고 실행 docker run -it --rm \ -v $(pwd):/workspace \ -w /workspace \ node:20 \ bash -c "npm install -g @anthropic-ai/claude-code && claude" # API 키는 환경변수로 전달 docker run -it --rm \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -v $(pwd):/workspace \ -w /workspace \ node:20 \ bash -c "npm install -g @anthropic-ai/claude-code && claude --dangerously-skip-permissions"
Docker 격리 실행의 장점:
Docker 없이도 settings.json의 allowedTools로 실행 가능한 명령을 최소화할 수 있습니다.
--dangerously-skip-permissions로 실행할 때는 반드시 Docker 컨테이너 안에서 실행하거나, allowedTools를 엄격하게 제한해야 합니다. PR 이벤트를 트리거로 쓰면 외부 기여자의 PR에 포함된 악의적 코드가 실행될 수 있습니다.Claude Code를 팀 환경이나 자동화 파이프라인에서 안전하게 운영하기 위한 실전 체크리스트입니다.
ANTHROPIC_API_KEY는 절대 코드에 하드코딩하지 마세요~/.zshrc 또는 ~/.bashrc에 export로 설정.env 파일에 넣더라도 반드시 .gitignore에 추가.claude/settings.json을 팀 레포에 커밋할 때는 반드시 팀 리뷰 거치기.claude/settings.json 내용 확인 필수deny 블록에 파괴적 명령어 명시적으로 추가allow에 추가 (최소 권한 원칙)프로덕션/리뷰 전용 settings.json — Plan mode 강제// .claude/settings.json (프로덕션 브랜치용) { "permissions": { "allow": [ "Read" ], "deny": [ "Edit", "Write", "Bash(*)", "WebFetch", "WebSearch" ] } } // Read만 허용 → 코드 읽기/분석만 가능, 어떤 변경도 불가
MCP(Model Context Protocol) 서버를 연결하면 Claude Code의 권한 범위가 MCP 서버가 제공하는 도구까지 확장됩니다. MCP 서버 관련 보안 주의사항입니다.
.mcp.json은 레포 루트에 위치하며, .claude/settings.json과 마찬가지로 외부 레포 클론 시 자동 로드됩니다.permissions.deny에 mcp__서버명__* 패턴으로 특정 MCP 서버 전체를 차단할 수 있습니다.MCP 도구 차단 예시 — settings.json{ "permissions": { "deny": [ "mcp__filesystem__write_file", "mcp__filesystem__delete_file", "mcp__github__create_or_update_file" ] } }
settings.json의 allow 블록에 필요한 도구만 명시적으로 추가하는 화이트리스트 방식을 권장합니다. 기본적으로 모든 MCP 도구를 deny하고, 필요한 것만 추가하는 패턴이 가장 안전합니다.권한 설정 중 자주 발생하는 문제와 해결법입니다.
allow에 추가했는데도 계속 승인을 요청함 — 도구 이름 오타가 원인인 경우가 많습니다. Bash(node --check *)처럼 공백과 와일드카드를 정확히 맞춰야 합니다. Claude Code를 시작할 때 --debug 플래그를 추가하면 어떤 도구 이름으로 요청되는지 확인할 수 있습니다.deny에 추가했는데도 실행이 됨 — 글로벌 설정(~/.claude/settings.json)의 allow가 프로젝트 settings.json의 deny보다 우선되는 경우가 있습니다. 프로젝트 설정이 글로벌 설정을 완전히 덮어쓰는지 확인하거나, 실행 플래그를 사용하세요.정리하면:
settings.json의 allow/deny로 도구별 허용/차단을 세밀하게 제어--dangerously-skip-permissions는 신뢰된 로컬 환경에서만 사용Bash(*) deny 후 필요한 것만 allow)이 가장 안전한 설정관련 가이드: