Devin.KR

비밀값 관리 - 키가 저장소에 들어가지 않게

개발자KR 조회 4

이 장에서 배우는 것

앞 장에서 게시판은 글을 수정하려는 사람이 글쓴이인지 확인했다. 이번에는 게시판 자체가 다른 서비스에 접속할 때 쓰는 자격 증명을 살펴본다. 게시판에 새 댓글 알림 기능을 붙이면서 발급받은 키가 코드나 로그에 섞이면, 글쓴이를 확인하는 검사로는 그 키를 보호할 수 없다. 키가 프로그램에 들어오는 경로와 프로그램에서 다시 나가는 경로를 모두 살펴야 한다.

  • 실행 환경마다 다른 비밀값을 환경 변수로 받고, 누락 시 값을 노출하지 않고 실행을 중단한다.
  • .gitignore가 적용되는 범위를 설명하고 커밋에 들어갈 내용을 검사한다.
  • 파일 묶음에서 비밀값 모양의 문자열을 찾아 원문을 숨긴 보고서를 출력한다.
  • 로그에서 필요한 필드만 남기고, 노출된 키를 교체하는 순서를 정한다.

문제 상황

게시판 운영자가 새 댓글을 알림 서비스로 보내려고 AI에 설정 코드와 오류 로그를 작성해 달라고 했다. 제안된 코드는 키를 모듈 상수에 넣었고, 알림 설정을 읽는 데 실패하면 설정 사전 전체를 로그에 남겼다. 운영자는 키를 별도 파일로 옮기고 그 파일 이름을 .gitignore에 추가했다. 그러나 첫 커밋에서 이미 설정 파일을 추적하기 시작했고, 오류 로그도 여전히 설정 전체를 달고 나왔다.

이 상황에서는 같은 키가 서로 다른 경로로 복제된다. 설정 파일에는 의도해서 넣었지만 커밋과 로그에는 의도하지 않게 들어갔다. 변경 사항을 검토할 때는 키를 읽는 줄뿐 아니라 값을 기록하는 줄, 그리고 다음 커밋에 실제로 들어가는 파일을 함께 살펴야 한다.

댓글 알림 키를 실행 환경에서 받아라. 키가 없으면 변수 이름만 보여 주고 중단하라. 로그에는 알림 처리 결과와 게시글 번호만 남겨라. 커밋에 들어갈 텍스트를 검사하는 함수와, 검사 결과에 비밀값 원문이 없는지 확인하는 예제도 작성하라.

실행 설정과 저장소의 경계

저장소에는 BOARD_API_KEY처럼 필요한 변수의 이름과 사용 목적을 기록한다. 실제 값은 실행 환경에서 주입하고, Python에서는 os.environ으로 읽는다. 개발 환경과 운영 환경에는 각각 발급한 키를 쓴다. 키가 없거나 공백뿐이면 시작 단계에서 설정 오류를 알린다. 소스에 기본 키를 넣으면 설정이 빠진 환경이 그 기본값으로 계속 동작하므로, 누락을 알아차리기 어렵다.

로컬 설정 파일을 쓰는 팀이라면 실제 값을 보관할 .env는 무시 목록에 넣고, 공유할 .env.example에는 BOARD_API_KEY=처럼 이름과 빈 값만 둔다. Python은 os.environ을 읽을 때 .env를 자동으로 해석하지 않는다. 실행 환경이 값을 주입하는 방식과 로컬 파일을 로드하는 방식 중 팀에서 정한 경로를 문서에 적는다. 완성 코드는 환경 변수 읽기를 흉내 내기 위해 사전을 넘긴다. 독자 컴퓨터의 환경 변수나 실제 키가 없어도 결과가 같다.

저장소는 변수 이름을 보관하고 실행 환경은 실제 키를 프로그램에 전달한다.

