권한 시스템과 보안

Published: at 07:41 AM

들어가며

이전 차시에서 Claude Code의 내장 도구 6가지를 살펴봤다. 도구 중에는 자동으로 실행되는 것(Read, Glob, Grep)과 사용자 승인이 필요한 것(Edit, Write, Bash)이 있었다. 이 구분이 바로 권한 시스템의 일부다.

Claude Code는 강력한 도구다. 파일을 수정하고, 명령을 실행하고, 패키지를 설치할 수 있다. 그만큼 안전장치가 필요하다. Claude Code의 권한 시스템은 “무엇을 자동으로 허용하고, 무엇을 사용자에게 물어보고, 무엇을 차단할 것인가”를 제어한다.

이번 차시에서는 권한 모드의 종류와 차이점, 도구별 권한 규칙 설정 방법, 그리고 샌드박스를 활용한 OS 수준의 보안까지 다룬다.

권한 시스템 개요

기본 원칙

Claude Code의 권한 시스템은 세 가지 원칙을 따른다.

  1. 읽기는 안전 → 자동 승인
  2. 파일 수정은 주의 필요 → 사용자 승인
  3. 명령 실행은 위험할 수 있음 → 사용자 승인

이 원칙에 따라 도구 유형별 기본 동작이 정해진다.

도구 유형예시승인 필요”다시 묻지 않기” 동작
읽기 전용Read, Glob, Grep아니오해당 없음
Bash 명령셸 실행예프로젝트 디렉토리와 명령별로 영구 저장
파일 수정Edit, Write예세션 종료까지 유지

Bash 명령을 “다시 묻지 않기”로 승인하면, 해당 프로젝트 디렉토리에서 같은 명령을 다시 실행할 때 자동으로 승인된다. 이 설정은 세션이 끝나도 유지된다. 반면 파일 수정 승인은 현재 세션에서만 유효하다.

권한 규칙의 세 가지 유형

Claude Code의 권한 규칙은 세 가지로 나뉜다.

규칙은 deny → ask → allow 순서로 평가된다. deny 규칙이 항상 우선한다. 즉, allow 목록에 있더라도 deny 목록에도 있으면 차단된다.

현재 설정된 권한 규칙을 확인하려면 /permissions 명령을 사용한다. 이 UI에서 모든 권한 규칙과 해당 규칙이 어떤 설정 파일에서 온 것인지 확인할 수 있다.

권한 모드

권한 모드는 “Claude가 어떤 작업을 승인 없이 할 수 있는가”의 기본값을 결정한다. 모드에 따라 세션의 흐름이 달라진다. default 모드에서는 각 작업마다 사용자가 검토하고, 느슨한 모드에서는 Claude가 더 긴 시간 동안 중단 없이 작업한다.

6가지 모드 비교

모드승인 없이 실행되는 작업적합한 상황
default읽기만처음 사용, 민감한 작업
acceptEdits읽기, 파일 수정, 기본 파일시스템 명령코드를 리뷰하면서 반복 작업
plan읽기만변경 전 코드베이스 탐색
auto모든 것 (백그라운드 안전 검사 포함)긴 작업, 승인 피로 감소
dontAsk사전 승인된 도구만CI/CD 파이프라인, 스크립트
bypassPermissions보호 경로 외 모든 것격리된 컨테이너/VM 전용

어떤 모드에서든 보호 경로에 대한 쓰기는 자동 승인되지 않는다. .git, .vscode, .idea, .husky, .claude(일부 제외) 같은 디렉토리와 .bashrc, .zshrc, .gitconfig 같은 파일이 보호 대상이다.

모드 전환 방법

세션 중에 Shift+Tab을 누르면 default → acceptEdits → plan 순으로 순환한다. 시작할 때 특정 모드를 지정할 수도 있다.

# 시작 시 모드 지정
claude --permission-mode plan

# acceptEdits 모드로 시작
claude --permission-mode acceptEdits

기본 모드를 설정 파일에 저장할 수도 있다.

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

VS Code에서는 프롬프트 박스 하단의 모드 표시기를 클릭해서 전환한다. JetBrains에서는 CLI와 같은 방식으로 Shift+Tab을 사용한다.

default 모드

가장 안전한 모드다. 읽기 작업만 자동으로 실행되고, 파일 수정과 명령 실행은 모두 승인이 필요하다.

[Edit] src/components/Button.tsx

