API 키와 비밀 정보 관리법

API 키, 데이터베이스 비밀번호, 결제 연동 키 같은 비밀을 코드에서 떼어 내 안전하게 다루는 법을 배워요. 저장소에서 비밀을 찾아내는 작은 검사기를 만들어 키 모양과 무작위해 보이는 문자열을 잡아내고, 지운 비밀도 git 기록에 그대로 남는 문제를 확인해요. 환경 변수와 운영체제의 비밀 보관함, 비밀 관리 서비스 중 무엇을 언제 쓰는지, 로그에서 가리는 법, 서비스를 멈추지 않고 키를 바꾸는 두 키 겹치기 방식, 그리고 키가 새었을 때 가장 먼저 할 일까지 다뤄요.

중급강의 3 / 6약 11분

서비스는 혼자 일하지 않아요. 결제 회사, 메일 발송 서비스, 지도, 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
  1. 새 키를 만들고, 받는 쪽이 옛 키와 새 키를 모두 받아들이게 해요.
  2. 보내는 쪽을 새 키로 바꿔요. 이 사이에 도착한 옛 서명도, 새 서명도 모두 통과해요.
  3. 옛 키를 쓰는 곳이 없는 걸 확인한 뒤, 옛 키를 폐기해요.

마지막 줄은 서명이 하는 일이에요. 금액을 39,000원에서 1원으로 바꾸면 서명이 맞지 않아 거절돼요. 결제 알림, 웹훅 같은 요청은 반드시 서명을 확인해야, 누군가 "결제 완료" 알림을 꾸며 보내는 일을 막을 수 있어요.

키가 새었을 때

  1. 바로 폐기하고 새로 발급해요. 기록을 지우는 것보다 먼저예요. 키가 살아 있는 동안 계속 쓰일 수 있어요.
  2. 사용 기록을 확인해요. 언제부터, 어디서, 무엇에 쓰였는지 서비스의 사용 기록과 요금을 봐요.
  3. 피해 범위를 정리해요. 그 키로 볼 수 있던 데이터, 할 수 있던 일을 확인하고, 필요하면 사용자에게 알려요.
  4. 원인을 막아요. 저장소 기록을 정리하고, 비밀 검사기를 커밋 전과 CI에 넣고, 키를 코드 밖으로 옮겨요.

실습

  1. 검사기에 -----BEGIN PRIVATE KEY----- 같은 개인 키 머리글을 찾는 규칙을 더해 보세요.
  2. 검사기가 README.md의 긴 주소나 해시 값을 잘못 잡는 경우를 만들어 보고, 엔트로피 기준을 어떻게 조정하면 좋을지 생각해 보세요. 오탐을 줄이면 무엇을 놓칠 수 있나요?
  3. 내 프로젝트의 .gitignore에 .env가 들어 있는지 확인하고, 이름만 적은 .env.example을 만들어 보세요.
  4. require_env를 바꿔, 시작할 때 필요한 비밀 목록을 한꺼번에 검사하고 빠진 것을 모두 알려 주게 해 보세요.
  5. 서명 예제에 "알림을 보낸 시각"을 더해, 5분보다 오래된 알림은 서명이 맞아도 거절하게 해 보세요. 왜 필요할까요?

자주 하는 실수

  • 코드에 키를 적는다. 언젠가 저장소에 올라가요. 실행할 때 바깥에서 받아요.
  • .env를 .gitignore에 넣지 않는다. 첫 커밋에 실려 올라가요.
  • 지우는 커밋으로 끝냈다고 생각한다. 기록에 남아요. 키를 바꿔요.
  • 모든 곳에 같은 키를 쓴다. 하나가 새면 전부 함께 막아야 해요. 쓰는 곳마다 따로 발급해요.
  • 로그와 오류 화면에 키를 찍는다. 가려서 남겨요.
  • 비밀이 없을 때 기본값으로 돌게 둔다. 설정이 빠진 걸 늦게 알아요. 시작할 때 멈춰요.
  • 키를 바꾸다가 서비스를 멈춘다. 잠시 두 키를 함께 받는 순서로 바꿔요.
  • 웹훅의 서명을 확인하지 않는다. 누구나 "결제 완료"를 꾸며 보낼 수 있어요.

점검 문제

  1. 비밀 정보가 새는 가장 흔한 경로는?
  2. 검사기가 비밀을 찾는 세 가지 방법은?
  3. 비밀을 지우는 커밋을 올려도 안전하지 않은 이유와, 해야 할 일은?
  4. 비밀이 빠졌을 때 기본값으로 돌지 않고 시작할 때 멈추게 하는 이유는?
  5. 블로그 자동화와 공개 웹사이트에 같은 API 키를 쓰면 안 되는 이유는?
  6. 키를 멈추지 않고 바꾸는 세 단계는?
  7. 웹훅에 서명을 확인해야 하는 이유는?
  8. 키가 새었을 때 가장 먼저 할 일은?

정답

  1. 코드나 설정 파일에 적어 둔 키를 저장소에 올리는 실수예요.
  2. 정해진 머리글 같은 키의 모양, PASSWORD = 같은 수상한 이름, 글자가 고르게 섞인 긴 문자열의 높은 엔트로피로 찾아요.
  3. git은 모든 커밋의 내용을 기억해서 이전 커밋에서 비밀을 꺼낼 수 있기 때문이에요. 이미 받아 간 사람이 있을 수 있으니 키를 바꾸고, 기록도 정리해요.
  4. 설정이 빠진 것을 배포 직후 바로 알아채기 위해서예요. 기본값으로 돌면 시험용 키로 조용히 돌다가 중요한 순간에 실패해요.
  5. 한쪽에서 키가 새거나 남용되면 다른 쪽까지 함께 막아야 하고, 사용량도 구별할 수 없기 때문이에요. 쓰는 곳마다 따로 발급하면 새었을 때 그것만 끊으면 돼요.
  6. 받는 쪽이 옛 키와 새 키를 모두 받게 하고, 보내는 쪽을 새 키로 바꾸고, 옛 키를 쓰는 곳이 없는 걸 확인한 뒤 옛 키를 폐기해요.
  7. 서명을 확인하지 않으면 누구나 "결제 완료" 같은 알림을 꾸며 보낼 수 있기 때문이에요. 내용이 바뀌면 서명이 맞지 않아 거절돼요.
  8. 새어 나간 키를 바로 폐기하고 새로 발급하는 거예요. 키가 살아 있는 동안은 계속 쓰일 수 있어요.

다음 강의

비밀을 지켰으니, 이번에는 서비스의 문을 노리는 공격을 막을 차례예요. 다음 강의에서는 지금까지 여러 강의에서 조금씩 본 XSS, SQL 인젝션, 그리고 CSRF를 하나씩 직접 재현하고 막는 법을 정리해요.