저장소 루트의 .gitignore에 /.env, /.env.local을 적으면 루트의 해당 파일이 새로 추적되는 일을 줄일 수 있다. 이미 추적 중인 파일은 무시 규칙을 추가해도 추적 상태가 바뀌지 않는다. 그 파일을 다음 커밋의 추적 대상에서 제거하고 변경 내역에서 삭제로 표시되는지 확인한다. 이전 커밋에 들어간 값은 그 커밋에 남으므로 키 교체를 별도로 진행한다.

커밋 전에 탐지하고 로그를 가리기

커밋 전 검사는 작업 폴더의 현재 파일과 커밋에 담길 내용이 다를 수 있다는 점에서 시작한다. 예를 들어 키가 있는 파일을 커밋 대상으로 올린 뒤 작업 폴더에서 키를 지워도, 수정본을 다시 올리기 전까지 커밋 대상에는 예전 내용이 남는다. 커밋 전 훅(pre-commit hook)에 탐지를 연결할 때는 스테이징 영역에 올라간 추가·수정 파일의 내용을 입력으로 넘긴다. 탐지 결과가 있거나 검사 대상 파일을 읽을 수 없으면 훅에서 커밋을 중단하도록 연결한다.

커밋 직전에는 스테이징된 파일을 읽고 원문을 가린 검사 결과로 커밋 여부를 결정한다.

탐지 규칙은 두 가지 단서를 쓴다. 하나는 이름이다. api_key 같은 설정에 빈 값이나 정해 둔 자리표시자 외의 값이 있으면 검토한다. 다른 하나는 값의 형식이다. 예제 전용 접두사 demo_board_ 뒤에 영문자나 숫자가 여덟 자 이상 붙으면 어떤 이름 아래 있든 검토한다. 이 접두사는 책에서 만든 것으로 알림 서비스가 발급하는 실제 키 형식과 관계없다.

두 탐지 규칙이 검사하는 단서
단서발견하는 경우검토가 필요한 이유
설정 이름BOARD_API_KEY에 값이 들어 있다.키 형식이 달라져도 찾을 수 있다. 테스트용 값도 걸릴 수 있다.
값의 형식메모에 예제 접두사를 가진 문자열이 들어 있다.변수 이름이 달라져도 찾을 수 있다. 규칙에 등록하지 않은 형식은 놓칠 수 있다.

로그는 기록할 필드를 정하는 단계에서 노출을 줄인다. 알림 처리에는 게시글 번호와 처리 결과를 남겨도 장애 위치를 좁힐 수 있다. 키가 들어 있는 설정 객체나 요청 정보 전체를 먼저 문자열로 만들면 여러 출력 경로에서 같은 값을 다시 가려야 한다. 탐지 보고서에는 파일을 구분하는 이름, 줄 번호, 규칙 이름, 고정된 가림 표시만 남긴다. 완성 코드의 비교용 함수는 취약한 로그와 보고서를 메모리에서만 만들고, 출력에는 예제 키가 들어 있었는지를 나타내는 불리언만 쓴다.

노출된 키 교체하기

아직 커밋에 들어가지 않은 값은 파일에서 제거하고 수정본을 다시 스테이징한 뒤 검사한다. 실제 키가 커밋이나 공유 로그에 남았다면 노출된 것으로 보고 키 교체를 시작한다. 저장소에서 해당 줄을 지워도 이미 복제된 키의 사용 권한은 그대로다.

  1. 어떤 키가 어느 환경에서 쓰이는지 식별하고, 발견 위치와 조치 시각을 기록한다. 기록할 때는 키 원문 대신 키 식별자를 사용한다.
  2. 오용이 의심되거나 노출 범위가 크면 기존 키를 즉시 폐기하고 필요한 기능을 복구한다. 운영을 이어 가야 하고 발급 시스템이 두 키의 동시 사용을 허용한다면, 새 키 배포와 확인에 필요한 짧은 시간만 두 키를 유지한다.
  3. 새 키를 발급하고 필요한 권한만 부여한다. 값을 실행 환경에 반영한 뒤 웹 프로세스와 알림 작업 프로세스를 갱신한다. 각 프로세스에서 정해 둔 알림 확인 요청이 성공하는지 살핀다.
  4. 기존 키가 아직 유효하면 폐기한다. 관리 화면이나 관리 기록에서 폐기 상태를 확인하고, 게시판의 새 알림이 정상 처리되는지 다시 확인한다.
  5. 키가 들어간 파일과 로그의 접근 범위를 파악하고 팀의 보존 절차에 따라 정리한다. 공유 저장소의 기록 정리가 필요하면 복제본을 가진 작업자들과 일정을 맞춘다.

