GitHub Secret Scanning이란? — 실수로 노출된 비밀키를 자동으로 찾아주는 보안 기능
개발 중에 가장 흔히 발생하는 보안 사고 중 하나는 API 키, 비밀번호, 토큰 등을 실수로 Git 저장소에 커밋하는 것입니다. 한번 GitHub에 올라간 시크릿은 공개 저장소라면 수분 내에 자동화 봇에 의해 탈취됩니다. 심지어 비공개 저장소라도 내부 계정 침해 시 유출됩니다.
GitHub Secret Scanning은 이런 실수를 자동으로 감지하는 GitHub의 보안 기능입니다. 2026년에는 모든 퍼블릭 저장소에 기본 활성화되어 있으며, 조직 계획에 따라 더욱 강력한 기능을 사용할 수 있습니다.
Secret Scanning의 핵심 기능 3가지
1. 자동 비밀키 감지
GitHub은 커밋된 코드에서 200개 이상의 시크릿 패턴을 자동 감지합니다. AWS 액세스 키, Stripe API 키, GitHub Personal Access Token, Slack Webhook URL, OpenAI API 키 등 주요 서비스의 인증 정보를 즉시 탐지합니다.
- 현재 코드 전체 스캔
- 모든 브랜치의 Git 히스토리 스캔
- Issue 설명, PR 코멘트, Gist 등도 스캔
- 새 시크릿 패턴 추가 시 기존 저장소 재스캔
2. Push Protection — 커밋 전에 차단
Secret Scanning의 가장 강력한 기능입니다. 시크릿이 포함된 코드를 git push하는 순간 자동으로 차단합니다. 즉, 저장소에 도달하기 전에 막아냅니다.
$ git push origin main
remote: ⚠️ Push blocked due to detected secret.
remote: GitHub Secret Scanning detected 1 secret:
remote:
remote: AWS Access Key: AKIAIOSFODNN7EXAMPLE
remote: File: config/aws.js, Line 5
remote:
remote: To push anyway (NOT recommended), use:
remote: git push --push-option=secret-scanning.skip-push-protection
remote: Or remove the secret and push again.
퍼블릭 저장소는 무료로 Push Protection이 활성화됩니다. GitHub Advanced Security(GHAS) 구독 시 프라이빗 저장소에도 적용됩니다.
3. 파트너 알림 & 자동 토큰 무효화
AWS, Stripe, Twilio 등 200여 개 서비스 파트너와 협력하여 시크릿 감지 즉시 해당 서비스에 자동으로 알림이 전송됩니다. 많은 파트너사는 알림을 받으면 자동으로 해당 토큰을 무효화(revoke)합니다.
Secret Scanning 설정 방법 — 단계별 가이드
퍼블릭 저장소 (무료, 자동 활성화)
퍼블릭 저장소는 별도 설정 없이 자동으로 Secret Scanning이 활성화됩니다.
- 저장소 → Settings → Security → Code security and analysis
- Secret scanning 항목 확인 (기본 ON)
- Push protection도 활성화 권장
프라이빗 저장소 (GitHub Advanced Security 필요)
# 조직 전체에 Secret Scanning 활성화 (GitHub CLI)
gh api \
--method PATCH \
/orgs/{org}/code-security/configurations/{configuration_id} \
-f secret_scanning=enabled \
-f secret_scanning_push_protection=enabled
커스텀 패턴 추가
내부 토큰, 자체 API 키 등 GitHub이 기본 감지하지 못하는 시크릿을 정규식으로 등록할 수 있습니다.
- Settings → Security → Secret scanning → Custom patterns
- New pattern 클릭
- 정규식과 테스트 문자열 입력
- 저장 시 전체 히스토리 재스캔
Push Protection 우회 시나리오 (꼭 알아야 할 예외 처리)
때로는 Push Protection이 거짓 양성(false positive)을 감지하거나, 테스트용 더미 값을 차단하는 경우가 있습니다. 이때는 다음 방법으로 처리하세요.
방법 1: 웹 인터페이스에서 허용
Push가 차단되면 GitHub이 제공하는 링크를 클릭하여 해당 알림 페이지로 이동합니다. "이 시크릿은 테스트용입니다" 또는 "이미 무효화했습니다" 등의 이유를 선택하고 통과시킬 수 있습니다.
방법 2: 환경변수로 대체 (권장)
# ❌ 잘못된 방법 — 코드에 직접 작성
const apiKey = "sk-1234567890abcdef";
# ✅ 올바른 방법 — 환경 변수 사용
const apiKey = process.env.API_KEY;
방법 3: .gitignore로 민감 파일 제외
# .gitignore
.env
.env.local
.env.production
config/secrets.yml
**/credentials.json
시크릿이 이미 노출된 경우 — 사고 대응 절차
이미 시크릿이 저장소에 올라갔다면 신속하게 다음 절차를 따르세요.
- 즉시 토큰 무효화: 해당 서비스에서 API 키/토큰 즉시 삭제 및 재발급
- Git 히스토리 정리:
git filter-repo로 커밋 히스토리에서 시크릿 제거 - 강제 푸시: 정리된 히스토리를 force push
- 접근 로그 확인: 해당 API 키가 실제로 악용되었는지 서비스 로그 확인
- 보안 인시던트 보고: 팀 내 보안 담당자에게 보고
# git filter-repo로 시크릿 제거 (설치 필요: pip install git-filter-repo)
git filter-repo --path config/secrets.yml --invert-paths
# 또는 특정 문자열 대체
git filter-repo --replace-text replacements.txt
# replacements.txt 내용: AKIAIOSFODNN7EXAMPLE==>REMOVED_SECRET
2026년 GitHub 보안 기능 총정리
| 기능 | 퍼블릭 저장소 | 프라이빗 (무료) | GHAS 필요 |
|---|---|---|---|
| Secret Scanning (기본) | ✅ 무료 | ✅ 무료 | - |
| Push Protection | ✅ 무료 | ❌ | ✅ |
| 커스텀 패턴 | ❌ | ❌ | ✅ |
| Dependabot 알림 | ✅ 무료 | ✅ 무료 | - |
| Code Scanning (CodeQL) | ✅ 무료 | ❌ | ✅ |
| 조직 보안 대시보드 | - | ❌ | ✅ |
Pre-commit 훅으로 로컬에서 먼저 차단하기
Push Protection보다 한 단계 앞서서, 로컬 커밋 시점에 시크릿을 감지하려면 pre-commit 훅과 detect-secrets 도구를 함께 사용하세요.
# detect-secrets 설치
pip install detect-secrets pre-commit
# .pre-commit-config.yaml 설정
repos:
- repo: https://github.com/Yelp/detect-secrets
rev: v1.5.0
hooks:
- id: detect-secrets
# 훅 설치
pre-commit install
# 베이스라인 파일 생성 (기존 코드의 허용 목록)
detect-secrets scan > .secrets.baseline
이제 git commit 시 자동으로 시크릿 스캔이 실행됩니다.
마치며 — 시크릿 유출 사고는 예방이 전부다
GitHub Secret Scanning과 Push Protection은 2026년 현재 무료로 사용할 수 있는 가장 강력한 보안 자동화 도구 중 하나입니다. 사고가 발생한 후 수습하는 데 드는 비용과 시간은 예방 비용의 수십 배입니다. 오늘 바로 저장소에서 Secret Scanning을 확인하고, Push Protection을 켜두세요. 작은 습관 하나가 서비스 보안의 기반이 됩니다.
