API 키 깃허브 노출 막는 방법, 세팅 순서

Pipedeck 실제 화면

작성자

카테고리:

지금 키가 깃에 올라갔는지 확인하는 법

자동화 스크립트에 키를 넣어 두고 나면 가장 먼저 드는 생각이 “이거 커밋에 같이 올라갔나?”다. 저도 설정 파일에 키를 직접 적어 두고 커밋 전에 한 번도 확인하지 않은 적이 있다. 그때 제일 불안했던 건 저장소가 공개인지도 모르는 상태였다는 점이다.

확인은 삭제보다 먼저 한다. 올라간 게 확인되면 키를 폐기하고 재발급하는 것이 다음 순서다. 진단 명령은 프로젝트 루트에서 그대로 실행하면 된다.

# 1. 지금 작업 트리에 키 패턴이 있는지
git grep -n -E "sk-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}"

# 2. 과거 커밋 중에 그 패턴이 바뀐 적이 있는지
git log --all --oneline -G "sk-[A-Za-z0-9_-]{20,}"

# 3. 추적 중인 파일 중에 설정 파일이 섞였는지
git ls-files | grep -E "\.env|secret|key"

해석은 단순하다. 1번에 결과가 나오면 지금 파일에 키가 있다. 2번에 커밋이 나오면 파일을 지워도 기록은 남는다. 3번에 .env가 보이면 .gitignore가 아무 역할도 못 하고 있다는 뜻이다. 패턴은 서비스마다 다르니 발급받은 키 앞부분 형식에 맞춰 고쳐서 돌려라. 결과가 비어 있다고 안심하면 안 된다.

저장소가 공개였다면 원격에 올라간 시점부터 외부에서 볼 수 있었다고 가정한다. 포크가 있는지도 확인한다. 원본에서 파일을 지워도 포크에는 그대로 남는다. 저장소 설정 화면에서 공개 여부를 보고, 포크 수가 0인지 확인하면 된다.

API 키를 코드 밖으로 빼는 구조

처음에는 설정 파일 하나에 키와 설정값을 같이 넣었다. 나중에 보니 같은 키가 프로젝트 세 곳에 복사돼 있었다. 그래서 키만 따로 빼고 디렉터리를 나눴다.

my-project/
├── src/
│   └── main.py
├── config/
│   └── settings.yaml      (키 없음, 설정값만)
├── .env                   (실제 키, 커밋 금지)
├── .env.example           (자리표시자만, 커밋 O)
├── .gitignore
└── README.md

.env.example에는 실제 키를 절대 넣지 않는다. 자리표시자만 적어서 다른 사람이나 미래의 나도 어떤 변수가 필요한지 알 수 있게 한다.

# .env.example
OPENAI_API_KEY=여기에_키_입력
DB_PASSWORD=여기에_비밀번호_입력

코드에서는 환경변수로만 읽는다. Python 예시는 다음과 같다.

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
    raise RuntimeError("OPENAI_API_KEY가 없습니다. .env 또는 환경변수를 확인하세요.")

Node.js라면 require('dotenv').config() 뒤에 process.env.OPENAI_API_KEY를 읽고, 같은 방식으로 없으면 바로 에러를 던지게 하면 된다. 키가 없을 때 조용히 빈 값으로 넘어가면 나중에 401 같은 에러로만 드러나서 원인을 찾기 어렵다.

키 이름은 로컬, 서버, 크론에서 전부 같게 쓴다. 이름이 환경마다 다르면 뒤에서 설명할 크론 문제가 더 헷갈린다. 어떤 키가 어느 프로젝트에서 쓰이는지는 표로 따로 적어 둔다. 키 이름, 쓰는 곳, 발급처, 마지막 교체일 네 칸이면 충분하다.

.gitignore를 설정했는데도 키가 올라가는 이유