변경사항:
- const Button = (props) => {
+ const Button: React.FC<ButtonProps> = (props) => {

이 변경사항을 적용할까요? [y/n/e]

처음 Claude Code를 사용하거나, 프로덕션 코드를 다루거나, 중요한 프로젝트에서 작업할 때 적합하다.

acceptEdits 모드

파일 수정을 자동으로 승인한다. mkdir, touch, rm, mv, cp, sed 같은 기본 파일시스템 Bash 명령도 자동 승인된다. 단, 자동 승인은 작업 디렉토리 내부의 경로에만 적용된다. 그 외의 Bash 명령은 여전히 승인이 필요하다.

claude --permission-mode acceptEdits

코드를 수정한 후 에디터나 git diff로 나중에 확인하고 싶을 때 유용하다. 빠른 프로토타이핑이나 반복적인 개발 작업에 적합하다.

plan 모드

Claude가 코드를 분석하고 변경 계획을 세우지만, 실제로 파일을 수정하지 않는다. 파일을 읽고, 셸 명령을 실행해서 탐색하고, 계획을 작성한다.

claude --permission-mode plan

계획이 준비되면 Claude가 다음 단계를 제안한다.

큰 변경 전에 전체 그림을 먼저 파악하거나, 팀과 공유할 계획을 세울 때 유용하다. 단일 프롬프트에 /plan을 접두사로 붙여서 사용할 수도 있다.

auto 모드

모든 작업을 승인 없이 실행한다. 별도의 분류 모델이 각 작업을 실행 전에 검토해서, 요청 범위를 벗어나거나 인식되지 않은 인프라를 대상으로 하거나 악의적인 콘텐츠에 의한 것으로 보이면 차단한다.

auto 모드는 다음 조건을 모두 충족해야 사용할 수 있다.

claude --enable-auto-mode

기본적으로 차단되는 작업:

기본적으로 허용되는 작업:

auto 모드는 리서치 프리뷰 단계다. 승인 프롬프트를 줄여주지만, 안전성을 보장하지는 않는다. 민감한 작업에서는 다른 모드를 사용하는 것이 좋다.

dontAsk 모드

사전 승인된 도구만 실행하고, 나머지는 모두 자동 거부한다. permissions.allow 규칙에 매칭되는 작업만 실행 가능하다. CI 파이프라인이나 제한된 환경에서 완전히 비대화형으로 동작해야 할 때 사용한다.

claude --permission-mode dontAsk

bypassPermissions 모드

권한 프롬프트와 안전 검사를 모두 비활성화한다. 보호 경로에 대한 쓰기만 여전히 프롬프트가 표시된다. 컨테이너, VM, 인터넷 접근이 없는 devcontainer 같은 격리된 환경에서만 사용해야 한다.

claude --permission-mode bypassPermissions

이 모드는 프롬프트 인젝션이나 의도하지 않은 작업에 대한 보호를 제공하지 않는다. 관리자는 managed settings에서 permissions.disableBypassPermissionsMode를 "disable"로 설정해서 이 모드를 차단할 수 있다.

권한 규칙 설정

규칙 문법

권한 규칙은 Tool 또는 Tool(specifier) 형식을 따른다.

도구 전체 매칭:

규칙효과
Bash모든 Bash 명령에 매칭
WebFetch모든 웹 요청에 매칭
Read모든 파일 읽기에 매칭

지정자로 세밀하게 제어:

규칙효과
Bash(npm run build)정확히 npm run build 명령에만 매칭
Read(./.env)현재 디렉토리의 .env 파일 읽기에 매칭
WebFetch(domain:example.com)example.com으로의 요청에 매칭

와일드카드 패턴

Bash 규칙은 *를 사용한 글로브 패턴을 지원한다. 와일드카드는 명령의 시작, 중간, 끝 어디에든 올 수 있다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

* 앞의 공백이 중요하다. Bash(ls *)는 ls -la에 매칭되지만 lsof에는 매칭되지 않는다. 반면 Bash(ls*)는 ls -la와 lsof 모두에 매칭된다.

Claude Code는 셸 연산자(&&)를 인식하므로, Bash(safe-cmd *)라는 접두사 매칭 규칙이 safe-cmd && other-cmd 명령을 허용하지 않는다.

Read와 Edit 규칙

Read와 Edit 규칙은 gitignore 명세를 따르는 네 가지 패턴 유형을 지원한다.

패턴의미예시
//path파일시스템 루트에서 절대 경로Read(//Users/alice/secrets/**)
~/path홈 디렉토리 기준 경로Read(~/Documents/*.pdf)
/path프로젝트 루트 기준 상대 경로Edit(/src/**/*.ts)
path 또는 ./path현재 디렉토리 기준 상대 경로Read(*.env)

주의할 점은 /Users/alice/file이 절대 경로가 아니라 프로젝트 루트 기준 상대 경로라는 것이다. 절대 경로를 지정하려면 //Users/alice/file처럼 슬래시 두 개를 사용해야 한다.

Read와 Edit의 deny 규칙은 Claude의 내장 파일 도구에만 적용된다. Read(./.env) deny 규칙은 Read 도구를 차단하지만, Bash에서 cat .env 명령을 실행하는 것은 차단하지 못한다. 모든 프로세스에서 접근을 차단하려면 샌드박스를 사용해야 한다.

실전 권한 설정 예제

개발 환경용 설정:

{
  "permissions": {
    "allow": [
      "Bash(npm run test *)",
      "Bash(npm run lint *)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(git clean *)",
      "Edit(*.env)",
      "Edit(*.key)",
      "Edit(*.pem)"
    ]
  }
}

자주 사용하는 안전한 명령은 allow에, 위험한 명령은 deny에 추가한다. .env나 키 파일처럼 민감한 파일의 편집도 차단할 수 있다.

데이터베이스 안전 설정:

{
  "permissions": {
    "deny": [
      "Bash(*DROP*)",
      "Bash(*DELETE FROM*)",
      "Bash(*TRUNCATE*)"
    ]
  }
}

설정 우선순위

권한 규칙은 다른 Claude Code 설정과 같은 우선순위를 따른다.

  1. Managed settings: 다른 어떤 수준에서도 재정의할 수 없다
  2. CLI 인수: 임시 세션 오버라이드
  3. 로컬 프로젝트 설정 (.claude/settings.local.json)
  4. 공유 프로젝트 설정 (.claude/settings.json)
  5. 사용자 설정 (~/.claude/settings.json)

어떤 수준에서든 도구가 deny되면, 다른 수준에서 allow할 수 없다. 예를 들어, managed settings의 deny는 --allowedTools CLI 인수로 재정의할 수 없다.

Hooks로 권한 확장

Claude Code의 Hooks 기능을 사용하면 커스텀 권한 평가 로직을 추가할 수 있다. PreToolUse 훅은 도구 호출 전에 실행되어 호출을 거부하거나, 프롬프트를 강제하거나, 프롬프트를 건너뛸 수 있다.

프롬프트를 건너뛰어도 기존 권한 규칙을 무시하지는 않는다. 훅이 "allow"를 반환해도 deny 규칙이 여전히 적용된다. 반대로, 훅이 종료 코드 2로 차단하면 allow 규칙보다 우선한다.

예를 들어, 대부분의 Bash 명령은 프롬프트 없이 실행하되 특정 명령만 차단하려면, "Bash"를 allow 목록에 추가하고 해당 명령을 거부하는 PreToolUse 훅을 등록하면 된다.

샌드박스

샌드박스란

샌드박스는 Bash 명령의 파일시스템과 네트워크 접근을 OS 수준에서 격리하는 기능이다. 권한 시스템이 “Claude에게 무엇을 허용할 것인가”를 제어한다면, 샌드박스는 “Bash 명령이 실제로 무엇에 접근할 수 있는가”를 강제한다.

기존 권한 기반 보안은 모든 Bash 명령에 사용자 승인이 필요하다. 이 방식은 안전하지만, 승인 피로(반복적으로 승인 버튼을 누르면서 주의력이 떨어지는 현상), 생산성 저하(중단 때문에 개발 흐름이 끊기는 현상), 제한된 자율성 같은 문제가 있다.

샌드박스는 이 문제를 해결한다. 사전에 경계를 정의하고, 그 안에서는 승인 없이 자유롭게 작업하되, 경계 밖 접근은 OS 수준에서 차단한다.

파일시스템 격리

샌드박스는 파일시스템 접근을 특정 디렉토리로 제한한다.

macOS에서는 Seatbelt, Linux에서는 bubblewrap을 사용한다. 이 제한은 kubectl, terraform, npm 같은 모든 하위 프로세스에도 적용된다.

네트워크 격리

네트워크 접근은 샌드박스 외부에서 실행되는 프록시 서버를 통해 제어된다.

샌드박스 활성화

세션 중 /sandbox 명령으로 활성화한다.

/sandbox

macOS에서는 별도 설치 없이 바로 사용할 수 있다. Linux/WSL2에서는 bubblewrap과 socat을 먼저 설치해야 한다.

# Ubuntu/Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

샌드박스 모드

Claude Code는 두 가지 샌드박스 모드를 제공한다.

Auto-allow 모드: 샌드박스 내부의 Bash 명령은 승인 없이 자동 실행된다. 샌드박스에서 실행할 수 없는 명령(허용되지 않은 호스트에 네트워크 접근이 필요한 경우 등)은 일반 권한 흐름으로 넘어간다.

Regular permissions 모드: 샌드박스 내에서도 모든 Bash 명령이 표준 권한 흐름을 거친다. 더 많은 제어가 가능하지만 더 많은 승인이 필요하다.

두 모드 모두 같은 파일시스템과 네트워크 제한을 적용한다. 차이는 샌드박스 내 명령이 자동 승인되느냐 아니냐뿐이다.

샌드박스 설정

settings.json에서 샌드박스 동작을 커스터마이징할 수 있다.

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"],
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

권한 시스템과 샌드박스의 관계

권한 시스템과 샌드박스는 상호 보완적인 보안 레이어다.

구분권한 시스템샌드박스
제어 대상Claude Code가 사용할 수 있는 도구Bash 명령의 파일시스템/네트워크 접근
적용 범위모든 도구 (Bash, Read, Edit, WebFetch 등)Bash 명령과 하위 프로세스만
적용 수준Claude의 의사결정 수준OS 수준

두 가지를 함께 사용하면 방어 심층(defense-in-depth)을 구현할 수 있다.

내장 보안 기능

Claude Code에는 권한 시스템과 샌드박스 외에도 여러 보안 기능이 내장되어 있다.

프롬프트 인젝션 방어

프롬프트 인젝션은 악의적인 텍스트를 삽입해서 AI 어시스턴트의 지시를 조작하려는 공격 기법이다. Claude Code는 다음과 같은 방어 장치를 갖추고 있다.

쓰기 접근 제한

Claude Code는 실행된 폴더와 그 하위 폴더에만 쓸 수 있다. 상위 디렉토리의 파일은 명시적 허가 없이 수정할 수 없다. 읽기는 작업 디렉토리 외부도 가능하지만(시스템 라이브러리나 의존성 접근에 유용), 쓰기는 프로젝트 범위 내로 엄격하게 제한된다.

보호 경로

모든 권한 모드에서 특정 경로에 대한 쓰기는 자동 승인되지 않는다.

보호 디렉토리:

보호 파일:

이 경로들은 리포지토리 상태, 에디터 설정, Claude 자체 설정이 의도치 않게 손상되는 것을 방지한다.

안전한 사용을 위한 체크리스트

다음 항목을 확인해서 Claude Code를 안전하게 사용할 수 있다.

정리

핵심 요점

  1. 권한의 세 가지 유형: allow(자동 허용), ask(확인 요청), deny(차단)가 있으며, deny → ask → allow 순으로 평가된다. deny가 항상 우선한다

  2. 6가지 권한 모드: default(안전), acceptEdits(파일 수정 자동 승인), plan(분석만), auto(AI 검사 포함 전체 자동), dontAsk(사전 승인만), bypassPermissions(격리 환경 전용). Shift+Tab으로 기본 모드를 순환하거나 --permission-mode 플래그로 지정한다

  3. 세밀한 규칙 설정: Bash(npm run *) 같은 와일드카드 패턴으로 특정 명령만 허용하거나 차단할 수 있다. Read/Edit 규칙은 gitignore 명세를 따른다

  4. 샌드박스: OS 수준의 파일시스템과 네트워크 격리를 제공한다. 권한 시스템과 함께 사용하면 방어 심층을 구현할 수 있다. /sandbox로 활성화한다

  5. 보호 경로: .git, .bashrc 같은 중요 파일은 어떤 모드에서든 자동 승인되지 않는다. 리포지토리 상태와 시스템 설정을 보호한다

  6. 설정 우선순위: managed settings > CLI 인수 > 로컬 프로젝트 > 공유 프로젝트 > 사용자 설정 순이다. deny는 어떤 수준에서든 설정되면 재정의할 수 없다

확인해볼 링크

다음 단계

다음 차시에서는 터미널에서 Claude Code를 효과적으로 사용하는 방법을 다룬다. CLI 옵션과 플래그, 세션 내 명령어 활용, 파이프와 리다이렉션 같은 고급 사용법을 살펴본다.

참고 자료

Next Post
내장 도구 활용하기