pqcaton · architecture

관측 위에 판정을 얹는 구조 Judgment laid on top of observation

pqcota가 관측하고, pqcaton이 그 관측을 선언과 대조해 리뷰에 올리고 확정합니다. 의존은 한 방향입니다. pqcaton이 pqcota의 공개 모듈을 가져다 쓰고, pqcota는 pqcaton에 의존하지 않습니다. pqcota observes; pqcaton reconciles those observations against the declaration, puts them in a review queue and finalizes them. The dependency runs one way: pqcaton uses pqcota's published modules, and pqcota does not depend on pqcaton.

01한눈에 At a glance

왼쪽이 기반(pqcota), 오른쪽이 이 리포(pqcaton)입니다. 가운데 띠가 둘 사이를 잇는 유일한 통로이고, 화살표는 그 띠를 두 번 건넙니다. 관측이 오른쪽으로 가고, 확정된 계획이 왼쪽으로 돌아갑니다. The base (pqcota) is on the left, this repository (pqcaton) on the right. The band in the middle is the only passage between them, and the arrows cross it twice: observations travel right, finalized plans come back left.

PQCOTA: 관측 · 정규화 · 전환 PQCOTA: OBSERVE · NORMALIZE · CONVERT CONTRACTS PQCATON: 대조 · 판정 · 거버넌스 PQCATON: RECONCILE · JUDGE · GOVERN proto → gen/ 어휘의 single source 단일 출처 of vocabulary 수집기: 대상 노드에서 돈다 Collectors: run on the target node collectors/{openssl, jvm, cng, network} ansible/discover.yml 이 반입·실행·회수 ansible/discover.yml ships, runs and collects them 커널: 관측을 사실로 바꾼다 Kernel: turns observation into fact kernel/posture · registry 협상된 그룹 → 양자내성 등급 negotiated group → quantum-resistance grade kernel/machineid · scope · sign 적재: 인벤토리가 되는 자리 Ingest: where it becomes an inventory discovery/{normalize, history} inventory/{ingest, profile, render} 완전성 맵 · 거절 이력 · 조직 축 completeness map · rejection history · org axis 선언 반입 Declaration import inventory/declaration 조직이 「이렇게 알고 있다」고 적은 것 what the organization wrote down as “this is what we know” 전환물 생성 · 적용 Generate and apply the conversion provisioning · pqcota-provision before 캡처 · 되돌림 before-capture · rollback 대조 엔진: 선언과 관측을 맞댄다 Reconciliation engine: declaration against observation pkg/inventory/reconcile 3-상태 · confidence 스코어링 · 리뷰 큐 · 토폴로지 three states · confidence scoring · review queue · topology CONFIRMED · UNDECLARED · UNOBSERVED UNOBSERVED는 기계가 확정하지 않는다 no machine finalizes an UNOBSERVED item 판정: 사람의 결론을 남겨 둔다 Judgment: holds the human conclusion pkg/inventory/decision draft → in-review → finalized · append-only 근거가 바뀌면 그 판정만 델타 리뷰 when the basis changes, only that judgment goes to delta review inventory/cmd/{pqcaton-report, decide, scope, ui} 사람이 돌리고 채우는 자리: 화면 · 리포트 · 토폴로지 where a person runs and fills in: screens · reports · topology CollectionResult 관측 레인 observation lane 선언 레인 declaration lane 리뷰 큐 review queue FinalizedPlan 확정된 것만 내려간다 only what is finalized goes down
그림 1. 계약 띠를 두 번 건넙니다. 관측이 오른쪽으로, 확정된 계획이 왼쪽으로. 왼쪽 상자들은 pqcaton 없이도 그대로 돕니다. 오른쪽이 없으면 판정이 없을 뿐 관측은 끝까지 됩니다. Figure 1. The contract band is crossed twice: observations to the right, finalized plans to the left. The boxes on the left run just as they are without pqcaton. Take the right side away and you lose the judgment, not the observation.

이 그림이 알려 주는 것 하나. pqcaton은 pqcota를 감싸지 않습니다. 나란히 서서 계약에 정의된 관측 결과와 확정 계획을 주고받습니다. 그래서 이 리포를 지워도 pqcota는 그 자체로 완결됩니다. 반대로 pqcota의 공개 모듈이 바뀌면 이 리포가 따라가야 합니다. One thing this diagram tells you. pqcaton does not wrap pqcota. They stand side by side and exchange the observation results and finalized plans that the contracts define. Delete this repository and pqcota is still complete on its own. The other way round, when pqcota's published modules change, this repository has to follow.

02연결은 한 방향입니다 The link runs one way

