llm-wiki/raw/official-docs/schema-jackson-polymorphic-deserialization.md

---
title: "official-doc / Jackson Polymorphic Deserialization (Security Guidance)"
source_type: official-doc
url: https://fasterxml.github.io/jackson-databind/javadoc/2.14/com/fasterxml/jackson/databind/jsontype/PolymorphicTypeValidator.html
archive_url:
vendor: FasterXML / jackson-databind
related_branches: [feature-boundary-validation-mapping-contract, feature-schema-serialization-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-tmpl, security, jackson, serialization, jackson-polymorphic, owasp]
status: raw
confidence: high
created: 2026-05-28
last_reviewed: 2026-05-28
---

# Jackson Polymorphic Deserialization (Security Guidance)

> Layer: `raw/official-docs/` — FasterXML jackson-databind 공식 Javadoc 과 NVD CVE 데이터베이스에서 추출한 verbatim 발췌. Polymorphic Deserialization 보안 지침 — sealed `Command` interface 패턴의 Jackson 안전 메커니즘 결정 근거 (블라인드 B5).

---

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-boundary-validation-mapping-contract]] | sealed `Command` interface + record subtypes 의 Jackson polymorphic deserialization 안전 메커니즘 결정 (블라인드 B5). `enableDefaultTyping()` 금지 + `@JsonTypeInfo` + `PolymorphicTypeValidator` 강제 근거 |

---

## 출처 / Source

| 항목 | 내용 |
|---|---|
| 원본 URL (Primary — Javadoc) | https://fasterxml.github.io/jackson-databind/javadoc/2.14/com/fasterxml/jackson/databind/jsontype/PolymorphicTypeValidator.html |
| 보조 URL (BasicPolymorphicTypeValidator Javadoc) | https://fasterxml.github.io/jackson-databind/javadoc/2.14/com/fasterxml/jackson/databind/jsontype/BasicPolymorphicTypeValidator.html |
| 보조 URL (ObjectMapper Javadoc) | https://fasterxml.github.io/jackson-databind/javadoc/2.14/com/fasterxml/jackson/databind/ObjectMapper.html |
| 보조 URL (wiki 요약 — 부분 발췌) | https://github.com/FasterXML/jackson-docs/wiki/JacksonPolymorphicDeserialization |
| 보조 URL (CVE-2019-14379, NVD) | https://nvd.nist.gov/vuln/detail/CVE-2019-14379 |
| 저자 / 조직 | FasterXML (Tatu Saloranta, @cowtowncoder) |
| 발행일 | jackson-databind 2.14.x Javadoc (2022-11 ~ 현재, `@since 2.10` 항목은 2019-09) |
| 마지막 확인일 | 2026-05-28 |

> **URL fetch 경위**: 사용자 제공 주 URL `https://github.com/FasterXML/jackson-databind/wiki/JacksonPolymorphicDeserialization` 은 WebFetch 시 wiki home 으로 redirect 됨 (페이지 존재 여부 불확실). 공식 Javadoc 이 동일 정보를 normative 하게 담고 있으므로 Javadoc URL 을 primary source 로 채택. wiki URL 은 `## Related` 에 후보로 표기.

---

## 왜 저장했는지 / Why archived

`feature-boundary-validation-mapping-contract` branch 의 블라인드 B5: sealed `Command` interface 와 record subtypes 의 Jackson polymorphic deserialization 안전 매커니즘 결정 근거. Jackson 2.10 이후 `enableDefaultTyping()` 이 `@Deprecated` 처리되고 `PolymorphicTypeValidator` 가 요구되는 이유, untrusted type attack(gadget chain) 위협 모델, `@JsonTypeInfo` + `@JsonSubTypes` 명시적 안전 방식의 normative 정의를 수집.

---

## 핵심 인용 / Key quotes (verbatim, self-grep 통과)

> [§PolymorphicTypeValidator class description] "Interface for classes that handle validation of class-name - based subtypes used with Polymorphic Deserialization: both via "default typing" and explicit `@JsonTypeInfo` when using Java Class name as Type Identifier."
> — Source: `PolymorphicTypeValidator` Javadoc, `@since 2.10`

> [§PolymorphicTypeValidator class description] "to allow pluggable allow lists to avoid security problems that occur with unlimited class names."
> — Source: `PolymorphicTypeValidator` Javadoc, purpose clause

> [§ObjectMapper, enableDefaultTyping deprecated] "Since 2.10 use activateDefaultTyping(PolymorphicTypeValidator) instead"
> — Source: `ObjectMapper` Javadoc, `@deprecated` tag on `enableDefaultTyping()`

