Claude Code hooks 보안 2026 — 자동 실행이 편할수록 왜 시크릿과 권한 경계부터 봐야 할까

Posted on by

hooks 하나 붙이면 일은 확실히 편해진다.

그런데 편해진다는 건 보통 자동 실행이 늘어난다는 뜻이고, 자동 실행이 늘어난다는 건 결국 권한이 자주 쓰인다는 뜻이다.

권한이 자주 쓰이면, 시크릿이 많이 지나가고, 로그가 많이 남고, 실수도 더 빨리 커진다.

그래서 hooks는 “자동화 도구”가 아니라 “보안 경계가 있는 자동화 도구”로 봐야 한다.

핵심만 먼저 잡으면, Claude Code hooks는 편의성보다 먼저 어떤 정보가 어느 권한으로 어디까지 흘러갈 수 있는지를 정해두지 않으면 언젠가 사고 난다.

먼저 확인할 사람

  • hooks로 lint, test, formatting, notify를 붙이기 시작한 사람
  • 프로젝트별로 다른 secret을 쓰는데도 설정을 한 군데서 우겨 넣는 사람
  • 팀에서 “일단 자동화부터”라는 말이 너무 빨리 나오는 사람
  • log file과 env file이 어디에 남는지 신경 안 쓰고 있는 사람
  • 세션마다 다른 권한을 쓰는 구조를 아직 정리하지 못한 사람

지금 결론

자동 실행은 편하지만, 편한 만큼 위험도 늘어난다.

그래서 hooks 보안의 순서는 늘 같다.

  1. 입력값을 줄인다.
  2. 권한을 최소화한다.
  3. secret을 실행 컨텍스트에서 분리한다.
  4. 실패 로그는 남기되, 민감정보는 지운다.
  5. 과한 자동화는 애초에 안 붙인다.

이 순서를 뒤집으면 나중에 “왜 잘 돌아가던 게 갑자기 위험하지”가 된다.

먼저 봐야 할 경계

경계 왜 중요하나 흔한 실수 안전한 기본값
secret hook이 읽을 수 있으면 유출 경로도 생김 .env를 repo 안에 둠 세션별 최소 export만 사용
권한 hook은 사람이 직접 실행하는 것보다 자주 돈다 write 권한을 기본으로 둠 read-only부터 시작
경로 hook이 어디서 도는지 항상 같지 않음 pwd를 진실로 착각 $CLAUDE_PROJECT_DIR 기준
로그 디버깅에 유용하지만 민감정보도 남음 전체 env dump 필요한 키만 마스킹
네트워크 외부 요청이 붙으면 유출면이 커짐 아무 API나 허용 allowlist만 허용

2026년 5월 25일 보강: 이벤트별로 얇게 나누기

Claude Code hooks 보안에서 제일 먼저 나눌 것은 스크립트 파일이 아니라 이벤트다. Anthropic hooks 문서 기준으로 PreToolUse는 도구 호출 전, PostToolUse는 도구 성공 후, UserPromptSubmit은 사용자 프롬프트 제출 전, Stop은 메인 에이전트 응답 종료 시점에 돈다. 같은 hook이라도 이벤트가 다르면 책임이 완전히 다르다.

이벤트 맡기기 좋은 일 피해야 할 일 보안 판단
PreToolUse Bash, Write, Edit 전 민감 파일 접근·위험 명령 차단 긴 보고서 생성, 느린 외부 호출 secret 접근 차단은 여기서 해야 의미가 있다
PostToolUse 실행 결과 요약, format/lint 피드백, 참조 체크 이미 실행된 위험 행동을 되돌리는 역할 사후 피드백이지 방화벽은 아니다
UserPromptSubmit 프롬프트의 secret, 금지 요청, 필수 컨텍스트 누락 검사 사용자 입력을 과하게 재작성 stdout이 컨텍스트로 들어갈 수 있어 짧게 유지
Stop 완료 전 체크리스트, 누락된 테스트·요약 요청 무한 재시도, 긴 작업 재개 막을 때는 다음 행동을 구체적으로 써야 한다
SubagentStop 하위 에이전트 산출물 품질 확인 메인 세션 전체 판단 대체 subagent 결과를 main thread로 가져오는 용도
PreCompact 장기 작업 요약, 상태 저장 새로운 작업 시작 컨텍스트 압축 전 구조화에만 쓰기

내 기본값은 thin hook이다. hook은 판단문만 남기고, 무거운 처리와 장기 작업은 별도 스크립트나 사람 승인 흐름으로 보낸다. 이 볼트의 .claude/settings.local.json도 비슷하다. PreToolUse에서는 Edit|Write 전에 .env, secrets, credentials, token 같은 민감 경로 신호를 경고하고, PostToolUse에서는 agent/skill 문서의 깨진 @참조를 확인한다.

