Files
clean-architecture-backend-…/docs/mongodb/security-observability.md
T
DongHyeonka 24eb1be36d docs(mongodb): MongoDB 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/mongodb 아래 살아 있는 문서 14개가 영어였고(문서 검사 language
예외), 몇 가지 주장이 지금 코드와 달랐다.
- repository-adaptation.md가 registry의 leaf 수(19)와 Spring Boot 버전을 옮겨
  적었다(number 예외 두 줄).
- 같은 문서와 advanced/signoff/README.md가 scripts/verify-mongodb-platform.sh·
  verify-mongodb-advanced.sh를 2026-08-15에 지웠다고 했다. 두 스크립트는 지금도
  있고 lane을 돌린다.
- testkit을 `testkit` source set에 둔다고 했다. 지금은 `testFixtures`(ADR-BUILD-001)와
  `mongoProviderTestkit`이다. `…mongo.architecture`도 main이 아니라 testFixtures에 있다.
- ArchUnit 규칙 이름 `stableNeverDependsOnAdvanced`·`productionNeverDependsOnTestkit`은
  없다. 실제는 MongoModuleBoundaryTest의 `noStablePackageDependsOnAnAdvancedCapability`·
  `noProductionPackageDependsOnTheTestkit`이다.
- support-matrix.md의 Boot·Spring Data·driver·Micrometer·Testcontainers 버전이
  lockfile과 달랐다(예: driver 5.6.1 → 5.6.5).
- consumer-leaf-guide.md가 템플릿에 없는 Gradle 경로를 인라인 코드로 적었다
  (reference 예외).
- document-modeling-guide.md가 타입 metadata를 bson-mapping-guide §4로 가리켰다(§5).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 버전과
leaf 수는 숫자 대신 정본(src/gradle/libs.versions.toml, registry, gradle.lockfile,
container-images.properties)을 가리킨다. 서비스가 만들 leaf의 확인 명령은 다른
단계와 같이 코드 블록에 두고 템플릿에 없는 경로라고 밝힌다.

