권한·보안·샌드박스: 허용 목록부터 Skip-permissions까지
'생산성'의 전제는 통제 가능성이다
Claude Code는 단순히 "답을 주는 도구"가 아니라, 파일을 읽고 고치고 명령을 실행하는 행동하는 에이전트입니다. 그래서 팀에서 안전하게 쓰려면 속도보다 먼저 "누가, 무엇을, 어디까지 자동화할지"가 합의돼야 합니다. 권한 시스템은 그 합의를 코드로 고정해 주는 장치이고, 샌드박스는 혹시 권한이 뚫리거나 사람이 실수로 승인하더라도 피해 범위를 줄이는 장치입니다. 두 개를 함께 쓰는 순간, 자동화는 '빠른데 불안한 요행'이 아니라 통제 가능한 자동화가 됩니다.1
이 챕터는 세 가지를 목표로 합니다.
퍼미션 규칙(allow/ask/deny) 과 퍼미션 모드(default/acceptEdits/plan/dontAsk/bypassPermissions) 를 구분해 이해한다.1
allowedTools/permissions.allow를 패턴 기반 허용 목록(allowlist) 으로 설계하는 방법을 익힌다.1위험 작업을 격리(샌드박스, 작업공간 경계, 네트워크 제한) 하는 원칙을 정리한다.12
권한 시스템의 뼈대: 규칙(allow/ask/deny)과 우선순위
Claude Code의 권한은 "도구(tool) 호출" 단위로 통제됩니다. 파일 읽기(Read), 파일 수정(Edit), 쉘 실행(Bash), 웹 요청(WebFetch), MCP 도구, 서브에이전트까지 모두 규칙 기반으로 허용/질문/차단 할 수 있습니다.1
핵심은 규칙이 세 종류라는 점입니다.
allow: 해당 도구/패턴은 묻지 않고 실행
ask: 해당 도구/패턴은 매번 확인
deny: 해당 도구/패턴은 완전 차단
그리고 실제 판단은 "선언 순서"가 아니라 우선순위로 결정됩니다. 공식 문서는 규칙 평가를 deny → ask → allow 로 설명하며, 첫 매칭 규칙이 승리하고 deny가 항상 최우선이라고 못 박습니다.1
이 모델이 팀 운영에서 중요한 이유는 간단합니다. 넓게 허용하더라도 일부만 예외로 차단할 수 있고(예: Bash(git *)는 허용하되 Bash(git push *)는 deny), 반대로 어떤 작업은 습관적 승인(자동화) 대신 반드시 사람이 확인하도록 ask로 고정할 수 있습니다.1
퍼미션 "모드"는 세션의 기본 태도다
규칙이 '정책(what)'이라면, 모드는 '기본 태도(how often)'입니다. 공식 문서는 defaultMode로 기본 모드를 지정할 수 있고, 다음 모드들을 제공합니다.1
default: 읽기는 기본 허용, 나머지 도구는 첫 사용 등 상황에 따라 승인 흐름이 개입되는 표준 동작
acceptEdits: 세션 동안 파일 수정(Edit) 승인을 자동 수락(명령 실행은 여전히 승인 흐름이 개입)
plan: 분석/탐색 전용(파일 수정과 명령 실행 불가)
dontAsk: 사전 승인(allow 규칙 등)된 것만 실행, 나머지는 자동 거부
bypassPermissions: 모든 권한 프롬프트를 스킵("안전한 환경에서만" 사용하라는 경고 포함)
팀 관점에서 권장되는 모드 운용은 대체로 이렇습니다.
새로운 저장소/외부 PR/낯선 레거시를 처음 열면 plan으로 시작해 "읽기만" 허용합니다.1
구현 단계에서 반복적인 파일 수정 승인에 피로가 쌓이면 acceptEdits로 전환하되, Bash/WebFetch/MCP는 계속 통제합니다.1
사람이 중간에 끼지 않는 자동화가 필요하면 dontAsk + 명시적 allowlist 로 설계해, 허용된 것만 조용히 실행되게 만듭니다.1
bypassPermissions또는--dangerously-skip-permissions는 "속도"가 아니라 "격리"가 준비된 경우에만 허용합니다(뒤에서 체크리스트로 다룹니다).13
allowedTools/allow 규칙: '허용 목록'이 자동화를 만든다
권한을 잘 쓰면 프롬프트를 덜 보면서도 안전해집니다. 요령은 간단합니다.
자주 반복되는 "안전한 작업"만 allow로 올립니다. 예: 테스트, 린트, 포맷,
git status/diff/commit같은 로컬 작업.위험도가 높은 계열은 애초에 deny로 막아 "실수 승인"이 피해로 이어지지 않게 만듭니다. 예:
sudo,rm -rf, 프로덕션 배포/DB 접속.경계가 애매한 작업은 ask로 고정합니다. 예:
git push, 외부 네트워크 접속.
공식 문서에서 허용 목록은 permissions.allow/permissions.deny/permissions.ask 규칙으로 구성하며, /permissions 화면에서 현재 규칙과 출처(settings.json)를 확인할 수 있다고 설명합니다.1
Bash 패턴은 "명령문"을 매칭한다
Bash 규칙은 Bash(명령 패턴) 형태이며 * 와일드카드로 매칭 범위를 조절합니다.1
다만 Bash 매칭은 생각보다 미묘합니다. 예를 들어 Bash(ls *) 는 ls -la처럼 공백 뒤 인자를 요구하는 "단어 경계"가 생기지만, Bash(ls*) 는 lsof 같은 전혀 다른 명령까지 매칭될 수 있습니다.1
그래서 팀 규칙은 "큰 덩어리 허용 + 위험 작업 carve-out(deny)" 구조가 실전적입니다.
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(npm test *)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git commit *)"
],
"ask": [
"Bash(git push *)"
],
"deny": [
"Bash(git push --force *)",
"Bash(rm -rf *)",
"Bash(sudo *)"
]
}
}이 구성의 의도는 분명합니다. 로컬 검증과 커밋은 자동화하되, "외부로 나가는 행위(push)"와 "파괴적/권한 상승 행위"는 구조적으로 제동을 겁니다.1
Read/Edit는 gitignore 스타일로 '경계'를 만든다
Read/Edit 규칙은 Read(패턴), Edit(패턴) 형태이며, 경로 패턴은 gitignore와 유사한 규칙을 따릅니다. 절대경로(앞에 //), 홈 기준(~/), 프로젝트 루트 기준(/), 현재 디렉터리 기준(relative) 등을 구분합니다.1
이 기능은 "민감 정보가 있는 파일"을 정책으로 고정할 때 특히 유용합니다. 예를 들어 .env나 키 파일을 읽기/수정 모두 deny로 잠그면, 에이전트가 실수로라도 내용을 세션 컨텍스트에 실어 보내거나 값을 덮어쓰는 사고를 크게 줄일 수 있습니다.1
주의할 점도 있습니다. Read deny는 "Read 도구" 차단에 가깝고, Bash로 cat 같은 명령을 실행해 읽어버리면(사용자가 승인하면) 결국 컨텍스트에 들어올 수 있습니다. 즉 정책은 도구별로 따로 세워야 하고, 파일 보호는 Read만이 아니라 Bash/샌드박스까지 포함해 보완해야 합니다.4
WebFetch는 '도메인'으로 통제한다
외부 네트워크는 데이터 유출과 직결됩니다. WebFetch는 WebFetch(domain:example.com) 처럼 도메인 단위로 제한할 수 있습니다.1
실무에선 "Bash의 curl 허용" 같은 방식보다, WebFetch 도메인 allowlist + (가능하면) 샌드박스 네트워크 제한 조합이 더 예측 가능합니다. Bash 패턴만으로 URL을 안전하게 필터링하려 하면 옵션 순서, 변수 치환, 파이프라인 등으로 우회될 여지가 커지기 때문입니다.1
MCP/서브에이전트도 권한 대상으로 본다
MCP 도구는 mcp__서버명__도구명 패턴으로 통제할 수 있고, 서버 전체를 허용하거나 특정 도구만 허용할 수 있습니다.1
서브에이전트는 Agent(Explore) 같은 규칙으로 제어할 수 있으며, 필요하면 deny로 비활성화할 수도 있습니다.1
팀에서 중요한 포인트는 하나입니다. 확장 지점(MCP, 에이전트, 훅)은 곧 공격면입니다. 기능을 열수록 정책도 함께 버전 관리로 묶어야 합니다.
위험 작업 격리 원칙: '권한'만으로는 부족하다
권한은 강력하지만, 본질적으로 애플리케이션 레벨의 제어입니다. 그래서 보안은 "권한(의사결정)"과 "격리(강제력)"를 분리해 설계해야 합니다. 이때 샌드박스는 "잠재적으로 위험한 코드/명령을 격리된 환경에서 실행해 호스트와 네트워크에 미치는 영향을 제한하는 보안 통제"라는 기본 개념으로 이해하면 충분합니다.5
NVIDIA의 에이전트 워크플로 보안 가이드는 간접 프롬프트 인젝션(저장소/파일/설정/도구 응답에 섞인 악성 지시) 위험을 강조하면서, 다음과 같은 통제를 "필수 또는 강력 권장"으로 제시합니다.2
임의 사이트로의 네트워크 이그레스(Outbound) 차단/제한
작업공간(workspace) 밖으로의 파일 쓰기 차단
훅/MCP/에이전트 설정 등 구성 파일 쓰기 차단
이 원칙은 Claude Code에도 그대로 적용됩니다. 즉, 팀에서 에이전트를 운영한다는 건 "허용 목록을 만들었다"로 끝나지 않고, 피해 반경(blast radius)을 설계했다로 완성됩니다.
실전 체크리스트: 격리 경계를 설계하는 6가지 질문
아래 질문에 답하면, "이 자동화는 팀에서 감당 가능한가?"가 선명해집니다.
작업공간 밖 파일을 읽거나 쓸 이유가 있는가? 있다면 어떤 디렉터리까지인가?
.env, 키 파일, 자격증명, 설정 파일에 대해 Read/Edit 모두 deny가 되어 있는가?네트워크는 어떤 도메인만 필요하며, 그 외는 막히는가?
프로덕션과 연결되는 경로(배포, DB, SSH)는 deny 또는 ask로 고정되어 있는가?
훅(PreToolUse 등)과 MCP 서버는 누가 승인·배포하고, 누가 수정할 수 있는가?
만약 모든 것이 잘못됐을 때, 복구는 가능한가? (커밋/백업/컨테이너 폐기)
공식 문서는 권한과 샌드박스가 상호 보완적인 보안 계층이며, 샌드박스는 Bash 및 자식 프로세스의 파일시스템·네트워크 접근을 OS 레벨에서 제한한다고 설명합니다.1
Skip-permissions(=bypassPermissions / --dangerously-skip-permissions)를 쓰는 기준
bypassPermissions(또는 CLI의 --dangerously-skip-permissions)는 말 그대로 모든 권한 프롬프트를 제거합니다.13 따라서 "편해서" 쓰기 시작하면, 팀 운영에서는 필연적으로 사고 확률이 올라갑니다.
그럼에도 필요한 순간이 있습니다. 예를 들어 CI에서 짧은 작업을 완전 자동으로 실행해야 하거나, 폐기 가능한 컨테이너 안에서 대규모 리팩터를 밤새 돌리고 싶을 때입니다. 이때 핵심은 하나입니다.
권한을 생략하는 대신, 환경이 강제력을 가져야 한다.
즉 Skip-permissions를 쓰려면 최소한 다음 조건을 갖추는 쪽이 안전합니다.
호스트와 분리된 컨테이너/VM 등 격리된 실행 환경
외부로 나가는 네트워크가 제한되거나, 필요한 도메인만 허용된 환경
작업 결과가 버전 관리로 롤백 가능한 흐름(작업 전 커밋, 브랜치/워크트리)
또한 조직에서는 아예 이 모드를 금지할 수 있습니다. 공식 문서는 managed settings에서 disableBypassPermissionsMode를 "disable"로 설정해 bypassPermissions 및 --dangerously-skip-permissions를 차단할 수 있다고 명시합니다.1
팀 배포: 설정 계층과 "관리형(Managed) 정책"
팀에서 권한이 강력해지는 지점은 "버전 관리에 올릴 수 있다"는 사실입니다. 프로젝트의 .claude/settings.json을 저장소에 커밋하면, 신규 합류자도 동일한 안전장치를 바로 갖게 됩니다.1
공식 문서는 설정 우선순위를 다음처럼 설명합니다.1
Managed settings(조직 정책): 최상위, 어떤 설정으로도 덮을 수 없음
CLI 인자: 세션 한정
로컬 프로젝트 설정: 개인용(
.claude/settings.local.json)공유 프로젝트 설정: 팀용(
.claude/settings.json)유저 설정: 개인 전역(
~/.claude/settings.json)
그리고 중요한 규칙이 하나 더 있습니다. 어느 레벨에서든 deny는 다른 레벨에서 allow로 뒤집을 수 없습니다. 즉, 조직이 관리형 정책으로 막아둔 도구는 사용자가 --allowedTools를 줘도 못 엽니다.1
또한 managed-only로만 동작하는 옵션들이 있습니다. 예를 들어 다음 설정들은 "정책을 정책답게" 만들어 줍니다.
allowManagedPermissionRulesOnly: 사용자/프로젝트가 임의로 allow/ask/deny를 추가하지 못하게 함allowManagedHooksOnly: 사용자/프로젝트 훅 로딩 차단allowManagedMcpServersOnly: MCP 서버를 관리형 allowlist로만 제한sandbox.network.allowManagedDomainsOnly: 네트워크 허용 도메인을 관리형 정책으로만 인정
팀에서 '통제 가능한 자동화'를 목표로 한다면, 최소한 "프로덕션/외부 네트워크/권한 상승"에 해당하는 규칙은 managed 또는 공유 프로젝트 설정으로 고정해두는 편이 운영 비용이 낮습니다.1
운영 팁: 권한은 '한 번 만들고 끝'이 아니다
1) /permissions로 현재 적용 규칙을 수시로 점검한다
Claude Code는 /permissions에서 현재 활성 규칙과 그 규칙이 어느 settings 파일에서 왔는지를 보여줍니다.1 팀 규칙이 기대대로 적용되는지(로컬 오버라이드가 섞이지 않았는지) 가장 먼저 확인할 곳입니다.
2) 훅(PreToolUse)으로 "정적 규칙을 넘어" 런타임 게이트를 만든다
공식 문서는 PreToolUse 훅이 권한 시스템보다 먼저 실행되어, 도구 호출을 승인/거부하는 결정을 대체할 수 있다고 설명합니다.1 정적 패턴만으로는 커버하기 어려운 정책(예: 특정 경로 조합, 특정 브랜치에서만 제한, PR 번호가 없는 gh 명령 차단 등)을 훅으로 보완할 수 있습니다.
3) 작업 디렉터리 확장은 최소화한다
Claude Code는 기본적으로 "시작한 디렉터리"에 접근하며, --add-dir 또는 /add-dir로 범위를 늘릴 수 있습니다.1 범위가 넓어질수록 실수의 피해 반경도 넓어집니다. 정말 필요한 디렉터리만 추가하고, 추가 디렉터리에도 동일한 Read/Edit 정책을 적용하는 흐름이 좋습니다.1
참고
1Configure permissions - Claude Code Docs
2Practical Security Guidance for Sandboxing Agentic Workflows and Managing Execution Risk
3Claude Code --dangerously-skip-permissions: 5 Modes, Only 1 Nuclear
4Understanding Claude Code Permissions and Security Settings
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.