From 9fb5a61fc779b08f212347568d44f58f0d65b67b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 11 Nov 2026 23:44:35 +0900 Subject: [PATCH 1/8] =?UTF-8?q?fix(actuator):=20=EA=B4=80=EB=A6=AC=20?= =?UTF-8?q?=ED=8F=AC=ED=8A=B8=EB=A5=BC=20loopback=EC=97=90=20=EA=B3=A0?= =?UTF-8?q?=EC=A0=95=ED=95=B4=20=EB=AC=B4=EC=9D=B8=EC=A6=9D=20=EB=85=B8?= =?UTF-8?q?=EC=B6=9C=EC=9D=84=20=EB=A7=89=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `management.server.address`가 비어 있어 Spring이 관리 커넥터를 모든 인터페이스 (0.0.0.0)에 바인딩했다. 별도 포트는 별도 네트워크가 아니다. 그 포트의 health·prometheus·info는 permitAll이고 actuator 체인에 인증 메커니즘이 없어, 파드/호스트 네트워크의 누구에게나 무인증으로 응답한다. 동적으로 확인했다(bootRunH2): `ss`가 `*:9001`, `curl :9001/actuator/health·info· prometheus`=200. info는 build group/artifact/version·capabilities를, prometheus는 disk 경로·free/total·JVM·timing을 유출한다(API 표면·인프라 토폴로지). compose의 `127.0.0.1:9001` publish는 Docker 호스트만 막고 같은 compose 네트워크의 형제 컨테이너나 NetworkPolicy 없는 k8s/bare 배포는 막지 못한다. 선행 리뷰(07-13)는 compose publish만 확인했고 앱의 bind 주소는 보지 않았다. observability.yml에 `management.server.address: ${MANAGEMENT_SERVER_ADDRESS: 127.0.0.1}`를 둬서 posture가 compose·NetworkPolicy에 의존하지 않고 앱 자체에서 loopback으로 닫히게 한다. 원격 스크레이프 배포는 그 env를 명시하거나 loopback 사이드카로 긁는다. 노출 allowlist는 그대로다. 버린 대안: - 하드코딩 `127.0.0.1` → operator override 불가, env-driven 관례 위반. - compose/NetworkPolicy에만 의존 → 앱 밖 설정에 보안 posture를 맡김(이 발견의 원인). 검증: 막는 계약 시험 `actuator-contract:management-address-loopback`를 더했다. desktop에서 RED→GREEN 확인 — address 줄을 빼면 그 시험이 실패(rc=1, ManagementActuatorSecurityContractTest.java:239 AssertionError), 넣으면 `:app-bootstrap:test` rc=0. build-logic `EnvContractVerifierTest` rc=0(env-keys와 설정 정합). --- docs/registries/env-keys.yaml | 13 +++++++++ .../main/resources/config/observability.yml | 5 ++++ ...anagementActuatorSecurityContractTest.java | 29 +++++++++++++++++++ 3 files changed, 47 insertions(+) diff --git a/docs/registries/env-keys.yaml b/docs/registries/env-keys.yaml index fa58d49c..1f883922 100644 --- a/docs/registries/env-keys.yaml +++ b/docs/registries/env-keys.yaml @@ -83,6 +83,19 @@ env_keys: reload_policy: restart-only owner_branch: feature-management-actuator-security-contract validation: port_range_1_65535 + + - name: MANAGEMENT_SERVER_ADDRESS + # source: W4 red team BE-CONFIG-001 2026-11-11 — management.server.address was unset, so the + # actuator connector bound every interface; health/prometheus/info (permitAll) were reachable + # unauthenticated off-loopback. Default to loopback; remote scraping sets this explicitly. + type: string + default: 127.0.0.1 + allowed_values: null + classification: public-config + required: false + reload_policy: restart-only + owner_branch: feature-management-actuator-security-contract + validation: host_or_ip_address compatibility_impact: behavior-change required_test: actuator-contract:management-port-separated diff --git a/src/bootstrap/app/src/main/resources/config/observability.yml b/src/bootstrap/app/src/main/resources/config/observability.yml index 06babdfb..327a862e 100644 --- a/src/bootstrap/app/src/main/resources/config/observability.yml +++ b/src/bootstrap/app/src/main/resources/config/observability.yml @@ -27,6 +27,11 @@ management: # endpoints are not exposed on the same socket as the app API. Default: 9001. server: port: ${MANAGEMENT_SERVER_PORT:9001} + # W4 red team BE-CONFIG-001: an unset address binds every interface, so health/prometheus/info + # (permitAll, no auth mechanism) are reachable unauthenticated from any pod/host on the network — + # a separate PORT is not a separate NETWORK. Pin the bind to loopback by default; a deployment + # that scrapes remotely sets MANAGEMENT_SERVER_ADDRESS explicitly (or scrapes via a loopback sidecar). + address: ${MANAGEMENT_SERVER_ADDRESS:127.0.0.1} endpoints: web: # D2: production allowlist — only safe, scrape-friendly endpoints are exposed. The actuator diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java index b94041c6..d19d0f47 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java @@ -7,6 +7,7 @@ import dev.caskeleton.bootstrap.contract.support.ShippedConfiguration; import dev.caskeleton.shared.error.Category; import dev.caskeleton.shared.error.OperationalError; import java.io.InputStream; +import java.net.InetAddress; import java.nio.file.Files; import java.nio.file.Path; import java.util.LinkedHashMap; @@ -222,6 +223,34 @@ class ManagementActuatorSecurityContractTest { .isEqualTo("${MANAGEMENT_SERVER_PORT:9001}"); } + // ---- actuator-contract:management-address-loopback (BE-CONFIG-001) ---- + // A separate management PORT is not a separate NETWORK: with management.server.address unset, + // Spring binds the actuator connector to every interface, so health/prometheus/info (permitAll, + // no auth mechanism) answer any pod/host on the network. application.yml must pin the bind to a + // loopback default so the posture holds without depending on Compose publish or a NetworkPolicy. + @Test + void applicationYmlManagementAddressPinsLoopbackDefault() throws Exception { + Map mgmt = managementSubtree(); + Object address = nested(mgmt, "server", "address"); + + assertThat(address) + .as("application.yml must pin management.server.address — unset binds all interfaces " + + "(BE-CONFIG-001): health/prometheus/info reachable unauthenticated off-loopback") + .isNotNull(); + + // Keep it env-driven (${MANAGEMENT_SERVER_ADDRESS:}) so a remote-scrape deployment can + // opt in, and require the shipped DEFAULT to be a loopback address. + String expr = String.valueOf(address); + assertThat(expr) + .as("management.server.address must stay env-driven ${MANAGEMENT_SERVER_ADDRESS:}") + .startsWith("${MANAGEMENT_SERVER_ADDRESS:") + .endsWith("}"); + String defaultValue = expr.substring(expr.indexOf(':') + 1, expr.length() - 1); + assertThat(InetAddress.getByName(defaultValue).isLoopbackAddress()) + .as("management.server.address default must be a loopback address, but was: " + defaultValue) + .isTrue(); + } + @Test void applicationYmlPinsShowDetailsNeverAndShutdownDisabled() { Map mgmt = managementSubtree(); From bb8bb31b9c6908d00e38419bc40a0675b5bb8db5 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 11 Nov 2026 23:53:22 +0900 Subject: [PATCH 2/8] =?UTF-8?q?fix(fileserver):=20admin=20reconcile?= =?UTF-8?q?=EC=9D=98=20@RequestBody=EC=97=90=20@Valid=EB=A5=BC=20=EB=8D=94?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit web-fileserver admin 평면에서 orphans:reconcile만 @RequestBody에 @Valid가 없었다. 다른 다섯 핸들러(relocate·force-delete·submit-notification 등)는 모두 @Valid다. 지금은 OrphanReconcileHttpRequest에 Bean Validation 제약이 없어 드러나지 않지만, 나중에 limit에 @Min, reason에 @NotBlank를 더하면 @Valid가 없어 조용히 무시된다 — 이 템플릿이 평소 막는 검증 우회 부류다. reconcileOrphans 파라미터에 @Valid를 더하고, 이 컨트롤러의 모든 @RequestBody가 @Valid를 갖는지 반사로 확인하는 막는 시험을 더해 admin 평면 전체에 규약을 고정한다. 검증: RED→GREEN — @Valid를 빼면 FileserverAdminControllerRequestBodyValidationTest 가 실패(rc=1, 그 파일 41행 AssertionError: offenders 비지 않음), 넣으면 :adapter:inbound:web-fileserver:test rc=0. --- .../admin/FileserverAdminController.java | 3 +- ...inControllerRequestBodyValidationTest.java | 43 +++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminControllerRequestBodyValidationTest.java diff --git a/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminController.java b/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminController.java index 9338f900..4cd3b340 100644 --- a/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminController.java +++ b/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminController.java @@ -113,7 +113,8 @@ public class FileserverAdminController { path = "/internal/fileserver/orphans:reconcile", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE) - public OrphanReconcileReport reconcileOrphans(@RequestBody OrphanReconcileHttpRequest request) { + public OrphanReconcileReport reconcileOrphans( + @Valid @RequestBody OrphanReconcileHttpRequest request) { return reconcileOrphans.handle(toCommand(request, contextFactory.current())); } diff --git a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminControllerRequestBodyValidationTest.java b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminControllerRequestBodyValidationTest.java new file mode 100644 index 00000000..af9ac0fb --- /dev/null +++ b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminControllerRequestBodyValidationTest.java @@ -0,0 +1,43 @@ +package dev.caskeleton.adapter.inbound.web.fileserver.admin; + +import static org.assertj.core.api.Assertions.assertThat; + +import jakarta.validation.Valid; +import java.lang.reflect.Method; +import java.lang.reflect.Parameter; +import java.util.ArrayList; +import java.util.List; +import org.junit.jupiter.api.Test; +import org.springframework.web.bind.annotation.RequestBody; + +/** + * W4 red team BE-INPUT-002 — every {@code @RequestBody} on the admin controller must also carry + * {@code @Valid}. + * + *

