API 응답에 화면이나 호출자가 쓰지 않는 필드가 함께 실려 나가는 문제는 저장된 기록을 그대로 반환할 때 흔히 생깁니다. 내부 ID, 해시된 비밀번호, 내부 메모, 다른 사용자의 이메일과 전화번호가 응답 JSON에 섞이면 화면에는 보이지 않아도 호출한 사람은 모두 볼 수 있습니다. 이 글에서는 취약한 API와 고친 API를 나란히 띄워 응답을 비교하고, 응답 필드를 자동으로 점검하는 스크립트를 만듭니다.
앱은 이 글을 위해 직접 만든 연습용입니다. 인증은 X-User 헤더로 대신했고 데이터는 모두 가짜(이메일은 example.com)이며 코드 안에 들어 있으므로 실제 서비스에 쓰지 마십시오. 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 |
| 호출 도구 | curl (Git Bash) |
작업 폴더에는 아래 다섯 파일을 둡니다. 전체 내용은 글 끝의 ## 전체 코드에 있습니다.
Dockerfile
requirements.txt
vulnerable_app.py
fixed_app.py
check_fields.py
1. 두 앱을 컨테이너로 띄우기
이미지 하나에 취약판과 수정판이 함께 들어 있고, 컨테이너를 만들 때 실행할 모듈만 다르게 지정합니다. 취약판은 18110, 수정판은 18111 포트입니다. Git Bash에서 docker exec 경로가 변환되는 경우가 있어 MSYS_NO_PATHCONV=1을 지정했습니다.
export MSYS_NO_PATHCONV=1
docker build -q -t cr-a16-lab:latest . && echo built
docker network create cr-a16-net
docker run -d --name cr-a16-vuln --network cr-a16-net -p 127.0.0.1:18110:8000 cr-a16-lab:latest uvicorn vulnerable_app:app --host 0.0.0.0 --port 8000
docker run -d --name cr-a16-fixed --network cr-a16-net -p 127.0.0.1:18111:8000 cr-a16-lab:latest
docker ps --filter name=cr-a16 --format 'table {{.Names}}\t{{.Ports}}'

사용자는 alice, dana, root 세 명이고 세 엔드포인트가 있습니다. GET /users/me는 내 정보, GET /users/{username}은 다른 사용자의 공개 프로필, GET /users는 목록입니다.
2. 취약판 응답 살펴보기
취약판은 세 엔드포인트 모두 USERS의 딕셔너리를 그대로 return합니다. alice가 dana의 프로필과 자신의 정보를 조회합니다.
curl -s -H 'X-User: alice' http://127.0.0.1:18110/users/dana; echo; curl -s -H 'X-User: alice' http://127.0.0.1:18110/users/me

alice가 받은 dana의 응답에 internal_id, password_hash, internal_note가 있고 이메일과 전화번호도 들어 있습니다. 공개 프로필 화면에는 이름과 팀만 보이더라도 API 응답은 기록 전체입니다. 본인 정보에서도 해시와 내부 메모는 본인이 볼 이유가 없는 값입니다.
3. 수정판: 응답 모델로 걸러 내기
수정판은 응답 모델을 둘로 나눕니다. PublicUser는 다른 사용자에게 보여 줄 username, display_name, team만 담고, MyProfile은 여기에 본인에게만 보여 줄 email, phone, role을 더합니다. 엔드포인트에 response_model을 지정하면 모델에 선언하지 않은 필드는 응답에서 빠집니다. FastAPI 공식 문서도 응답 모델에 선언되지 않은 데이터는 걸러진다고 설명하고, 입력 모델과 출력 모델을 나눠 비밀번호가 응답에 나가지 않게 하는 예를 보여 줍니다. 목록은 list[PublicUser]로 지정했습니다. 해시와 내부 메모는 어느 모델에도 넣지 않았습니다.
같은 요청을 수정판에 보냅니다.
curl -s -H 'X-User: alice' http://127.0.0.1:18111/users/dana; echo; curl -s -H 'X-User: alice' http://127.0.0.1:18111/users/me

