# API 과다 응답 걸러 내기: FastAPI response_model과 응답 필드 점검 게이트

> 저장된 사용자 기록을 그대로 반환하는 연습용 FastAPI 앱에서 해시된 비밀번호, 내부 메모, 다른 사용자의 이메일과 전화번호까지 응답에 나가는 것을 curl로 확인합니다. 응답 모델로 고친 수정판과 비교하고, 허용 필드 목록 대조와 민감 키 이름 탐지를 하는 점검 스크립트를 CI 게이트로 붙입니다.

- 주소: https://copyandrun.com/blog/api-excessive-data-exposure-response-filter/
- 분야: API 보안
- 발행일: 2026-11-02
- 태그: 과다 데이터 노출, response_model, FastAPI, Pydantic, CI 게이트

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. 두 앱을 컨테이너로 띄우기

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

이미지 하나에 취약판과 수정판이 함께 들어 있고, 컨테이너를 만들 때 실행할 모듈만 다르게 지정합니다. 취약판은 18110, 수정판은 18111 포트입니다. Git Bash에서 `docker exec` 경로가 변환되는 경우가 있어 `MSYS_NO_PATHCONV=1`을 지정했습니다.

```bash
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}}'
```

![두 컨테이너가 127.0.0.1의 18110과 18111 포트에만 연결되어 올라온 것을 확인합니다.](https://copyandrun.com/img/api-excessive-data-exposure-response-filter/01-lab-environment.png)

사용자는 `alice`, `dana`, `root` 세 명이고 세 엔드포인트가 있습니다. `GET /users/me`는 내 정보, `GET /users/{username}`은 다른 사용자의 공개 프로필, `GET /users`는 목록입니다.

## 2. 취약판 응답 살펴보기

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

취약판은 세 엔드포인트 모두 `USERS`의 딕셔너리를 그대로 `return`합니다. alice가 dana의 프로필과 자신의 정보를 조회합니다.

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

![취약판에서는 dana의 프로필에 이메일, 전화번호, password_hash, internal_note까지 담겨 나가는 것을 확인합니다.](https://copyandrun.com/img/api-excessive-data-exposure-response-filter/02-vulnerable-exposes-fields.png)

alice가 받은 dana의 응답에 `internal_id`, `password_hash`, `internal_note`가 있고 이메일과 전화번호도 들어 있습니다. 공개 프로필 화면에는 이름과 팀만 보이더라도 API 응답은 기록 전체입니다. 본인 정보에서도 해시와 내부 메모는 본인이 볼 이유가 없는 값입니다.

## 3. 수정판: 응답 모델로 걸러 내기

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

수정판은 응답 모델을 둘로 나눕니다. `PublicUser`는 다른 사용자에게 보여 줄 `username`, `display_name`, `team`만 담고, `MyProfile`은 여기에 본인에게만 보여 줄 `email`, `phone`, `role`을 더합니다. 엔드포인트에 `response_model`을 지정하면 모델에 선언하지 않은 필드는 응답에서 빠집니다. FastAPI 공식 문서도 응답 모델에 선언되지 않은 데이터는 걸러진다고 설명하고, 입력 모델과 출력 모델을 나눠 비밀번호가 응답에 나가지 않게 하는 예를 보여 줍니다. 목록은 `list[PublicUser]`로 지정했습니다. 해시와 내부 메모는 어느 모델에도 넣지 않았습니다.

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

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

![수정판에서는 dana의 프로필에 이름과 팀만 나오고, 본인 정보에는 이메일과 전화번호가 더해지되 해시와 내부 메모는 없는 것을 확인합니다.](https://copyandrun.com/img/api-excessive-data-exposure-response-filter/03-fixed-filters-fields.png)

모델에 필드를 추가하지 않는 한 저장소에 새 컬럼이 생겨도 응답에는 나가지 않습니다. 허용 목록 방식이라서 나중에 기록에 값이 늘어나는 경우에도 안전한 쪽으로 동작합니다.

다만 이 걸러 내기는 함수가 딕셔너리나 모델 객체를 돌려줄 때만 적용됩니다. `JSONResponse` 같은 `Response` 객체를 직접 만들어 반환하면 `response_model`이 쓰이지 않습니다. 같은 모델을 지정한 두 엔드포인트를 따로 띄워 확인하면 아래와 같습니다.

```python
@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. 응답 필드 점검 게이트

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

사람이 화면으로 확인하면 빠뜨리기 쉬우므로 `check_fields.py`로 자동화합니다. 엔드포인트마다 허용 필드 목록을 적어 두고, 실제 응답의 키가 목록을 벗어나면 실패로 처리합니다. 벗어난 키 중 `password`, `hash`, `secret`, `token`, `api_key`, `internal`, `note`가 이름에 들어가면 민감 키 이름으로 함께 보고합니다. 목록 응답은 항목마다 같은 목록을 적용하고, 위반이 있으면 종료 코드 1을 돌려줍니다. 표준 라이브러리만 써서 컨테이너 안에서도 호스트에서도 돌릴 수 있습니다.

먼저 취약판에 돌려 게이트가 실제로 걸리는지 확인합니다.

```bash
docker exec cr-a16-vuln python check_fields.py http://127.0.0.1:8000
```

![취약판에서는 세 엔드포인트 모두 FAIL이고 password_hash와 internal_note가 민감 키 이름으로 보고되는 것을 확인합니다.](https://copyandrun.com/img/api-excessive-data-exposure-response-filter/04-gate-fails-vulnerable.png)

수정판에서는 모두 통과합니다.

```bash
docker exec cr-a16-fixed python check_fields.py http://127.0.0.1:8000
```

![수정판에서는 세 엔드포인트 모두 PASS이고 결과가 모두 통과인 것을 확인합니다.](https://copyandrun.com/img/api-excessive-data-exposure-response-filter/05-gate-passes-fixed.png)

CI에서는 테스트용으로 띄운 서비스 주소를 인자로 주고 이 스크립트를 실행하며, 종료 코드가 1이면 병합을 막는 단계로 둡니다. 새 엔드포인트를 만들면 `CHECKS`에 허용 목록을 함께 추가해야 점검 대상이 됩니다.

## 결과 정리

- 저장된 기록(ORM 객체나 딕셔너리)을 그대로 반환하면 내부 ID, 해시, 내부 메모, 다른 사용자의 개인정보가 응답에 실립니다.
- 응답 모델을 엔드포인트별로 따로 선언하고 `response_model`로 지정하면 선언하지 않은 필드는 걸러집니다.
- 본인용과 타인용 모델을 나누면 같은 기록에서도 보여 줄 필드를 다르게 할 수 있습니다.
- 허용 필드 대조와 민감 키 이름 탐지를 CI에 넣어 응답에 필드가 새로 섞이는 것을 막습니다.

## 전체 코드

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

```
Dockerfile
requirements.txt
vulnerable_app.py
fixed_app.py
check_fields.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 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

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

```python
"""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
"""응답 필드 점검 게이트입니다. 표준 라이브러리만 씁니다.

사용: 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` 헤더 인증은 연습용입니다. 점검 스크립트의 민감 키 이름 목록은 예시이며 키 이름에 드러나지 않는 민감한 값은 허용 필드 대조로만 잡을 수 있습니다.