.gitignore에 .env를 넣고 안심했다가 다시 확인하게 된 적이 있다. 원인은 .env가 이미 커밋된 상태였기 때문이다. 아래 원인 중 자기 상황에 맞는 것을 골라 확인하면 된다.

  • 이미 추적 중인 파일. .gitignore는 아직 추적하지 않은 파일에만 적용된다. git ls-files .env에 결과가 나오면 이 경우다. 해결은 git rm --cached .env로 추적을 끊고 커밋하는 것이다. 로컬 파일은 그대로 남는다.
  • 패턴 위치 착오. 패턴에 슬래시가 없는 .env는 모든 하위 디렉터리에 적용된다. /.env처럼 앞에 슬래시를 붙이면 루트만 잡힌다. git check-ignore -v 경로로 어떤 규칙이 적용되는지 본다.
  • 다른 이름의 파일. prod.env, keys.json, secrets.txt는 .env 규칙에 안 걸린다. git ls-files | grep -E "\.env$|secret|key"로 이름을 훑는다.
  • 로그 출력. HTTP 클라이언트 디버그 로그에 Authorization 헤더가 그대로 찍히는 경우가 있다. grep -rn "Authorization" logs/로 확인한다.
  • 노트북 출력. Jupyter 노트북은 셀 출력이 .ipynb 파일에 저장된다. API 호출 결과를 찍은 셀에 키가 같이 남을 수 있다.
  • 문서와 커밋 메시지. README에 curl 예제를 붙이면서 실키를 넣거나, 커밋 메시지에 키를 적는 실수도 많다. git log --all --format=%B | grep "sk-"로 메시지를 본다.

문서나 로그 쪽은 아래 명령으로 한 번에 훑을 수 있다.

grep -rn -E "sk-[A-Za-z0-9_-]{20,}" --include="*.md" --include="*.ipynb" --include="*.log" .
Pipedeck 실제 화면

로컬, 서버, 크론에서 키를 각각 주입하는 방법

로컬은 .env와 load_dotenv로 충분하다. 일회성으로 돌릴 때만 셸에서 export를 쓰고, 그 명령은 히스토리에 키가 남지 않게 앞에 공백을 붙이거나 변수를 직접 읽는 쪽으로 바꾼다.

서버에서는 systemd의 EnvironmentFile을 쓴다. 키를 서비스 파일에 직접 쓰면 서비스 파일이 여기저기 복사되니 env 파일을 하나 만들어 분리했다.

# /etc/myjob/env  (따옴표와 export 없이 KEY=값 형식)
OPENAI_API_KEY=여기에_실제_키
DB_PASSWORD=여기에_실제_비밀번호
# /etc/systemd/system/myjob.service
[Service]
User=myjob
EnvironmentFile=/etc/myjob/env
ExecStart=/usr/bin/python3 /home/myjob/projects/my-project/src/main.py

권한은 실행 계정 소유에 600으로 맞춘다. systemd는 서비스 실행 계정으로 떨어지기 전에 루트 권한으로 env 파일을 읽기 때문에 600이어도 서비스는 정상으로 돈다.

sudo chown myjob:myjob /etc/myjob/env
sudo chmod 600 /etc/myjob/env
ls -l /etc/myjob/env

크론이 문제였다. 로컬 터미널에서 잘 돌던 스크립트가 크론에서만 인증 에러를 냈다. 터미널은 로그인 셸 설정 파일을 읽어서 환경변수가 잡혀 있었는데, 크론은 최소한의 환경으로 실행되니 키가 없었다. 래퍼 스크립트로 env 파일을 직접 읽게 하니 해결됐다.

#!/bin/bash
# /home/myjob/bin/run_daily.sh
set -euo pipefail
set -a
source /etc/myjob/env
set +a
cd /home/myjob/projects/my-project
exec /usr/bin/python3 /home/myjob/projects/my-project/src/main.py
chmod 700 /home/myjob/bin/run_daily.sh
# crontab -e 에 등록
0 9 * * * /home/myjob/bin/run_daily.sh >> /home/myjob/logs/daily.log 2>&1

crontab에서 % 문자는 줄바꿈으로 해석되니 date +%Y처럼 쓰면 명령이 깨진다. date +\%Y로 이스케이프해야 한다. 파이썬도 /usr/bin/python3처럼 절대 경로로 적는다. 크론의 PATH는 짧아서 가상환경 경로를 못 찾는 경우가 많다.

