Django 프로젝트 설정 값에 환경변수를 사용하여 보안 강화

.github/workflows/django.yml

@@ -26,6 +26,9 @@ jobs:
         python -m pip install --upgrade pip
         pip install -r requirements.txt
     - name: Run Tests
+      env:
+        SECRET_KEY: "django-insecure-0000-temporal-secret-key-for-testing-0000"
+        ALLOWED_HOSTS: "[\"localhost\", \"127.0.0.1\", \"[::1]\"]"
       run: |
         cd app
         python manage.py test

README.md

@@ -11,3 +11,16 @@ TLE(Time Limit Exceeded)의 마이크로서비스 아키텍처를 위한 인증
 -   **회원가입/로그인**: 사용자 계정 관리
 -   **API 문서화**: Swagger UI 제공
 -   **마이크로서비스**: 다른 서비스와의 JWT 토큰 공유
+
+## 개발 가이드
+
+### 환경 변수
+
+Docker compose를 사용하지 않고 직접 컨테이너를 실행할 경우 필요한 환경 변수입니다.
+
+| 변수명            | 설명                                               | 기본값  | 필수                             |
+| ----------------- | -------------------------------------------------- | ------- | -------------------------------- |
+| `SECRET_KEY`      | Django 암호화 키                                   |         | `SECRET_KEY_FILE` 미설정 시 필수 |
+| `SECRET_KEY_FILE` | Django 암호화 키가 저장된 파일                     |         | `SECRET_KEY` 미설정 시 필수      |
+| `DEBUG`           | 디버그 모드 활성 여부                              | `False` | 선택 사항                        |
+| `ALLOWED_HOSTS`   | 허용된 호스트명 (JSON 배열, 예: `["example.com"]`) |         | 디버그 모드가 아니면 필수        |

app/.env.sample

@@ -0,0 +1,12 @@
+# Sample .env file for development and testing purposes
+
+# Set DEBUG to true for development, false for production
+DEBUG=false
+
+# Django secret key for cryptographic signing
+# NOTE: Python handles forward slashes correctly on all platforms, including Windows.
+SECRET_KEY_FILE=../.secrets/secret_key.txt
+# SECRET_KEY='<YOUR_SECRET_KEY>'
+
+# Allowed hosts for the Django application
+# ALLOWED_HOSTS=["example.com", "www.example.com"]

app/app/env.py