완성 코드

main.py

프로그램은 임시 디렉터리에 설정 예시와 알림 메모를 만들고, 두 파일을 검사한 뒤 종료한다. 게시글 번호 17은 앞 장에서 작성자 확인을 마친 글에 댓글이 달렸다고 가정한 입력이다. 알림 전송 없이 키 읽기와 로그 작성만 확인한다. 파일 이름은 프로그램이 정한 고정 이름을 쓰고, 줄 번호는 1부터 센다.

import os
import re
from collections.abc import Mapping
from pathlib import Path
from tempfile import TemporaryDirectory

KEY_NAME = "BOARD_API_KEY"
MASK = "[가림]"
PLACEHOLDERS = {"", "CHANGE_ME"}
ASSIGNMENT = re.compile(
    r"^\s*(?:export\s+)?(?:BOARD_API_KEY|API_KEY|ACCESS_TOKEN)"
    r"\s*[:=]\s*(?P<value>.*)$",
    re.IGNORECASE,
)
TOKEN = re.compile(r"\bdemo_board_[A-Za-z0-9]{8,}\b")


def read_api_key(environ: Mapping[str, str]) -> str:
    value = environ.get(KEY_NAME, "")
    if not value.strip():
        raise ValueError(f"{KEY_NAME} 설정이 필요하다")
    return value


def unsafe_log(post_id: int, key: str) -> str:
    settings = {"post_id": post_id, "api_key": key}
    return f"알림 준비 {settings!r}"


def safe_log(post_id: int) -> str:
    return f"알림 준비 post_id={post_id}"


def find_rule(line: str) -> str | None:
    assignment = ASSIGNMENT.fullmatch(line)
    if assignment:
        value = assignment["value"].strip()
        if len(value) >= 2 and value[0] in "\"'" and value[0] == value[-1]:
            value = value[1:-1].strip()
        if value not in PLACEHOLDERS:
            return "설정 이름"
    if TOKEN.search(line):
        return "키 모양"
    return None


def scan_files(
    directory: Path, names: tuple[str, ...]
) -> list[tuple[str, int, str]]:
    findings = []
    for name in sorted(names):
        content = (directory / name).read_text(encoding="utf-8")
        for line_no, line in enumerate(content.splitlines(), start=1):
            rule = find_rule(line)
            if rule is not None:
                findings.append((name, line_no, rule))
    return findings


def format_report(findings: list[tuple[str, int, str]]) -> str:
    rows = [f"탐지 {len(findings)}줄"]
    for name, line_no, rule in findings:
        rows.append(f"{name}:{line_no} | {rule} | {MASK}")
    return "\n".join(rows)


def checks() -> None:
    cases = (
        ('BOARD_API_KEY=""', None),
        ("export BOARD_API_KEY='CHANGE_ME'", None),
        ("api_key: sample", "설정 이름"),
        ("메모 demo_board_12345678", "키 모양"),
        ("메모 demo_board_short", None),
        ("BOARD_API_KEY=demo_board_12345678", "설정 이름"),
        ("# BOARD_API_KEY=", None),
    )
    for line, expected in cases:
        if find_rule(line) != expected:
            raise AssertionError("탐지 규칙 결과가 예상과 다르다")

    for environ in ({}, {KEY_NAME: "  "}):
        try:
            read_api_key(environ)
        except ValueError as error:
            if str(error) != "BOARD_API_KEY 설정이 필요하다":
                raise AssertionError("설정 오류 메시지가 예상과 다르다")
        else:
            raise AssertionError("빈 키를 허용했다")


