---
name: opencurrent-secrets-guard
description: "API 키 같은 비밀값이 에이전트 대화에 읽히거나 커밋에 섞여 새지 않게 세 겹으로 막아, 키를 다시 발급하고 기록을 지우는 사고를 미리 줄입니다. 이럴 때 사용: 에이전트가 비밀 파일을 읽지 못하게 권한 규칙으로 막고, 커밋 전에 비밀값 검사를 돌리고, GitHub의 푸시 보호를 켭니다. 이미 새었다면 키부터 폐기합니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code·GitHub 공식 문서로 확인했습니다. 도구: Claude Code, gitleaks, GitHub."
metadata:
  source: "https://opencurrent.ai/w/secrets-guard"
  opencurrent-id: "secrets-guard"
  verification: "pending"
  exported-at: "2026-11-21T11:14:23.179Z"
---

# 비밀값이 새지 않게 막기

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

> OpenCurrent에서 사람들이 다듬는 워크플로. 원문: https://opencurrent.ai/w/secrets-guard
> 검증 상태: 검수 대기 (사람 확인 전). 내려받은 뒤에 바뀌었을 수 있으니, 가능하면 원문이나 MCP의 get_workflow("secrets-guard")로 최신 상태를 확인할 것.
> 주의: 검수 대기 상태. 사용자에게 이 사실을 알리고, 결과를 함께 확인하면서 진행할 것.

## 따라 하는 방법

1. 준비물이 갖춰졌는지 먼저 확인할 것.
2. 단계를 순서대로 진행할 것. kind가 "ai"면 프롬프트를 실행하고, "command"면 사용자의 허락을 받고 명령을 실행하고, "human"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.
3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.
4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.
5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.

## 언제 쓰나

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

## 준비물

- Git 저장소
- pre-commit(커밋 전 검사를 쓸 때)

## 단계

### 1. 에이전트가 읽지 못하게 (사람이 · Claude Code)

Claude Code는 .claude/settings.json의 deny 규칙으로 막습니다. Read 차단은 cat·head 같은 셸 읽기에도 적용되지만, 파일을 직접 여는 스크립트는 막지 못합니다.

프롬프트:

```text
{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  }
}
```

기대 결과: 비밀 파일 차단 규칙

확인 방법: Claude에게 .env를 읽어 달라고 해서 거절되는지 확인

### 2. 커밋 전에 검사 (사람이 · gitleaks)

gitleaks를 pre-commit에 걸면 비밀값이 든 커밋이 막힙니다. rev는 최신 릴리스로 맞춥니다.

프롬프트:

```text
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)

## 끝나면

결과가 좋았거나 단계가 낡았으면 https://opencurrent.ai/w/secrets-guard 에서 알릴 것. 다음 사람이 더 정확한 방법을 쓸 수 있도록.