@@ -0,0 +1,223 @@
+"""
+환경 변수와 관련된 기능 혹은 유틸리티 모음.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Optional, Union
+
+import dotenv
+
+# Define truthy and falsy values
+_TRUTHY_VALUES = ('true', '1', 't', 'y', 'yes', 'on')
+_FALSY_VALUES = ('false', '0', 'f', 'n', 'no', 'off')
+
+
+def load(dotenv_path: Optional[Path] = None):
+    """.env 파일이 있다면 .env 파일에서 환경 변수를 로드합니다.
+
+    Args:
+        dotenv_path: .env 파일 경로 (기본값: None)
+    """
+    # Load .env file if it exists
+    if (dotenv_path is not None) and dotenv_path.exists():
+        dotenv.load_dotenv(dotenv_path=dotenv_path, override=True)
+
+
+def get(key: str, default: Optional[str] = None, required: bool = False, strip: bool = True, blank: bool = False) -> Optional[str]:
+    """환경 변수 값을 가져옵니다.
+
+    Args:
+        key: 환경 변수 이름
+        default: 기본값 (환경 변수가 없을 때 반환)
+        required: 필수 여부 (True일 때 환경 변수가 없으면 예외 발생)
+        strip: 값의 앞뒤 공백 제거 여부 (기본값: True)
+        blank: 빈 문자열 허용 여부 (False일 때 빈 문자열은 None으로 간주)
+
+    Returns:
+        환경 변수 값 또는 기본값
+
+    Raises:
+        ValueError: required=True이고 환경 변수가 설정되지 않은 경우
+    """
+    string_value = os.getenv(key, default)
+
+    if strip and (string_value is not None):
+        string_value = string_value.strip()
+
+    if not blank and (string_value == ''):
+        string_value = None
+
+    if required and (string_value is None):
+        raise ValueError(
+            f'Environment variable "{key}" is required but not set.'
+        )
+
+    return string_value
+
+
+def get_bool(key: str, default: Optional[bool] = None, strip: bool = True, required: bool = False) -> Optional[bool]:
+    """환경 변수를 불린 값으로 파싱합니다.
+
+    Args:
+        key: 환경 변수 이름
+        default: 기본값 (환경 변수가 없을 때 반환)
+        strip: 앞뒤 공백 제거 여부 (기본값: True)
+        required: 필수 여부 (True일 때 환경 변수가 없으면 예외 발생)
+
+    Returns:
+        불린 값 또는 기본값
+
+    Raises:
+        ValueError: 잘못된 불린 값이거나 required=True이고 환경 변수가 설정되지 않은 경우
+    """
+    raw_value = os.getenv(key)
+    boolean_value = default
+
+    if raw_value is not None:
+        if _is_truthy(raw_value, strip=strip):
+            boolean_value = True
+        elif _is_falsy(raw_value, strip=strip):
+            boolean_value = False
+        else:
+            raise ValueError(
+                f'Environment variable "{key}" has invalid boolean value.'
+            )
+
+    if required and (boolean_value is None):
+        raise ValueError(
+            f'Environment variable "{key}" is required but not set.'
+        )
+
+    return boolean_value
+
+
+def get_json(key: str, default: Optional[Any] = None, required: bool = False) -> Optional[Any]:
+    """환경 변수 값을 JSON으로 파싱하여 반환하거나 기본값을 반환합니다.
+
+    Args:
+        key: 환경 변수 이름
+        default: 기본값 (환경 변수가 없을 때 반환)
+        required: 필수 여부 (True일 때 환경 변수가 없으면 예외 발생)
+
+    Returns:
+        JSON으로 파싱된 값 또는 기본값
+
+    Raises:
+        ValueError: 환경 변수 값이 올바른 JSON이 아니거나 required=True이고 환경 변수가 설정되지 않은 경우
+    """
+    raw_value = os.getenv(key)
+    json_value = default
+
+    if raw_value is not None:
+        try:
+            json_value = json.loads(raw_value)
+        except ValueError as e:
+            raise ValueError(
+                f'Environment variable "{key}" has invalid JSON value.'
+            ) from e
+
+    if required and (json_value is None):
+        raise ValueError(
+            f'Environment variable "{key}" is required but not set.'
+        )
+
+    return json_value
+
+
+def get_path(key: str, default: Optional[Path] = None, required: bool = False, relative_to: Optional[Union[Path, str]] = None) -> Optional[Path]:
+    """환경 변수에 지정된 파일 경로를 Path 객체로 반환합니다.
+
+    Args:
+        key: 파일 경로가 저장된 환경 변수 이름
+        default: 기본값 (환경 변수가 없을 때 반환)
+        required: 필수 여부 (True일 때 환경 변수가 없으면 예외 발생)
+        relative_to: 파일 탐색을 허용할 최상위 경로.
+            이 값이 None이면 모든 경로가 허용됩니다.
+            (기본값: None)
+
+    Returns:
+        파일 경로 또는 기본값
+
+    Raises:
+        ValueError: 환경 변수 값이 유효하지 않거나 required=True이고 환경 변수가 설정되지 않은 경우
+    """
+    raw_path = os.getenv(key)
+    path = default
+
+    if raw_path is not None:
+        try:
+            path = Path(raw_path).resolve()
+        except OSError as e:
+            raise ValueError(
+                f'Environment variable "{key}" has invalid file path.'
+            ) from e
+
+    # 파일 경로가 허용 탐색 범위 이내인지 검사
+    if relative_to and (path is not None):
+        try:
+            relative_to_path = Path(relative_to).resolve()
+        except OSError as e:
+            raise ValueError(
+                f'Invalid "relative_to" parameter value.'
+            ) from e
+
+        # 디렉토리인지 검증
+        if not relative_to_path.is_dir():
+            raise ValueError(
+                f'The "relative_to" parameter must be a directory, got: {relative_to_path}'
+            )
+
+        try:
+            path.relative_to(relative_to_path)
+        except ValueError:
+            raise ValueError(
+                f'Path specified in environment variable "{key}" is outside '
+                f'the allowed directory "{relative_to_path}".'
+            )
+
+    if required and (path is None):
+        raise ValueError(
+            f'Environment variable "{key}" is required but not set.'
+        )
+
+    return path
+
+
+def _is_truthy(value: Optional[str], strip: bool = True) -> bool:
+    """문자열이 참 값인지 확인합니다.
+
+    Args:
+        value: 확인할 문자열
+        strip: 앞뒤 공백 제거 여부 (기본값: True)
+
+    Returns:
+        참 값 여부 (true, 1, t, y, yes, on 중 하나인 경우 True)
+    """
+    if strip and (value is not None):
+        value = value.strip()
+
+    if value is None:
+        return False
+
+    return value.lower() in _TRUTHY_VALUES
+
+
+def _is_falsy(value: Optional[str], strip: bool = True) -> bool:
+    """문자열이 거짓 값인지 확인합니다.
+
+    Args:
+        value: 확인할 문자열
+        strip: 앞뒤 공백 제거 여부 (기본값: True)
+
+    Returns:
+        거짓 값 여부 (false, 0, f, n, no, off 중 하나인 경우 True)
+    """
+    if strip and (value is not None):
+        value = value.strip()
+
+    if value is None:
+        return False
+
+    return value.lower() in _FALSY_VALUES

app/app/settings.py

@@ -12,20 +12,59 @@
 
 from pathlib import Path
 
+from app import env
+
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = Path(__file__).resolve().parent.parent
 
 
+env.load(dotenv_path=BASE_DIR / '.env')
+
+
 # Quick-start development settings - unsuitable for production
 # See https://docs.djangoproject.com/en/5.2/howto/deployment/checklist/
 
 # SECURITY WARNING: keep the secret key used in production secret!
-SECRET_KEY = 'django-insecure-^&757(fcj_5idk9lfj5%mc#5ozvfoigka&#z73lxc_(!4j_e$o'
+secret_key = env.get("SECRET_KEY")
+secret_key_file = env.get_path("SECRET_KEY_FILE")
+# NOTE: path traversal attack에 대하여,
+# Docker Compose를 구성할 경우, secret이 담긴 파일이 프로젝트 디렉터리 외부에 있는 경우도 있다.
+# 따라서 relative_to 를 설정할 경우, "/run/secrets/*" 와 같은 경로에 접근을 못하게 될 가능성이 높다.
+# 더군다나 위 코드는 최초 설정시에만 실행되기에 약점의 크기가 상당히 작다고 판단하여
+# path traversal attack을 허용할 여지가 있더라도, 더 좋은 방법을 찾기 전까지는 relative_to를 설정하지 않는다.
+
+if secret_key and secret_key_file:
+    raise ValueError("Cannot set both SECRET_KEY and SECRET_KEY_FILE")
+elif secret_key:
+    SECRET_KEY = secret_key
+elif secret_key_file:
+    # NOTE: 명확한 에러 추적을 위해 파일 경로는 오류 메시지로 노출.
+    # 오류가 발생하면 애플리케이션 구동이 안되기에, 보안을 위해 키 값도 아닌,
+    # 경로 자체를 숨기는 것은 과하다고 판단함.
+    if not secret_key_file.exists():
+        raise ValueError(f"SECRET_KEY_FILE does not exist: {secret_key_file}")
+    if not secret_key_file.is_file():
+        raise ValueError(f"SECRET_KEY_FILE is not a file: {secret_key_file}")
+
+    # Fail-fast, 명확한 에러 추적을 위해 파일 읽기 중 오류는 예외 처리를 하지 않음.
+    SECRET_KEY = secret_key_file.read_text(encoding='utf-8').strip()
+
+    if not SECRET_KEY:
+        raise ValueError(f"SECRET_KEY_FILE is empty: {secret_key_file}")
+else:
+    raise ValueError("Either SECRET_KEY or SECRET_KEY_FILE must be set")
+
 
 # SECURITY WARNING: don't run with debug turned on in production!
-DEBUG = True
+DEBUG = env.get_bool('DEBUG', default=False)
+
 
-ALLOWED_HOSTS = []
+# Allow all hosts during development, require explicit hosts in production.
+if DEBUG:
+    ALLOWED_HOSTS = env.get_json('ALLOWED_HOSTS',
+                                 default=['localhost', '127.0.0.1', '[::1]'])
+else:
+    ALLOWED_HOSTS = env.get_json('ALLOWED_HOSTS', required=True)
 
 
 # Application definition
@@ -74,6 +113,7 @@
 # Database
 # https://docs.djangoproject.com/en/5.2/ref/settings/#databases
 
+# TODO: Use PostgreSQL for production.
 DATABASES = {
     'default': {
         'ENGINE': 'django.db.backends.sqlite3',