Copy & Run

API 대량 할당 막기: FastAPI Pydantic extra=forbid

요청 JSON을 그대로 사용자 기록에 합치는 연습용 FastAPI 앱에서 일반 사용자가 role을 admin으로 올리는 과정을 curl로 확인합니다. 같은 API를 Pydantic 허용 필드 모델로 고치면 422로 거절되는 것을 비교하고, 회귀를 막는 pytest 게이트를 붙입니다.

대량 할당(mass assignment)은 클라이언트가 보낸 JSON의 키를 걸러 내지 않고 서버의 데이터 객체에 그대로 합칠 때 생깁니다. 프로필 수정 요청에 role 같은 키를 슬쩍 넣으면 일반 사용자가 관리자 권한을 얻을 수 있습니다. 이 글에서는 취약한 API와 고친 API를 나란히 띄우고, 같은 요청이 각각 어떻게 처리되는지 확인합니다.

앱은 이 글을 위해 직접 만든 연습용입니다. 인증은 X-User 헤더로 대신했고 데이터는 메모리에만 두므로 실제 서비스에 쓰지 마십시오. Windows Git Bash에서 Docker Desktop으로 실행했고, 컨테이너 포트는 호스트 127.0.0.1에만 열었습니다.

준비물

항목 확인한 값
실행 환경 Docker 컨테이너(python:3.12-slim, Python 3.12.16)
FastAPI 0.162.0
Pydantic 2.14.2
uvicorn 0.54.0
httpx 0.28.1 (TestClient용)
pytest 9.2.0
호출 도구 curl (Git Bash)

작업 폴더는 아래 다섯 파일입니다. 전체 내용은 글 끝의 ## 전체 코드에 있습니다.

Dockerfile
requirements.txt
vulnerable_app.py
fixed_app.py
test_gate.py

1. 두 앱을 컨테이너로 띄우기

이미지 하나에 취약판 vulnerable_app.py와 수정판 fixed_app.py가 모두 들어 있고, 컨테이너를 만들 때 실행할 모듈만 다르게 지정합니다. 취약판은 18260, 수정판은 18261 포트입니다.

docker build -q -t cr-fx-lab:latest . && echo built
docker network create cr-fx-net
docker run -d --name cr-fx-vuln --network cr-fx-net -p 127.0.0.1:18260:8000 cr-fx-lab:latest uvicorn vulnerable_app:app --host 0.0.0.0 --port 8000
docker run -d --name cr-fx-fixed --network cr-fx-net -p 127.0.0.1:18261:8000 cr-fx-lab:latest
docker ps --filter name=cr-fx --format 'table {{.Names}}	{{.Ports}}'

두 컨테이너가 127.0.0.1의 18260과 18261 포트에만 연결되어 올라온 것을 확인합니다.
두 컨테이너가 127.0.0.1의 18260과 18261 포트에만 연결되어 올라온 것을 확인합니다.

사용자는 alice(role이 user)와 root(role이 admin) 두 명입니다. 세 엔드포인트가 있습니다. GET /users/me는 내 정보, PATCH /users/me는 프로필 수정, GET /admin/report는 admin만 볼 수 있는 목록입니다.

2. 취약판에서 role 올리기

취약한 부분은 update_me 한 줄입니다. 본문을 dict로 받아 user.update(body)로 기록에 합치므로 클라이언트가 보낸 모든 키가 반영됩니다. 화면에 보이는 필드(display_name)만 바꾸려는 요청이어도 서버는 다른 키를 구분하지 않습니다.

먼저 alice가 관리자 목록을 열어 보면 403이 나옵니다. 그다음 프로필 수정 요청에 role을 함께 보내고 다시 목록을 엽니다.

curl -s -w ' HTTP %{http_code}\n' -H 'X-User: alice' http://127.0.0.1:18260/admin/report
curl -s -w ' HTTP %{http_code}\n' -X PATCH -H 'X-User: alice' -H 'Content-Type: application/json' -d '{"display_name":"Alice","role":"admin"}' http://127.0.0.1:18260/users/me
curl -s -w ' HTTP %{http_code}\n' -H 'X-User: alice' http://127.0.0.1:18260/admin/report

