Files
clean-architecture-backend-…/docs/mongodb/security-observability.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

7.2 KiB

Security and Observability

Design §26–§28, decision D-05. The application plane and the admin plane are different credentials on different clients, and telemetry never becomes an exfiltration path.

1. Roles

MongoPrincipalRole — one credential per role, least privilege:

Role Grants
APP_READ find on allowlisted collections
APP_WRITE insert, update, delete on allowlisted collections
CHANGE_STREAM changeStream, find
MIGRATION index and validator management on the target collections
SEARCH_ADMIN search index management
SHARD_ADMIN shard key operations
ENCRYPTION_ADMIN key vault access
DBA the human plane; never used by an application

MongoSecurityProfileValidator checks the profile at startup. forbiddenPrivilegesHeld() names the privileges the profile holds and must not — the validator reports which one, because "your credential is over-privileged" without a name is an unactionable finding.

The privileges that must never appear on an application credential: dropDatabase, dropCollection, shutdown, killop, root, __system, dbOwner, userAdminAnyDatabase.

2. Credentials are references, not values

MongoCredentialReference holds a secret://… reference plus the role. The reference is resolved at connection time by the secret provider; the password is never a property value, a log field, or a constructor argument that could end up in a stack trace.

MongoCredentialRotationPolicy states the rotation contract: overlapping validity, a drain window, and a rotation that never requires a restart. MongoClientGenerationRegistry implements the swap — a new MongoClientGeneration starts serving new operations while the previous generation is markDraining() until its in-flight operations finish. Killing the old client immediately fails every in-flight request, which is why rotation without generations is an outage.

Rotation is a failover scenario in the release gate (MongoFailoverScenario.CREDENTIAL_ROTATION), not a runbook step people hope works.

3. TLS and connection policy

MongoSecurityProfile.production(...) requires TLS and refuses tlsAllowInvalidCertificates / tlsAllowInvalidHostnames. MongoSecurityProfile.local(...) exists so a developer does not have to weaken the production factory to get a container to connect; the startup validator refuses a local profile on a production runtime profile.

4. Admin plane (D4)

MongoAdminGateway is the only path to MongoAdminOperation, and it runs on the D4 client with the DBA-scoped credential — not the application's.

  • MongoAdminAuthorization checks the caller's role against the operation.
  • MongoAdminRuntimeGuard refuses high-risk operations (highRisk()) unless the runtime profile explicitly permits them; a dropCollection reachable from a running application is a data-loss vector regardless of how well-reviewed the calling code is.
  • MongoAdminAuditRecord records who ran what, when and against which collection profile — before execution, so a failed attempt is recorded too.

The native capability gateway (D3) refuses any admin-category command, so there is no path from the application plane into the admin plane.

5. Observability tags

MongoObservationConvention allowlists exactly eight tag names:

mongoProfile, databaseProfile, collectionProfile, operationName,
operationType, result, failureCategory, consistencyProfile

and explicitly forbids:

documentId, rawTenantId, tenantId, dynamicCollectionName, queryParameter,
query, fullBson, resumeToken, shardKeyValue, plaintextPII, credential

Two reasons, and both matter. Cardinality: a tag whose values are document ids produces one time series per document, which is how a metrics backend falls over. Confidentiality: a metric label is stored, shipped and retained by systems with a different access model than the database. requireAllowed(tagName) throws on anything outside the list, so a new tag is a deliberate change to the convention rather than a line in a service.

MicrometerMongoOperationObserver implements the MongoOperationObserver port; NoOpMongoOperationObserver is the default so observation is opt-in and never a hard dependency.

6. Driver-native listeners

MongoDriverObservabilityConfiguration registers three driver listeners, because they answer questions the application-level timer cannot:

Listener Answers
MongoCommandObservationListener How long did the server take, versus how long the caller waited?
MongoPoolObservationListener Was the wait time connection checkout rather than query execution?
MongoSdamObservationListener Did the topology change — an election, a node removed — during the window?

Without pool and SDAM events, every failover looks like "the database got slow", and the difference between "we need a bigger pool" and "we lost a primary" is invisible.

7. Command redaction

MongoObservationRedactor.describe(commandName):

  • Authentication and user-management commands (authenticate, saslStart, saslContinue, getnonce, createUser, updateUser, copydb*) render as <redacted> — their arguments carry credentials and key material.
  • Structural commands (ping, hello, buildInfo, listCollections, listIndexes, collStats) render by name; their arguments are not data-bearing.
  • Everything else renders as name(...): you get the command, never the filter or the document.

isAlwaysRedacted(...) is the assertion hook so a test can prove no logging path can render an auth command's arguments.

8. Startup validation

MongoStartupValidator runs at context refresh, before the first request:

  1. MongoTopologyProbe reports the actual MongoTopology and its MongoCapabilitySet.
  2. Every profile's declared topology must match it, and a production profile on STANDALONE fails.
  3. With platform.transactions=true, the probe must report TRANSACTION as STABLE; on STANDALONE it does not, so startup fails.
  4. MongoSecurityProfileValidator checks credentials and TLS, and that the admin credential differs from the runtime one; the MongoSchemaVersionRange must not be inverted.
  5. MongoPlatformHealthIndicator reports topology mismatch and secondary availability for the readiness probe.

A misconfiguration found at startup costs a failed deploy. The same misconfiguration found at runtime costs an incident, and the failing operation is rarely the one that reveals the cause.

9. How the security lane proves any of this

cd src
./gradlew :adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest --console=plain

The lane runs against MongoAuthenticatedReplicaSetContainer, which starts mongod with --auth and a generated keyfile. That detail is the whole lane: Testcontainers' MongoDBContainer starts mongod without --auth, so users created on it all have every privilege and a least-privilege assertion passes no matter how wrong the roles are. A security test that cannot fail is not a security test.

What the lane asserts is the refusal: the read role's insert is rejected, and the application role's dropDatabase is rejected. Then it checks that MongoSecurityProfileValidator names the same privilege the server just refused.