대량 할당(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}}'

사용자는 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

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

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. 회귀 방지 게이트
나중에 누군가 편의상 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

게이트가 실제로 취약점을 잡는지도 확인합니다. 취약판 모듈을 지정해 같은 테스트를 돌립니다.
docker exec -e APP_MODULE=vulnerable_app cr-fx-vuln python -m pytest -q --tb=no -p no:warnings test_gate.py

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