alice의 관리자 목록 요청이 403이었다가 role 포함 PATCH 뒤에는 200으로 바뀌고 응답에 api_key까지 보이는 것을 확인합니다.
alice의 관리자 목록 요청이 403이었다가 role 포함 PATCH 뒤에는 200으로 바뀌고 응답에 api_key까지 보이는 것을 확인합니다.

응답에서 두 가지를 볼 수 있습니다. role이 admin으로 바뀌었고, 응답에 api_key까지 그대로 나옵니다. 사용자 기록 전체를 돌려주는 것도 같은 뿌리의 문제입니다. 입력에도 출력에도 "필요한 필드만" 남기는 목록이 없습니다.

이 단계의 파일 내려받기:vulnerable_app.py

3. 수정판: 허용 필드만 받고 응답도 걸러 내기

수정한 부분은 모델 두 개입니다. 입력용 ProfileUpdate는 바꿀 수 있는 필드(display_name, team)만 선언하고 extra="forbid"를 줍니다. Pydantic 공식 문서에 따르면 extra의 기본값은 'ignore'이고, 'forbid'는 선언하지 않은 데이터가 들어오면 ValidationError를 일으킵니다. 오류 유형은 extra_forbidden입니다. FastAPI는 요청 본문 검증 실패를 422로 응답하며, 아래에서 직접 확인합니다.

출력용 UserOut은 응답에 담을 필드만 선언하고, 엔드포인트에 response_model=UserOut을 지정합니다. FastAPI 공식 문서가 설명하듯 응답 모델에 없는 데이터는 걸러집니다. 그래서 내부 기록에 api_key가 있어도 응답에는 나가지 않습니다.

같은 요청을 수정판(18261)에 보냅니다.

curl -s -w ' HTTP %{http_code}\n' -H 'X-User: alice' http://127.0.0.1:18261/users/me
curl -s -w ' HTTP %{http_code}\n' -X PATCH -H 'X-User: alice' -H 'Content-Type: application/json' -d '{"display_name":"Alice","role":"admin"}' http://127.0.0.1:18261/users/me
curl -s -w ' HTTP %{http_code}\n' -X PATCH -H 'X-User: alice' -H 'Content-Type: application/json' -d '{"display_name":null}' http://127.0.0.1:18261/users/me
curl -s -w ' HTTP %{http_code}\n' -H 'X-User: alice' http://127.0.0.1:18261/admin/report

수정판은 내 정보에 api_key가 없고, role 포함 PATCH는 extra_forbidden, null 값 PATCH는 string_type 오류의 422로 거절되며 관리자 목록은 계속 403인 것을 확인합니다.
수정판은 내 정보에 api_key가 없고, role 포함 PATCH는 extra_forbidden, null 값 PATCH는 string_type 오류의 422로 거절되며 관리자 목록은 계속 403인 것을 확인합니다.

display_name에 null을 보내는 요청도 422입니다. 필드를 str | None으로 선언하고 model_dump(exclude_unset=True)로 합치면 null이 "값이 설정됨"으로 취급되어 기록이 None이 되고, 응답 모델 검증이 실패해 /users/me가 500을 돌려줍니다. 직접 확인했고 이후 요청도 계속 500이었습니다. 그래서 str로 선언하고 min_length, max_length를 걸어 null과 빈 문자열을 입력 단계에서 거절합니다. 기본값 ""는 exclude_unset 때문에 기록에 쓰이지 않습니다.

display_name은 정상 필드인데도 role이 섞이면 요청 전체가 거절됩니다. 일부만 반영하지 않으므로 어느 필드가 실제로 바뀌었는지 따져 볼 필요가 없습니다. 기본값인 extra="ignore"였다면 role은 조용히 버려지고 200이 나갑니다. 공격은 막히지만 클라이언트가 잘못된 키를 보내고 있다는 사실이 드러나지 않습니다.

