English · 한국어

데이터 모델 스키마 (계약 SSOT 참조)¶

계약 파일과 네임스페이스 목록, CycloneDX property 대응은 contracts/README를 보세요.

0. 규약¶

• 네임스페이스 = 단계: pqcota.common.v1(공유) · pqcota.discovery.v1 · pqcota.inventory.v1 · pqcota.provisioning.v1. 생성되는 Go 패키지는 commonv1, discoveryv1, inventoryv1, provisioningv1입니다.
• protojson 표현: 필드는 camelCase(target_node_id→targetNodeId), bytes는 base64 문자열(cbom_cyclonedx), 열거형은 이름 문자열("DETECTION_METHOD_RUNTIME_INTROSPECTION"), Timestamp는 RFC3339입니다.
• enum 0 = *_UNSPECIFIED = "알 수 없음". "없음"이 아니라 "판단할 수 없음"을 뜻하며, 완전성 맵과 함께 "정말로 없는 것"과 "원리상 관측할 수 없는 것"을 구분합니다.
• 하위 호환: 필드 번호를 다시 쓰지 않고, 없앤 필드는 reserved로 표시하고, 열거형 값은 맨 끝에만 붙이고, 호환을 깨는 변경은 새 v2로 합니다.

1. 모델을 관통하는 원칙 네 가지¶

필드가 지금처럼 나뉜 이유를 설명합니다.

1. 출처 레인 분리: 데이터가 어디서 왔는지에 따라 레인을 나눕니다. 서로 섞지 않습니다.
2. 관측(Observed): 수집기가 실제로 본 것입니다. CollectionResult, ObservedEdge, MachineIdentity.
3. 선언(Declared): CMDB나 사용자가 채운 것입니다. MachineProfile, 범위 마스터, 선언된 연결 간선.
4. 파생(Derived): 코어가 관측에서 다시 계산하는 뷰입니다. Finding, evidence_strength, QuantumPosture. 수집기 출력에는 없습니다. 원본(raw)에서 언제든 다시 만들 수 있습니다(재현성).
5. 행위(Action): 도구가 한 일을 추가만 하는 기록입니다. ProvisioningRecord, Decision.
6. 식별 모델: 세 겹입니다. 권위 = node_id(범위 마스터 / CMDB이며, 안정적이고 전역에서 유일합니다). 상관 = MachineIdentity 지문(machine-id, hw-uuid, cloud-id, fqdn으로 node_id를 검증하고, CMDB가 없으면 자체 ID를 도출합니다). 위치 지정자 = IP(ID가 아니며, 네트워크 관측을 노드로 풀어낼 때만 씁니다).
7. 파생 뷰의 재현성: 파생 결과는 raw_capture(불변의 원본)에서 보강 규칙으로 만듭니다. 그래서 파생 메시지는 derived_from_snapshot_id와 ruleset_version(어느 원본과 어느 규칙에서 재현할 수 있는지)을 싣습니다.
8. 비밀은 절대 저장하지 않습니다: 접근 비밀(SSH 키, 비밀번호, 계정)은 어떤 스키마에도 필드가 없습니다. MachineEndpoint가 대표적인 경우입니다. 이 타입에는 비밀을 담을 수 없으므로 컴파일 시점에 보장됩니다.

2. common.v1: 공유 어휘 (단계를 가로지름)¶

통제 어휘(열거형): 모든 단계가 공유¶

메시지¶

3. discovery.v1: 관측과 파생¶

collector.proto: 접수 계약 (수집기가 돌려주는 것)¶

코어는 "노드를 주면 정본 CBOM을 돌려받는다"는 추상에만 의존합니다. 이 gRPC 경계는 GPL 전염 차단벽이기도 합니다(라이선스 안내).

수집기 = 파이프라인의 1–2단계(원본 수집 + CycloneDX 변환) + Envelope입니다. 파생된 Finding은 만들지 않습니다.

