Files
messaging-library/docs/messaging/security.md
T
DongHyeonka 6e2dcae094 refactor(repo)!: 쓰지 않는 파일과 운영 인프라 파일을 지운다
문제: infra/ 43개 중 12개는 코드·테스트·workflow·스크립트 어디서도
읽지 않는다(httpclient·jpa·messaging·notification의 toxiproxy compose와
README). nginx 설정, Kubernetes PVC 인증 job, DB 역할 SQL 셋은 운영
인프라라 개발 repo에 둘 것이 아니다(소유자 결정 2026-11-07). release.yml
의 fileserver-pvc-certification job은 그 매니페스트 문자열만 grep했다.

고른 방법:
- 15개를 지운다.
- 운영 조건만 그 기능 문서에 한국어로 남긴다.
  docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」(nginx
  internal location·alias·X-Accel-Redirect 헤더 제거·스트리밍, PVC
  ReadWriteOnce·fsGroup), storage-certification.md(인증 절차),
  docs/jpa/security.md 「역할과 권한」·「서버 설정」(역할 SQL과
  jpa/postgres README 내용), docs/messaging/security.md(인증서 SAN).
  httpclient TLS README 내용은 docs/httpclient/security.md에 이미 있다.
- release.yml job과 needs 줄, fileserver-pr.yml·pr-adapters.yml의 지운
  경로 필터를 지운다.
- fileserver 지원 표의 "Kubernetes ReadWriteOnce PVC — Limited" 행은
  근거 job이 없어져 「주장하지 않음」으로 옮긴다.
버린 대안: 인프라 파일을 project-infra로 옮기기(설계 Q6). 그 repo는
특정 프로젝트용이라 범용 템플릿 파일을 받을 자리가 없다.

위험·한계: 지원 표에서 PVC 주장이 빠진다. 파생 서비스가 그 파일을
배포에 썼다면 병합이 지운다(B-50). 클러스터 인증은 이제 배포하는 쪽이
문서 절차로 한다.

검증(desktop, 트리 749a3328, ~/t1-layout-logs/):
- :composition:fileserver-platform:check :app-bootstrap:check
  :app-bootstrap:documentContractTest rc=0 (repositoryContractTest,
  FileserverDocumentationCoverageTest 실행)
- :verifyStrictLaneStages --dry-run rc=0
- scripts/verify-compose-profile-contracts.sh rc=0 (18 lane)
- check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/01-backend-layout.md 4.4, 6.3
BREAKING CHANGE: infra/fileserver/nginx, infra/fileserver/kubernetes, infra/jpa, infra/httpclient, infra/messaging, infra/notification/toxiproxy와 release.yml fileserver-pvc-certification job이 없어진다. docs/upgrade/2026-11-maturity-review.md B-50.
2026-11-07 12:22:47 +09:00

113 lines
5.3 KiB
Markdown

