--- title: Runbook — ACTUATOR_FORBIDDEN (Actuator 접근 거부) category: AUTHZ error_codes: [ACTUATOR_FORBIDDEN] severity: P2 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: ACTUATOR_FORBIDDEN (`runbook://management/actuator-forbidden`) ## 증상 - `ACTUATOR_FORBIDDEN`은 enum 상수(`OperationalError`)와 registry 행(`docs/registries/error-codes.yaml`)이 있지만 내는 코드가 없다. - 실제 신호: 노출한 actuator(`health`·`info`·`prometheus`) 밖의 경로(env·configprops·heapdump·threaddump·shutdown·loggers)는 actuator chain이 잡지 않아 메인 보안 chain으로 간다. token이 없으면 401 `AUTH_TOKEN_MISSING`(Envelope, `WWW-Authenticate: Bearer`)과 WARN 줄 `security failure: code=AUTH_TOKEN_MISSING category=AUTH method=… path=/actuator/…`(logger `AuthErrorResponseWriter`)이다. 인증된 호출자는 mapping이 없어 404다(`config/observability.yml`의 `management.endpoints.web.exposure`). - 서비스가 노출 목록을 넓혀 `health`·`info`·`prometheus` 밖의 endpoint를 더하면, 그 endpoint는 actuator chain이 잡고 본문 없는 401로 답한다. 그 chain에는 인증 수단이 없다(`ManagementSecurityConfig`). 이 401과 인증된 호출자의 404는 보안 로그 줄을 남기지 않는다. ## 진단 - 관리 포트 노출은 포트로 가른다. 클러스터 밖에서 `curl -s -o /dev/null -w '%{http_code}' http://:9001/actuator/health`가 200이면 관리 포트(`MANAGEMENT_SERVER_PORT`, 기본 9001, bind 주소 `MANAGEMENT_SERVER_ADDRESS`, 기본 `127.0.0.1`)가 클러스터 밖에 노출된 것이다. kubelet·Prometheus가 pod IP로 읽도록 `0.0.0.0`에 묶은 배포에서 클러스터 안의 200은 정상이다. 401·404만으로는 가를 수 없다: actuator가 없는 메인 포트의 `/actuator/env`도 메인 chain이 같은 401·WARN 줄·404로 답한다. - 앱 로그에서 `path=/actuator`가 든 `security failure` 줄을 찾는다(token 없는 시도). 그 줄에는 포트가 없다. 인증된 호출자의 404는 보안 로그 줄이 없다. 앞단 프록시·ingress 접근 로그로 어느 포트를 누가 불렀는지 찾는다. ## 조치 - 관리 포트를 클러스터 밖으로 열지 않는다. kubelet 프로브와 Prometheus는 pod IP로 붙으므로 둘 중 하나를 고른다(`src/bootstrap/service-runtime/README.md` 「ManagementSecurityConfig」): `MANAGEMENT_SERVER_ADDRESS`를 `0.0.0.0`으로 두고 NetworkPolicy로 클러스터 안의 그 둘만 들이거나, 같은 pod의 sidecar가 loopback으로 읽는다. 기본값(loopback) 그대로면 liveness가 실패한다. - heapdump·threaddump는 노출 목록에서 빠져 있다. 꼭 필요하면 운영 조직의 break-glass 절차를 따른다. 이 저장소에는 그 절차 문서가 없다. ## 에스컬레이션 - 관리 포트가 밖에 열려 있고(위 `curl`이 200) 외부에서 actuator를 두드린 흔적이 있으면 P1. 메인 포트의 `/actuator/…` 시도만 있으면 보통 스캐너다. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.