Claude Code 보안 설정 완벽 가이드

Claude Code는 채팅창에 답만 주는 도구가 아닙니다. 파일을 읽고 쓰고, 터미널 명령을 실행하고, MCP 서버를 통해 외부 시스템에 연결하고, CI 파이프라인 안에서 자동으로 돌아갈 수도 있습니다. 생산성은 바로 이 "실제로 일을 하는" 능력에서 나옵니다. 그리고 보안 위험도 정확히 같은 곳에서 나옵니다.

이 글은 Claude Code를 금지하는 방법이 아니라, 권한을 이해하고 최소한만 열어 안전하게 쓰는 방법을 다룹니다. 개인 설정부터 팀 정책, 그리고 마지막에 바로 복사해 쓸 수 있는 체크리스트까지 이어집니다.

Claude Code가 실제로 만질 수 있는 것

위험을 논하려면 먼저 권한 모델을 정확히 봐야 합니다. Claude Code의 접근 능력은 크게 네 갈래입니다.

• 파일 접근 — 작업 디렉토리의 파일을 읽고, 편집하고, 새로 만듭니다. 열어둔 경로에 따라 소스뿐 아니라 .env, 설정 파일, 키까지 시야에 들어옵니다.
• 터미널 실행 — 셸 명령을 실행합니다. npm test부터 git push, 네트워크 요청까지 — 승인 방식을 어떻게 두느냐에 따라 위험 폭이 완전히 달라집니다.
• MCP 연결 — MCP 서버를 통해 GitHub, 데이터베이스, Slack, 사내 API 등 외부 시스템에 손을 뻗습니다. 이건 별도의 큰 주제라 MCP 보안 가이드에서 깊게 다룹니다.
• CI·자동화 — 파이프라인이나 스크립트 안에서 사람 승인 없이 돌아갈 수 있습니다. 이 경우 "매번 물어보는" 안전장치가 사라지므로 설정이 곧 유일한 방어선입니다.

브라우저 트래픽만 보는 기존 보안 도구로는 로컬에서 파일을 읽고 셸을 실행하는 코딩 에이전트가 보이지 않는다. 통제는 네트워크가 아니라 에이전트의 권한 경계에 걸어야 한다.

개발자가 마주하는 위험 요소 5가지

추상적인 "AI 위험"이 아니라, 실제 설정에서 반복적으로 발견되는 다섯 가지 구체적 패턴입니다.

1. 위험한 셸 명령의 무분별한 실행

터미널 실행을 전부 자동 승인해두면, 프롬프트 한 번에 rm -rf 같은 파괴적 명령, curl … | bash처럼 원격 스크립트를 받아 그대로 실행하는 명령, gh로 저장소를 조작하는 명령까지 사람 확인 없이 돌 수 있습니다. 특히 파이프-투-셸 패턴은 무엇이 실행될지 사전에 알 수 없다는 점에서 가장 위험합니다.

2. .env·시크릿 파일에 대한 접근

작업 경로를 넓게 열어두면 에이전트가 .env, .pem, ~/.aws/credentials, id_rsa 같은 파일을 읽을 수 있습니다. 그 값이 대화 맥락에 한번 들어가면, 이후 요약·로그·커밋 메시지·PR 설명 어디로든 흘러갈 여지가 생깁니다.

3. 광범위한 MCP 서버 연결

write 권한을 가진 GitHub MCP, 홈 디렉토리 전체를 연 filesystem MCP, 출처 불명의 custom 서버 — 이런 것들이 붙으면 Claude Code의 실질 권한이 폭발적으로 커집니다. 프롬프트 인젝션 한 번에 에이전트가 코드를 커밋하거나 데이터를 외부로 보낼 통로가 됩니다.

4. 커밋·PR 자동 생성의 무검토 병합

에이전트가 만든 커밋·PR을 사람이 읽지 않고 머지하면, 미묘한 취약 코드나 의도치 않은 의존성이 그대로 들어갑니다. AI가 쓴 코드일수록 "그럴듯해 보이지만 틀린" 변경이 리뷰를 통과하기 쉽습니다.

5. CI 안에서의 무경계 실행

CI에서 에이전트를 돌릴 때 프로덕션 시크릿을 그대로 환경변수로 주입하고, 네트워크·쓰기 권한을 열어두면, 사람 승인이라는 안전장치 없이 광범위한 접근이 상시화됩니다. 자동화의 편의가 그대로 상시 위험이 됩니다.

권한을 최소화하는 설정

핵심 원칙은 하나입니다 — 기본은 거부, 필요한 것만 명시적으로 허용(allowlist). "일단 다 열고 문제 생기면 막는다"가 아니라 그 반대로 갑니다.

터미널: 위험 명령은 승인 게이트로

읽기·테스트처럼 안전한 명령만 자동 허용하고, 파괴적이거나 네트워크를 타는 명령은 매번 사람 확인을 거치게 둡니다. 개념적으로 이런 정책입니다.

# 허용(allowlist) — 부작용 없는 읽기/테스트
allow: [ "npm run test", "npm run lint", "git status", "git diff", "ls", "cat" ]