버린 대안: support-matrix 버전을 lockfile 값으로 고쳐 적기. 다음 업그레이드에서 다시
틀리고, 같은 시간에 도는 의존성 세션과 같은 줄을 고치게 된다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 설계 번호(§, D-xx)는
그대로 두었다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0).
docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java`
— package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는
advanced 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00

142 lines
7.8 KiB
Markdown

# 보안과 관측
설계서 §26–§28, 결정 D-05. 애플리케이션 plane과 admin plane은 다른 client 위의 다른 credential이다.
그리고 telemetry는 절대 데이터 유출 경로가 되지 않는다.
## 1. Role
`MongoPrincipalRole` — role마다 credential 하나, 최소 권한:
| Role | 주는 권한 |
|---|---|
| `APP_READ` | 허용 목록 collection의 `find` |
| `APP_WRITE` | 허용 목록 collection의 `insert`, `update`, `delete` |
| `CHANGE_STREAM` | `changeStream`, `find` |
| `MIGRATION` | 대상 collection의 index·validator 관리 |
| `SEARCH_ADMIN` | 검색 index 관리 |
| `SHARD_ADMIN` | shard key 작업 |
| `ENCRYPTION_ADMIN` | key vault 접근 |
| `DBA` | 사람의 plane. 애플리케이션은 절대 쓰지 않는다 |
`MongoSecurityProfileValidator`가 시작할 때 profile을 검사한다. `forbiddenPrivilegesHeld()`는 profile이 갖고
있으면 안 되는데 가진 권한의 이름을 댄다. validator가 *어느* 권한인지 말하는 이유는, 이름 없이 「credential
권한이 너무 크다」고만 하면 대응할 수 없는 발견이기 때문이다.
애플리케이션 credential에 절대 있으면 안 되는 권한: `dropDatabase`, `dropCollection`, `shutdown`, `killop`,
`root`, `__system`, `dbOwner`, `userAdminAnyDatabase`.
## 2. Credential은 값이 아니라 참조다
`MongoCredentialReference`는 `secret://…` 참조와 role을 가진다. 참조는 연결할 때 secret provider가 푼다.
비밀번호는 속성 값, 로그 필드, stack trace에 남을 수 있는 생성자 인자가 절대 되지 않는다.
`MongoCredentialRotationPolicy`가 교체 계약을 말한다: 유효 기간이 겹치고, 비우는 구간(drain window)이 있고,
교체에 재시작이 필요 없다. `MongoClientGenerationRegistry`가 바꿔 끼우기를 구현한다. 새
`MongoClientGeneration`이 새 연산을 받는 동안 앞 세대는 `markDraining()` 상태로 처리 중인 연산이 끝날 때까지
남는다. 옛 client를 바로 죽이면 처리 중인 요청이 모두 실패한다. 세대 없는 교체가 장애인 이유다.
교체는 릴리스 게이트의 failover 시나리오(`MongoFailoverScenario.CREDENTIAL_ROTATION`)다. 잘 되기를 바라는
runbook 단계가 아니다.
## 3. TLS와 연결 정책
`MongoSecurityProfile.production(...)`은 TLS를 요구하고 `tlsAllowInvalidCertificates` /
`tlsAllowInvalidHostnames`를 거부한다. `MongoSecurityProfile.local(...)`이 있는 것은 개발자가 container에
붙으려고 production factory를 약하게 만들지 않게 하려는 것이다. 시작 validator는 운영 runtime profile에서
local profile을 거부한다.
## 4. Admin plane (D4)
`MongoAdminGateway`가 `MongoAdminOperation`으로 가는 유일한 길이고, 애플리케이션 것이 아니라 DBA 범위
credential을 쓰는 D4 client에서 돈다.
- `MongoAdminAuthorization`이 호출자의 role을 연산과 대조한다.
- `MongoAdminRuntimeGuard`는 runtime profile이 명시적으로 허락하지 않으면 위험한 연산(`highRisk()`)을
거부한다. 실행 중인 애플리케이션에서 닿을 수 있는 `dropCollection`은 호출 코드를 아무리 잘 검토했어도
데이터 손실 경로다.
- `MongoAdminAuditRecord`가 누가 무엇을, 언제, 어느 collection profile에 돌렸는지 실행 *전에* 기록한다.
그래서 실패한 시도도 남는다.
native capability gateway(D3)는 admin 분류의 명령을 모두 거부한다. 그래서 애플리케이션 plane에서 admin
plane으로 가는 길은 없다.
## 5. 관측 tag
`MongoObservationConvention`은 tag 이름을 정확히 여덟 개만 허용한다.
```
mongoProfile, databaseProfile, collectionProfile, operationName,
operationType, result, failureCategory, consistencyProfile
```
그리고 다음을 명시적으로 금지한다.
```
documentId, rawTenantId, tenantId, dynamicCollectionName, queryParameter,
query, fullBson, resumeToken, shardKeyValue, plaintextPII, credential
```
이유는 둘이고 둘 다 중요하다. 가짓수: 값이 문서 id인 tag는 문서마다 시계열 하나를 만들고, 그렇게 metric
저장소가 쓰러진다. 기밀성: metric label은 DB와 접근 모델이 다른 시스템이 저장하고, 보내고, 보관한다.
`requireAllowed(tagName)`는 목록 밖의 것에 예외를 던진다. 그래서 새 tag는 서비스 코드의 한 줄이 아니라
convention의 의도적인 변경이 된다.
`MicrometerMongoOperationObserver`가 `MongoOperationObserver` port를 구현한다. 기본값은
`NoOpMongoOperationObserver`라서 관측은 켜야 생기고 필수 의존이 되지 않는다.
## 6. Driver 자체 listener
`MongoDriverObservabilityConfiguration`은 driver listener 셋을 등록한다. 애플리케이션 수준 timer로는 답할 수
없는 질문에 답하기 때문이다.
| Listener | 답하는 질문 |
|---|---|
| `MongoCommandObservationListener` | *서버*가 걸린 시간과 호출자가 기다린 시간은 각각 얼마인가? |
| `MongoPoolObservationListener` | 기다린 시간이 query 실행이 아니라 connection checkout이었나? |
| `MongoSdamObservationListener` | 그 구간에 토폴로지가 바뀌었나 — 선출, 노드 빠짐? |
pool과 SDAM 이벤트가 없으면 모든 failover가 「DB가 느려졌다」로 보이고, 「pool을 늘려야 한다」와
「primary를 잃었다」의 차이가 보이지 않는다.
## 7. 명령 가리기
`MongoObservationRedactor.describe(commandName)`:
- 인증·사용자 관리 명령(`authenticate`, `saslStart`, `saslContinue`, `getnonce`, `createUser`,
`updateUser`, `copydb*`)은 `<redacted>`로 보인다. 인자에 credential과 key 재료가 있다.
- 구조 명령(`ping`, `hello`, `buildInfo`, `listCollections`, `listIndexes`, `collStats`)은 이름으로
보인다. 인자에 데이터가 없다.
- 나머지는 모두 `name(...)`으로 보인다. 명령은 보이고 filter나 문서는 보이지 않는다.
`isAlwaysRedacted(...)`는 테스트가 어떤 로그 경로도 인증 명령의 인자를 그리지 못함을 증명하는 단언 hook이다.
## 8. 시작 검증
`MongoStartupValidator`는 context refresh 때, 첫 요청 전에 돈다.
1. `MongoTopologyProbe`가 실제 `MongoTopology`와 그 `MongoCapabilitySet`을 보고한다.
2. profile마다 선언한 토폴로지가 그것과 맞아야 하고, `STANDALONE` 위의 production profile은 실패한다.
3. `platform.transactions=true`이면 probe가 `TRANSACTION`을 `STABLE`로 보고해야 한다. `STANDALONE`에서는
그렇지 않으므로 시작이 실패한다.
4. `MongoSecurityProfileValidator`가 credential과 TLS, 그리고 admin credential이 runtime credential과
다른지를 검사한다. `MongoSchemaVersionRange`는 거꾸로면 안 된다.
5. `MongoPlatformHealthIndicator`가 readiness probe에 토폴로지 불일치와 secondary 가용성을 보고한다.
시작할 때 발견한 설정 오류는 배포 한 번 실패로 끝난다. 같은 오류를 실행 중에 발견하면 장애가 되고, 실패한
연산이 원인을 드러내는 일은 드물다.
## 9. 보안 lane이 이것을 어떻게 증명하나
```bash
cd src
./gradlew :adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest --console=plain
```
이 lane은 `MongoAuthenticatedReplicaSetContainer`에서 돈다. 이것은 `--auth`와 생성한 keyfile로 mongod를
띄운다. 그 세부가 lane의 전부다. Testcontainers의 `MongoDBContainer`는 mongod를 `--auth` *없이* 띄운다.
그 위에서 만든 사용자는 모두 모든 권한을 가지므로, role이 아무리 틀려도 최소 권한 단언이 통과한다. 실패할
수 없는 보안 테스트는 보안 테스트가 아니다.
lane이 단언하는 것은 거부다. `read` role의 insert가 거부되고, 애플리케이션 role의 `dropDatabase`가
거부된다. 그다음 `MongoSecurityProfileValidator`가 서버가 방금 거부한 바로 그 권한을 이름으로 대는지 본다.