AI 코딩 중 API 키가 커밋되지 않게 막기: git pre-commit 훅 직접 만들고 시험하기
이 글의 핵심
AI에게 코드를 맡기면 예제 값 자리에 실제 키를 붙여 넣거나 .env를 같이 올리는 실수가 생기기 쉽습니다. 커밋 직전에 스테이징된 변경을 검사하는 셸 훅 하나를 만들고, 임시 저장소에서 10가지 경우로 시험했습니다. 첫 실행에서 개인 키 검사가 조용히 꺼져 있던 버그를 찾은 과정, 그리고 GitHub 토큰은 잡지 못하는 한계도 함께 적었습니다.
AI 코딩 도구에게 외부 서비스 연동을 시키면 코드에 키 자리가 생긴다. 그 자리에 예제 값 대신 내가 붙여 넣은 실제 키가 남거나, .env 파일이 같이 스테이징되는 일이 생길 수 있다. 사람이 훑어보는 것만으로는 놓치기 쉬워서, 커밋 직전에 기계가 한 번 걸러 주도록 git pre-commit 훅을 만들었다. 이 글은 그 훅의 전체 코드와, 임시 저장소에서 10가지 경우를 실행한 결과를 적는다.
시험 환경은 macOS, git 2.54.0, 기본 /bin/sh와 macOS 기본 grep이다. 모든 시험은 임시 저장소에서 했고, 사용한 키는 AWS 문서의 예제 키(AKIAIOSFODNN7EXAMPLE)나 내가 만든 가짜 문자열이다.
훅의 동작
git은 .git/hooks/pre-commit 실행 파일이 0이 아닌 값으로 끝나면 커밋을 중단한다. 이 훅은 두 가지를 본다.
- 스테이징된 파일 이름이
.env,.env.*,*.env,*.pem,*id_rsa*,*.p12인지. 폴더는 따지지 않고 파일 이름만 본다..env.example은 제외한다. - 스테이징된 변경 중 추가된 줄(
+로 시작)에 비밀값처럼 보이는 패턴이 있는지. 변경 전체가 아니라 추가된 줄만 보므로, 이미 있던 코드를 건드려서 걸리는 일이 줄어든다.
#!/bin/sh
# 스테이징된 변경에서 비밀값처럼 보이는 것을 찾아 커밋을 막는다.
fail=0
# 1) 올리면 안 되는 파일 이름 (폴더와 상관없이 파일 이름만 본다)
git diff --cached --name-only --diff-filter=ACM | while IFS= read -r f; do
b=$(basename "$f")
case "$b" in
.env|.env.*|*.env|*.pem|*id_rsa*|*.p12)
[ "$b" = ".env.example" ] || echo "차단: 비밀 파일 이름 $f" ;;
esac
done > /tmp/.hook_names.$$
if [ -s /tmp/.hook_names.$$ ]; then cat /tmp/.hook_names.$$; fail=1; fi
rm -f /tmp/.hook_names.$$
# 2) 추가된 줄의 내용 패턴
added=$(git diff --cached -U0 --no-color | grep '^+' | grep -v '^+++')
check() {
if printf '%s\n' "$added" | grep -E -q -e "$2"; then
echo "차단: $1 패턴 발견"; fail=1
fi
}
check "AWS 액세스 키" 'AKIA[0-9A-Z]{16}'
check "개인 키 헤더" '-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----'
check "sk- 형태 API 키" 'sk-[A-Za-z0-9_-]{20,}'
check "하드코딩된 secret/password" '(secret|password|passwd|api_key|apikey|token)[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']{8,}["'"'"']'
[ $fail -ne 0 ] && echo "커밋이 중단되었습니다. 의도한 값이면 git commit --no-verify" && exit 1
exit 0
설치는 파일을 .git/hooks/pre-commit으로 복사하고 chmod +x 하면 끝이다.
첫 실행에서 찾은 버그
처음 쓴 훅은 grep -E -q "$2"였다. 시험을 돌리니 개인 키 검사 줄에서 이런 오류가 났다.
grep: unrecognized option `-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----'
usage: grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz] [-A num] [-B num] [-C[num]]
패턴이 -로 시작해서 grep이 옵션으로 읽은 것이다. 이 경우 grep은 오류로 끝나고 if는 거짓이 되므로, 개인 키 검사는 아무것도 막지 못한 채 훅이 통과한다. 오류 문구가 화면에 떠서 알았을 뿐, 출력이 없었다면 검사가 켜져 있다고 믿었을 것이다. -e "$2"로 고치니 해결되었다.
이 사례의 교훈은 검사 도구도 한 번은 실제로 걸리는 입력으로 시험해야 한다는 점이다. AI가 훅 스크립트를 써 주더라도 마찬가지다. 통과하는 시험만 하면 이런 버그를 못 본다.
10가지 시험 결과
고친 훅으로 임시 저장소에서 실행한 결과다. 종료 코드 1이면 막힌 것이다.
| 번호 | 스테이징한 내용 | 결과 |
|---|---|---|
| 1 | print("hello") | 통과 |
| 2 | AWS_KEY = "AKIAIOSFODNN7EXAMPLE" | 차단 (AWS 액세스 키) |
| 3 | .env 파일 | 차단 (비밀 파일 이름) |
| 4 | .env.example 파일 | 통과 |
| 5 | password = "correct-horse-battery" | 차단 (하드코딩 비밀번호) |
| 6 | password = os.environ["DB_PASSWORD"] | 통과 |
| 7 | -----BEGIN RSA PRIVATE KEY----- 줄 | 차단 (개인 키 헤더) |
| 8 | x = "sk- + a 30개 + " | 차단 (sk- 형태) |
| 9 | 2번과 같은 AWS 키를 --no-verify로 커밋 | 통과 (훅이 실행되지 않음) |
| 10 | tok = "ghp_ + b 36개 + " | 통과 (잡지 못함) |
6번처럼 환경 변수를 읽는 코드는 막히지 않아야 쓸 만한데, 이 패턴은 = 바로 뒤에 따옴표로 둘러싼 8자 이상의 값이 올 때만 걸리기 때문에 그렇게 동작했다.
두 번째 버그: 하위 폴더와 공백 이름
위 표의 10가지를 통과한 첫 버전으로 파일 이름 검사를 더 시험했다. 처음 쓴 반복문은 for f in $(git diff --cached --name-only ...)에 case "$f" in .env|.env.*|...였다.
| 스테이징한 파일 | 첫 버전 | 고친 버전 |
|---|---|---|
config/.env | 통과 (놓침) | 차단 |
prod.env | 통과 (놓침) | 차단 |
my key.pem | 차단됐지만 이름이 key.pem으로 잘려 표시 | 차단, 이름 그대로 표시 |
case 패턴 .env는 경로 전체와 비교하기 때문에 하위 폴더의 .env와 맞지 않았다. 그리고 $(...) 결과를 공백으로 쪼개서 공백이 든 이름이 두 조각이 되었다. 앞의 10가지 시험은 모두 저장소 최상위 파일이어서 이 버그를 드러내지 못했다. 고친 버전은 basename으로 파일 이름만 비교하고 read -r로 한 줄씩 읽는다. 고친 뒤 앞의 1~8번을 다시 돌려 결과가 같음을 확인했다. 이름이 .env local처럼 점 없이 공백이 이어지는 파일은 패턴에 맞지 않아 통과한다.
팀에서 같은 훅 쓰기
.git/hooks는 저장소에 커밋되지 않는다. 훅 파일을 .githooks/pre-commit으로 저장소에 넣고 각자 한 번 git config core.hooksPath .githooks를 실행하면 같은 훅이 쓰인다. 임시 저장소에서 이렇게 설정해도 훅이 실행되는 것을 확인했다. 각자 설정해야 한다는 점은 그대로여서, 설정을 건너뛴 사람의 커밋은 검사되지 않는다.
문서 속 예제 키도 걸린다
notes.md에 AKIAIOSFODNN7EXAMPLE만 적어 커밋해도 AWS 키 패턴으로 차단되었다. 문서에 예제 키를 적는 글이나 README에서는 거짓 양성이 되므로, 이럴 때는 예제 값을 AKIA...처럼 줄여 쓰거나 해당 커밋만 --no-verify를 쓴다.
한계
- 10번처럼 이 훅이 모르는 형식은 잡지 못한다. GitHub 토큰 형태(
ghp_...)는 패턴을 넣지 않아 통과했다. 서비스마다 형식이 다르므로 쓰는 서비스에 맞춰 패턴을 추가해야 한다. - 9번처럼
--no-verify로 건너뛸 수 있다. 훅은 실수를 막는 장치이지 정책 강제 수단이 아니다. - 훅은 로컬 저장소에만 설치된다. 새로 clone한 저장소에는 직접 복사해야 하고, 팀 단위로 강제하려면 CI나 서버 쪽 검사가 따로 필요하다.
- 패턴 검사라서 거짓 양성이 생긴다.
token = "example-token-value"같은 문서용 예제 문자열도 걸린다. - 정규식 검사가 못 잡는 비밀값(임의의 긴 문자열)이 있다. 전문 도구(예: gitleaks 등)는 더 많은 형식을 다룬다. 이 글에서는 그런 도구를 실행해 비교하지 않았다.
- 이미 커밋한 키는 이 훅과 무관하다. 기록에서 지우는 것보다 키 폐기와 재발급이 먼저다.
AI 코딩에서 같이 챙길 것
- AI에게 키를 대화창에 붙여 넣지 않는다. 키는 환경 변수나
.env로만 전달하고, 코드에는os.environ이나process.env로 읽는 줄만 남기게 지시한다. .gitignore에.env를 넣는 일을 프로젝트 첫 단계에 포함시킨다. 이 훅은.gitignore를 대체하지 않고 그 뒤의 두 번째 방어선이다.- 지침 파일에 “비밀값은 코드에 쓰지 않는다”는 한 줄을 적어 둔다. 지침 파일 쓰는 방법은 바이브 코딩 작업 규칙 글에 적었다.