From 1444d1e0df2b675dbf5c45e11700c8798902b133 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 00:20:34 +0900 Subject: [PATCH] =?UTF-8?q?docs(security):=20=EC=9A=94=EC=B2=AD=EB=A5=A0?= =?UTF-8?q?=20=EC=A0=9C=ED=95=9C=EC=9D=80=20=EA=B8=B0=EB=B3=B8=20off=C2=B7?= =?UTF-8?q?ingress=20=EC=B1=85=EC=9E=84=EC=9E=84=EC=9D=84=20=EB=AA=85?= =?UTF-8?q?=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. 완료 기준