이 단계의 파일 내려받기:fixed_app.py

4. 회귀 방지 게이트

나중에 누군가 편의상 extra를 풀거나 입력 모델에 role을 추가하면 같은 문제가 되살아납니다. test_gate.py는 허용 필드 수정이 되는지, role, is_admin, api_key, username이 422로 거절되는지, 섞인 요청이 아무것도 바꾸지 않는지, 관리자 목록이 닫혀 있는지, 응답에 api_key가 없는지, null 값이 거절되는지를 합쳐 모두 10건을 검사합니다. 환경 변수 APP_MODULE로 검사할 모듈을 고릅니다.

docker exec cr-fx-fixed python -m pytest -q -p no:warnings test_gate.py

수정판에서 10건이 모두 통과하는 것을 확인합니다.
수정판에서 10건이 모두 통과하는 것을 확인합니다.

게이트가 실제로 취약점을 잡는지도 확인합니다. 취약판 모듈을 지정해 같은 테스트를 돌립니다.

docker exec -e APP_MODULE=vulnerable_app cr-fx-vuln python -m pytest -q --tb=no -p no:warnings test_gate.py

취약판에서는 10건 중 9건이 실패하고 허용 필드 수정 1건만 통과하는 것을 확인합니다.
취약판에서는 10건 중 9건이 실패하고 허용 필드 수정 1건만 통과하는 것을 확인합니다.

CI에서는 실제 서비스 코드를 가리키도록 APP_MODULE을 지정해 이 테스트를 돌리고, 실패하면 병합을 막는 단계로 둡니다.

이 단계의 파일 내려받기:test_gate.py

결과 정리

  • 요청 본문을 dict로 받아 기록에 합치면 role 같은 키가 그대로 반영됩니다.
  • 입력은 허용 필드만 선언한 Pydantic 모델과 extra="forbid"로 받고, 모르는 키는 422로 거절합니다.
  • 응답은 response_model로 별도 출력 모델을 지정해 api_key 같은 내부 값을 걸러 냅니다.
  • 권한을 정하는 값은 서버에서만 바꾸고, 위 테스트로 회귀를 막습니다.

전체 코드

작업 폴더 구조는 아래와 같습니다.

Dockerfile
requirements.txt
vulnerable_app.py
fixed_app.py
test_gate.py

Dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY vulnerable_app.py fixed_app.py test_gate.py ./
EXPOSE 8000
CMD ["uvicorn", "fixed_app:app", "--host", "0.0.0.0", "--port", "8000"]

requirements.txt

fastapi==0.162.0
uvicorn==0.54.0
pydantic==2.14.2
httpx==0.28.1
pytest==9.2.0

vulnerable_app.py

"""연습용 취약 API입니다. 실제 서비스에 쓰지 마십시오.

요청 본문(JSON)을 검사 없이 사용자 기록에 합치는 구조를 일부러 만들었습니다.
인증은 X-User 헤더로 대신하는 연습용 방식입니다.
"""
from fastapi import Body, Depends, FastAPI, Header, HTTPException

app = FastAPI(title="mass-assignment vulnerable (practice only)")
USERS = {}


def seed():
    USERS.clear()
    USERS["alice"] = {"username": "alice", "display_name": "Alice", "team": "sales",
                      "role": "user", "api_key": "key-alice-111"}
    USERS["root"] = {"username": "root", "display_name": "Root", "team": "ops",
                     "role": "admin", "api_key": "key-root-999"}


seed()


def current_user(x_user: str | None = Header(default=None)):
    if x_user not in USERS:
        raise HTTPException(status_code=401, detail="X-User 헤더가 필요합니다")
    return USERS[x_user]


@app.get("/users/me")
def read_me(user: dict = Depends(current_user)):
    return user