이 방식이 좋은 이유는 실패 반경이 작기 때문이다. hook이 모든 걸 고치려고 들면 권한도 커지고 로그도 커진다. 반대로 “위험 신호를 짧게 감지하고 멈추거나 경고한다”로 역할을 줄이면, 팀원이 hook을 읽고 신뢰하기 쉽다. 자동화가 강해질수록 hook은 똑똑한 만능 직원이 아니라 짧고 엄격한 신호등에 가까워야 한다.

왜 위험이 빨리 커지나

hooks는 한 번 설정하면 사람이 매번 확인하지 않는다.

즉, 처음에는 아주 작아 보였던 권한이 나중엔 자동으로 반복된다.

그게 무서운 이유는 단순하다.

  • 한 번의 실수로 끝나지 않는다
  • 한 번의 과한 권한이 수십 번 재사용된다
  • 사람이 빠르게 고치기 어려운 곳에서 자동으로 반복된다

이건 편의성의 반대편에 있는 리스크다.

실전 체크리스트

1. secret은 hook 내부에서 직접 읽지 않는다

가능하면 필요한 최소 값만 환경으로 넘긴다.

예를 들면 이런 식이다.

export REVIEW_API_KEY="..."
export NOTIFY_TOKEN="..."

그런데 여기서도 핵심은 “많이”가 아니라 “최소”다.

hook이 필요한 키보다 더 많은 키를 보면, 나중에 누가 어디까지 쓸 수 있는지 흐려진다.

2. read-only hook과 write hook을 나눈다

검사용 hook과 수정용 hook을 같은 그룹으로 묶지 않는 게 좋다.

예를 들면:

  • lint, verify, dry-run -> read-only
  • file modify, auto-fix, deploy prep -> write

같은 자동화라도 위험도는 다르다.

3. 세션과 프로젝트를 같은 것으로 보지 않는다

pwd는 현재 위치고, $CLAUDE_PROJECT_DIR는 프로젝트 기준이다.

이걸 섞어 쓰면 경로 꼬임이 생기고, 경로 꼬임은 보통 로그 꼬임으로 이어진다.

4. 로그는 남기되 값은 마스킹한다

운영에서 로그가 없으면 디버깅이 안 된다.

하지만 시크릿이 로그에 그대로 남으면 디버깅보다 사고가 먼저 온다.

좋은 로그는 이런 느낌이다.

  • 실행된 명령
  • 현재 폴더
  • 사용한 hook 이름
  • 결과 코드

나쁜 로그는 이런 느낌이다.

  • 전체 env
  • 토큰 원문
  • secret 값 그대로
  • 파일 전체 덤프

5. 네트워크는 기본 차단, 예외만 허용한다

hook이 외부로 나가는 건 생각보다 위험하다.

왜냐면 외부 전송은 “내 컴퓨터에서 끝나는 작업”이 아니기 때문이다.

기본값은 차단이 낫고, 꼭 필요할 때만 allowlist로 여는 편이 덜 피곤하다.

실패 TOP

1. .env를 repo에 같이 넣는 실수

처음엔 편하다.

나중엔 보안팀이 제일 싫어하는 형태가 된다.

2. write 권한을 너무 빨리 붙이는 실수

수정 자동화는 좋지만, 검증 없이 자동 수정만 붙이면 사고 확률이 오른다.

3. 실패를 조용히 넘기는 실수

hook 실패를 숨기면 “자동화가 잘 돈다”고 착각한다.

사실은 그냥 조용히 망하고 있는 걸 수도 있다.

4. team-wide hook에 개인 secret을 얹는 실수

공용 설정과 개인 비밀정보는 분리하는 게 맞다.

5. 네트워크 호출을 아무 검증 없이 여는 실수

외부 API 호출은 편하지만, 그만큼 책임도 커진다.

6. 권한 경계보다 편의성을 먼저 보는 실수

자동화가 편해질수록 경계 설계는 더 중요하다.

7. 어디까지 자동인지 문서가 없는 실수

문서가 없으면 사람마다 다른 자동화를 상상한다.

그게 가장 운영하기 어렵다.

언제 과한가

hooks가 과해지는 순간은 보통 세 가지다.

  • 검증보다 수정이 많아질 때
  • 사람이 최종 승인하는 단계가 사라질 때
  • 실패해도 누가 봐야 하는지 안 정해졌을 때

이 중 하나라도 걸리면, 자동화는 이미 편의 도구가 아니라 운영 리스크가 된다.

이럴 땐 안 써도 된다

  • 단발성 수동 작업
  • 팀 공용 저장소에서 아직 규칙이 정리되지 않은 상태
  • secret 분리가 안 된 상태
  • 외부 네트워크를 막아야 하는 프로젝트
  • 로그/감사 추적이 아직 없는 프로젝트