모델에 필드를 추가하지 않는 한 저장소에 새 컬럼이 생겨도 응답에는 나가지 않습니다. 허용 목록 방식이라서 나중에 기록에 값이 늘어나는 경우에도 안전한 쪽으로 동작합니다.
다만 이 걸러 내기는 함수가 딕셔너리나 모델 객체를 돌려줄 때만 적용됩니다. JSONResponse 같은 Response 객체를 직접 만들어 반환하면 response_model이 쓰이지 않습니다. 같은 모델을 지정한 두 엔드포인트를 따로 띄워 확인하면 아래와 같습니다.
@app.get("/a", response_model=PublicUser)
def a():
return USERS["dana"]
@app.get("/b", response_model=PublicUser)
def b():
return JSONResponse(USERS["dana"])
/a는 {"username":"dana","display_name":"Dana","team":"ops"}만 돌려주고, /b는 password_hash와 internal_note를 포함한 기록 전체를 돌려줍니다. FastAPI 공식 문서도 Response를 반환하면 Pydantic 데이터 변환 없이 그대로 전달된다고 설명합니다. Response를 직접 반환하는 엔드포인트가 있다면 아래 4단계의 점검 스크립트 같은 응답 대조를 꼭 거칩니다.
4. 응답 필드 점검 게이트
사람이 화면으로 확인하면 빠뜨리기 쉬우므로 check_fields.py로 자동화합니다. 엔드포인트마다 허용 필드 목록을 적어 두고, 실제 응답의 키가 목록을 벗어나면 실패로 처리합니다. 벗어난 키 중 password, hash, secret, token, api_key, internal, note가 이름에 들어가면 민감 키 이름으로 함께 보고합니다. 목록 응답은 항목마다 같은 목록을 적용하고, 위반이 있으면 종료 코드 1을 돌려줍니다. 표준 라이브러리만 써서 컨테이너 안에서도 호스트에서도 돌릴 수 있습니다.
먼저 취약판에 돌려 게이트가 실제로 걸리는지 확인합니다.
docker exec cr-a16-vuln python check_fields.py http://127.0.0.1:8000

수정판에서는 모두 통과합니다.
docker exec cr-a16-fixed python check_fields.py http://127.0.0.1:8000

