cc-guard
Claude Code를 안전하게 만드는 원커맨드 도구. 772개의 example hook · 71건 이상의 Anthropic 공식 Issue에 대응 · 9,228+ 테스트 ·
npx @gaebalai/cc-guard
10초 만에 8개의 안전 hook을 설치한다. rm -rf / 차단, main 브랜치 push 방지, 시크릿 유출 감지, 구문 오류 자동 검출. 의존성 제로.
hook이란? Claude Code가 명령을 실행하기 전에 내용을 검사하고 위험하면 중단시키는 구조. 공항의 보안 검색대와 같다 — 탑승구(명령 실행) 앞에 체크포인트(hook)가 있어, 위험물(rm -rf 등)을 소지하고 있으면 통과시키지 않는다.
기능
| 명령 | 기능 |
|---|
npx @gaebalai/cc-guard | 8개의 안전 hook 설치 |
--shield | 최대 안전(stack 감지 + 권장 hook 자동 선택) |
--install-example <name> | 772개의 example 중 개별 설치 |
--examples | 모든 example 일람 표시 |
--create "설명" | 자연어로 커스텀 hook 생성 |
--verify | 각 hook의 동작 확인 |
--audit | 안전 스코어(0-100) |
--doctor | 동작하지 않는 원인 진단 |
--dashboard | 차단 통계 대시보드 |
--stats | 차단 통계 리포트 |
--lint | 설정의 정적 분석 |
--benchmark | hook 실행 속도 측정 |
--diff <file> | 설정 비교 |
--watch | 차단된 명령을 실시간으로 표시 |
--export / --import | 팀에서 설정 공유 |
--team | 프로젝트에 커밋해 공유 |
56개의 CLI 명령 전체 리스트: npx @gaebalai/cc-guard --help
설치
npx @gaebalai/cc-guard
Claude Code 재시작. 완료.
차단되는 동작
| 동작 | Before | After |
|---|
rm -rf / | 실행됨 | 차단 |
git push --force | 실행됨 | 차단 |
git push origin main | 실행됨 | 차단 |
git add .env | 실행됨 | 차단 |
cat ~/.netrc | 토큰 표시 | 차단 |
| Python 구문 오류 | 알아차리지 못함 | 자동 감지 |
| 컨텍스트 고갈 | 갑작스러운 종료 | 단계적 경고 |
| CLAUDE.md 규칙 소실 | 압축 후 무시 | 자동 재주입 |
| 서브에이전트의 지시 무시 | v2.1.84 이후 CLAUDE.md 제외 (#40459) | hook으로 제약 |
| 읽지 않고 편집 | 6%→34%로 증가 (#42796) | 경고 |
📘 token 소비가 너무 많은가? Token Checkup 무료 진단 도구로 30초 만에 자신의 소비 패턴을 확인할 수 있다. CLAUDE.md 최적화 · hook을 통한 token 제어 · 컨텍스트 관리 · 워크플로 설계 가이드는 COOKBOOK과 hook 예제를 참고한다.
알려진 제약:
FileChanged 알림은 파일 내용을 hook의 이전에 컨텍스트로 주입한다. session 중에 .env나 credentials.json이 외부에서 변경된 경우 hook으로 차단할 수 없다(#44909). 대책: dotenv-watch로 경고를 수신하고, Claude Code 실행 중에는 기밀 파일을 편집하지 않는다.
Session 보호 hook
session의 손상이나 token 낭비를 방지하는 hook.
| hook | 해결하는 문제 | Issue |
|---|
cch-cache-guard | session 파일 읽기로 인한 cache 오염 차단 | #40652 |
image-file-validator | 가짜 이미지 파일(텍스트의 .png) 읽기 차단 | #24387 |
large-read-guard | 큰 파일의 cat에 의한 컨텍스트 낭비 경고 | #41617 |
prompt-usage-logger | 모든 prompt를 로깅해 token 소비 패턴 추적 | #41249 |
compact-alert-notification | auto-compaction 발화 알림(token 낭비 사이클 감지) | #41788 |
token-budget-guard | session 비용 상한 초과 시 tool 호출 차단 | #38335 |
session-index-repair | 종료 시 sessions-index.json 재구축(--resume로 session 소실 방지) | #25032 |
session-backup-on-start | 시작 시 session JSONL 백업(임의의 삭제로부터 보호) | #41874 |
working-directory-fence | CWD 밖의 Read/Edit/Write 차단(다른 프로젝트에서의 오작업 방지) | #41850 |
pre-compact-transcript-backup | compaction 전에 JSONL 전체 백업(rate limit 시 데이터 손실 방지) | #40352 |
read-before-edit | 읽지 않고 편집하는 패턴을 감지해 경고(Read:Edit 비율이 70% 저하 — #42796) | #42796 |
subagent-error-detector | 서브에이전트의 529/502/timeout 결과를 감지해 경고 | #41911 |
subagent-identity-leak-guard | 자식 에이전트가 부모의 신분을 사칭하거나 부모의 대화 이력을 누설하는 것을 예방(delegation prompt의 신분 경계 검사) | #55488 |
subagent-tool-allowlist-enforcer | 자식 에이전트의 도구 경계를 delegation prompt로 명시하고, 부모의 검증 절차를 유도(허위 보고 예방) | #55653 |
subagent-spawn-verification-enforcer | 자식 에이전트의 spawn 응답이 허위가 아닌지 산출물의 검증 절차로 예방 | #55666 |
subagent-destructive-git-guard | 자식 에이전트의 delegation prompt에서 destructive한 git 명령의 금지와 안전한 대체(git stash) 및 working tree 상태 확인 지시가 명시되어 있는지 검사(4/25-5/8의 3건의 동형 data-loss 예방) | #57463 / #46444 / #53765 |
