105 lines
9.1 KiB
Markdown
105 lines
9.1 KiB
Markdown
---
|
|
title: Spring Boot Actuator — Endpoint Exposure & Security Defaults
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-actuator, spring-boot, actuator, endpoint-exposure, security-defaults]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-management-actuator-security-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Spring Boot Actuator — Endpoint Exposure & Security Defaults
|
|
|
|
> Layer: `raw/official-docs/` — Spring Boot 공식 reference (Actuator Endpoints) 의 exposure / security default 원문 발췌.
|
|
> ca-tmpl `feature-management-actuator-security-contract` 의 prod allowlist (`health`, `prometheus`, `info`) + forbidden (`env`, `configprops`, `heapdump`, `threaddump`) 결정 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-management-actuator-security-contract]] | prod allowlist (`health`, `prometheus`, `info`) + forbidden (`env`, `configprops`, `heapdump`, `threaddump`) 정책이 Spring Boot default 강화임을 증명하는 근거 |
|
|
|
|
## 컨텍스트
|
|
|
|
`feature-management-actuator-security-contract` ca-tmpl 이 정한 prod allowlist 와 forbidden 목록이 Spring Boot 공식 권고 / 기본값과 어떻게 부합하는지 확인. baseline 이 임의 정책이 아니라 공식 default 를 강화한 것임을 증명.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html
|
|
- 관련 property: `management.endpoints.web.exposure.include`, `management.endpoint.health.show-details`
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Spring Team (VMware / Broadcom)
|
|
- 발행일: Spring Boot 3.x reference (4.0.6 anchors observed)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§actuator.endpoints.exposing] "By default, only the health endpoint is exposed over HTTP and JMX."
|
|
|
|
> [§actuator.endpoints.security] "Before setting the `management.endpoints.web.exposure.include`, ensure that the exposed actuators do not contain sensitive information, are secured by placing them behind a firewall, or are secured by something like Spring Security."
|
|
|
|
> [§actuator.endpoints.security] "If Spring Security is on the classpath and no other `SecurityFilterChain` bean is present, all actuators other than `/health` are secured by Spring Boot auto-configuration."
|
|
|
|
> [§actuator.endpoints.sanitization] "Information returned by the `/env`, `/configprops` and `/quartz` endpoints can be sensitive, so by default values are always fully sanitized (replaced by `******`)."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| SB-ACT-EXP-C1 | Spring Boot Actuator 의 default 는 HTTP / JMX 모두에서 **health endpoint 하나만** 노출 | [§actuator.endpoints.exposing] "By default, only the health endpoint is exposed over HTTP and JMX." | `official-vendor-doc` | Spring Boot Actuator dependency 가 클래스패스에 있는 모든 Spring Boot 앱 | `prometheus`, `info` 등 다른 endpoint 가 자동 노출된다는 뜻은 아님 — 명시적 `include` 필요 |
|
|
| SB-ACT-EXP-C2 | `management.endpoints.web.exposure.include` 설정 전에 노출되는 actuator 가 (a) 민감 정보 없거나 (b) firewall 뒤 또는 (c) Spring Security 보호되도록 보장해야 함 (공식 권고) | [§actuator.endpoints.security] "Before setting the `management.endpoints.web.exposure.include`, ensure that the exposed actuators do not contain sensitive information, are secured by placing them behind a firewall, or are secured by something like Spring Security." | `official-vendor-doc` | actuator endpoint 를 default 보다 더 노출하려는 모든 시나리오 | 세 옵션 중 어느 것이 모든 환경에서 최선인지의 판단은 본 인용 범위 밖 — 상황별 선택 |
|
|
| SB-ACT-EXP-C3 | Spring Security 가 classpath 에 있고 다른 `SecurityFilterChain` bean 이 없으면, `/health` 외 모든 actuator 가 Spring Boot auto-configuration 으로 secured | [§actuator.endpoints.security] "If Spring Security is on the classpath and no other `SecurityFilterChain` bean is present, all actuators other than `/health` are secured by Spring Boot auto-configuration." | `official-vendor-doc` | spring-boot-starter-security 사용 + custom SecurityFilterChain 없는 환경 | custom `SecurityFilterChain` bean 을 정의한 순간 이 auto-config 가 비활성되므로, 개발자가 actuator 보호 룰을 명시해야 함 — 흔한 함정 |
|
|
| SB-ACT-EXP-C4 | `/env`, `/configprops`, `/quartz` endpoint 의 응답 값은 default 로 **항상 완전히 sanitize** 되어 `******` 로 치환됨 | [§actuator.endpoints.sanitization] "Information returned by the `/env`, `/configprops` and `/quartz` endpoints can be sensitive, so by default values are always fully sanitized (replaced by `******`)." | `official-vendor-doc` | Spring Boot Actuator 의 default sanitizer 동작 | `/heapdump`, `/threaddump` 등 다른 sensitive endpoint 의 sanitization 은 본 인용 범위 밖 — 별도 페이지 확인 필요 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `SB-ACT-EXP-C1`: default 노출 = `health` 하나
|
|
- `SB-ACT-EXP-C2`: 더 많은 endpoint 노출 시 보안 조치 권고 (3가지 옵션)
|
|
- `SB-ACT-EXP-C3`: Spring Security + no SecurityFilterChain → `/health` 외 auto-secured
|
|
- `SB-ACT-EXP-C4`: `/env`, `/configprops`, `/quartz` default sanitize
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- prod 에서 `env`, `configprops`, `heapdump`, `threaddump` 를 **endpoint 자체로 금지**하라는 공식 의무 — ca-tmpl 의 forbidden 정책은 default sanitize 보다 한 단계 더 strict 한 자체 결정
|
|
- `/info` 의 default 노출 여부 — 본 인용 범위 밖 (default 는 health 만이므로 info 도 명시 include 필요)
|
|
- `/prometheus` endpoint 가 자동 노출되는 조건 (micrometer-registry-prometheus dependency 등) — 별도
|
|
- custom `SecurityFilterChain` 정의 시 actuator 보호가 disable 되는 정확한 동작 (모두 permit 인지 모두 deny 인지)
|
|
- **내 프로젝트 (ca-tmpl) 에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl 의 prod 환경에서 `management.endpoints.web.exposure.include=health,prometheus,info` 설정 시 실제 노출되는 sub-endpoint 셋 (`/actuator/health/liveness` 등 group sub-path 포함 여부)
|
|
- custom SecurityFilterChain 정의된 ca-tmpl 환경에서 actuator path 가 `permitAll()` / `authenticated()` 어디로 떨어지는지 (auto-config 비활성 영향)
|
|
- prometheus endpoint 의 prod 노출 시 scrape 인증 방식 (network ACL 외 추가 인증 필요한지)
|
|
|
|
## ca-tmpl 함의 (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용이 아니라 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 `wiki/projects/ca-skeleton-operational-contract` source-summary 로 이전.
|
|
|
|
- **공식 default 와의 매핑**:
|
|
- 공식 default = "only health exposed" → ca-tmpl prod allowlist (`health/*`, `prometheus`, `info`) 는 **default 를 약간 확장** (prometheus, info 추가).
|
|
- 공식 권고 = "not sensitive OR behind firewall OR Spring Security" → ca-tmpl 의 management port 분리 (9001) + network ACL 은 "behind firewall" 옵션 선택.
|
|
- 공식 default sanitize = `env` / `configprops` 값 `******` → ca-tmpl 은 한 단계 더 나아가 prod 에서 **endpoint 자체 forbidden** (default 보다 strict).
|
|
- **`/info` 주의**: ca-tmpl 은 "build info only, no secret" 명시. `git.commit.id`, `build.version` 외 contributor 가 추가 정보로 secret 노출할 가능성을 별도 review 로 차단.
|
|
- **heapdump / threaddump**: 공식 문서는 endpoint 정의는 하나 "prod 금지" 의무는 두지 않음. ca-tmpl 의 명시적 forbidden 은 운영 보안 강화 자체 결정.
|
|
- **장점**: 공식 default 보다 strict → 보안 회귀 가능성 ↓. `info` 만 추가 노출이라 향후 Spring Boot 버전업 시 default 변동 영향 적음.
|
|
- **단점**: prometheus 노출은 scrape 환경 (인증 or network ACL) 이 명시적으로 보장돼야 의미 — ca-tmpl 의 network ACL 은 기본 충족, 외부 노출 시 별도 인증 필요.
|
|
|
|
## 메모 / Notes
|
|
|
|
- 2026-05-27 재검증: 4개 핵심 인용 모두 verbatim 으로 reference 의 해당 anchor 에 존재 확인.
|
|
- 다음 fetch 후보:
|
|
- `https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.sanitization` (heapdump / threaddump sanitization 별도 정책)
|
|
- `https://docs.spring.io/spring-boot/reference/actuator/observability.html#actuator.observability.prometheus` (prometheus endpoint 노출 조건)
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/actuator-management-port-spring-official]] — management port 분리 결정
|
|
- [[raw/official-docs/runtime-health-spring-actuator-groups]] — health endpoint group 모델
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-management-actuator-security-contract]]
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]]
|
|
- 인용한 wiki 요약: (미작성)
|