@app.patch("/users/me")
def update_me(body: dict = Body(...), user: dict = Depends(current_user)):
    user.update(body)  # 취약: 클라이언트가 보낸 키가 그대로 기록에 들어갑니다
    return user


@app.get("/admin/report")
def admin_report(user: dict = Depends(current_user)):
    if user["role"] != "admin":
        raise HTTPException(status_code=403, detail="관리자만 볼 수 있습니다")
    return {"users": len(USERS), "teams": [u["team"] for u in USERS.values()]}

fixed_app.py

"""vulnerable_app.py의 수정판입니다. 연습용이며 실제 서비스에 쓰지 마십시오.

입력 모델은 허용 필드만 받고(extra="forbid"), 응답은 별도 출력 모델로 걸러 냅니다.
"""
from fastapi import Depends, FastAPI, Header, HTTPException
from pydantic import BaseModel, ConfigDict, Field

app = FastAPI(title="mass-assignment fixed (practice only)")
USERS = {}


def seed():
    USERS.clear()
    USERS["alice"] = {"username": "alice", "display_name": "Alice", "team": "sales",
                      "role": "user", "api_key": "key-alice-111"}
    USERS["root"] = {"username": "root", "display_name": "Root", "team": "ops",
                     "role": "admin", "api_key": "key-root-999"}


seed()


class ProfileUpdate(BaseModel):
    """클라이언트가 바꿀 수 있는 필드만 선언합니다."""
    model_config = ConfigDict(extra="forbid")
    # str 로 선언해 null 을 거절합니다. 기본값은 exclude_unset 때문에 쓰이지 않습니다
    display_name: str = Field(default="", min_length=1, max_length=40)
    team: str = Field(default="", min_length=1, max_length=40)


class UserOut(BaseModel):
    """응답에 담을 필드만 선언합니다. api_key는 넣지 않습니다."""
    username: str
    display_name: str
    team: str
    role: str


def current_user(x_user: str | None = Header(default=None)):
    if x_user not in USERS:
        raise HTTPException(status_code=401, detail="X-User 헤더가 필요합니다")
    return USERS[x_user]


@app.get("/users/me", response_model=UserOut)
def read_me(user: dict = Depends(current_user)):
    return user


@app.patch("/users/me", response_model=UserOut)
def update_me(body: ProfileUpdate, user: dict = Depends(current_user)):
    user.update(body.model_dump(exclude_unset=True))
    return user


@app.get("/admin/report")
def admin_report(user: dict = Depends(current_user)):
    if user["role"] != "admin":
        raise HTTPException(status_code=403, detail="관리자만 볼 수 있습니다")
    return {"users": len(USERS), "teams": [u["team"] for u in USERS.values()]}

test_gate.py

"""대량 할당 회귀 방지 게이트입니다.

사용: pytest -q test_gate.py             (수정판 fixed_app 검사)
      APP_MODULE=vulnerable_app pytest -q test_gate.py   (취약판이 걸리는지 확인)
"""
import importlib
import os

import pytest
from fastapi.testclient import TestClient

mod = importlib.import_module(os.environ.get("APP_MODULE", "fixed_app"))
client = TestClient(mod.app)
ALICE = {"X-User": "alice"}


@pytest.fixture(autouse=True)
def fresh_data():
    mod.seed()


def test_allowed_fields_still_work():
    r = client.patch("/users/me", json={"display_name": "Alice K"}, headers=ALICE)
    assert r.status_code == 200
    assert r.json()["display_name"] == "Alice K"


@pytest.mark.parametrize("field,value", [("role", "admin"), ("is_admin", True),
                                         ("api_key", "stolen"), ("username", "root")])
def test_forbidden_fields_are_rejected(field, value):
    r = client.patch("/users/me", json={field: value}, headers=ALICE)
    assert r.status_code == 422
    assert r.json()["detail"][0]["type"] == "extra_forbidden"


@pytest.mark.parametrize("field", ["display_name", "team"])
def test_null_value_is_rejected(field):
    r = client.patch("/users/me", json={field: None}, headers=ALICE)
    assert r.status_code == 422
    assert client.get("/users/me", headers=ALICE).status_code == 200