> [§BasicPolymorphicTypeValidator class description] "Standard BasicPolymorphicTypeValidator implementation that users may want to use for constructing validators based on simple class hierarchy and/or name patterns to allow and/or deny certain subtypes."
> — Source: `BasicPolymorphicTypeValidator` Javadoc, `@since 2.10`

> [§CVE-2019-14379, NVD description] "SubTypeValidator.java in FasterXML jackson-databind before 2.9.9.2 mishandles default typing when ehcache is used (because of net.sf.ehcache.transaction.manager.DefaultTransactionManagerLookup), leading to remote code execution."
> — Source: NVD CVE-2019-14379, CVSS v3.1: 9.8 CRITICAL

---

## Claims Extracted / 추출된 주장

> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트 적용 결론은 `## 메모` 또는 branch-note `Decision Evidence Map` 에서만 작성.

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| JACK-POLY-C1 | `PolymorphicTypeValidator` 는 polymorphic deserialization 시 class-name 기반 subtype 을 검증하는 인터페이스로, default typing 과 `@JsonTypeInfo` 양쪽 모두에 적용된다 | [§PolymorphicTypeValidator] "Interface for classes that handle validation of class-name - based subtypes used with Polymorphic Deserialization: both via "default typing" and explicit `@JsonTypeInfo` when using Java Class name as Type Identifier." | `official-vendor-doc` | Jackson 2.10+ 의 모든 polymorphic deserialization 경로 | type name (`Id.NAME`) 방식의 경우 class name 을 직접 쓰지 않으므로 이 validator 의 주된 방어 대상이 아님 |
| JACK-POLY-C2 | `PolymorphicTypeValidator` 의 목적은 "unlimited class names" 에 의한 보안 문제를 방지하기 위한 허용 목록(allow list) 플러그인 포인트 제공이다 | [§PolymorphicTypeValidator] "to allow pluggable allow lists to avoid security problems that occur with unlimited class names." | `official-vendor-doc` | class name type id (`Id.CLASS`, `Id.MINIMAL_CLASS`) 사용 시 | type name 기반 (`Id.NAME` + `@JsonSubTypes`) 방식은 class name 을 직접 노출하지 않으므로 이 claim 의 주된 적용 대상이 아님 |
| JACK-POLY-C3 | Jackson 2.10 부터 `enableDefaultTyping()` 메서드는 deprecated 처리되었으며, 대체 API 는 `PolymorphicTypeValidator` 를 첫 번째 인자로 요구하는 `activateDefaultTyping()` 이다 | [§ObjectMapper] "Since 2.10 use activateDefaultTyping(PolymorphicTypeValidator) instead" | `official-vendor-doc` | Jackson 2.10+ 모든 ObjectMapper 사용자 | deprecated 처리가 해당 기능의 제거를 의미하지는 않음; 여전히 호출 가능. 단지 새 API 사용을 공식 권고 |
| JACK-POLY-C4 | `BasicPolymorphicTypeValidator` 는 클래스 계층 또는 이름 패턴 기반으로 허용/거부 subtype 을 구성하는 표준 구현체이며, `@since 2.10` | [§BasicPolymorphicTypeValidator] "Standard BasicPolymorphicTypeValidator implementation that users may want to use for constructing validators based on simple class hierarchy and/or name patterns to allow and/or deny certain subtypes." | `official-vendor-doc` | Jackson 2.10+ 에서 default typing 또는 class name type id 를 사용하는 모든 케이스 | 사용자 정의 `PolymorphicTypeValidator` 구현을 대체한다고 보장하지 않음; 복잡한 유효성 요구사항에는 커스텀 구현 필요 |
| JACK-POLY-C5 | CVE-2019-14379: FasterXML jackson-databind 2.9.9.2 이전 버전은 default typing 이 활성화된 상태에서 ehcache `DefaultTransactionManagerLookup` 클래스를 통해 RCE(원격 코드 실행) 로 이어지는 gadget 체인 공격에 취약하다 (CVSS v3.1 9.8 CRITICAL) | [CVE-2019-14379] "SubTypeValidator.java in FasterXML jackson-databind before 2.9.9.2 mishandles default typing when ehcache is used (because of net.sf.ehcache.transaction.manager.DefaultTransactionManagerLookup), leading to remote code execution." | `official-standard` (NVD) | Jackson 2.9.9.1 이하 + default typing 활성화 + ehcache 클래스패스 존재 환경 | 이 CVE 단독으로 "모든 default typing 은 위험" 을 normative 하게 진술하지 않음 — 특정 gadget 클래스 (ehcache) + 특정 버전 조합의 취약성 |