아직 못 푼 게 하나 있다. 실행 계정을 바꾸면 env 파일의 소유자와 권한을 같이 바꿔야 하는데, 이걸 빼먹어도 에러가 바로 나지 않고 다음 실행에서야 실패한다. 지금은 계정을 바꿀 때 체크리스트를 보고 확인하는 수준이다.

이미 올라간 키는 삭제만 하면 안전한가

아니다. 삭제만으로는 부족하다. 키가 외부에 노출됐다고 가정하면 순서는 이렇게 간다.

  1. 해당 키를 서비스 콘솔에서 먼저 폐기한다. 메뉴 이름은 서비스마다 다르고 자주 바뀌니 API 키 관리 화면에서 찾는다.
  2. 새 키를 발급하고 로컬, env 파일, .env를 모두 교체한다. 크론 래퍼가 읽는 파일도 빠뜨리지 않는다.
  3. 폐기 시점 이전과 이후의 사용 내역을 콘솔에서 확인한다. 낯선 호출 패턴이나 갑자기 늘어난 호출이 있는지 본다.
  4. git 히스토리에서 키를 지운다.
  5. 원격에 강제 푸시하고, 포크와 캐시에 남았을 가능성을 기록한다.
  6. 대응 내용을 기록으로 남긴다.

히스토리에서 키를 지우는 도구는 git filter-repo가 낫다. 치환할 문자열을 파일에 적고 실행한다.

# replacements.txt
sk-실제키값==>REMOVED_KEY

pip install git-filter-repo
git filter-repo --replace-text replacements.txt
git push origin --force --all

이 방법의 한계는 분명하다. 히스토리를 다시 쓰면 커밋 해시가 전부 바뀌고, 다른 사람의 클론과 포크에는 옛 기록이 그대로 있다. 키가 이미 복제됐다면 히스토리 정리는 뒷정리일 뿐이고, 키를 폐기하는 것이 실제 차단이다. 그래서 순서는 폐기와 재발급이 먼저다.

기록은 나중에 같은 상황이 와도 빠뜨리지 않도록 양식으로 남겨 둔다.

발견 시각 / 키 이름 / 노출 경로(파일, 커밋 해시) / 저장소 공개 여부 / 포크 존재 여부 / 폐기 시각 / 재발급 시각 / env 파일 교체 여부 / 크론 재실행 확인 / 사용 내역 확인 결과 / 빠뜨린 것

재발급만 하고 서버의 env 파일을 그대로 두면 크론 작업이 다음 실행에서 조용히 실패한다. 나도 이 항목을 빼먹을 뻔해서 양식 맨 아래 칸으로 넣어 두었다.

Pipedeck 실제 화면

노출을 빨리 알아채는 정기 점검 루틴

한 번 설정하고 끝내면 다음 실수를 못 잡는다. 점검은 커밋 전, 주간, 월간으로 나눠서 돌린다.

커밋 전에는 pre-commit 훅으로 gitleaks를 건다. 설정 파일 예시는 다음과 같다. rev에는 릴리스 페이지에서 확인한 최신 태그를 넣는다.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.4
    hooks:
      - id: gitleaks
pip install pre-commit
pre-commit install
pre-commit run --all-files

주간 점검은 크론으로 돌린다. 모든 저장소의 히스토리를 훑고, 발견되면 로그에 기록한다. gitleaks 버전에 따라 서브커맨드가 다르니 gitleaks git --help로 확인한다.

