API 키 유출 경로를 7가지로 정리합니다 | .env 검색에 대한 대응 절차

이 글의 핵심 요약

• API 키 유출 원인은 Git 히스토리, 프론트엔드 결과물, 공개 설정 실수, 로그, 외부 도구, 서버 공개 파일, 인적 공유의 7가지 경로로 정리할 수 있으며, '직접 .env를 도난당하는' 경우는 그 일부에 불과합니다.
• 공개 사이트에는 /.env 를 찾는 접근이 일상적으로 도착하므로, 웹 루트에 비밀 정보를 두지 않는 설계와, 유출을 전제로 즉시 무효화 절차를 준비해 두는 것이 가장 효과적인 대책입니다. - 대응 우선순위는 '무효화할 수 있는 체제 → 누설하지 않는 구성 → 탐지의 자동화' 순서입니다. 커밋 전 스캔과 GitHub의 Push Protection을 결합하면, 번거로움이 적으면서도 효과를 볼 수 있습니다.

API 키는 어디에서 유출되는가

'API 키 유출'이라고 검색하는 많은 사람들은 다음 의문을 가지고 있습니다.

• 내 사이트에 /.env 에 대한 접근이 오고 있다. 괜찮은 것인가? - 유출된다면, 어느 부분이 위험한가?
• 유출되면 무엇을 해야 하는가?