# Messaging 보안
## Credential 분리
producer / consumer / admin은 **서로 다른 credential**이다.
`MessageSecurityValidator`가 startup에서 강제한다.
```text
producer credential == consumer credential → 실패
admin credential == producer|consumer → 실패
production 프로필에 admin credential 존재 → 실패
```
마지막 규칙이 "애플리케이션은 topic을 purge할 수 없다"를 **구조적으로** 만든다.
runtime이 admin 자격 증명을 아예 보유하지 않으므로, 침해된 handler가 상승시킬 대상이 없다.
## Production 필수 조건
- TLS 활성
- TLS hostname verification 활성
- broker authentication 활성
- topology auto-create 비활성
broker 인증서는 `subjectAltName`에 접속 이름을 가져야 한다. hostname verification은 SAN을 보므로, SAN이
없는 인증서는 실패하는 것이 맞다. 검사를 끄지 않는다. 키와 인증서는 배포 환경의 PKI가 발급해 실행 때
마운트하고, repo에 두지 않는다.
Kafka는 추가로 `enable.idempotence=true`, `acks=all`,
`max.in.flight.requests.per.connection <= 5`, consumer auto-commit 금지.
RabbitMQ는 추가로 publisher confirm, publisher return, `mandatory=true`,
durable work queue의 quorum queue, consumer auto-ack 금지.
## Credential은 값이 아니라 참조다
`BrokerCredentialProfile`의 어떤 variant도 secret을 담지 않는다.
식별자만 보관하고 connect 시점에 `CredentialProvider`로 해석한다.
heap dump나 설정 출력에서 사용 가능한 credential이 나오지 않는다.
`CredentialIds`는 `bearer `, `sk-`, `-----begin`, `eyJ` 같은 접두사를 거부한다.
참조가 들어갈 자리에 secret 자체를 붙여넣는 가장 흔한 사고를 막는다.
SASL(PLAIN·SCRAM) 사용자 이름도 `CredentialProvider.username(credentialId)`가 준다. credential id는
저장소 안의 참조이지 broker가 아는 사용자 이름이 아니다. provider가 이름을 주지 않으면 기동에
실패한다.
key store·trust store는 경로만 설정에 둔다. 비밀번호는 credential id로 provider가 해석한다
(`configuration-reference.md` 보안 절).
## Rotation
`CredentialRotationPlan.isDue()`는 만료 **전에** 참이 된다.
broker가 연결을 거부하기 시작한 시점에는 이미 publish가 실패하고 consumer가 멈춰 있다.
Kafka SASL credential은 producer를 다시 만들지 않고 바뀐다. JAAS 설정에는 login module 이름만
있고, `KafkaCredentialCallbackHandler`가 연결이 인증할 때마다 `CredentialRuntimeRegistry`에서
사용자 이름과 비밀번호를 읽는다. registry는 provider가 준 만료 시각의 rotation lead(기본 30분)
안으로 들어오면 새로 가져오므로, 새 연결과 재인증(broker `connections.max.reauth.ms`)이 새 값을
쓴다. 만료 시각을 주지 않는 provider의 credential은 캐시된 값을 계속 쓴다.
key store·trust store 비밀번호는 예외다. Kafka가 SSL context를 만들 때 한 번 읽으므로 바꾸려면
producer를 다시 만들어야 한다(재기동).
transport 세대 교체(`DefaultMessagingRuntimeRegistry.install()`)는 transport 자체를 바꿀 때 쓴다.
새 세대를 원자적으로 게시하고, 이전 세대는 마지막 lease가 닫힐 때까지 열려 있다가 닫힌다.
drain deadline이 이 대기를 제한한다.
## Header
금지 header는 application·platform 양쪽에서 거부한다.
```text
Authorization, Proxy-Authorization, Cookie, Set-Cookie,
access_token, refresh_token, api_key, password, client_secret
```
credential이 header에 들어가면 broker storage, DLQ dump, 운영 도구에 남는다.
downstream redaction으로는 되돌릴 수 없다.
예약 header(`msg.*`, `traceparent`, `tracestate`, `baggage`)는 platform만 쓴다.
application이 `msg.id`를 설정할 수 있으면 Inbox 중복 제거와 DLQ 상관관계가 의존하는
logical identity가 호출자 제어가 된다.
## ACL
publisher가 broker ACL **이전에** 검사한다(`PUBLISH_FORBIDDEN`).
broker ACL 거부는 애플리케이션 컨텍스트가 없는 연결 수준 오류로 도착하므로
"어느 모듈이 어디에 publish하려 했는가"가 조사 대상이 된다.
publish 가능한 destination은 선언된 destination이다. broker에 `app.messaging.security.<broker>`
항목이 있으면 그중 `access.publishable`에 적힌 것만 남는다(빈 목록이면 publish 불가).
## 관측성 누출
`MessagingRedactor`는 denylist다.
- secret: authorization, cookie, token, password, secret, credential
- per-message identity: messageId, correlationId, causationId, partitionKey, key, offset, deliveryTag, sequence
- payload: payload, body, data
- 예외 상세: exceptionMessage, stackTrace
identity를 지우는 이유는 두 가지다. bounded metric을 message당 하나의 series로 만들고,
support log를 재식별 표면으로 만들기 때문이다.
`CardinalityGuard`는 dimension당 값 개수를 상한한다.
cardinality 사고는 점진적이지 않다. 테스트 10건에서는 멀쩡하고 운영에서 백엔드를 죽인다.
## 감사
`MessagingAuditEvent`는 replay, redrive, offset reset, purge, delete를 기록한다.
subject(운영자 identity), approval ticket, 그리고 redactor를 통과한 details만 담는다.
누가 무엇을 했는지 증명하되 payload의 두 번째 사본이 되지 않는다.