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

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

- 주소: https://copyandrun.com/blog/api-mass-assignment-pydantic-allowlist/
- 분야: API 보안
- 발행일: 2026-11-02
- 태그: 대량 할당, Mass Assignment, FastAPI, Pydantic, 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. 두 앱을 컨테이너로 띄우기

<!-- files: Dockerfile, requirements.txt, vulnerable_app.py, fixed_app.py -->

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

```bash
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 포트에만 연결되어 올라온 것을 확인합니다.](https://copyandrun.com/img/api-mass-assignment-pydantic-allowlist/01-lab-environment.png)

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

## 2. 취약판에서 role 올리기

<!-- files: vulnerable_app.py -->

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

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

```bash
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까지 보이는 것을 확인합니다.](https://copyandrun.com/img/api-mass-assignment-pydantic-allowlist/02-vulnerable-role-escalation.png)

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

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

<!-- files: fixed_app.py -->

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

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

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

```bash
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인 것을 확인합니다.](https://copyandrun.com/img/api-mass-assignment-pydantic-allowlist/03-fixed-rejects-role.png)

`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이 나갑니다. 공격은 막히지만 클라이언트가 잘못된 키를 보내고 있다는 사실이 드러나지 않습니다.

## 4. 회귀 방지 게이트

<!-- files: test_gate.py -->

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

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

![수정판에서 10건이 모두 통과하는 것을 확인합니다.](https://copyandrun.com/img/api-mass-assignment-pydantic-allowlist/04-gate-passes-fixed.png)

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

```bash
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건만 통과하는 것을 확인합니다.](https://copyandrun.com/img/api-mass-assignment-pydantic-allowlist/05-gate-fails-vulnerable.png)

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

## 결과 정리

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

## 전체 코드

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

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

### Dockerfile

```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

```python
"""연습용 취약 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

```python
"""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

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

사용: 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` 헤더 인증은 연습용입니다.
