대상: 1인·소규모 개발에서 Git을 쓰며 "실수로 API 키를 커밋하면 어쩌지?" 걱정하는 사람. 공격자 메커니즘은 없다 — 오직 시크릿이 자기 저장소에서 새어 나가지 못하게 막는 장치다.
본 사이트의 견해: .gitignore만으로는 시크릿을 지킬 수 없다
"내 .env는 .gitignore에 있으니 괜찮아"는 흔한 말이고 — 구멍이 있다. .gitignore는 새 파일이 추적되는 것만 막을 뿐이다. 이미 커밋된 시크릿, 급히 git add -f로 강제 추가한 것, .env.local.bak 같은 예상 밖 이름은 잡지 못한다. 입구의 일부만 막는다. 실제로 커밋 내용을 들여다보고 "시크릿처럼 보이는 문자열"을 표시하는 무언가 — 탐지기 — 가 필요하다. 그것이 gitleaks의 역할이다.
왜 "커밋 전"에 막는가
시크릿이 위험한 이유는 Git이 히스토리를 영원히 보관하기 때문이다. 최신 파일에서 지워도 과거 커밋에 남는다. 그리고 push되는 순간 그 히스토리는 다른 머신, 서버, CI 로그로 복사된다.
그러니 시크릿 방어는 사실 유출 후 복구가 아니라 유출 전 예방이다. "공개 디렉터리에 시크릿을 남기지 마라"는 인벤토리(→ 웹루트 인벤토리)와 같은 발상을, 코드의 세계로 가져온 것이다.
관문은 어디에 두는가
시크릿이 코드에서 세상으로 가는 경로 위에 두 관문을 둘 수 있다: 로컬 커밋의 순간, 그리고 공유되기 직전(CI).
코드 속 시크릿
API 키, 키, 토큰
관문 1: pre-commit
커밋 시 로컬에서 탐지 & 중단
관문 2: CI / cron
push 후, 머지/배포 전 탐지
공개 / 공유
이 지점을 지나면 유출로 간주
gitleaks 연결하는 법
먼저 기존 히스토리를 스캔
gitleaks detect로 저장소 히스토리 전체를 한 번 스캔하라. 과거 커밋에 잠든 시크릿을 솎아내는 것이 첫 작업이다. 여기서 나온 것은 아래처럼 폐기가 필요하다고 가정한다.관문 1: pre-commit 훅 구축
gitleaks protect --staged를 실행해, 시크릿이 포함된 커밋을 그 자리에서 중단하라. pre-commit 프레임워크(.pre-commit-config.yaml)에 넣어 모두에게 같은 점검이 로컬에서 적용되게 하라.관문 2: CI / cron 구축
gitleaks detect를 CI 작업으로 — 자체 호스팅이면 주기적 스캔으로 — 돌려 빠져나간 것을 잡아라(의존성 감사와 같은 기계 모니터링 발상)..gitleaks.toml에서 오탐 조정
.gitleaks.toml에서 규칙과 허용 목록을 조정하라. 올바른 실천은 "침묵시키기"가 아니라 "왜 안전한지 기록하기"다 — 근거 없는 제외는 다음 사고의 씨앗이다.탐지되면 '폐기'가 먼저, 히스토리 재작성은 나중
커밋되어 push된 시크릿을 발견하면, 최우선은 그 키나 토큰을 폐기하고 재발급(교체)하는 것이다. git filter-repo로 히스토리에서 지우는 것도 중요하지만, 그것은 "더 퍼지는 것을 멈추는" 정리일 뿐이다. 공개 저장소, 포크, CI 로그, 남의 클론에 닿은 시크릿은 회수 불가라고 가정하고 — 먼저 무효화한 다음 히스토리를 정리하라. 순서를 뒤집으면 지우는 동안 악용된다.
.gitignore에 의존
- 새 추적만 막음
- 이미 커밋된 시크릿은 그대로 통과
git add -f나 이상한 파일명에 무력- "그거 추가할 생각 없었는데"를 검증 못 함
gitleaks(탐지 + 폐기 실천)
- 작업 트리와 히스토리 내용을 실제로 검사
- 두 관문에서 막음: pre-commit과 CI
- 탐지 시 폐기까지 이어지는 절차
- 오탐은 기록된 근거와 함께 제외
본 사이트는 어떻게 하는가
본 사이트는 시크릿을 Git에 아예 두지 않는 토대 위에 서 있다 — 연결 문자열과 API 키는 서버의 보호된 설정(권한 제한된 env 파일)에만 있고, 저장소나 인계 노트에 평문으로 두지 않는다(→ 시크릿을 git 밖에 두기 / 자체 호스팅 Git vs GitHub). 그 위에, 사람은 늘 실수한다는 전제로 탐지기를 겹친다. 설계는 "넣지 않음"을 보장하고, gitleaks 같은 스캔이 "그래도 들어간 것"을 잡는다 — 이 두 층이 본 사이트의 시크릿 유출 방어다. 시크릿을 다루는 원칙 자체는 .env 파일과 시크릿, 비밀번호를 안전하게 저장하기와 이어진다.
다음으로 읽기
FAQ
Qgitleaks가 무엇인가요?
Git 저장소의 작업 트리와 커밋 히스토리를 스캔해 시크릿 — API 키, 개인 키, 토큰 — 이 커밋됐는지 탐지하는 무료 도구입니다. 정규식 규칙과 문자열 엔트로피(무작위성)로 '시크릿처럼 보이는 문자열'을 찾고, pre-commit 훅이나 CI에서 자동 점검으로 돌 수 있습니다.
Q.gitignore에 넣으면 시크릿이 보호되지 않나요?
충분치 않습니다. .gitignore는 '새 추적'만 막을 뿐 — 이미 커밋된 시크릿이나 git add -f 로 강제 추가된 것은 탐지하지 못합니다. 사고의 일부만 막으므로, gitleaks 같은 탐지기를 pre-commit과 CI 양쪽에 함께 두세요.
Q실수로 시크릿을 커밋하고 push했다면 어떻게 하나요?
그 시크릿을 유출된 것으로 다루세요. 최우선은 히스토리 재작성이 아니라, 노출된 키나 토큰을 폐기하고 교체(재발급)하는 것입니다. 공개 저장소나 로그에 닿은 시크릿은 회수할 수 없다고 가정하고 — 먼저 무효화한 다음, 히스토리를 정리하고 예방(gitleaks)을 더하세요.