이 리포는 pqcota의 공개 모듈 넷을 Go 패키지로 가져다 씁니다. 계약 타입만이 아니라 등급·스코프 규칙 같은 공통 코드, 이력·정규화·선언 반입, 로컬 스캔이 부르는 수집기도 그대로 씁니다. 아래 표가 그 전부입니다. 관측 로직도, 저장소 스키마도 재구현하지 않습니다. This repository imports four published modules of pqcota as Go packages. That is not only the contract types: it uses shared code such as the grading and scope rules, the history, normalization and declaration import, and the collector behind the local scan, as they are. The table below lists all of it. It reimplements neither the observation logic nor the storage schema.

이 리포가 쓰는 상류 Upstream this repository uses무엇을 위해 What for
pqcota-common/gen/…/common/v1Envelope·CryptoRuntime 등 공통 어휘 Shared vocabulary such as Envelope and CryptoRuntime
pqcota-common/gen/…/discovery/v1관측 결과(CollectionResult)를 읽는다 Reads observation results (CollectionResult)
pqcota-common/gen/…/inventory/v1ReconState·Decision. 3-상태와 판정의 SSOT ReconState and Decision — the SSOT for the three states and for judgments
pqcota-inventory/pkg/inventory/history관측 이력 저장소를 그대로 쓴다 Uses the observation history store as it is
pqcota-inventory/pkg/inventory/normalize정규화된 관측을 받는다 Takes normalized observations
pqcota-inventory/pkg/inventory/resultio회수된 관측 결과 파일을 읽는다 Reads the collected observation result files
pqcota-inventory/pkg/inventory/ingest테스트에서만 쓴다. 상류 적재가 만드는 스냅샷 지문과 이 리포의 것이 같은지 맞댄다 Used only in tests: checks that this repository's snapshot fingerprint equals the one the upstream ingestion produces
pqcota-inventory/pkg/inventory접근 정보(hosts.csv)를 읽고 Ansible 인벤토리를 만든다 Reads the access file (hosts.csv) and builds the Ansible inventory
pqcota-inventory/pkg/inventory/declaration선언(CMDB) 반입 Imports the declaration (CMDB)
pqcota-common/pkg/kernel/posture양자내성 등급. 우리가 다시 판단하지 않는다 Quantum-resistance grading — we do not judge it again
pqcota-common/pkg/kernel/registry결정론적 서명 매칭 데이터 Deterministic signature-matching data
pqcota-common/pkg/kernel/scope자산 스코프 규칙. 형식과 집행을 그대로 쓴다 Asset scope rules — both the format and the enforcement are used as they are
pqcota-discovery/collectors/openssl로컬 스캔에서 호출한다 Called by the shortcut that scans this machine
pqcota-common/gen/…/provisioning/v1확정 계획(FinalizedPlan)의 형식 The shape of a finalized plan (FinalizedPlan)
pqcota-common/pkg/kernel/sign계획의 승인 서명과 그 확인 Signs plan approvals and checks them
pqcota-provisioning/pkg/provisioning승인 전이 · 실행 관문 · 적용과 되돌리기 플레이북 생성 The approval transition, the execution gate, and generating the apply and rollback playbooks
pqcota-common/pkg/org조직 격리 축 The organization isolation axis

internal/probe는 계약 타입을 실제로 가져다 쓸 수 있는지 확인하는 최소 코드입니다. pqcota-common의 gen 타입 하나를 import하고, pqcota가 enum 이름을 바꾸면 테스트가 여기서 끊깁니다. internal/probe is the smallest code that checks the contract types can actually be consumed. It imports one gen type from pqcota-common; if pqcota renames an enum value, the test breaks here.

03이 리포가 더하는 것 What this repository adds