자동화는 항상 정답이 아니다.

안 붙이는 게 더 안전한 시기도 있다.

2026 회수 업데이트: 팀 설정에 넣을 안전선

2026년 5월 기준으로 hooks를 팀 운영에 붙일 때는 무엇을 자동화할까보다 어떤 동작을 자동화하지 않을까를 먼저 적어두는 편이 낫다. 자동 실행은 한 번 편해지면 금방 기본값이 되기 때문에, 금지 범위를 문서로 남기지 않으면 나중에 권한 경계가 흐려진다.

첫 번째 안전선은 secret을 hook의 기본 입력으로 보지 않는 것이다. 필요한 토큰만 세션 단위로 넘기고, 전체 .env를 덤프하거나 공용 설정 파일에 개인 키를 섞는 방식은 피해야 한다.

두 번째 안전선은 read-only hook을 먼저 운영하는 것이다. lint, test, schema check처럼 결과만 알려주는 자동화는 비교적 안전하지만, 파일 수정이나 배포 준비처럼 상태를 바꾸는 hook은 별도 승인 단계를 두는 편이 오래 간다.

세 번째 안전선은 로그 포맷을 미리 정하는 것이다. 로그에는 명령 이름, 종료 코드, 실행 위치, 실패 이유 정도만 남기고, 토큰 원문이나 요청 본문 전체는 기본적으로 남기지 않는다고 합의해야 한다.

네 번째 안전선은 네트워크 호출을 예외로 두는 것이다. 외부 API 호출이 들어가는 순간 hook은 로컬 편의 기능이 아니라 데이터 이동 경로가 되므로, 도메인 allowlist와 실패 시 동작을 같이 정해야 한다.

다섯 번째 안전선은 프로젝트별 권한을 분리하는 것이다. 개인 실험 저장소에서 허용한 hook을 팀 저장소에 그대로 가져오면 너무 많은 권한이 따라오기 쉽고, 이때 문제가 생기면 원인 추적도 괜히 길어진다.

여섯 번째 안전선은 실패를 조용히 넘기지 않는 것이다. hook 실패를 숨기면 사용자는 자동화가 정상이라고 믿게 되고, 실제로는 중요한 검증이 계속 빠진 상태로 작업이 쌓일 수 있다.

일곱 번째 안전선은 사람이 최종 결정을 하는 단계다. 자동 수정이나 자동 배포는 매력적이지만, secret과 권한이 얽힌 영역에서는 사람이 보는 마지막 체크포인트가 남아 있어야 팀이 안심하고 확장할 수 있다.

이렇게 보면 hooks 보안은 거창한 보안 프레임워크보다 운영 습관에 가깝다. 입력을 줄이고, 권한을 나누고, 로그를 절제하고, 외부 전송을 좁히는 네 가지 습관만 잡아도 대부분의 사고 면적은 확실히 줄어든다.

팀 저장소라면 hook 목록을 README나 운영 문서에 짧게 남기는 것도 좋다. 어떤 이벤트에서 어떤 명령이 돌고, 실패하면 누가 보는지만 적어도 새로 합류한 사람이 자동화의 범위를 훨씬 빨리 이해한다.

개인 저장소라면 더 가볍게 가도 된다. 다만 개인 실험에서 만든 hook을 회사 프로젝트로 옮길 때는 secret, 네트워크, write 권한 세 가지만 다시 확인해야 한다.

마지막으로 hook은 한 번에 크게 붙이지 않는 편이 낫다. 작은 read-only 자동화를 며칠 돌려보고 로그와 실패 패턴을 본 뒤에 write 동작을 붙이면, 편의성과 안전선이 같이 자란다.

FAQ

Q1. hooks를 다 막아버리는 게 더 안전하지 않나?

완전 차단은 안전해 보이지만 운영 효율을 많이 깎는다.

그래서 read-only부터 시작하고, 필요한 것만 점진적으로 여는 편이 낫다.

Q2. secret은 어디에 두는 게 좋나?

최소 노출 원칙으로 세션 단위 환경 변수나 별도 안전 저장소를 쓰는 게 낫다.

repo 안에 plain text로 두는 건 피해야 한다.

Q3. 로그를 얼마나 남겨야 하나?

재현에 필요한 만큼만 남기고, 비밀값은 마스킹한다.

Q4. hooks가 잦아질수록 무엇을 먼저 점검해야 하나?

권한, 경로, 로그, 네트워크 순서다.

Q5. 팀에서 제일 먼저 합의할 건 뭐냐?

어떤 hook이 read-only인지, 어떤 hook이 write인지부터 정해야 한다.

관련 글

Sources