# 비밀값이 새지 않게 막기
id: secrets-guard · 종류: 워크플로 · 상태: 검수 대기 (사람 확인 전) · 주제: 개발
주소: https://opencurrent.ai/w/secrets-guard
기준일: 2026-11-21 (여기서 고친 날)
도구: Claude Code, gitleaks, GitHub
걸리는 시간: 약 20분
평가 점수: 32/100 (확인 없음 · 검수 대기)

API 키 같은 비밀값이 에이전트 대화에 읽히거나 커밋에 섞여 새지 않게 세 겹으로 막아, 키를 다시 발급하고 기록을 지우는 사고를 미리 줄입니다.

설명: 에이전트가 비밀 파일을 읽지 못하게 권한 규칙으로 막고, 커밋 전에 비밀값 검사를 돌리고, GitHub의 푸시 보호를 켭니다. 이미 새었다면 키부터 폐기합니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code·GitHub 공식 문서로 확인했습니다.

준비물: Git 저장소 · pre-commit(커밋 전 검사를 쓸 때)

단계:
1. [사람이 · Claude Code] 에이전트가 읽지 못하게 — Claude Code는 .claude/settings.json의 deny 규칙으로 막습니다. Read 차단은 cat·head 같은 셸 읽기에도 적용되지만, 파일을 직접 여는 스크립트는 막지 못합니다.
   프롬프트:
   > {
   >   "permissions": {
   >     "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
   >   }
   > }
   기대 결과: 비밀 파일 차단 규칙
   확인 방법: Claude에게 .env를 읽어 달라고 해서 거절되는지 확인
2. [사람이 · gitleaks] 커밋 전에 검사 — gitleaks를 pre-commit에 걸면 비밀값이 든 커밋이 막힙니다. rev는 최신 릴리스로 맞춥니다.
   프롬프트:
   > repos:
   >   - repo: https://github.com/gitleaks/gitleaks
   >     rev: v8.24.2
   >     hooks:
   >       - id: gitleaks
   기대 결과: .pre-commit-config.yaml
   확인 방법: pre-commit autoupdate && pre-commit install 뒤 가짜 키로 커밋이 막히는지 확인
3. [사람이 · GitHub] 푸시 보호 켜기 — GitHub 저장소의 secret scanning 푸시 보호를 켜면 알려진 형식의 키가 든 푸시가 막힙니다. 공개 저장소로의 개인 푸시는 기본으로 켜져 있고, 저장소 단위 설정은 관리자가 켭니다.
   기대 결과: 켜진 푸시 보호
   확인 방법: 가짜 형식 키를 푸시해 막히는지 확인
4. [사람이 · GitHub] 새었을 때 — 커밋이나 대화에 키가 들어갔으면 기록을 지우기 전에 그 키를 먼저 폐기하고 새로 발급합니다.
   기대 결과: 폐기된 키와 새 키
   확인 방법: 옛 키로 요청이 거절되는지 확인

주의:
- .claudeignore는 효과 없음. Read deny 규칙으로
- 푸시 보호는 누구나 이유를 적고 우회할 수 있는 것이 기본. 우회 권한을 좁히기
- gitleaks 저장소는 기능이 완성됐다고 밝히고 후속 도구(Betterleaks)로 옮겨 가는 중. 새로 고를 때 확인
- 지운 커밋도 포크와 캐시에 남을 수 있음. 키 폐기가 먼저

출처:
- Claude Code 문서: 권한 설정 https://code.claude.com/docs/en/permissions
- GitHub 문서: 푸시 보호 https://docs.github.com/en/code-security/secret-scanning/push-protection-for-repositories-and-organizations
- gitleaks 저장소 https://github.com/gitleaks/gitleaks