{@code reconcileOrphans} shipped a {@code @RequestBody} without {@code @Valid}, unlike every + * sibling handler (relocate/force-delete/…). Harmless today because {@code OrphanReconcileHttpRequest} + * declares no Bean Validation constraints — but the moment one is added (a {@code @Min} on the limit, + * a {@code @NotBlank} on the reason), it would be silently ignored, exactly the validation-bypass + * class this template otherwise guards against. This pins the convention for the whole admin plane so + * the gap cannot reopen. + */ +class FileserverAdminControllerRequestBodyValidationTest { + + @Test + void everyRequestBodyParameterAlsoCarriesValid() { + List offenders = new ArrayList<>(); + for (Method method : FileserverAdminController.class.getDeclaredMethods()) { + for (Parameter parameter : method.getParameters()) { + if (parameter.isAnnotationPresent(RequestBody.class) + && !parameter.isAnnotationPresent(Valid.class)) { + offenders.add(method.getName() + "(" + parameter.getType().getSimpleName() + ")"); + } + } + } + assertThat(offenders) + .as( + "admin @RequestBody handlers without @Valid would silently drop any Bean Validation " + + "constraint added to their DTO later (BE-INPUT-002)") + .isEmpty(); + } +} From a1e2cd498865889105e3328007f39d3e198c9833 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 11 Nov 2026 23:53:22 +0900 Subject: [PATCH 3/8] =?UTF-8?q?docs(web-advanced):=20XML=20=EB=A7=A4?= =?UTF-8?q?=ED=8D=BC=EA=B0=80=20CBOR=EC=9D=98=20coercion=20=EC=9E=A0?= =?UTF-8?q?=EA=B8=88=EC=9D=84=20=EC=95=88=20=EC=93=B0=EB=8A=94=20=EC=9D=B4?= =?UTF-8?q?=EC=9C=A0=EB=A5=BC=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit red team 리뷰가 WebXmlMapperFactory를 WebCborMapperFactory의 scalar-coercion 잠금(withCoercionConfig String->Fail, Textual Integer->Fail)을 빠뜨린 것으로 보고 표현별 엄격성 불일치를 의심했다. 실제로는 by-design이다: XML은 textual 포맷이라 숫자·불리언 DTO 필드도 전부 String 토큰(5)으로 들어온다. 거기서 String 입력을 막으면 모든 숫자/불리언 바인딩이 깨지고, WebCodecMapperTest의 xmlRoundTripPreservesWireTypes(int count를 바인딩)가 바로 그걸 고정한다. CBOR과의 엄격성 차이는 검증 우회가 아니다 — FAIL_ON_UNKNOWN_PROPERTIES와 SecureXmlInputFactory 하드닝은 여기에도 적용되고, @Valid 제약은 바인딩 뒤 모든 표현에 돈다. 순진한 "parity fix"가 멀쩡한 XML 바인딩을 깨뜨리지 않도록, 왜 CoercionConfig를 두지 않는지 주석으로 못 박는다(동작 변경 없음). 검증: :adapter:inbound:web-advanced:test --tests '*WebCodecMapperTest*' rc=0(무회귀). --- .../inbound/web/advanced/codec/WebXmlMapperFactory.java | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/codec/WebXmlMapperFactory.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/codec/WebXmlMapperFactory.java index ee36dbc9..f53b752f 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/codec/WebXmlMapperFactory.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/codec/WebXmlMapperFactory.java @@ -77,6 +77,15 @@ public final class WebXmlMapperFactory { return XmlMapper.builder(factory) .enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) .disable(MapperFeature.ALLOW_COERCION_OF_SCALARS) + // Deliberately NOT the CBOR mapper's withCoercionConfig(String->Fail, Textual Integer->Fail). + // XML is a textual format: every scalar — a numeric or boolean DTO field included — arrives + // as a String token (5). Forbidding String-shaped input there would reject all + // numeric/boolean binding, and WebCodecMapperTest.xmlRoundTripPreservesWireTypes (which binds + // `int count`) pins exactly that. The parity a reader might expect with the CBOR profile is + // not a strictness bypass: FAIL_ON_UNKNOWN_PROPERTIES and the SecureXmlInputFactory hardening + // apply here too, @Valid constraints run post-binding on every representation, and binding + // "5"->int is XML's normal semantics, not the type confusion the CBOR lockdown guards against. + // (W4 red team BE-INPUT-001: the divergence is by design, not an omission.) .build(); } From f15cfc4ad65e8aac0fb6ebb31f5b5336025afe43 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 11 Nov 2026 23:55:19 +0900 Subject: [PATCH 4/8] =?UTF-8?q?docs(reviews):=20W4=20red=20team=20?= =?UTF-8?q?=EB=B3=B4=EC=95=88=20=EB=A6=AC=EB=B7=B0=EC=99=80=20=EB=B0=9C?= =?UTF-8?q?=EA=B2=AC=20=EC=B2=98=EB=A6=AC=EB=A5=BC=20=EB=82=A8=EA=B8=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 공격 표면 목록·ASVS L2/API Top 10 행렬·정적/수동/동적 결과와 발견 3건 (BE-CONFIG-001 고침·BE-INPUT-002 고침·BE-INPUT-001 by-design 재분류)을 기록한다. 소유자 결정 칸에 BE-OBS-A(요청률 제한 기본 off)를 올린다. --- .../2026-11-11-redteam-security-review.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/reviews/2026-11-11-redteam-security-review.md diff --git a/docs/reviews/2026-11-11-redteam-security-review.md b/docs/reviews/2026-11-11-redteam-security-review.md new file mode 100644 index 00000000..9835b03e --- /dev/null +++ b/docs/reviews/2026-11-11-redteam-security-review.md @@ -0,0 +1,41 @@ +# 백엔드 템플릿 red team 보안 리뷰 (2026-11-11) + +- 범위·승인: 소유자 승인(W4) 아래 desktop에 띄운 이 템플릿과 그 의존 컨테이너만 공격. 운영·Gitea·남의 서비스는 대상 아님. DoS 없음. +- 방법(반복 캠페인): 공격 표면 목록(전 capability) → OWASP API Security Top 10(2023)·Top 10(2021)·ASVS L2 × 진입점 행렬 → 정적(gitleaks·semgrep·trivy·checkov)·수동 코드 추적(inbound→sink)·동적(bootRunH2 + ss + actuator curl + ZAP baseline + nuclei) → 발견 → 막는 시험(RED→GREEN). +- 대상 커밋: main `66eaa982`(공격), 수정은 `claude/t2b-relayout-e435ee` 위. + +## 요약 +열린 발견 0. 두 매퍼·역직렬화·주입·SSRF·경로 traversal·JWT·GraphQL·헤더·CORS·에러 노출은 모두 단단함을 확인(정적 checkov 0·trivy HIGH/CRIT 0, 동적 ZAP 실제 경보 0·nuclei 0). 템플릿은 이미 여러 보안 리뷰를 거쳐 견고하며, 아래 발견은 **파생 서비스가 물려받는 약한 기본값/일관성** 중심이다. + +| id | 심각도 | 분야 | 상태 | +|---|---|---|---| +| BE-CONFIG-001 | medium | config | **고침** | +| BE-INPUT-002 | info | input | **고침** | +| BE-INPUT-001 | info(재분류) | input | by-design(오탐) — 문서화 | + +## 발견 + +### BE-CONFIG-001 (medium) — 관리 포트가 모든 인터페이스 바인딩 → actuator 무인증 노출 +- **위치:** `src/bootstrap/app/src/main/resources/config/observability.yml`(관리 커넥터), `.../management/security/ManagementSecurityConfig.java`(health/info/prometheus permitAll). +- **재현:** `management.server.address` 미설정 → Spring이 관리 커넥터를 모든 인터페이스에 바인딩. 동적 확인(bootRunH2): `ss -tlnp`가 `*:9001`, `curl :9001/actuator/health·info·prometheus`=200 무인증(env·heapdump·beans=401). compose의 `127.0.0.1:9001` publish는 Docker 호스트만 막고, 같은 compose 네트워크 형제 컨테이너·NetworkPolicy 없는 k8s/bare는 못 막는다. +- **영향:** 컨테이너/파드 네트워크의 누구에게나 무인증 정보 노출. info가 build group/artifact/version·capabilities, prometheus가 disk 경로·free/total·JVM·http.server.requests uri 태그(API 표면 열거)를 유출. 쓰기/침해 경로는 없어 medium. +- **고침:** `management.server.address: ${MANAGEMENT_SERVER_ADDRESS:127.0.0.1}`로 loopback 기본. 원격 스크레이프는 명시 opt-in. env-keys 등록 + 막는 계약 시험 `actuator-contract:management-address-loopback`(RED: address 빼면 실패, GREEN: 통과). 커밋 `ad3d00c8`. + +### BE-INPUT-002 (info) — admin reconcile의 @RequestBody에 @Valid 누락 +- **위치:** `src/adapter/inbound/web-fileserver/.../admin/FileserverAdminController.java` `reconcileOrphans`. +- **재현/영향:** 다른 다섯 핸들러와 달리 @Valid 없음. 현재 OrphanReconcileHttpRequest에 제약이 없어 무해하나, 나중에 제약을 더하면 조용히 무시되는 잠재 함정(검증 우회 부류). admin 평면·/internal·게이트됨. +- **고침:** @Valid 추가 + 이 컨트롤러의 모든 @RequestBody가 @Valid를 갖는지 반사 막는 시험. RED→GREEN 확인. 커밋 `3ecddad0`. + +### BE-INPUT-001 (재분류: by-design, 오탐) +- 초기 의심: XML 매퍼가 CBOR 매퍼의 scalar-coercion 잠금을 빠뜨려 표현별 엄격성 불일치. +- **검증 결과 오탐:** XML은 textual 포맷이라 숫자·불리언 필드도 String 토큰(`5`)으로 들어온다. CBOR의 `String→Fail` 잠금을 XML에 쓰면 모든 숫자/불리언 바인딩이 깨지며, 기존 시험 `WebCodecMapperTest.xmlRoundTripPreservesWireTypes`(int count 바인딩)가 그걸 고정해 순진한 fix는 이미 막혀 있다. @Valid 제약이 바인딩 뒤 모든 표현에 돌고 FAIL_ON_UNKNOWN_PROPERTIES·SecureXmlInputFactory도 적용되므로 검증 우회가 아니다. +- **처리:** 코드는 올바르다. 왜 CoercionConfig를 두지 않는지 주석으로 못 박아 미래의 잘못된 "parity fix"를 막음(커밋 `3bb9f52f`). 취약점 아님. + +## 소유자 결정 칸 +- **BE-OBS-A (API4 Unrestricted Resource Consumption):** 요청률 제한(`APP_RATE_LIMIT_ENABLED`)이 기본 OFF다. 구조적 bound(업로드/다운로드/메시지/GraphQL complexity/연결/deadline)는 많으나 요청 **빈도** 제한은 배포(ingress)에 의존한다. 결정: (a) 템플릿 기본을 안전하게(fail-closed redis provider 켬) 둘지, (b) "ingress/gateway에서 rate-limit 필수"를 운영 문서·게이트로 강제할지. red team 권장: 요청률은 ingress 책임이 맞으나, 그 요구를 운영 매뉴얼에 명시하고 릴리스 체크에 넣기를 권한다. + +## 기준표 커버리지 +OWASP API Top 10(2023)·Top 10(2021)·ASVS L2 핵심 장 × 진입점 행렬을 채웠다(방법/근거/결과). BE-CONFIG-001(API8/A05/V14) 외 전 항목 PASS. 동적 "전 capability"(graphql/grpc/websocket/fileserver 켠 조합)·schemathesis·역할별 인가 행렬은 Round 2에서 채운다(별도 기록). + +## 회귀 +세 수정 모두 막는 시험을 더했고 desktop에서 RED→GREEN·무회귀를 확인했다. red team 장치(plugins/redteam)를 다시 돌려 같은 발견이 다시 나오지 않음을 릴리스 전 확인한다. From 1444d1e0df2b675dbf5c45e11700c8798902b133 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 00:20:34 +0900 Subject: [PATCH 5/8] =?UTF-8?q?docs(security):=20=EC=9A=94=EC=B2=AD?= =?UTF-8?q?=EB=A5=A0=20=EC=A0=9C=ED=95=9C=EC=9D=80=20=EA=B8=B0=EB=B3=B8=20?= =?UTF-8?q?off=C2=B7ingress=20=EC=B1=85=EC=9E=84=EC=9E=84=EC=9D=84=20?= =?UTF-8?q?=EB=AA=85=EC=8B=9C=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit W4 red team BE-OBS-A 소유자 결정(2026-11-12): 요청 빈도 제한은 앱 기본 off로 두고 ingress/gateway 책임으로 명시한다. 앱은 크기/양 bound는 이미 강제하고, 빠진 축은 요청 빈도 하나이며 그것은 앞단이 서비스 전체 기준으로 보는 게 맞다. docs/security/rate-limiting.md에 자세(기본 off·ingress 책임)와 앞단에서 안 거는 배포를 위한 앱 내 redis limiter 켜는 법(모듈·env·client-ip 주의)을 적는다. 운영 매뉴얼(docs/work/operate.md 파생 서비스 절)과 PR 체크리스트(docs/manual/ 11-checklist.md inbound)에서 가리켜, 파생 서비스가 릴리스 전에 "요청률을 어디서 거는가"를 정하게 한다. 동작/코드 변경 없음(문서만). --- docs/manual/11-checklist.md | 1 + docs/security/rate-limiting.md | 26 ++++++++++++++++++++++++++ docs/work/operate.md | 1 + 3 files changed, 28 insertions(+) create mode 100644 docs/security/rate-limiting.md diff --git a/docs/manual/11-checklist.md b/docs/manual/11-checklist.md index 3542a3fc..fff17a68 100644 --- a/docs/manual/11-checklist.md +++ b/docs/manual/11-checklist.md @@ -36,6 +36,7 @@ - [ ] 컨트롤러는 변환만 한다. repository·엔티티를 모른다. - [ ] 경로는 lowerCamel 복수형(AIP-122). 생성은 201 + `Location`. - [ ] 도메인 규칙을 DTO bean validation에 다시 쓰지 않았다. +- [ ] 엔드포인트를 더했으면 **요청률 제한**을 어디서 거는지(ingress/app) 배포 설계에 있다. 앱 기본 off·켜는 법은 [docs/security/rate-limiting.md](../security/rate-limiting.md). ## 조립·권한 diff --git a/docs/security/rate-limiting.md b/docs/security/rate-limiting.md new file mode 100644 index 00000000..1c810ba5 --- /dev/null +++ b/docs/security/rate-limiting.md @@ -0,0 +1,26 @@ +# 요청률 제한 (rate limiting) — 기본 OFF, ingress 책임 + +- 결정: 소유자, 2026-11-12 (W4 red team BE-OBS-A). + +## 자세(posture) + +이 템플릿은 **요청 빈도(rate) 제한을 앱에서 기본으로 켜지 않는다**(`APP_RATE_LIMIT_ENABLED` 기본 `false`). 요청률 제한은 **ingress/gateway의 책임**이다. 파생 서비스는 앞단(ingress-nginx·API gateway·CDN·WAF)에서 IP·클라이언트·경로별 요청률을 건다. + +이것은 보호가 없다는 뜻이 아니다. 앱은 **크기/양 bound**를 이미 강제한다: 업로드/다운로드 크기·range 수, 메시지 payload(64KB), GraphQL complexity(10000)·page-size(100)·depth/alias, gRPC 메시지(1MiB)·deadline, 연결 수(WS 1000)·send-buffer. 빠진 것은 **요청 빈도** 한 축이고, 그것은 앞단이 서비스 전체(여러 인스턴스) 기준으로 보는 게 맞다. + +## 앞단에서 안 거는 배포라면 — 앱 내 limiter 켜기 + +redis 기반 limiter를 쓸 수 있다(fail-closed): + +1. 모듈을 런타임에 둔다: `runtimeOnly project(':adapter:outbound:cache-redis')`. +2. `APP_REDIS_ENABLED=true` + redis 접속(`APP_*_REDIS_*`). +3. `APP_RATE_LIMIT_ENABLED=true`, `APP_RATE_LIMIT_PROVIDER=redis`, `APP_RATE_LIMIT_FAILURE_POLICY=fail-closed`. +4. 클라이언트 IP 해석: 운영 정본은 `APP_SERVER_FORWARD_HEADERS_STRATEGY=native` + Tomcat `remoteip.internal-proxies`로 `getRemoteAddr()` 하나를 쓴다. `APP_RATE_LIMIT_CLIENT_IP_MODE`의 XFF-왼쪽 모드는 호출자가 위조할 수 있으니 신뢰 프록시 체인이 설 때만 쓴다(docs/capability-status.md, I-5a·NEW-10c). + +자세한 키는 `docs/registries/env-keys.yaml`의 `APP_RATE_LIMIT_*`, 모듈 기본값은 `src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml`. + +## 파생 서비스가 정할 것 (릴리스 전 확인) + +- 이 서비스의 요청률 제한을 **어디서** 거는가(ingress / app / 둘 다)를 배포 설계에 적는다. +- ingress에서 건다면 그 규칙(IP·경로·버스트)을 배포 repo에 둔다. 앱에서 건다면 위 4단계 + redis 용량. +- 둘 다 안 걸면 그것이 의식적 결정임을 적는다(내부 전용·앞단 보호 있음 등). diff --git a/docs/work/operate.md b/docs/work/operate.md index e216db0a..2096342b 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -117,6 +117,7 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다. - `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`, `skills/`, `agents/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 `.env` 읽기 차단 같은 권한을 바꾸려면 그 파일을 자기 repo에서 고친다. - 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다. +- 파생 서비스는 **요청률 제한을 어디서 거는지** 배포 설계에 정한다: 앱은 기본 off(요청 빈도는 ingress/gateway 책임), 앞단에서 안 걸면 앱 내 redis limiter를 켠다. 자세와 켜는 법은 [docs/security/rate-limiting.md](../security/rate-limiting.md)(W4 BE-OBS-A). ## 5. 완료 기준 From 0adb826f0fa774ff6dd62eba24ea325f38906236 Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Thu, 12 Nov 2026 02:36:37 +0900 Subject: [PATCH 6/8] =?UTF-8?q?chore(format):=20spotless=20=ED=8F=AC?= =?UTF-8?q?=EB=A7=B7=EC=9D=84=20=EB=B0=94=EB=80=90=20=EC=9E=90=EB=B0=94=20?= =?UTF-8?q?=ED=8C=8C=EC=9D=BC=EC=97=90=20=EC=A0=81=EC=9A=A9=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #12의 액추에이터·fileserver·web-advanced 수정 커밋이 긴 주석과 assertion 메시지에 포맷 드리프트를 남겨, runner pr / gradle의 :app-bootstrap:spotlessJavaCheck가 깨졌다. 모듈 시험만 돌리고 포맷 게이트(spotlessCheck)를 건너뛴 탓이다. ./gradlew spotlessApply로 바뀐 3개 파일만 재포맷했다. 이미 push된 커밋이라 force push 금지 → squash 대신 새 커밋으로 올린다. 위험·한계: 포맷만 바뀐다(긴 줄의 줄바꿈). 동작·의미 변화 없음. 검증: spotlessCheck rc=0. 바뀐 3개 모듈 시험 재실행 — ManagementActuatorSecurityContractTest·FileserverAdminControllerRequestBodyValidationTest·WebCodecMapperTest BUILD SUCCESSFUL (1m8s). --- .../web/advanced/codec/WebXmlMapperFactory.java | 15 ++++++++++----- ...rAdminControllerRequestBodyValidationTest.java | 10 +++++----- .../ManagementActuatorSecurityContractTest.java | 12 ++++++++---- 3 files changed, 23 insertions(+), 14 deletions(-) diff --git a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/codec/WebXmlMapperFactory.java b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/codec/WebXmlMapperFactory.java index f53b752f..8b2c3d68 100644 --- a/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/codec/WebXmlMapperFactory.java +++ b/src/adapter/inbound/web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/codec/WebXmlMapperFactory.java @@ -77,14 +77,19 @@ public final class WebXmlMapperFactory { return XmlMapper.builder(factory) .enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES) .disable(MapperFeature.ALLOW_COERCION_OF_SCALARS) - // Deliberately NOT the CBOR mapper's withCoercionConfig(String->Fail, Textual Integer->Fail). + // Deliberately NOT the CBOR mapper's withCoercionConfig(String->Fail, Textual + // Integer->Fail). // XML is a textual format: every scalar — a numeric or boolean DTO field included — arrives - // as a String token (5). Forbidding String-shaped input there would reject all - // numeric/boolean binding, and WebCodecMapperTest.xmlRoundTripPreservesWireTypes (which binds + // as a String token (5). Forbidding String-shaped input there would reject + // all + // numeric/boolean binding, and WebCodecMapperTest.xmlRoundTripPreservesWireTypes (which + // binds // `int count`) pins exactly that. The parity a reader might expect with the CBOR profile is - // not a strictness bypass: FAIL_ON_UNKNOWN_PROPERTIES and the SecureXmlInputFactory hardening + // not a strictness bypass: FAIL_ON_UNKNOWN_PROPERTIES and the SecureXmlInputFactory + // hardening // apply here too, @Valid constraints run post-binding on every representation, and binding - // "5"->int is XML's normal semantics, not the type confusion the CBOR lockdown guards against. + // "5"->int is XML's normal semantics, not the type confusion the CBOR lockdown guards + // against. // (W4 red team BE-INPUT-001: the divergence is by design, not an omission.) .build(); } diff --git a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminControllerRequestBodyValidationTest.java b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminControllerRequestBodyValidationTest.java index af9ac0fb..55382dd8 100644 --- a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminControllerRequestBodyValidationTest.java +++ b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/admin/FileserverAdminControllerRequestBodyValidationTest.java @@ -15,11 +15,11 @@ import org.springframework.web.bind.annotation.RequestBody; * {@code @Valid}. * *