# 확인 필요(ask) — 부작용·네트워크·되돌리기 어려운 명령
ask:   [ "git push", "gh *", "rm *", "curl *", "npm install *" ]

# 거부(deny) — 원격 스크립트를 받아 바로 실행
deny:  [ "curl * | sh", "curl * | bash", "wget * | sh" ]

정확한 문법은 도구 버전에 따라 다르지만, allow / ask / deny 3단으로 나누는 사고방식은 어디서나 통합니다. 파이프-투-셸은 예외 없이 deny에 두세요.

파일: 작업 경로를 프로젝트로 좁히기

에이전트의 파일 시야를 프로젝트 루트로 한정하고, 민감 파일은 접근 대상에서 제외합니다. 저장소 루트에 무시 규칙을 두는 방식이 가장 견고합니다.

# .env·키·자격증명은 에이전트 시야에서 제외
.env
.env.*
*.pem
*.key
id_rsa*
**/credentials
**/secrets/**

MCP: 최소 서버·최소 스코프

붙이는 MCP 서버를 꼭 필요한 것만으로 줄이고, 각 서버를 read-only·특정 리소스로 제한합니다. GitHub는 write 대신 read부터, filesystem은 홈 전체 대신 프로젝트 폴더로. 상세 판정 기준은 MCP 보안 가이드를 참고하세요.

시크릿을 코드·에이전트에서 분리

권한을 좁혀도 시크릿이 에이전트 손 닿는 곳에 평문으로 있으면 소용이 없습니다. 시크릿은 처음부터 에이전트 경계 밖에 두는 게 정답입니다.

• 비밀은 파일이 아니라 시크릿 매니저에. 로컬은 OS 키체인이나 direnv+금고, CI는 러너의 시크릿 스토어를 씁니다. 저장소에는 .env.example만 두고 실제 값은 커밋하지 않습니다.
• 테스트·문서에는 명백한 더미만. 예시로 키가 필요하면 sk-test-0000…처럼 절대 유효하지 않은 가짜 패턴만 씁니다. 진짜 키를 "잠깐 예시로" 붙여넣는 순간이 사고의 시작입니다.
• 커밋 전 시크릿 스캐너. pre-commit 훅이나 CI에 시크릿 탐지를 걸어, 에이전트든 사람이든 키를 커밋하면 막습니다.
• 범위·수명이 짧은 토큰. 에이전트가 써야 하는 토큰은 최소 권한·짧은 만료로 발급하고, 유출 시 즉시 회수 가능하게 둡니다.

팀 정책으로 굳히기

개인 설정은 스냅샷일 뿐입니다. 개발자마다 다르고, 어제 안전하던 설정이 오늘 바뀝니다. 진짜 통제는 팀 단위 정책으로 고정하는 것입니다.

• 설정을 저장소에 커밋 — allow/ask/deny 정책과 무시 규칙을 리포지토리에 두어, 팀 전원이 같은 기준으로 시작하게 합니다.
• 에이전트 변경은 예외 없이 PR 검토 — AI가 만든 커밋도 사람이 읽고 머지합니다. "AI가 했으니 맞겠지"를 금지어로 둡니다.
• MCP allowlist 운영 — 팀이 승인한 MCP 서버 목록을 정하고, 목록 밖 서버가 붙으면 알림·승인 절차를 거칩니다.
• CI는 격리·최소권한 — 파이프라인 안의 에이전트는 전용 최소권한 자격증명으로, 필요한 네트워크만 열어 실행합니다.
• 가시성 확보 — 누구 PC에 어떤 도구·MCP·권한이 붙어 있는지 한 화면에서 보이게 합니다. 단, 프롬프트·파일 원문은 저장하지 않고 메타데이터만.

마지막 원칙이 중요합니다. 개발자를 감시하는 도구가 되면 팀이 우회합니다. 통제는 사람이 아니라 권한과 데이터에만 걸어야 도입 저항이 사라집니다.

안전 설정 체크리스트

1. 터미널 명령을 allow / ask / deny 3단으로 나눴는가? (파이프-투-셸은 deny)
2. 에이전트의 파일 시야가 프로젝트 루트로 좁혀져 있는가?
3. .env·.pem·키·자격증명 파일이 접근 대상에서 제외됐는가?
4. 붙어 있는 MCP 서버가 꼭 필요한 최소 개수·최소 스코프인가?
5. 시크릿이 파일이 아니라 시크릿 매니저·키체인에 있는가?
6. 예시·테스트에 진짜 키가 아니라 더미(sk-test-0000…)만 쓰는가?
7. 커밋 전 시크릿 스캐너가 걸려 있는가?
8. 에이전트가 만든 커밋·PR을 사람이 검토하고 머지하는가?
9. CI 안의 에이전트가 전용 최소권한으로 격리 실행되는가?
10. 팀 전체의 도구·MCP·권한을 한눈에 볼 방법이 있는가?

세 개 이상 "아니오"라면, 지금이 설정을 손볼 때입니다.