def main() -> None:
    checks()
    example_key = "demo_board_A1B2C3D4"
    note_key = "demo_board_E5F6G7H8"

    environ = {KEY_NAME: example_key}
    # 서비스 시작점에서는 read_api_key(os.environ)으로 읽는다.
    key = read_api_key(environ)
    previous_log = unsafe_log(17, key)
    current_log = safe_log(17)

    with TemporaryDirectory() as tmp:
        directory = Path(tmp)
        (directory / "settings.env").write_text(
            f"BOARD_NAME=동네 게시판\n{KEY_NAME}={key}\n",
            encoding="utf-8",
        )
        (directory / "notes.txt").write_text(
            f"댓글 알림 메모\n테스트 문자열 {note_key}\n",
            encoding="utf-8",
        )
        findings = scan_files(directory, ("settings.env", "notes.txt"))

    expected = [
        ("notes.txt", 2, "키 모양"),
        ("settings.env", 2, "설정 이름"),
    ]
    if findings != expected:
        raise AssertionError("파일 탐지 위치가 예상과 다르다")

    # 비교용 문자열은 메모리에서만 만들고 출력은 불리언으로 제한한다.
    previous_report = f"settings.env:2 | {key}"
    report = format_report(findings)
    unsafe_log_contains_key = key in previous_log
    safe_log_contains_key = key in current_log
    unsafe_report_contains_key = key in previous_report
    safe_report_contains_key = any(
        sample in report for sample in (key, note_key)
    )
    if (
        not unsafe_log_contains_key
        or safe_log_contains_key
        or not unsafe_report_contains_key
        or safe_report_contains_key
    ):
        raise AssertionError("비밀값 노출 비교가 예상과 다르다")

    print(f"기존 로그에 키 포함 {unsafe_log_contains_key}")
    print(f"수정 로그에 키 포함 {safe_log_contains_key}")
    print(f"기존 보고서에 키 포함 {unsafe_report_contains_key}")
    print(f"수정 보고서에 키 포함 {safe_report_contains_key}")
    print(report)


if __name__ == "__main__":
    main()

줄별 해설

  1. KEY_NAME과 read_api_key()는 이름과 값의 출처를 분리한다. 서비스에서는 os.environ을, 실행 예제에서는 사전을 넘긴다. 공백인지 확인할 때만 strip()을 쓰고, 설정이 유효하면 발급받은 값을 그대로 돌려준다.
  2. unsafe_log()의 {settings!r}은 설정 사전의 표현을 문자열에 삽입한다. 이 사전에 키가 있으므로 로그에도 키가 들어간다. safe_log()는 함수 인자로 게시글 번호만 받아 정해진 메시지를 만든다. 호출부에서 키를 넘기지 않으므로 메시지를 고치는 사람이 실수로 키까지 포매팅할 가능성을 줄인다.
  3. ASSIGNMENT는 줄 앞쪽에서 설정 이름을 확인하고, 구분자 뒤쪽을 value 그룹에 담는다. TOKEN은 줄 어디에서든 예제 접두사를 가진 문자열을 찾는다. 정규식에 쓴 원시 문자열(raw string)은 \s, \b 같은 표기를 정규식 엔진에 그대로 전달한다.
  4. find_rule()은 값 양끝의 따옴표가 짝을 이루면 벗긴 뒤 빈 값과 CHANGE_ME를 허용한다. 한 줄이 두 규칙에 모두 해당하면 설정 이름 쪽을 먼저 반환한다. 그래서 보고서의 개수는 발견한 키 수가 아니라 탐지한 줄 수다. 이 함수는 줄 중심의 간단한 규칙을 쓰므로 여러 줄에 걸친 값이나 형식이 알려지지 않은 값은 놓칠 수 있다.
  5. scan_files()는 파일 이름을 정렬해서 읽고, 탐지 위치를 (파일 이름, 줄 번호, 규칙 이름)으로 보관한다. format_report()가 받는 레코드에는 줄 원문과 일치한 값이 들어갈 자리가 없다. 예제는 이름을 직접 지정한 UTF-8 텍스트만 읽는다. 팀 훅으로 연결할 때는 스테이징된 내용과 파일 경로를 가져오는 부분이 추가로 필요하며, 외부에서 받은 파일 이름을 보고서에 넣을 때는 제어 문자나 비밀값이 섞일 가능성도 고려한다.
  6. checks()는 빈 값, 자리표시자, 다른 이름 없이 등장하는 키 모양, 길이가 짧은 문자열을 확인한다. main()은 실제 파일 쓰기와 읽기를 거쳐 결과의 순서와 줄 번호를 확인한다. 마지막 비교는 두 예제 키 가운데 어느 하나라도 수정 보고서에 나타나면 실패한다. 실패 메시지에도 검사 입력은 넣지 않는다.