def test_mixed_body_changes_nothing():
    r = client.patch("/users/me", json={"display_name": "Mallory", "role": "admin"}, headers=ALICE)
    assert r.status_code == 422
    assert mod.USERS["alice"]["display_name"] == "Alice"


def test_role_stays_user_and_admin_report_is_closed():
    client.patch("/users/me", json={"role": "admin"}, headers=ALICE)
    assert mod.USERS["alice"]["role"] == "user"
    assert client.get("/admin/report", headers=ALICE).status_code == 403


def test_response_does_not_leak_api_key():
    assert "api_key" not in client.get("/users/me", headers=ALICE).json()

자주 막히는 곳

  • PATCH를 한 번 보낸 뒤 처음 상태로 돌아가지 않습니다. 데이터가 메모리에만 있어서 취약판에서 alice가 admin이 된 상태가 컨테이너를 다시 시작할 때까지 남습니다. 2단계를 다시 해 보려면 docker restart cr-fx-vuln을 실행합니다. 테스트는 시작할 때마다 seed()로 초기화하므로 영향을 받지 않습니다.
  • pytest 출력에 httpx 관련 경고가 나옵니다. starlette.testclient가 httpx 사용이 더 이상 권장되지 않는다는 StarletteDeprecationWarning을 냈습니다. 테스트 결과에는 영향이 없어서 이 글의 화면에서는 -p no:warnings로 숨겼습니다.

확인 범위

  • 확인한 것: 위의 모든 명령과 출력은 Docker 컨테이너와 Git Bash에서 실제로 실행한 결과입니다. Pydantic extra 옵션(기본 ignore, forbid의 ValidationError, extra_forbidden)은 https://pydantic.dev/docs/validation/latest/api/pydantic/config/, FastAPI의 response_model 출력 필터링은 https://fastapi.tiangolo.com/tutorial/response-model/에서 확인했습니다.
  • 하지 못한 것: PowerShell, Linux, macOS에서는 실행하지 않았습니다. 실제 인증(JWT 등), 데이터베이스 ORM과 함께 쓰는 경우, 중첩 객체의 extra 처리는 다루지 않았습니다. 422 응답 코드는 직접 실행으로 확인했습니다. FastAPI 오류 처리 문서(https://fastapi.tiangolo.com/tutorial/handling-errors/)는 요청 데이터가 잘못되면 RequestValidationError를 일으키고 기본 처리기가 있다고 설명하며, 예제 처리기에서 status_code=422를 지정하지만 기본 응답 코드가 422라는 문장은 찾지 못했습니다.
  • 범위의 한계: 입력 검증은 대량 할당을 막는 한 방법이고 권한 검사를 대신하지 않습니다. 이 글의 X-User 헤더 인증은 연습용입니다.

이 글의 다음 단계

  • API 과다 응답 걸러 내기: FastAPI response_model과 응답 필드 점검 게이트저장된 사용자 기록을 그대로 반환하는 연습용 FastAPI 앱에서 해시된 비밀번호, 내부 메모, 다른 사용자의 이메일과 전화번호까지 응답에 나가는 것을 curl로 확인합니다. 응답 모델로 고친 수정판과 비교하고, 허용 필드 목록 대조와 민감 키 이름 탐지를 하는 점검 스크립트를 CI 게이트로 붙입니다.
  • OpenAPI 명세로 API 자동 시험: Schemathesis로 500 오류 찾기직접 만든 작은 FastAPI 연습용 API에 입력 검증 없는 정수 파라미터와 명세와 다른 응답 형식을 일부러 넣고, Schemathesis가 어떤 입력으로 어떤 실패(500 오류, 응답 스키마 위반, 문서에 없는 상태 코드)를 찾는지 봅니다. 수정한 뒤 같은 명령이 통과하는 과정까지 로컬에서 따라 합니다.

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글