byteforce

CPN 한국어 자습서 · Claude Code in Action

3 · 훅과 SDK

훅 주의점

Gotchas around hooks

훅은 강력한 만큼 보안 함정도 있습니다. Claude Code 문서가 권하는 다섯 가지 안전 수칙을 짚고, 그중 절대 경로 권장이 만드는 공유 문제와 그 해법($PWD 자리표시자 + init-claude.js)을 살펴봅니다. 본 레슨은 자막이 없어 강의 스크린샷에서 내용을 추출했습니다.

이 장에서 배우는 것What you'll learn

약 3분
1

훅 작성 시 입력을 절대 맹신하지 않기

2

셸 변수는 항상 따옴표 — "$VAR"

3

.. 경로 탐색(path traversal) 차단

4

스크립트는 절대 경로로 지정

5

.env·.git/·키 등 민감 파일은 건너뛰기

6

절대 경로의 공유 문제 → $PWD + init-claude.js

먼저 짚고 갈 용어
경로 탐색 (path traversal)
..로 상위 디렉터리를 거슬러 올라가 의도 밖 파일에 접근하는 공격. 막아야 한다.
절대 경로 (absolute path)
/home/.../hooks/x.js처럼 루트부터의 전체 경로. 상대 경로보다 가로채기에 안전.
$PWD 자리표시자
공유용 설정 파일에 넣는 표식. setup 때 실제 프로젝트 경로로 치환된다.
init-claude.js
npm run setup 때 도는 스크립트. $PWD를 실제 경로로 바꿔 settings.local.json을 만든다.

훅 보안 모범 사례

Security best practices

앞서 npm run setup 뒤 .claude 디렉터리에 settings.json 파일이 둘 생긴 걸 눈치챘을 수 있습니다. Claude Code 문서는 훅 보안에 관해 다섯 가지를 권합니다. 항목을 눌러 펼치고 확인하세요.

훅 보안 모범 사례 · 항목을 눌러 펼치고 체크
✓입력 검증·정제 Validate & sanitize›

훅에 들어오는 데이터를 절대 맹신하지 않습니다. 파일 경로·도구 입력을 항상 검사하고 정제한 뒤 사용합니다.

✓셸 변수는 항상 따옴표 Quote "$VAR"›

셸에서 변수를 쓸 땐 "$VAR"처럼 따옴표로 감쌉니다. $VAR로 두면 공백·특수문자로 의도치 않은 동작이 생길 수 있습니다.

✓경로 탐색 차단 Block ..›

파일 경로에 ..가 있는지 확인합니다. 상위 디렉터리를 거슬러 올라가 의도 밖 파일에 닿는 것을 막습니다.

✓스크립트는 절대 경로로 Absolute paths›

훅 스크립트 경로는 전체(절대) 경로로 지정합니다. 경로 가로채기(path interception)와 바이너리 심기(binary planting) 공격을 줄여 줍니다.

✓민감 파일 건너뛰기 Skip secrets›

.env·.git/·키 파일 등 민감한 대상은 다루지 않도록 합니다. 앞서 만든 .env 차단 훅이 그 예입니다.

확인함 0 / 5

절대 경로의 함정 — 공유

The sharing gotcha

권장 사항 중 하나가 바로 절대 경로 사용입니다. 경로 가로채기와 바이너리 심기 공격을 줄여 주죠. 그런데 이게 공유를 어렵게 만듭니다 — 내 컴퓨터의 절대 경로는 동료의 경로와 다르기 때문입니다.

문제 — 그냥 공유하면

절대 경로는 사람마다 다르다

안전을 위해 절대 경로를 쓰면, 그 경로는 내 컴퓨터에만 맞습니다. 그대로 커밋해 공유하면 동료의 경로와 달라 동작하지 않습니다.

/Users/grider/code/queries
해법 — $PWD 자리표시자

setup이 실제 경로로 치환

공유용 settings.example.json엔 $PWD 표식만 둡니다. npm run setup이 init-claude.js로 이를 실제 경로로 바꿔 settings.local.json을 만듭니다.

$PWD → /Users/you/.../queries

해법 — $PWD 자리표시자

The $PWD placeholder

이 문제를 풀기 위해, 프로젝트엔 settings.example.json 파일을 둡니다. 그 안의 명령은 $PWD 자리표시자를 담습니다. npm run setup을 돌리면 함께 설치된 init-claude.js가 $PWD를 프로젝트의 실제 절대 경로로 바꿔 settings.local.json에 씁니다.

settings.example.json · $PWD 자리표시자
// settings.example.json (공유·커밋되는 파일)
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "node $PWD/hooks/read_hook.js"   // 자리표시자
          }
        ]
      }
    ]
  }
}
터미널 · init-claude.js가 치환
$ npm run setup

# npm install && node ./scripts/init-claude.js
added 170 packages

✓ Successfully created .claude/settings.local.json
  Replaced $PWD with: /Users/you/code/queries

$ # 이제 절대 경로지만, 공유 파일은 그대로 일반적
결과

공유되는 설정 파일은 일반적인 채로 두면서, 각자의 컴퓨터에서는 권장대로 절대 경로를 쓰게 됩니다. 두 마리 토끼를 잡는 셈입니다.

정리 & 점검

Recap & check
핵심 정리
  • 훅 보안 5수칙: 입력 검증 · 변수 따옴표 · .. 차단 · 절대 경로 · 민감 파일 회피.
  • 절대 경로는 안전하지만, 사람마다 달라 그대로는 공유가 안 된다.
  • 공유용 settings.example.json에 $PWD 자리표시자를 둔다.
  • npm run setup의 init-claude.js가 $PWD를 실제 경로로 치환해 settings.local.json 생성.

Q1훅에서 셸 변수를 안전하게 쓰는 방법은?

Q2절대 경로를 쓰면 생기는 공유 문제는?

Q3settings.example.json의 $PWD는 언제 실제 경로로 바뀌나요?

MEMBER SESSION REQUIRED · REGISTRATION IS FREE

여기부터는 등록한 분에게 열립니다.

전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 16개 레슨을 끝까지 읽을 수 있습니다.

등록하고 이어서 읽기

이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.