diff --git a/.claude/skills/be-security/SKILL.md b/.claude/skills/be-security/SKILL.md index 1a2fa06b..9f49deeb 100644 --- a/.claude/skills/be-security/SKILL.md +++ b/.claude/skills/be-security/SKILL.md @@ -95,4 +95,4 @@ Gradle·Docker는 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은 - `docs/jpa/security.md`, `docs/httpclient/security.md`, `docs/fileserver/security.md`, `docs/notification/security-privacy.md` - `.github/dependency-vulnerability-policy.md` — 심각도별 처리와 기한, KEV 대조. - `docs/work/reference/decisions.md` 2.6절(JWT audience·role, `fixture-` 거부, 파일 서버 인가, redirect 헤더, 오류 디스패치)·2.7절(취약 의존성). -- runbook: `docs/runbooks/auth-public-path-misconfiguration.md`, `docs/runbooks/management-actuator-forbidden.md`, `docs/runbooks/authz-cross-tenant-violation.md` +- runbook: `docs/runbooks/auth-decoder-misconfiguration.md`, `docs/runbooks/management-actuator-forbidden.md`, `docs/runbooks/authz-cross-tenant-violation.md` diff --git a/docs/registries/error-codes.yaml b/docs/registries/error-codes.yaml index 1b72892a..d999e811 100644 --- a/docs/registries/error-codes.yaml +++ b/docs/registries/error-codes.yaml @@ -192,7 +192,7 @@ errors: # source: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL" # 지금 이 코드는 JWT decoder를 만들지 못할 때(issuer discovery 4xx·issuer 불일치·jwks_uri 없음) 나온다. 공개 경로 - # 설정 오류는 이 코드를 내지 않는다(runbook auth-public-path-misconfiguration.md). + # 설정 오류는 이 코드를 내지 않는다(runbook auth-decoder-misconfiguration.md). - code: INTERNAL_AUTH_MISCONFIGURATION category: INTERNAL http_status: 500 @@ -201,7 +201,7 @@ errors: owner_branch: feature-security-operational-baseline owner_layer: crosscut client_safe_message: "요청을 처리할 수 없습니다." - runbook_link: "runbook://auth/public-path-misconfiguration" + runbook_link: "runbook://auth/decoder-misconfiguration" compatibility_impact: none required_test: contract-verification:auth-category diff --git a/docs/runbooks/auth-public-path-misconfiguration.md b/docs/runbooks/auth-decoder-misconfiguration.md similarity index 67% rename from docs/runbooks/auth-public-path-misconfiguration.md rename to docs/runbooks/auth-decoder-misconfiguration.md index 92a14795..7c4e9101 100644 --- a/docs/runbooks/auth-public-path-misconfiguration.md +++ b/docs/runbooks/auth-decoder-misconfiguration.md @@ -5,10 +5,10 @@ error_codes: [INTERNAL_AUTH_MISCONFIGURATION] severity: P1 owner: oncall last_updated: 2026-11-13 -status: 초안 +status: 운영 --- -# Runbook: INTERNAL_AUTH_MISCONFIGURATION (`runbook://auth/public-path-misconfiguration`) +# Runbook: INTERNAL_AUTH_MISCONFIGURATION (`runbook://auth/decoder-misconfiguration`) ## 증상 @@ -16,23 +16,23 @@ status: 초안 - ERROR 로그 줄 `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…` (logger `AuthErrorResponseWriter`). - 이 코드는 JWT decoder를 만들 수 없을 때 나온다: issuer metadata가 망가졌거나 네트워크 문제가 아닌 이유로 decoder 초기화가 실패했다(`JwtDecoderConfig` → `SecurityErrorClassifier`). decoder는 첫 token을 검증할 때 만들어지므로 기동은 성공하고, token을 실은 요청마다 이 500이 난다. -- 공개 경로 설정 오류는 이 코드를 내지 않는다. 잘못 연 공개 경로는 오류 없이 열리므로 스냅숏 검사(아래)로만 잡힌다. +- 공개 경로 설정 오류는 이 코드를 내지 않는다. 잘못 연 공개 경로는 오류 없이 열리므로 CI의 `verifyPublicPathSnapshot` + (공개 경로 목록을 스냅숏과 비교하는 검사)으로만 잡힌다. 이 runbook의 대상이 아니다. ## 진단 - 먼저 issuer 설정을 본다. 앱이 도는 곳에서 `/.well-known/openid-configuration`을 받는다. 이 500은 discovery 후보 주소가 모두 4xx(없는 realm, 틀린 경로)이거나, 응답의 `issuer`가 `APP_SECURITY_JWT_ISSUER`와 글자까지 다르거나(끝의 `/` 포함), `jwks_uri`가 없을 때다. - 연결 실패·5xx·JSON이 아닌 응답이면 이 코드가 아니라 503 `AUTH_JWKS_UNAVAILABLE`이다(`docs/runbooks/auth-jwks-unavailable.md`). -- 공개 경로를 의심하면 CI의 `verifyPublicPathSnapshot` 결과와 공개 경로 목록(`config/security.yml`의 `public-paths`, `SECURITY_PUBLIC_PATHS`)의 최근 변경을 본다. ## 조치 - `APP_SECURITY_JWT_ISSUER`를 IdP discovery의 `issuer`와 같게 고쳐 다시 배포한다. 설정은 기동 때 읽는다. -- 잘못된 공개 경로 변경을 되돌린다. 저장소 루트에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다. ## 에스컬레이션 -- P1 즉시: token을 싣는 모든 요청이 500이다. 공개 경로를 잘못 열어 인증을 건너뛸 수 있을 때도 P1이다. +- P1 즉시: token을 싣는 모든 요청이 500이다. --- -> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. +이 runbook은 템플릿의 JWT decoder(`JwtDecoderConfig`)가 내는 신호만 다룬다. 서비스가 decoder를 바꾸면 진단 절을 그 decoder에 +맞춘다. diff --git a/docs/runbooks/auth-issuer-mismatch.md b/docs/runbooks/auth-issuer-mismatch.md index 07e6f169..791ae996 100644 --- a/docs/runbooks/auth-issuer-mismatch.md +++ b/docs/runbooks/auth-issuer-mismatch.md @@ -18,7 +18,7 @@ status: 초안 ## 진단 - 검증기가 비교하는 값은 `app.security.issuer-uri`(env `APP_SECURITY_JWT_ISSUER`)다(`config/security.yml` → `JwtDecoderConfig`). 같은 env가 `spring.security.oauth2.resourceserver.jwt.issuer-uri`도 채우지만 decoder는 그 키를 읽지 않는다. -- 거부된 token의 `iss`를 클라이언트 쪽에서 디코딩해 `APP_SECURITY_JWT_ISSUER`와 견준다. 흔한 원인은 hostname(내부·외부 주소), realm 이름, 끝의 `/` 차이다. IdP discovery의 `issuer`와 설정값이 다르면 이 401이 아니라 decoder를 만들지 못한 500 `INTERNAL_AUTH_MISCONFIGURATION`이다(`docs/runbooks/auth-public-path-misconfiguration.md`). +- 거부된 token의 `iss`를 클라이언트 쪽에서 디코딩해 `APP_SECURITY_JWT_ISSUER`와 견준다. 흔한 원인은 hostname(내부·외부 주소), realm 이름, 끝의 `/` 차이다. IdP discovery의 `issuer`와 설정값이 다르면 이 401이 아니라 decoder를 만들지 못한 500 `INTERNAL_AUTH_MISCONFIGURATION`이다(`docs/runbooks/auth-decoder-misconfiguration.md`). - 토큰, `Authorization` 헤더, JWT payload는 로그에 남지 않고 남겨서도 안 된다. ## 조치 diff --git a/docs/runbooks/internal-error-spike.md b/docs/runbooks/internal-error-spike.md index bab656ea..aa6c98e8 100644 --- a/docs/runbooks/internal-error-spike.md +++ b/docs/runbooks/internal-error-spike.md @@ -39,7 +39,7 @@ status: 초안 - 가능한 원인: - 직전 deploy의 회귀 버그 → rollback - JVM OOM (메모리 leak 또는 부하 증가) → heap dump 분석(`runtime-jvm-oom.md`) - - JWT decoder 설정 오류 (`INTERNAL_AUTH_MISCONFIGURATION`) → issuer 설정과 discovery(`auth-public-path-misconfiguration.md`) + - JWT decoder 설정 오류 (`INTERNAL_AUTH_MISCONFIGURATION`) → issuer 설정과 discovery(`auth-decoder-misconfiguration.md`) - thread starvation (pool 고갈) → thread dump (`jstack `) ## 4. Mitigation diff --git a/docs/upgrade/2026-11-round9-followups.md b/docs/upgrade/2026-11-round9-followups.md index 91e2c517..2350d249 100644 --- a/docs/upgrade/2026-11-round9-followups.md +++ b/docs/upgrade/2026-11-round9-followups.md @@ -1,11 +1,12 @@ # 업그레이드 안내 — 2026-11 GraphQL 관측 tag·안 쓰는 헤더 상수·인증 설정 runbook 이름 -- 범위: 2026-11-12 전체 리뷰를 고친 뒤 남은 후속. GraphQL resolver·DataLoader 지표가 플랫폼 tag를 달고, GraphQL 지표가 요청마다 같은 tag key를 달고, 쓰는 곳 없는 `ApiHeaders` 상수 둘을 지웠다. +- 범위: 2026-11-12 전체 리뷰를 고친 뒤 남은 후속. GraphQL resolver·DataLoader 지표가 플랫폼 tag를 달고, GraphQL 지표가 요청마다 같은 tag key를 달고, 쓰는 곳 없는 `ApiHeaders` 상수 둘을 지웠고, `INTERNAL_AUTH_MISCONFIGURATION`의 runbook 이름을 내용에 맞췄다. - 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 관측·인증 묶음을 고칠 때 범위 밖으로 남긴 후속 ## 1. 누가 읽나 -이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 GraphQL을 켜고 그 지표로 대시보드를 만든 서비스, web `ApiHeaders` 상수를 부르는 서비스다. +이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 GraphQL을 켜고 그 지표로 대시보드를 만든 서비스, +web `ApiHeaders` 상수를 부르는 서비스, 오류 코드의 runbook 링크로 경보를 만든 서비스다. ## 2. 할 일 @@ -16,6 +17,7 @@ | 3 | `graphql.dataloader` timer의 tag가 Spring 기본값(`graphql.loader.name`, `graphql.error.type`, `graphql.outcome`)에서 `graphql.dataloader.name`, `graphql.outcome`, `graphql.batch.size.bucket`(`1`·`2-10`·`11-100`·`100+`)으로 바뀌었다. loader 이름은 등록한 이름이거나 Spring이 `@BatchMapping` loader에 붙이는 schema 좌표(`Book.author`)다. 클래스 이름으로 등록한 loader(`forTypePair`)와 이름 문법 밖의 loader는 `unknown` 하나로 묶인다. `error` tag는 그대로 있다 | `graphql.loader.name`으로 거른 패널·경보를 `graphql.dataloader.name`으로 바꾼다. 클래스 이름 loader를 따로 보려면 이름을 주어 등록한다(`BatchLoaderRegistry`의 `forName(…)`이나 `forTypePair(…).withName(…)`) | 그 패널이 비고, 클래스 이름 loader가 `unknown`에 섞인다 | DataLoader를 쓰는 GraphQL 서비스 | | 4 | `GraphQlResolverObservationConvention`이 내는 무게 tag 이름이 `graphql.operation.type`에서 `graphql.resolver.weight`로, `GraphQlDataLoaderObservationConvention`의 batch 크기 tag가 `graphql.complexity.bucket`에서 `graphql.batch.size.bucket`으로 바뀌었다. 두 convention은 이제 `DataFetcherObservationConvention`·`DataLoaderObservationConvention` bean(adapter)으로 Spring observation에 붙는다 | 두 convention의 `tags(...)`를 직접 불러 옛 key를 읽던 코드를 새 key로 바꾼다. 자기 `DataFetcherObservationConvention`·`DataLoaderObservationConvention` bean을 둔 서비스는 그 bean이 쓰이고 위 2·3번 tag가 붙지 않는다 | 옛 key를 찾는 코드가 빈 값을 본다 | 두 convention을 직접 쓰거나 바꾼 서비스 | | 5 | web `ApiHeaders.DEPRECATION`·`ApiHeaders.DATE` 상수를 지웠다. 운영 코드가 쓰지 않았다 | 그 상수를 부르던 코드는 자기 상수나 Spring `HttpHeaders.DATE`로 바꾼다(마지막으로 있던 커밋은 `docs/capability-status.md` 제거 표) | 컴파일이 실패한다 | 그 상수를 부르던 서비스 | +| 6 | `INTERNAL_AUTH_MISCONFIGURATION`의 `runbook_link`가 `runbook://auth/public-path-misconfiguration`에서 `runbook://auth/decoder-misconfiguration`으로, 파일이 `docs/runbooks/auth-public-path-misconfiguration.md`에서 `docs/runbooks/auth-decoder-misconfiguration.md`로 바뀌었다. 그 runbook은 `status: 운영`이라 `RunbookCoverageContractTest`의 `LEGACY_STUB_DEBT`(초안 runbook 목록)에서 빠졌다 | 옛 링크·파일 이름을 가리키는 경보·대시보드·문서를 새 이름으로 바꾼다. 옛 파일을 자기 쪽에서 고쳐 두었으면 그 내용을 새 파일로 옮기고 옛 파일을 지운다 | 경보의 runbook 링크가 없는 파일을 가리킨다. 옛 파일이 `status: 초안`으로 남으면 목록과 맞지 않아 `RunbookCoverageContractTest`가 실패한다 | 그 runbook을 쓰거나 고친 서비스 | ## 3. 바뀌지 않은 것 diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RunbookCoverageContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RunbookCoverageContractTest.java index 658a602d..a650de92 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RunbookCoverageContractTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RunbookCoverageContractTest.java @@ -82,7 +82,6 @@ class RunbookCoverageContractTest { "auth-issuer-mismatch.md", "auth-jwks-unavailable.md", "auth-kid-unknown.md", - "auth-public-path-misconfiguration.md", "auth-token-expired.md", "auth-token-invalid-signature.md", "auth-token-malformed.md",