#!/bin/bash
# /home/me/bin/weekly_scan.sh
for repo in /home/me/projects/*/; do
  if ! gitleaks git "$repo" --redact --exit-code 1 >/dev/null 2>&1; then
    echo "$(date) 확인 필요: $repo" >> /home/me/logs/alerts.log
  fi
done
chmod 700 /home/me/bin/weekly_scan.sh
# crontab: 매주 일요일 오전 9시
0 9 * * 0 /home/me/bin/weekly_scan.sh

오탐도 나온다. 테스트 픽스처나 예제 값이 키 패턴과 비슷하면 걸린다. 이런 파일은 .gitleaksignore에 해시를 적어서 제외하는데, 무턱대고 제외 목록을 늘리면 진짜 키까지 놓치니 제외할 때마다 이유를 한 줄씩 적는다.

월간 점검은 사용량 확인이다. 각 서비스 콘솔에서 이상 과금 알림을 걸어 두는 것까지는 할 수 있는데, 알림 설정 방식이 서비스마다 달라서 빠짐없이 걸었는지 매달 키 목록과 대조해야 한다. 알림이 실제로 발송되는지 테스트하는 방법은 아직 정리하지 못했다.

Pipedeck 실제 화면

이 방식이 맞지 않는 경우

이 구조는 혼자 쓰는 개인 스크립트에 맞는다. 다음 경우에는 쓰지 마라.

  • 팀 프로젝트. 누가 어떤 키를 받았는지, 퇴사자 키를 어떻게 회수하는지를 env 파일로는 관리할 수 없다. 공유 시크릿 저장소나 시크릿 매니저가 필요하다.
  • 서버가 털렸을 때. env 파일은 서버 안에 평문으로 있다. 서버 접근을 막지 못하면 env 파일도 같이 털린다. 환경변수 방식은 저장 위치를 옮긴 것일 뿐, 서버 보안을 대신하지 않는다.
  • 로그와 에러 출력. 예외 메시지에 설정 객체를 통째로 찍으면 키가 로그로 나온다. 로그 수집 쪽으로 키가 흘러가는 건 이 구조로는 막을 수 없다.

내 경우는 지금 서버에 크론이 70개, 노트북에 9개 돌고 있다. 2026년 10월 6일 기준 작업 폴더도 서버 41개, 노트북 35개, git 저장소는 합쳐서 26개다. 이 규모에서 키가 어느 env 파일에 있는지 표 없이는 파악이 안 된다. 시크릿 매니저를 검토하기 시작한 건 이 지점부터다. 아직 도입하지는 않았다.

오늘 할 일과 매달 할 일

오늘 바로 할 것은 진단, 폐기, 재발급, 주입 방식 전환이다. 진단 명령으로 노출 여부를 보고, 노출됐으면 폐기부터 한다. 그다음 로컬, env 파일, 크론 래퍼의 키를 교체하고 크론을 한 번 수동으로 돌려 확인한다.

이번 주에 할 것은 pre-commit 훅과 주간 스캔 설정이다. 훅은 커밋마다, 주간 스캔은 일요일 아침에 돌아가게 두고, 로그 파일 위치를 한 번 열어서 확인한다.

매달 할 것은 세 가지다. 콘솔에서 사용량을 보고, 키 목록 표를 실제 env 파일과 맞춰 보고, 사고 기록 양식이 비어 있지 않은지 본다. 기록할 사고가 없다면 "없음"이라고 한 줄 적어 두는 편이 나중에 비교하기 좋다.

크론 환경변수 쪽은 이 글에서 다 다루지 못했다. 래퍼 스크립트를 더 단순하게 줄이는 방법은 다음 글에서 따로 정리할 생각이다.


글쓴이 정보

아일리고입니다. 자동화를 만들고 굴리며 겪은 일을 여기에 적습니다. 숏폼 영상은 ClipSquare 를 씁니다.

자주 나오는 질문

깃허브에 API 키를 올렸다면 가장 먼저 무엇을 해야 하나요?

파일에서 키를 지우기 전에 키부터 폐기하고 새로 발급받으세요. 저장소가 공개였다면 원격에 올라간 순간부터 외부에서 볼 수 있었다고 보는 게 안전합니다. 포크가 있는지도 같이 확인해야 합니다.

.gitignore에 .env를 넣었는데도 키가 깃에 올라가는 이유는 뭔가요?

.gitignore는 아직 추적하지 않은 파일에만 적용됩니다. 이미 커밋된 .env는 계속 추적되니, git rm --cached .env로 추적만 끊고 커밋하면 됩니다. 로컬 파일은 그대로 남습니다.

커밋 기록에 남은 키는 파일을 지우면 없어지나요?

아니요, 파일을 지워도 과거 커밋에는 키가 그대로 남아 있습니다. 그래서 기록을 고치는 것보다 키를 폐기하고 재발급하는 것이 먼저입니다. 기록 정리는 그다음에 해도 늦지 않습니다.