CI에서는 테스트용으로 띄운 서비스 주소를 인자로 주고 이 스크립트를 실행하며, 종료 코드가 1이면 병합을 막는 단계로 둡니다. 새 엔드포인트를 만들면 CHECKS에 허용 목록을 함께 추가해야 점검 대상이 됩니다.
결과 정리
- 저장된 기록(ORM 객체나 딕셔너리)을 그대로 반환하면 내부 ID, 해시, 내부 메모, 다른 사용자의 개인정보가 응답에 실립니다.
- 응답 모델을 엔드포인트별로 따로 선언하고
response_model로 지정하면 선언하지 않은 필드는 걸러집니다. - 본인용과 타인용 모델을 나누면 같은 기록에서도 보여 줄 필드를 다르게 할 수 있습니다.
- 허용 필드 대조와 민감 키 이름 탐지를 CI에 넣어 응답에 필드가 새로 섞이는 것을 막습니다.
전체 코드
작업 폴더 구조는 아래와 같습니다.
Dockerfile
requirements.txt
vulnerable_app.py
fixed_app.py
check_fields.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 check_fields.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
vulnerable_app.py
"""연습용 취약 API입니다. 실제 서비스에 쓰지 마십시오.
저장된 사용자 기록(딕셔너리)을 걸러 내지 않고 그대로 반환하는 구조를 일부러 만들었습니다.
인증은 X-User 헤더로 대신하는 연습용 방식이고, 데이터는 모두 가짜입니다.
"""
from fastapi import Depends, FastAPI, Header, HTTPException
app = FastAPI(title="excessive-data-exposure vulnerable (practice only)")
DOMAIN = "example.com" # 예약된 예시 도메인만 씁니다
USERS = {
"alice": {"id": 1, "internal_id": "emp-00417", "username": "alice",
"display_name": "Alice", "email": f"alice@{DOMAIN}",
"phone": "010-0000-1111", "team": "sales", "role": "user",
"password_hash": "pbkdf2$fake$9f2c41aa7d", "internal_note": "VIP 계약 갱신 예정"},
"dana": {"id": 2, "internal_id": "emp-00532", "username": "dana",
"display_name": "Dana", "email": f"dana@{DOMAIN}",
"phone": "010-0000-2222", "team": "ops", "role": "user",
"password_hash": "pbkdf2$fake$3b7d90c1e5", "internal_note": "결제 지연 이력 있음"},
"root": {"id": 3, "internal_id": "emp-00001", "username": "root",
"display_name": "Root", "email": f"root@{DOMAIN}",
"phone": "010-0000-3333", "team": "ops", "role": "admin",
"password_hash": "pbkdf2$fake$c04e8a6b12", "internal_note": "관리자 계정"},
}
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.get("/users/{username}")
def read_user(username: str, user: dict = Depends(current_user)):
if username not in USERS:
raise HTTPException(status_code=404, detail="없는 사용자입니다")
return USERS[username] # 취약: 다른 사용자의 개인정보와 내부 값까지 나갑니다
@app.get("/users")
def list_users(user: dict = Depends(current_user)):
return list(USERS.values()) # 취약: 목록 전체가 그대로 나갑니다
fixed_app.py
"""vulnerable_app.py의 수정판입니다. 연습용이며 실제 서비스에 쓰지 마십시오.
엔드포인트마다 응답 모델을 따로 두고 response_model로 지정해, 모델에 없는 필드는 응답에서 걸러 냅니다.
"""
from fastapi import Depends, FastAPI, Header, HTTPException
from pydantic import BaseModel
from vulnerable_app import USERS # 같은 가짜 데이터를 씁니다
app = FastAPI(title="excessive-data-exposure fixed (practice only)")
class PublicUser(BaseModel):
"""다른 사용자에게 보여 줄 필드만 선언합니다."""
username: str
display_name: str
team: str
class MyProfile(PublicUser):
"""본인에게만 보여 주는 필드를 더합니다. 해시와 내부 메모는 여기에도 넣지 않습니다."""
email: str
phone: 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=MyProfile)
def read_me(user: dict = Depends(current_user)):
return user
@app.get("/users/{username}", response_model=PublicUser)
def read_user(username: str, user: dict = Depends(current_user)):
if username not in USERS:
raise HTTPException(status_code=404, detail="없는 사용자입니다")
return USERS[username]
@app.get("/users", response_model=list[PublicUser])
def list_users(user: dict = Depends(current_user)):
return list(USERS.values())
check_fields.py
"""응답 필드 점검 게이트입니다. 표준 라이브러리만 씁니다.
사용: python check_fields.py http://127.0.0.1:8000
엔드포인트마다 허용 필드 목록과 대조하고, 민감해 보이는 키 이름이 있으면 함께 보고합니다.
위반이 하나라도 있으면 종료 코드 1을 돌려줍니다.
"""
import json
import re
import sys
import urllib.request
CALLER = "alice"
# (경로, 허용 필드). 목록 응답은 항목마다 같은 허용 필드를 적용합니다.
CHECKS = [
("/users/me", {"username", "display_name", "team", "email", "phone", "role"}),
("/users/dana", {"username", "display_name", "team"}),
("/users", {"username", "display_name", "team"}),
]
SENSITIVE = re.compile(r"password|hash|secret|token|api_?key|internal|note", re.I)
def fetch(base, path):
req = urllib.request.Request(base + path, headers={"X-User": CALLER})
with urllib.request.urlopen(req, timeout=5) as r:
return json.load(r)
def main():
base = sys.argv[1].rstrip("/") if len(sys.argv) > 1 else "http://127.0.0.1:8000"
bad = 0
for path, allowed in CHECKS:
data = fetch(base, path)
items = data if isinstance(data, list) else [data]
extra = sorted({k for item in items for k in item} - allowed)
flagged = [k for k in extra if SENSITIVE.search(k)]
if extra:
bad += 1
print(f"FAIL {path}: 허용 목록에 없는 필드 {extra} (민감 키 이름: {flagged or '없음'})")
else:
print(f"PASS {path}: 필드 {len(allowed)}개 이내")
print("결과:", "실패 %d건" % bad if bad else "모두 통과")
sys.exit(1 if bad else 0)
if __name__ == "__main__":
main()
자주 막히는 곳
docker exec나docker run의 경로가 이상하게 바뀝니다. Git Bash(MSYS)는/로 시작하는 인자를 Windows 경로로 바꾸는 경우가 있습니다. 이 글의 명령에는 경로 인자가 없지만 다른 명령을 덧붙일 때는export MSYS_NO_PATHCONV=1을 먼저 실행합니다.- 수정판이
vulnerable_app을 불러옵니다.fixed_app.py는 같은 가짜 데이터를 쓰려고from vulnerable_app import USERS를 합니다. 이미지에 두 파일이 함께 들어 있어야 합니다. 취약판 모듈이 수정판 이미지에 남는 것은 연습 편의 때문이므로 실제 프로젝트에서는 공통 데이터를 별도 모듈로 분리합니다.Dockerfile의COPY줄에서 한쪽을 빼면 수정판이 시작되지 않습니다. - 점검 스크립트가 새 엔드포인트를 검사하지 않습니다.
CHECKS목록에 적힌 경로만 점검합니다. 경로를 추가한 뒤 목록에 허용 필드를 같이 적습니다.
확인 범위
- 확인한 것: 위의 모든 명령과 출력은 Docker 컨테이너와 Git Bash에서 실제로 실행한 결과입니다.
response_model이 선언하지 않은 데이터를 걸러 내는 동작, 입력 모델과 출력 모델을 나누는 예,response_model에 모델 목록을 지정하는 방법은https://fastapi.tiangolo.com/tutorial/response-model/에서,Response를 직접 반환하면 Pydantic 변환이 적용되지 않는다는 설명은https://fastapi.tiangolo.com/advanced/response-directly/에서 확인했고 위/b동작은 컨테이너에서 직접 실행해 확인했습니다. - 하지 못한 것: PowerShell, Linux, macOS에서는 실행하지 않았습니다. 실제 인증, 데이터베이스 ORM 객체, 중첩 객체, 페이지 단위 응답은 다루지 않았습니다.
- 범위의 한계: 응답 필터링은 과다 노출을 줄이는 방법이고 다른 사용자의 기록을 볼 수 있는지 정하는 접근 권한 검사를 대신하지 않습니다. 이 글의
X-User헤더 인증은 연습용입니다. 점검 스크립트의 민감 키 이름 목록은 예시이며 키 이름에 드러나지 않는 민감한 값은 허용 필드 대조로만 잡을 수 있습니다.
이 글의 다음 단계
- OpenAPI 명세로 API 자동 시험: Schemathesis로 500 오류 찾기직접 만든 작은 FastAPI 연습용 API에 입력 검증 없는 정수 파라미터와 명세와 다른 응답 형식을 일부러 넣고, Schemathesis가 어떤 입력으로 어떤 실패(500 오류, 응답 스키마 위반, 문서에 없는 상태 코드)를 찾는지 봅니다. 수정한 뒤 같은 명령이 통과하는 과정까지 로컬에서 따라 합니다.
- API 대량 할당 막기: FastAPI Pydantic extra=forbid요청 JSON을 그대로 사용자 기록에 합치는 연습용 FastAPI 앱에서 일반 사용자가 role을 admin으로 올리는 과정을 curl로 확인합니다. 같은 API를 Pydantic 허용 필드 모델로 고치면 422로 거절되는 것을 비교하고, 회귀를 막는 pytest 게이트를 붙입니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com