참고한 것은 자사 사이트에 도착한 .env 검색 1,566건을 분석한 Qiita의 글입니다 (https://qiita.com/songchong/items/02672765fe53f911a1a0). 제목에 따르면 공개 사례를 7가지 경로로 나누고 있습니다.

본 글은 그 주제를 '자신의 환경에서 무엇을 점검할 것인가'라는 시각으로 재구성한 것입니다. 7가지 경로의 구분 방식은 필자의 정리이며, 원문 기사의 분류와 일치한다고 보장할 수 없습니다. 건수 외의 수치는 게재하지 않습니다.

자신의 사이트에 오는 .env 검색의 정체

무슨 일이 일어나고 있는가

공개 웹 서버에는 /.env 나 /.git/config, /wp-config.php.bak 등을 기계적으로 찾는 접근이 도착합니다. 목표는 설정 파일의 분실입니다.

이는 특정 사이트를 겨냥한 공격이 아닙니다. 인터넷 전체를 무차별로 조사하는 자동 스캔의 일종입니다. 접근 로그에 404가 나열되어 있어도, 즉시 침해되었다고 말할 수는 없습니다.

정말 위험한 경우는 언제인가

위험한 것은 로그 안에 '200이 반환된' 줄이 있을 때입니다. 다음 명령어로 확인할 수 있습니다.

# nginx의 접근 로그에서, .env 계열에 대한 접근과 응답 코드를 본다
grep -E '/(env|git)' /var/log/nginx/access.log | awk '{print $9}' | sort | uniq -c

200이나 403 외의 것이 섞여 있다면, 그 경로에 파일이 존재할 가능성이 있습니다. 먼저 응답 내용을 확인해 주십시오.

유출 경로를 7가지로 나누어 정리한다

1. Git 히스토리

가장 많이 언급되는 경로입니다. 파일을 삭제해도 히스토리에는 남아 있습니다. 공개 리포지토리라면 누구나 커밋을 추적할 수 있습니다.

GitHub는 이미 알려진 형식의 시크릿을 커밋 시 감지하는 기능을 제공합니다 (https://docs.github.com/en/code-security/secret-scanning). Push Protection은 push 시점에서 차단하는 메커니즘입니다.

2. 프론트엔드 결과물

브라우저에 배포되는 JavaScript에 키가 들어있는 패턴입니다. 환경 변수를 내장(embed)하는 설정 상태로 비밀 키를 넘겨버리는 경우입니다.

예를 들어 Next.js는 NEXT_PUBLIC_

de로 시작하는 변수를 브라우저용으로 공개하는 사양입니다 (https://nextjs.org/docs/app/guides/environment-variables). 이 접두사를 붙이는 순간, 공개 전제가 됩니다. 소스맵을 프로덕션에 두는 경우에도 원본 코드가 읽힙니다.

3. 웹 루트의 공개 파일

자사 사이트에 도달하는 .env를 찾는 것이 노리는 경로입니다. 문서 루트 아래에 .env를 놓으면, 설정에 따라 URL에서 가져올 수 있습니다.

대책은 간단합니다. 설정 파일을 웹 루트 밖에 둡니다. 둘 수 없는 경우, 웹 서버 측에서 점 파일(dot file)을 거부합니다.

# nginx: 점으로 시작하는 파일 접근 거부
location ~ /\. {
deny all;
...

4. 로그・에러 화면

디버그 모임 상태로 프로덕션에 배포하면, 환경 변수를 포함한 에러 화면이 표시될 수 있습니다. 로그에 Authorization 헤더를 그대로 출력하는 구현도 같은 문제입니다.

로그 출력 단계에서 키의 형식을 마스킹(mask)해야 합니다.

5. CI/CD・컨테이너

Docker 이미지는 레이어 히스토리(layer history)를 가집니다. 빌드 중에 COPY .env나 ENV KEY=...를 작성하면, 나중에 지워도 레이어에 남아있습니다. 빌드용 비밀은 BuildKit의 secret 마운트 등으로 전달하는 것이 안전합니다.

6. 외부 도구・챗

채팅에 붙여넣기, 화면 공유, AI 어시스턴트에 입력하는 것이 해당됩니다. 기술적인 결함이 아니라 운영상의 문제입니다.

공유 수단을 하나로 정해야 합니다. 비밀번호 관리자나 시크릿 관리 서비스로 모으면 경로가 줄어듭니다.

7. 의존・제3자 서비스

사용 중인 패키지나 연동 앱이 침해되면, 거기서 환경 변수가 읽힐 우려가 있습니다. 스스로 막기 어려운 경로입니다.

그렇기에 키의 권한은 최소화해야 합니다. 침해되어도 피해가 작아지기 때문입니다.

유출된 전제하에 작동하는 것: 폐기 절차

감지보다 먼저 정해두어야 할 것은, 폐기(revocation) 절차입니다. 유출되면 다음 순서로 진행합니다.

• 해당 키를 발행처의 관리 화면에서 무효화한다
• 새로운 키를 발행하고, 프로덕션 설정을 교체한다
• 이용 이력을 확인하여 의심스러운 호출이 없는지 조사한다
• 원인의 경로를 특정하여 막는다

이력에서 파일을 지우는 것은 4번 이후의 이야기입니다. 먼저 폐기합니다. 미리 이력을 수정해도, 이미 복사되었을 가능성은 사라지지 않습니다.

유출되지 않는 시스템 구축하기

커밋 전에 gitleaks로 검사하기

gitleaks는 리포지토리의 시크릿을 탐지하는 오픈소스 도구입니다 (https://github.com/gitleaks/gitleaks).

# 리포지토리 전체 이력 검사
gitleaks detect --source . -v
# 커밋 전 훅(pre-commit hook)으로, 스테이징된 변경만 검사
...

도입 시에는 먼저 과거 이력에 대해 한 번 실행해 주세요. 오래된 키가 발견될 수 있습니다.

설계의 기본은 환경 변수와 분리하기

설정을 환경 변수에 두는 생각은 Twelve-Factor App에 정리되어 있습니다 (https://12factor.net/config). 코드와 설정을 분리함으로써, 실수로 커밋할 기회가 줄어듭니다.

더 나아가, .gitignore에 .env를 넣고 대신 .env.example을 커밋합니다. 내용은 더미 값만으로 합니다.

일차적인 소감: 건수보다 '배치'의 문제

원문 기사와 공식 문서를 비교하며 알게 된 점이 있습니다. 1,566건이라는 숫자는 크게 보이지만, 내용은 자동 스캔 시도 횟수입니다. 중요한 것은 그중 몇 건이 200을 반환했는지였습니다.

자신의 로그로 같은 확인만 해도 대부분의 사람은 안심할 수 있을 것입니다. 다만, 손으로 모든 경로를 재현하여 시험한 것은 아닙니다. 경로 4~7은 공개된 해설을 바탕으로 정리한 것입니다.

단점・부적합한 사람・잘 안 되는 경우

지금까지의 대책에는 한계도 있습니다.

• 스캐너는 만능이 아닙니다. 자체 형식의 키나 암호화/분할된 문자열은 탐지하기 어렵습니다. - 오탐지(誤検知) 운영 비용이 있습니다. 작은 팀에서는 무시 규칙이 늘어나 결국 형식적으로만 남게 될 수 있습니다. - 히스토리 수정은 부작용이 큽니다. 팀 개발에서 강제 푸시를 하면 다른 사람의 작업을 망가뜨립니다. 실행 전에 반드시 합의를 얻으세요. - 개인의 취미 사이트에서는 과도할 때도 있습니다. 하지만 결제나 개인 정보에 관련된 키를 다룬다면 규모와 상관없이 필요합니다. - 프런트엔드만으로 완결되는 설계로는 지킬 수 없습니다. 브라우저로 전달된 값은 모두 노출된다는 전제로 다루어야 합니다.

다음에 취할 행동

오늘 할 수 있는 것은 3가지입니다.

• 자사 사이트의 접근 로그에서 /.env 에 대한 응답 코드를 확인하기 - 손에 쥔 주요 리포지토리에서 gitleaks detect 를 한 번 실행하기 - 사용 중인 API 키의 만료 절차를 발행처별로 메모해 두기

남은 질문은 하나입니다. 지금의 키를 5분 이내에 교체할 수 있습니까?

자주 묻는 질문

사이트에 /.env 접근이 오면 침해된 건가요

접근이 왔다고 해서 침해된 것은 아닙니다. 자동 스캔이 전체적으로 보내는 시도입니다. 응답 코드가 404나 403이라면 파일은 가져가지 못했습니다. 200이 반환되었다면 즉시 해당 키를 만료시키세요.

.env를 문서 루트에 두면 왜 위험한가요

웹 서버가 파일을 정적 파일로 배포해 버릴 가능성이 있기 때문입니다. URL을 직접 지정하면 내용물이 읽힐 수 있습니다. 설정 파일은 문서 루트 외부에 두는 것이 기본입니다.

GitHub에 API 키를 커밋했다면 어떻게 해야 하나요

먼저 발행처에서 키를 만료시키고, 새로운 키로 교체해야 합니다. 히스토리 삭제는 그 이후입니다. 공개 리포지토리에서는 복사되었을 가능성을 전제로 생각합니다.

커밋한 파일을 삭제하면 안전한가요

안전하지 않습니다. Git은 과거의 커밋을 보관하고 있기 때문에, 히스토리에서 추출할 수 있습니다. 히스토리 수정은 보조적인 수단이며, 만료시키는 것이 우선입니다.

프런트엔드에 API 키를 둬도 되는 경우는 있나요

공개 전제로 발행된 키(도메인 제한이 걸린 공개용 키 등)라면 가능합니다. 비밀키는 둘 수 없습니다. 브라우저로 전달되는 값은 누구나 볼 수 있습니다.

시크릿 탐지 도구는 무엇을 골라야 하나요

우선 무료로 사용할 수 있는 gitleaks와 GitHub의 Push Protection 병용이 추천됩니다. 커밋 전과 푸시 시 두 단계에서 막을 수 있습니다. 도입 후에는 오탐지 처리를 결정해 두면 지속하기 쉽습니다.

키 로테이션은 어느 정도 주기로 해야 하나요

일률적인 정답은 없습니다. 발행처의 권장 사항과 키의 권한 크기에 따라 결정합니다. 권한이 큰 것일수록 짧고 빈번한 운영이 적합합니다. 우선 만료 절차를 갖추는 것이 먼저입니다.

Discussion