실행 결과

main.py가 있는 디렉터리에서 다음 명령을 실행한다. 첫 줄은 컴파일 경고를 오류로 처리해 문법을 확인하고, 둘째 줄은 파일 검사와 노출 여부 비교를 실행한다. 컴파일이 성공하면 첫 명령은 화면에 아무것도 출력하지 않는다.

python3 -W error -m py_compile main.py
python3 main.py
기존 로그에 키 포함 True
수정 로그에 키 포함 False
기존 보고서에 키 포함 True
수정 보고서에 키 포함 False
탐지 2줄
notes.txt:2 | 키 모양 | [가림]
settings.env:2 | 설정 이름 | [가림]

AI가 이 코드를 수정했다면 같은 명령을 다시 실행하고 변경 내역(diff)을 검토한다. 특히 print()에 새로 전달되는 값과 scan_files()의 반환 형식을 본다. 두 줄을 잘 탐지해도 보고서에 원문을 추가하면 그 보고서가 또 하나의 비밀값 복제본이 된다.

실무에서 자주 틀리는 것

환경 변수에 키 기본값을 붙인다

다음 코드는 환경 변수가 빠진 경우에도 소스에 적힌 값으로 프로그램을 시작한다. 예제 문자열은 가짜 키다.

import os

key = os.environ.get("BOARD_API_KEY", "demo_board_A1B2C3D4")

다음 코드는 필수 설정의 누락을 시작 단계에서 드러낸다. 오류 메시지에는 설정 이름만 들어간다.

import os

key = os.environ.get("BOARD_API_KEY", "")
if not key.strip():
    raise SystemExit("BOARD_API_KEY 설정이 필요하다")

로그에 설정 전체를 넘긴다

다음 코드는 설정 사전이 커질 때마다 출력되는 정보가 함께 늘어난다.

def write_notice_log(settings):
    print(f"알림 준비 {settings!r}")

함수의 인자를 게시글 번호로 좁히면 호출부에서도 로그에 필요한 데이터가 드러난다.

def write_notice_log(post_id: int) -> None:
    print(f"알림 준비 post_id={post_id}")

탐지한 줄을 통째로 보고서에 붙인다

다음 함수는 검토 위치와 함께 키가 있는 줄을 다시 출력한다.

def report_line(name, line_no, line):
    return f"{name}:{line_no} | {line}"

수정한 함수는 탐지 규칙을 보고한다. 호출부는 탐지에 사용한 줄을 이 함수에 넘기지 않는다.

def report_line(name, line_no, rule):
    return f"{name}:{line_no} | {rule} | [가림]"