---

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - **JACK-POLY-C1**: Jackson 2.10+ 에서 `PolymorphicTypeValidator` 가 class-name 기반 polymorphic deserialization 의 공식 검증 진입점임
  - **JACK-POLY-C2**: Jackson 공식 문서가 "unlimited class names" 를 보안 문제로 명시하고, allow list 메커니즘을 제공 목적으로 설명함
  - **JACK-POLY-C3**: `enableDefaultTyping()` 이 Jackson 2.10 시점에 공식 deprecated 처리되었음
  - **JACK-POLY-C4**: `BasicPolymorphicTypeValidator` 가 2.10 이후의 표준 구현체로 Javadoc 에 명시됨
  - **JACK-POLY-C5**: default typing 활성화 상태에서 classpath gadget 을 통한 RCE 가 실제 CVE 로 기록됨 (CVSS 9.8)

- 이 자료가 증명하지 않는 것:
  - `@JsonTypeInfo(use = Id.NAME)` + `@JsonSubTypes` 조합이 "항상 안전하다" 는 normative 보장 — Javadoc 은 NAME 방식의 보안 보장을 명시적으로 서술하지 않음
  - sealed interface 나 Java 21 record 와의 Jackson 연동 방식 — 이것은 `feature-boundary-validation-mapping-contract` 에서 별도 구현/테스트로 확인 필요
  - `PolymorphicTypeValidator` 없이도 `@JsonSubTypes` 만으로 gadget chain 을 완전 차단할 수 있다는 보장

- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl 의 sealed `Command` interface 가 `@JsonTypeInfo(use = Id.NAME)` + `@JsonSubTypes` 로 안전하게 매핑되는지 — Spring Boot integration test 에서 untrusted type 주입 시도 필요
  - `activateDefaultTyping()` 호출 여부 — 팀 codebase 에 `enableDefaultTyping` 또는 `activateDefaultTyping` 가 호출되는지 grep 으로 확인 필요
  - Jackson 2.10 이상 버전 사용 여부 — `build.gradle` 의 jackson-databind 의존성 버전 확인 필요

---

## 메모 / Notes

> 검증되지 않은 추론은 적지 않는다. 이 섹션은 `/ingest` 시 wiki/concepts 로 옮길 때 참고용.

- **URL redirect 문제**: 사용자 제공 GitHub wiki URL 3개 모두 home 또는 요약 응답만 반환. Javadoc 이 normative source 로 더 적절하므로 primary URL 을 Javadoc 으로 대체했음. GitHub wiki 가 접근 가능해질 경우 archive_url 에 추가 권장.
- **NAME vs CLASS**: JACK-POLY-C1/C2 는 class name (`Id.CLASS`) 사용 시 위험을 다룬다. sealed interface 를 `Id.NAME` 으로 매핑하면 class name 을 외부에 노출하지 않아 gadget chain attack surface 가 줄어들지만, 이 자료 자체는 NAME 방식의 안전성을 normative 하게 보증하지 않음 — wiki/concepts 에서 별도 analysis 필요.
- **Jackson 2.10 milestone**: PolymorphicTypeValidator (`@since 2.10`) 도입과 `enableDefaultTyping()` deprecation 이 동시에 이루어진 것은 설계 의도의 명확한 시그널 — 단 이 자료만으로 "2.9 이하 사용 금지" normative 는 없음. CVE history 가 실질 근거.
- **추가로 봐야 할 동일 출처 페이지**: Jackson 공식 문서 `JacksonFAQ.md`, `PolymorphicTypeHandling.md` (github wiki 접근 가능 시), `@JsonTypeInfo` annotation Javadoc.

---

## Related / 관련

- 이 자료를 인용하는 branch: [[raw/branch-notes/feature-boundary-validation-mapping-contract]]
- 같은 주제 다른 자료 (향후):
  - Jackson `@JsonTypeInfo` Javadoc — type id mechanism 별 안전성 비교
  - OWASP Deserialization Cheat Sheet — gadget chain 위협 모델 일반 정의
  - Spring Security / Bean Validation 관련: [[raw/official-docs/validation-jakarta-bean-validation-3.0-spec]]
- 이 자료를 인용한 wiki 요약: `wiki/concepts/jackson-polymorphic-deserialization` (생성 시)