API 키와 비밀 정보 관리법
API 키, 데이터베이스 비밀번호, 결제 연동 키 같은 비밀을 코드에서 떼어 내 안전하게 다루는 법을 배워요. 저장소에서 비밀을 찾아내는 작은 검사기를 만들어 키 모양과 무작위해 보이는 문자열을 잡아내고, 지운 비밀도 git 기록에 그대로 남는 문제를 확인해요. 환경 변수와 운영체제의 비밀 보관함, 비밀 관리 서비스 중 무엇을 언제 쓰는지, 로그에서 가리는 법, 서비스를 멈추지 않고 키를 바꾸는 두 키 겹치기 방식, 그리고 키가 새었을 때 가장 먼저 할 일까지 다뤄요.
서비스는 혼자 일하지 않아요. 결제 회사, 메일 발송 서비스, 지도, AI API, 클라우드 저장소와 대화하려면 비밀 정보가 필요해요. API 키, 데이터베이스 비밀번호, 서명용 비밀 값 같은 것들이요. 이 비밀은 돈과 직결돼요. 새어 나간 AI API 키로 하룻밤에 큰 요금이 나오거나, 클라우드 키로 남의 채굴 서버가 돌아가는 일이 실제로 흔해요. 그리고 대부분은 해킹이 아니라 코드에 적어 둔 키를 저장소에 올리는 실수에서 시작해요.
코드에 적힌 비밀 찾기
공개 저장소에 올라온 키는 몇 분 안에 자동 수집 프로그램에 발견된다고 알려져 있어요. 내 저장소에 비밀이 섞여 있는지 찾는 작은 검사기를 만들어 볼게요. 예제의 값은 모두 가짜예요(AKIAIOSFODNN7EXAMPLE은 AWS 공식 문서의 예시 값이에요).
import math
import re
from collections import Counter
files = { # 어느 저장소의 파일들이라고 쳐요(값은 모두 가짜예요)
"app.py": 'API_KEY = "sk-live-4f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c"\nTIMEOUT = 30\n',
"deploy.sh": "export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\n",
"settings.py": 'DB_PASSWORD = "correct-horse-battery"\nDEBUG = False\n',
"README.md": "설치하려면 pip install -r requirements.txt 를 실행하세요\n",
"config.yaml": "upload_token: Zq8xVb2NcR7tLw4KpY9sHf3JdG6mTa1E\n",
}
PATTERNS = {
"API 키 모양(sk-)": re.compile(r"sk-[A-Za-z0-9-]{20,}"),
"AWS 접근 키": re.compile(r"AKIA[0-9A-Z]{16}"),
"비밀번호 대입": re.compile(r"(?i)(password|passwd|secret)\w*\s*[=:]\s*\S+"),
}
def entropy(text): # 글자가 얼마나 고르게 섞였는지(비트/글자)
counts = Counter(text)
return -sum(c / len(text) * math.log2(c / len(text)) for c in counts.values())
for name, text in files.items():
for line_no, line in enumerate(text.splitlines(), 1):
hits = [label for label, pattern in PATTERNS.items() if pattern.search(line)]
long_tokens = [t for t in re.findall(r"[A-Za-z0-9+/=_-]{24,}", line) if entropy(t) > 4.0]
if long_tokens and not hits:
hits.append("무작위해 보이는 긴 문자열")
if hits:
print(f"{name}:{line_no} {', '.join(hits)}")
app.py:1 API 키 모양(sk-)
deploy.sh:1 AWS 접근 키
settings.py:1 비밀번호 대입
config.yaml:1 무작위해 보이는 긴 문자열
- 모양으로 찾기: 많은 서비스의 키는 정해진 머리글(
sk-,AKIA등)로 시작해서 정규식으로 찾기 쉬워요. - 이름으로 찾기:
PASSWORD = "..."처럼 이름이 수상한 대입문을 찾아요. - 무작위성으로 찾기:
upload_token은 이름도 모양도 평범하지만, 값이 글자가 고르게 섞인 긴 문자열이라 엔트로피(확률과 통계 트랙의 정보 이론 강의에서 본 그것)가 높아요. 사람이 쓴 낱말은 같은 글자가 자주 반복돼서 엔트로피가 낮아요.
실제로는 gitleaks, trufflehog 같은 검사 도구를 쓰고, 커밋하기 전에 자동으로 검사하게 하거나(pre-commit) CI 파이프라인에 넣어요. GitHub도 공개 저장소에 알려진 모양의 키가 올라오면 경고하고, 푸시 자체를 막는 기능을 제공해요.
지운 비밀도 기록에 남아요
"키를 지우는 커밋을 하나 더 올리면 되지 않나?"라고 생각하기 쉬워요. 도커 강의의 이미지 층과 같은 이야기예요.
commits = [ # (커밋 설명, 그때의 settings.py)
("처음 만듦", 'DB_PASSWORD = "correct-horse-battery"\n'),
("비밀번호를 환경 변수로 옮김", 'DB_PASSWORD = os.environ["DB_PASSWORD"]\n'),
]
print("지금 파일:", commits[-1][1].strip())
print("기록을 뒤지면:", [msg for msg, text in commits if "correct-horse" in text])
지금 파일: DB_PASSWORD = os.environ["DB_PASSWORD"]
기록을 뒤지면: ['처음 만듦']
git은 모든 커밋의 내용을 기억해요. 지금 파일에는 비밀이 없어도, 누구든 저장소를 받으면 첫 커밋에서 비밀번호를 꺼낼 수 있어요. 기록을 다시 써서(git filter-repo 같은 도구) 지울 수는 있지만, 이미 누군가 받아 갔을 수 있으니 한 번 올라간 비밀은 샌 것으로 보고 바꿔야 해요. 처음부터 올리지 않는 게 가장 좋아요.
비밀은 어디에 두나
| 어디에 | 어울리는 때 | 주의할 점 |
|---|---|---|
| 환경 변수 | 서버와 컨테이너에 설정을 넣는 가장 흔한 방법 | 프로세스 목록이나 오류 화면에 드러나지 않게 조심해요 |
.env 파일 | 개발용 컴퓨터에서 환경 변수를 편하게 넣을 때 | 반드시 .gitignore에 넣어요. 예시용 .env.example에는 이름만 적어요 |
| 운영체제의 비밀 보관함 | 내 컴퓨터에서 도는 자동화 프로그램 | 윈도의 자격 증명 관리자와 DPAPI, 맥의 키체인처럼 로그인한 사용자만 풀 수 있게 암호화해 줘요 |
| 호스팅과 CI의 비밀 설정 | 배포된 서비스, 파이프라인 | 화면에서 다시 볼 수 없게 하고, 필요한 곳에만 줘요 |
| 비밀 관리 서비스 | 서비스가 많고 사람이 많을 때 | 누가 언제 꺼냈는지 기록되고, 자동으로 바꿀 수도 있어요 |
프로그램은 비밀을 실행할 때 바깥에서 받고, 받지 못하면 바로 멈추게 만들어요. 로그에는 가려서 남겨요.
import os
def require_env(name):
value = os.environ.get(name)
if not value:
raise SystemExit(f"설정이 빠졌어요: 환경 변수 {name}를 넣어 주세요") # 시작할 때 바로 멈춰요
return value
def mask(value, keep=4):
return "*" * 8 + value[-keep:] if len(value) > keep * 2 else "*" * 8
os.environ["PAYMENT_API_KEY"] = "pk-test-0123456789abcdefWXYZ" # 실제로는 서버 설정에서 넣어 줘요
key = require_env("PAYMENT_API_KEY")
print("로그에는 이렇게:", mask(key))
try:
require_env("MAIL_API_KEY")
except SystemExit as e:
print(e)
로그에는 이렇게: ********WXYZ
설정이 빠졌어요: 환경 변수 MAIL_API_KEY를 넣어 주세요
- 빠지면 시작부터 멈춰요. 비밀이 없는 채로 일단 돌다가 한참 뒤 결제하는 순간에 실패하는 것보다, 배포 직후 바로 알아채는 게 나아요.
- 가려서 남겨요. 끝 몇 글자만 보여 주면 "어떤 키가 쓰였는지"는 구별하면서 키 자체는 드러나지 않아요. 짧은 비밀은 전부 가려요.
- 기본값을 두지 않아요.
os.environ.get("KEY", "test-key")처럼 기본값을 두면, 설정을 빠뜨린 운영 서버가 시험용 키로 조용히 돌아가요.
키를 나눠 쓰고, 좁게 쓰고
- 환경마다 다른 키. 개발용, 시험용, 운영용 키를 나눠요. 개발 컴퓨터에서 새도 운영 데이터는 안전해요.
- 서비스마다 다른 키. 블로그 자동화와 공개 웹사이트가 같은 AI API 키를 쓰면, 공개 사이트에서 키가 새거나 남용될 때 블로그 자동화까지 함께 멈춰요. 쓰는 곳마다 따로 발급하면 새었을 때 그것만 끊으면 돼요. 사용량도 따로 보여요.
- 권한과 한도를 좁게. 읽기만 하면 되는 곳에는 읽기 권한만, 특정 주소에서만 쓰게, 하루 사용 한도를 걸 수 있다면 걸어요.
- 브라우저에는 두지 않아요. 비동기 강의에서 봤듯이 브라우저로 보낸 코드는 누구나 열어 봐요. 비밀이 필요한 호출은 내 서버가 대신 해요.
멈추지 않고 키 바꾸기
키는 정기적으로, 그리고 새었을 때 바로 바꿔야 해요. 그런데 키를 바꾸는 순간 옛 키를 쓰는 쪽이 모두 실패하면 서비스가 멈춰요. 그래서 잠시 두 키를 함께 받는 순서로 바꿔요. 결제 회사가 보내는 알림의 서명을 확인하는 상황으로 볼게요.
import hashlib
import hmac
def sign(key, body):
return hmac.new(key, body, hashlib.sha256).hexdigest()
def verify(body, signature, active_keys): # 바꾸는 동안에는 키 두 개를 함께 받아요
return any(hmac.compare_digest(sign(k, body), signature) for k in active_keys)
old_key, new_key = b"key-2026-10", b"key-2026-11"
body = b'{"event": "payment.done", "amount": 39000}'
print("1단계(옛 키만):", verify(body, sign(old_key, body), [old_key]))
print("2단계(둘 다 받음): 옛 서명", verify(body, sign(old_key, body), [new_key, old_key]),
"/ 새 서명", verify(body, sign(new_key, body), [new_key, old_key]))
print("3단계(옛 키 폐기): 옛 서명", verify(body, sign(old_key, body), [new_key]),
"/ 새 서명", verify(body, sign(new_key, body), [new_key]))
print("내용을 바꾸면:", verify(b'{"event": "payment.done", "amount": 1}', sign(new_key, body), [new_key]))
1단계(옛 키만): True
2단계(둘 다 받음): 옛 서명 True / 새 서명 True
3단계(옛 키 폐기): 옛 서명 False / 새 서명 True
내용을 바꾸면: False
- 새 키를 만들고, 받는 쪽이 옛 키와 새 키를 모두 받아들이게 해요.
- 보내는 쪽을 새 키로 바꿔요. 이 사이에 도착한 옛 서명도, 새 서명도 모두 통과해요.
- 옛 키를 쓰는 곳이 없는 걸 확인한 뒤, 옛 키를 폐기해요.
마지막 줄은 서명이 하는 일이에요. 금액을 39,000원에서 1원으로 바꾸면 서명이 맞지 않아 거절돼요. 결제 알림, 웹훅 같은 요청은 반드시 서명을 확인해야, 누군가 "결제 완료" 알림을 꾸며 보내는 일을 막을 수 있어요.
키가 새었을 때
- 바로 폐기하고 새로 발급해요. 기록을 지우는 것보다 먼저예요. 키가 살아 있는 동안 계속 쓰일 수 있어요.
- 사용 기록을 확인해요. 언제부터, 어디서, 무엇에 쓰였는지 서비스의 사용 기록과 요금을 봐요.
- 피해 범위를 정리해요. 그 키로 볼 수 있던 데이터, 할 수 있던 일을 확인하고, 필요하면 사용자에게 알려요.
- 원인을 막아요. 저장소 기록을 정리하고, 비밀 검사기를 커밋 전과 CI에 넣고, 키를 코드 밖으로 옮겨요.
실습
- 검사기에
-----BEGIN PRIVATE KEY-----같은 개인 키 머리글을 찾는 규칙을 더해 보세요. - 검사기가
README.md의 긴 주소나 해시 값을 잘못 잡는 경우를 만들어 보고, 엔트로피 기준을 어떻게 조정하면 좋을지 생각해 보세요. 오탐을 줄이면 무엇을 놓칠 수 있나요? - 내 프로젝트의
.gitignore에.env가 들어 있는지 확인하고, 이름만 적은.env.example을 만들어 보세요. require_env를 바꿔, 시작할 때 필요한 비밀 목록을 한꺼번에 검사하고 빠진 것을 모두 알려 주게 해 보세요.- 서명 예제에 "알림을 보낸 시각"을 더해, 5분보다 오래된 알림은 서명이 맞아도 거절하게 해 보세요. 왜 필요할까요?
자주 하는 실수
- 코드에 키를 적는다. 언젠가 저장소에 올라가요. 실행할 때 바깥에서 받아요.
.env를.gitignore에 넣지 않는다. 첫 커밋에 실려 올라가요.- 지우는 커밋으로 끝냈다고 생각한다. 기록에 남아요. 키를 바꿔요.
- 모든 곳에 같은 키를 쓴다. 하나가 새면 전부 함께 막아야 해요. 쓰는 곳마다 따로 발급해요.
- 로그와 오류 화면에 키를 찍는다. 가려서 남겨요.
- 비밀이 없을 때 기본값으로 돌게 둔다. 설정이 빠진 걸 늦게 알아요. 시작할 때 멈춰요.
- 키를 바꾸다가 서비스를 멈춘다. 잠시 두 키를 함께 받는 순서로 바꿔요.
- 웹훅의 서명을 확인하지 않는다. 누구나 "결제 완료"를 꾸며 보낼 수 있어요.
점검 문제
- 비밀 정보가 새는 가장 흔한 경로는?
- 검사기가 비밀을 찾는 세 가지 방법은?
- 비밀을 지우는 커밋을 올려도 안전하지 않은 이유와, 해야 할 일은?
- 비밀이 빠졌을 때 기본값으로 돌지 않고 시작할 때 멈추게 하는 이유는?
- 블로그 자동화와 공개 웹사이트에 같은 API 키를 쓰면 안 되는 이유는?
- 키를 멈추지 않고 바꾸는 세 단계는?
- 웹훅에 서명을 확인해야 하는 이유는?
- 키가 새었을 때 가장 먼저 할 일은?
정답
- 코드나 설정 파일에 적어 둔 키를 저장소에 올리는 실수예요.
- 정해진 머리글 같은 키의 모양,
PASSWORD =같은 수상한 이름, 글자가 고르게 섞인 긴 문자열의 높은 엔트로피로 찾아요. - git은 모든 커밋의 내용을 기억해서 이전 커밋에서 비밀을 꺼낼 수 있기 때문이에요. 이미 받아 간 사람이 있을 수 있으니 키를 바꾸고, 기록도 정리해요.
- 설정이 빠진 것을 배포 직후 바로 알아채기 위해서예요. 기본값으로 돌면 시험용 키로 조용히 돌다가 중요한 순간에 실패해요.
- 한쪽에서 키가 새거나 남용되면 다른 쪽까지 함께 막아야 하고, 사용량도 구별할 수 없기 때문이에요. 쓰는 곳마다 따로 발급하면 새었을 때 그것만 끊으면 돼요.
- 받는 쪽이 옛 키와 새 키를 모두 받게 하고, 보내는 쪽을 새 키로 바꾸고, 옛 키를 쓰는 곳이 없는 걸 확인한 뒤 옛 키를 폐기해요.
- 서명을 확인하지 않으면 누구나 "결제 완료" 같은 알림을 꾸며 보낼 수 있기 때문이에요. 내용이 바뀌면 서명이 맞지 않아 거절돼요.
- 새어 나간 키를 바로 폐기하고 새로 발급하는 거예요. 키가 살아 있는 동안은 계속 쓰일 수 있어요.
다음 강의
비밀을 지켰으니, 이번에는 서비스의 문을 노리는 공격을 막을 차례예요. 다음 강의에서는 지금까지 여러 강의에서 조금씩 본 XSS, SQL 인젝션, 그리고 CSRF를 하나씩 직접 재현하고 막는 법을 정리해요.