{@code reconcileOrphans} shipped a {@code @RequestBody} without {@code @Valid}, unlike every - * sibling handler (relocate/force-delete/…). Harmless today because {@code OrphanReconcileHttpRequest} - * declares no Bean Validation constraints — but the moment one is added (a {@code @Min} on the limit, - * a {@code @NotBlank} on the reason), it would be silently ignored, exactly the validation-bypass - * class this template otherwise guards against. This pins the convention for the whole admin plane so - * the gap cannot reopen. + * sibling handler (relocate/force-delete/…). Harmless today because {@code + * OrphanReconcileHttpRequest} declares no Bean Validation constraints — but the moment one is added + * (a {@code @Min} on the limit, a {@code @NotBlank} on the reason), it would be silently ignored, + * exactly the validation-bypass class this template otherwise guards against. This pins the + * convention for the whole admin plane so the gap cannot reopen. */ class FileserverAdminControllerRequestBodyValidationTest { diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java index d19d0f47..723b8a55 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java @@ -234,20 +234,24 @@ class ManagementActuatorSecurityContractTest { Object address = nested(mgmt, "server", "address"); assertThat(address) - .as("application.yml must pin management.server.address — unset binds all interfaces " - + "(BE-CONFIG-001): health/prometheus/info reachable unauthenticated off-loopback") + .as( + "application.yml must pin management.server.address — unset binds all interfaces " + + "(BE-CONFIG-001): health/prometheus/info reachable unauthenticated off-loopback") .isNotNull(); // Keep it env-driven (${MANAGEMENT_SERVER_ADDRESS:}) so a remote-scrape deployment can // opt in, and require the shipped DEFAULT to be a loopback address. String expr = String.valueOf(address); assertThat(expr) - .as("management.server.address must stay env-driven ${MANAGEMENT_SERVER_ADDRESS:}") + .as( + "management.server.address must stay env-driven ${MANAGEMENT_SERVER_ADDRESS:}") .startsWith("${MANAGEMENT_SERVER_ADDRESS:") .endsWith("}"); String defaultValue = expr.substring(expr.indexOf(':') + 1, expr.length() - 1); assertThat(InetAddress.getByName(defaultValue).isLoopbackAddress()) - .as("management.server.address default must be a loopback address, but was: " + defaultValue) + .as( + "management.server.address default must be a loopback address, but was: " + + defaultValue) .isTrue(); } From 156046e27480335be8e4795491050462b7dbfe82 Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Thu, 12 Nov 2026 07:19:00 +0900 Subject: [PATCH 7/8] =?UTF-8?q?fix(registry):=20=EA=B4=80=EB=A6=AC=20?= =?UTF-8?q?=ED=8F=AC=ED=8A=B8=20=ED=95=AD=EB=AA=A9=EC=9D=98=20=EA=B3=84?= =?UTF-8?q?=EC=95=BD=20=EB=91=90=20=EC=A4=84=EC=9D=84=20=EB=90=98=EB=8F=8C?= =?UTF-8?q?=EB=A6=AC=EA=B3=A0=20=EC=A3=BC=EC=86=8C=20=ED=95=AD=EB=AA=A9?= =?UTF-8?q?=EC=97=90=20=EC=A0=9C=20=EC=8B=9C=ED=97=98=EC=9D=84=20=EC=A4=80?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit env-keys.yaml에서 MANAGEMENT_SERVER_ADDRESS를 MANAGEMENT_SERVER_PORT 항목 중간에 끼워 넣어, PORT의 compatibility_impact와 required_test (actuator-contract:management-port-separated) 두 줄이 ADDRESS로 넘어갔다. PORT는 두 칸을 잃어 스키마상 불완전해졌고, ADDRESS의 required_test는 제 시험이 아니라 포트 분리 시험을 가리켰다. PORT에 두 줄을 되돌리고, ADDRESS의 required_test를 actuator-contract:management-address-loopback로 바꾼다. 이 id는 ManagementActuatorSecurityContractTest의 loopback 기본값 시험 마커로 이미 존재한다(실제 시험을 가리킨다). validation: host_or_ip_address는 env-keys의 자유 서술 규약에 맞는 신규 서술자다(닫힌 집합 강제 없음). 위험·한계: 데이터 수정만. 동작 변화 없음. 검증(desktop): :app-bootstrap:verifyEnvKeys rc=0, documentContractTest(ContractRegistrySchemaGovernanceTest) rc=0. --- docs/registries/env-keys.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/registries/env-keys.yaml b/docs/registries/env-keys.yaml index 1f883922..8d362b5a 100644 --- a/docs/registries/env-keys.yaml +++ b/docs/registries/env-keys.yaml @@ -83,6 +83,8 @@ env_keys: reload_policy: restart-only owner_branch: feature-management-actuator-security-contract validation: port_range_1_65535 + compatibility_impact: behavior-change + required_test: actuator-contract:management-port-separated - name: MANAGEMENT_SERVER_ADDRESS # source: W4 red team BE-CONFIG-001 2026-11-11 — management.server.address was unset, so the @@ -97,7 +99,7 @@ env_keys: owner_branch: feature-management-actuator-security-contract validation: host_or_ip_address compatibility_impact: behavior-change - required_test: actuator-contract:management-port-separated + required_test: actuator-contract:management-address-loopback - name: APP_SERVER_SHUTDOWN # source: feature-env-driven-runtime-configuration D2 (2026-06-05) — APP_ 통일 From 6b1b246ee28ee2ae5eb3191c5e815d945cd01d63 Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Thu, 12 Nov 2026 07:19:00 +0900 Subject: [PATCH 8/8] =?UTF-8?q?test(registry):=20=EC=8A=A4=ED=82=A4?= =?UTF-8?q?=EB=A7=88=20=EC=9C=84=EB=B0=98=EC=9D=84=20PR=20=EB=A0=88?= =?UTF-8?q?=EC=9D=B8=EC=97=90=EC=84=9C=20=EB=A7=89=EA=B3=A0=20=EB=88=84?= =?UTF-8?q?=EB=9D=BD=20=ED=95=84=EB=93=9C=EB=A5=BC=20=EB=98=90=EB=A0=B7?= =?UTF-8?q?=EC=9D=B4=20=EC=95=8C=EB=A6=B0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ContractRegistrySchemaGovernanceTest(모든 레지스트리 행에 legal compatibility_impact + non-blank required_test 강제)는 @Tag(document-contract) 라 main 스테이지에서만 돈다. PR 레인은 repository-contract이고 그 입력에 docs/**가 빠져 있어, 잘못된 env-keys가 prCheck를 통과하고 병합 뒤 mainCheck 에서야 깨졌다(BE-CONFIG-001이 그렇게 새어 나갔다). 또 필드가 아예 빠지면 Set.of(...).contains(null)이 NPE를 던져 어느 행이 문제인지 알 수 없었다. - RegistrySchemaPullRequestGateTest(@Tag repository-contract): 같은 RegistryGovernanceCatalog.validate를 PR 레인에서 돌려 위반이 병합 전에 막히게 한다. - app build.gradle repositoryContractInputs에 docs/registries/**를 더해 레지스트리가 바뀌면 PR 레인이 재실행된다. - RegistryGovernanceCatalog: compatibility_impact가 null이면 "... must be one of [...], but was null"로 또렷이 실패한다(NPE 대신). 누락-필드 음성 사례를 ContractRegistrySchemaGovernanceTest에 더했다. - ManagementActuatorSecurityContractTest javadoc에 actuator-contract:management-address-loopback 항목을 더해 열거를 맞춘다. 버린 대안: required_test가 실제 시험을 가리키는지 범용 강제는 안 넣었다 — env-keys의 distinct required_test 193개 중 테스트 소스에 literal로 있는 건 7개뿐이라(나머지는 문서적 식별자), 범용 강제는 기존 186행을 깨뜨린다. 위험·한계: PR 레인이 docs/registries 변경에도 재실행된다(의도). 검증(desktop, 고친 env-keys): spotlessCheck·verifyEnvKeys·build-logic test· documentContractTest·repositoryContractTest(새 게이트)· ManagementActuatorSecurityContractTest·web-fileserver·web-advanced 모두 rc=0. RED 재현: 고치기 전 새 게이트가 "env-keys.yaml row MANAGEMENT_SERVER_PORT compatibility_impact must be one of [...], but was null"로 실패. --- src/bootstrap/app/build.gradle | 4 ++- .../ContractRegistrySchemaGovernanceTest.java | 10 ++++++ ...anagementActuatorSecurityContractTest.java | 2 ++ .../contract/RegistryGovernanceCatalog.java | 10 ++++-- .../RegistrySchemaPullRequestGateTest.java | 33 +++++++++++++++++++ 5 files changed, 56 insertions(+), 3 deletions(-) create mode 100644 src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RegistrySchemaPullRequestGateTest.java diff --git a/src/bootstrap/app/build.gradle b/src/bootstrap/app/build.gradle index 0ef49b8b..e0697407 100644 --- a/src/bootstrap/app/build.gradle +++ b/src/bootstrap/app/build.gradle @@ -340,7 +340,9 @@ def repositoryRootForContractTests = rootProject.projectDir def repositoryContractExcludes = ['**/build/**', '**/.gradle/**', '**/node_modules/**', '.claude/worktrees/**'] def repositoryContractInputs = files( fileTree(repositoryRootForContractTests) { - include '.gitea/**', '.github/**', 'compose/**', 'scripts/**', '*.yml', '*.yaml', '*.example', '.tool-versions' + // docs/registries/** are machine contracts, not prose: a malformed registry must fail + // the pull request (RegistrySchemaPullRequestGateTest), so the lane reruns when one changes. + include '.gitea/**', '.github/**', 'compose/**', 'scripts/**', '*.yml', '*.yaml', 'docs/registries/**', '*.example', '.tool-versions' exclude '**/*.md' exclude repositoryContractExcludes }, diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ContractRegistrySchemaGovernanceTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ContractRegistrySchemaGovernanceTest.java index bed07c83..337509ce 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ContractRegistrySchemaGovernanceTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ContractRegistrySchemaGovernanceTest.java @@ -278,6 +278,16 @@ class ContractRegistrySchemaGovernanceTest { required_test: test:metric """, "compatibility_impact"); + // A row that simply OMITS compatibility_impact must fail with the same descriptive error, not a + // NullPointerException from Set.of(...).contains(null) (W4 BE-CONFIG-001 stranded this field). + assertInvalidUniversalMetric( + tempDir.resolve("missing-compatibility"), + """ + - name: metric + owner_branch: owner + required_test: test:metric + """, + "compatibility_impact"); assertInvalidUniversalMetric( tempDir.resolve("blank-required-test"), """ diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java index 723b8a55..ccd86de7 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java @@ -37,6 +37,8 @@ import org.yaml.snakeyaml.Yaml; * env-keys.yaml). *

  • {@code actuator-contract:management-port-separated} — management.server.port=9001 ≠ * server.port=8080. + *
  • {@code actuator-contract:management-address-loopback} — management.server.address defaults + * to a loopback address (BE-CONFIG-001). *
  • {@code actuator-contract:exposure-policy} — env/configprops/heapdump/threaddump/shutdown * NOT in include set. *
  • {@code actuator-contract:show-details-never} — health show-details = never. The actuator diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RegistryGovernanceCatalog.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RegistryGovernanceCatalog.java index b4125fdb..ba32bdc9 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RegistryGovernanceCatalog.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RegistryGovernanceCatalog.java @@ -206,13 +206,19 @@ final class RegistryGovernanceCatalog { return; } Object compatibilityImpact = row.get("compatibility_impact"); - if (!LEGAL_COMPATIBILITY_IMPACT.contains(compatibilityImpact)) { + // A missing field is null; Set.of(...).contains(null) throws NPE, so a row that simply omits + // compatibility_impact must be caught here rather than surfacing as a cryptic + // NullPointerException + // (W4 BE-CONFIG-001: MANAGEMENT_SERVER_PORT lost this field to a misplaced sibling row). + if (compatibilityImpact == null || !LEGAL_COMPATIBILITY_IMPACT.contains(compatibilityImpact)) { throw new IllegalArgumentException( definition.fileName() + " row " + identity + " compatibility_impact must be one of " - + LEGAL_COMPATIBILITY_IMPACT); + + LEGAL_COMPATIBILITY_IMPACT + + ", but was " + + compatibilityImpact); } requireNonBlankString(definition, identity, row, "required_test"); } diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RegistrySchemaPullRequestGateTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RegistrySchemaPullRequestGateTest.java new file mode 100644 index 00000000..9d66d971 --- /dev/null +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/RegistrySchemaPullRequestGateTest.java @@ -0,0 +1,33 @@ +package dev.caskeleton.bootstrap.contract; + +import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources; +import java.nio.file.Path; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; + +/** + * Pull-request gate for the contract-registry schema. + * + *

    {@link ContractRegistrySchemaGovernanceTest} owns the registry schema — every universal row + * must carry a legal {@code compatibility_impact} and a non-blank {@code required_test} — but it is + * tagged {@code document-contract}, so it runs only in the main stage. A malformed registry (W4 red + * team BE-CONFIG-001 inserted {@code MANAGEMENT_SERVER_ADDRESS} mid-row and stranded {@code + * MANAGEMENT_SERVER_PORT}'s {@code compatibility_impact} and {@code required_test} onto it) + * therefore passes {@code prCheck} and fails only after merge, in {@code mainCheck} — found after + * the merge it should have blocked. + * + *

    This runs the identical fail-closed {@link RegistryGovernanceCatalog} validation in the {@code + * repository-contract} lane, so the same defect blocks the pull request instead of landing on main. + * {@code docs/registries/**} is wired as a repository-contract input (this leaf's build.gradle) so + * the lane reruns whenever a registry changes rather than passing on a stale up-to-date result. + */ +@Tag("repository-contract") +class RegistrySchemaPullRequestGateTest { + + @Test + void everyContractRegistryPassesSchemaGovernanceBeforeMerge() throws Exception { + Path registriesDir = + RepositoryContractResources.fromSystemProperty().requireTrackedDirectory("docs/registries"); + RegistryGovernanceCatalog.validate(registriesDir); + } +}