cbom.proto: 파생된 Finding (정규화 파이프라인의 3–6단계가 만듭니다)¶

코어 정규화 파이프라인이 cbom_cyclonedx 본문에서 도출하는, 타입이 있는 뷰입니다. 다시 계산할 수 있습니다.

asset.proto: 자산 계층 (Machine → Application → Process)¶

프로세스는 저장하지 않습니다. PID는 휘발성입니다. 전환물 생성 직전에 ProcessMatch로 그때그때 풀어냅니다.

edge.proto: 통신 연결 간선 (노드 사이의 관계)¶

4. inventory.v1: 메타데이터와 판정¶

machine.proto: 머신 메타데이터 (사람이 읽는 정보이며 식별과 분리됩니다)¶

decision.proto: 검토 판정 (스키마만 있고 판정 엔진은 없습니다)¶

FinalizedPlan(전환물 생성)에 대응하는 인벤토리 쪽입니다. 판정이 확정되면 확정된 계획으로 이어집니다.

5. provisioning.v1: 생성과 되돌림¶

plan.proto: 확정된 계획 (전환물 생성이 실행되는 유일한 근거)¶

rollback.proto: 전환물 생성 이력과 되돌림 (스키마는 OSS이며, 이 리포지터리가 되돌림 플레이북도 생성합니다)¶

6. 관계도: 메시지가 이어지는 방식¶

[Collector]  ──returns──▶  CollectionResult { Envelope(+MachineIdentity) · raw_capture · cbom_cyclonedx · ObservedEdge[] · Completeness }
                                     │  (scope gate · ed25519 verification)
                                     ▼
[Normalize]  ──derives──▶  Finding[] (evidence_strength·app_keys) ─┐   ObservedEdge + QuantumPosture (derived)
                                     │                            │
                          app_keys attribution                    │
                                     ▼                            ▼
                             Application (node_id, app_key)   [central inventory view]
                                     │                            ▲  ▸MachineEndpoint · MachineProfile (the metadata lane)
                         ProcessMatch │ (live)                    │
                                     ▼                            │
                              LiveProcess (volatile)         [review] Decision ══(finalize)══╗
                                                                                             ║
                                                                                             ▼
[Provisioning]  FinalizedPlan { RemediationAction[] } ──FINALIZED gate──▶ playbooks (L1/L2/L3)
                                     │                                                  +
                                     ▼                                         ProvisioningRecord
                          before = CryptoState(the Findings)  ────────────▶  { before/after · app_keys · status }  (append-only rollback basis)

레인으로 다시 보면: 관측(CollectionResult, ObservedEdge) → 파생(Finding, QuantumPosture) → 선언/메타데이터(MachineProfile, Decision) → 행위(ProvisioningRecord). node_id는 모든 레인을 꿰는 닻이고, app_key(s)는 암호 자산을 앱에 귀속시키며 관측에서 전환물 생성까지 이어집니다.

app_key가 항상 채워지지는 않습니다. Finding과 ProvisioningRecord는 관측한 프로세스에서 곧바로 나오므로 항상 귀속됩니다. ObservedEdge도 앱에 닿지만, 조회하는 시점에 소켓이 아직 열려 있을 때만입니다. 수동 와이어 관측에는 PID가 없으므로, app_key를 채우려면 소켓 inode를 /proc/*/fd와 대조해야 합니다.

그래서 금방 닫힌 연결은 비어 있고, 권한이 없어 프로세스를 읽지 못한 연결도 비어 있습니다. 빈 app_key는 "귀속할 수 없었다"는 뜻이지 "이 연결 간선에 앱이 없다"는 뜻이 아니며, 어느 쪽인지는 완전성 note에 적힙니다. 놓친 것은 사람이 채울 수 있습니다 (pqcota-declare-attribution). 그러나 그 선언은 관측을 고치지 않습니다. 자기 레인에 따로 기록되고, 결합은 인벤토리 화면에서 일어납니다.

실행 가능한 예제: examples/.