모듈 Module하는 일 What it does왜 상류가 안 만들었나 Why upstream did not build it
pkg/inventory/reconcile 3-상태 대조 · confidence 스코어링 · 리뷰 큐 · 거버넌스 토폴로지 Three-state reconciliation, confidence scoring, the review queue, the governance topology 관측 도구가 “무엇이 위험한가”를 판정하기 시작하면 관측의 정직성이 무너집니다 Once an observation tool starts judging “what is risky”, the honesty of the observation is gone
pkg/inventory/decision 리뷰-확정 상태기계 · 판정 영속(append-only) · 확정 계획 The review-to-finalize state machine, append-only judgment persistence, the finalized plan 판정은 조직의 책임이고 감사 대상입니다. 혼자 쓰면 필요 없습니다 A judgment is the organization's responsibility and subject to audit. Working alone, you do not need it
inventory/cmd/* · pkg/inventory/ui 대조 실행 · 리포트와 토폴로지 렌더 · 사람이 쓰는 화면(선언 · 암호 자산 스코프 · 대조 · 판정 · 인벤토리 조회) Runs the reconciliation, renders reports and the topology, and serves the screens people use — declaration, crypto asset scope, reconciliation, judgment, inventory lookup 사람이 돌리고 사람이 채우는 자리 The place a person runs and a person fills in
saas/runner 호스팅으로 쓸 때만 필요한, 결과를 내보내는 자리 The place that sends results out, needed only when we host it 고객 인프라 안에서만 돌 때는 필요 없습니다. 05 Not needed when everything runs inside the customer's infrastructure. 05

3-상태가 이 도구의 어휘입니다 The three states are this tool's vocabulary

상태 State정의 Definition등급 Grade무엇을 뜻하나 What it means
CONFIRMED선언 ∩ 관측 declared ∩ observedAUTO신뢰도 최상 The highest confidence
UNDECLARED관측만 observed onlyAUTO조직이 모르는 통신입니다. 이 도구가 주는 첫 번째 쓸모입니다 Traffic the organization does not know about. This is the first thing the tool is good for
UNOBSERVED선언만 declared onlyMANUAL실재하는데 못 본 것인지 이미 없어진 것인지는 사람만 압니다 Whether it exists and was missed or is already gone — only a person knows

UNOBSERVED를 기계가 확정하지 않는 것이 설계의 축입니다. pqcota의 완전성 맵이 “원리상 관측 불가”와 “실제 없음”을 구분해 주고, 그 위에서 사람이 정합니다. The axis of the design is that no machine finalizes an UNOBSERVED item. pqcota's completeness map separates “cannot be observed in principle” from “really absent”, and a person decides on top of that.

04전체 실행 과정 How one full turn runs

직접 설치에서는 밖으로 나가는 것이 하나도 없습니다. 모든 단계가 고객 인프라 안에서 끝납니다. 호스팅으로 쓸 때 무엇이 달라지는지는 05절에 있습니다. In a self-hosted install nothing leaves the network. Every step finishes inside the customer's own infrastructure. What changes when we host it for you is in section 05.

선언 Declaration CMDB 반입 CMDB import 관측 Observe pqcota 3 적재 Ingest pqcota 4 조회 Look up pqcota 5 대조 Reconcile 3-상태 · confidence three states · confidence 리뷰 큐 구성 build the review queue 리뷰 · 확정 Review · finalize 사람이 판정 a person judges 승인 서명 approval signature 확정 계획 → 적용 Finalized plan → apply pqcota 6 · 7 · 8 before 캡처 · 되돌림 before-capture · rollback 관문 gate pqcaton 없이: 손으로 쓴 계획 without pqcaton: a hand-written plan 근거가 바뀐 판정만 델타 리뷰 delta review for judgments whose basis changed 재관측 · 변화 diff re-observe · diff the change
그림 2. 가운데 두 상자만 이 리포입니다. 아래 점선이 pqcaton 없이 가는 경로입니다. pqcota는 확정 계획을 입력으로만 받고, 손으로 쓴 계획으로도 끝까지 돕니다. 확정 앞의 화살표가 이 제품에서 반드시 거쳐야 하는 관문입니다: finalized 전에는 적용이 돌지 않습니다. Figure 2. Only the two middle boxes are this repository. The dashed line below is the path without pqcaton: pqcota takes a finalized plan as input only, and a hand-written plan carries it through just as well. The arrow before finalization is the gate this product insists on — nothing is applied before it is finalized.

05호스팅으로 쓸 때만 붙는 것 What is added only when we host it

위 그림에는 러너가 없습니다. 자기 서버에서 돌릴 때는 필요 없기 때문입니다. pqcota-ingest가 결과를 바로 읽고, 대조와 판정이 같은 기계에서 끝납니다. There is no runner in the diagram above, because on your own servers you do not need one. pqcota-ingest reads the results directly, and reconciliation and judgment finish on the same machine.

우리가 대신 돌려 주는 호스팅에서는 관측 결과가 고객망을 나와야 하고, 그것을 내보내는 자리가 saas/runner입니다. 그 코드만 이 리포에 있는 이유는 하나입니다. 고객 서버에서 고객 권한으로 도니 무엇을 밖으로 보내는지 읽어서 확인할 수 있어야 합니다. 컨트롤 플레인 쪽 코드와 설계는 이 리포에 없습니다. When we run it for you, the observation results have to leave the customer network, and saas/runner is the place that sends them out. Only that piece lives in this repository, for one reason: it runs on the customer's servers with the customer's privileges, so what it sends must be open to reading. The control-plane code and its design are not here.