한눈에 보기

비밀값이 지나가는 위치마다 확인할 것
위치확인할 것확인 방법
실행 환경환경별 키와 필수 설정 검사변수를 비웠을 때 이름만 표시하고 중단하는지 본다.
저장소로컬 설정 파일의 무시 규칙과 추적 상태실제 설정 파일이 커밋에 들어갈 목록에 있는지 살핀다.
커밋 전 검사스테이징된 내용과 탐지 결과예제 키가 든 입력에서 파일과 줄 번호를 확인한다.
로그와 보고서출력에 허용한 필드예제 키 원문이 출력 문자열에 없는지 검사한다.
키 교체새 키 적용과 기존 키 폐기새 키로 알림이 처리되는지, 기존 키가 폐기됐는지 각각 확인한다.

연습 문제

  1. api_key=''와 export ACCESS_TOKEN=CHANGE_ME를 checks()에 추가한다. 각각 어떤 결과가 나와야 하는지 정하고 실행한다.
  2. 알림 메모에 예제 키 두 개를 같은 줄에 적는다. 보고서의 탐지 줄 수가 어떻게 되는지 실행 전에 예상하고 확인한다.
  3. 설정 파일에 키가 있는 버전을 스테이징한 뒤 작업 폴더의 파일에서 그 줄만 제거했다. 커밋 전 훅이 어느 내용을 검사해야 하는지 설명한다.
  4. 운영 키가 공유 로그에서 발견됐다. 알림을 이어 가야 하고 발급 시스템은 두 키의 동시 사용을 허용한다. 오용 징후가 없을 때 교체 순서를 적고, 오용이 의심되면 첫 조치를 어떻게 바꿀지 설명한다.

정답과 해설

  1. 두 입력의 기대값은 모두 None이다. 첫 줄에서 따옴표를 벗기면 빈 값이 남는다. 둘째 줄의 값은 허용한 자리표시자다. 입력을 추가한 뒤 기존 파일 검사도 그대로 통과하는지 본다.
  2. 기존 notes.txt의 둘째 줄에 두 키를 넣었다면 전체 탐지는 여전히 2줄이다. 새 줄에 두 키를 넣었다면 예상 결과 목록에 ("notes.txt", 3, "키 모양")을 추가해야 하며, 전체는 3줄이다. 새 테스트 값이 원문 그대로 보고서에 나타나지 않는지도 확인한다.
  3. 커밋 전 훅은 키가 들어 있는 스테이징 버전을 검사해야 한다. 작업 폴더에서 수정한 버전을 다시 스테이징한 뒤 재검사하면 커밋 대상으로 올라간 변경을 확인할 수 있다.
  4. 동시 사용이 가능한 동안 새 키를 발급하고 실행 환경과 프로세스를 갱신한다. 알림이 처리되는지 확인한 뒤 이전 키를 폐기하고 폐기 상태를 확인한다. 오용이 의심되면 알림 복구보다 기존 키 폐기를 앞에 둔다. 공유 로그의 접근 범위와 남은 복제본도 조사한다.

현업에서 이렇게 본다

키를 어디에 저장하는지 물으면 팀원들은 대개 한곳을 가리킨다. 키가 어디에 복사되는지 물으면 답이 달라진다. 리뷰에서 알림 설정을 볼 때 나는 키를 읽는 함수부터 오류가 출력되는 지점까지 따라간다. 장애 때 필요한 정보는 게시글 번호와 처리 결과인 경우가 많다. 그 두 값만 받는 로그 함수는 검토하기 쉽고 다음 사람이 기능을 고칠 때도 의도가 드러난다. 다음 장에서는 이 코드가 가져다 쓰는 외부 패키지가 어떤 경로로 프로젝트에 들어오는지 살펴본다.

댓글 0

아직 댓글이 없습니다. 첫 댓글을 남겨 보세요.

댓글을 남기려면 로그인이 필요합니다.