English · 한국어

Data model schema (the contracts SSOT reference)¶

For the list of contract files and namespaces and the CycloneDX property mapping, see contracts/README.

0. Conventions¶

• Namespace = stage: pqcota.common.v1 (shared) · pqcota.discovery.v1 · pqcota.inventory.v1 · pqcota.provisioning.v1. The generated Go packages are commonv1, discoveryv1, inventoryv1, provisioningv1.
• protojson representation: fields are camelCase (target_node_id→targetNodeId), bytes is a base64 string (cbom_cyclonedx), enums are name strings ("DETECTION_METHOD_RUNTIME_INTROSPECTION"), and Timestamp is RFC3339.
• enum 0 = *_UNSPECIFIED = "unknown". Not "absent" but "could not determine" — together with the completeness map it separates "genuinely not there" from "impossible to observe in principle".
• Backward compatibility: never reuse a field number, mark removals reserved, append enum values only at the end, and make breaking changes as a new v2.

1. Four principles that run through the model¶

These explain why the fields split the way they do.

1. Provenance lane separation — lanes are split by where the data came from. They are never mixed.
2. Observed: what a collector actually saw — CollectionResult, ObservedEdge, MachineIdentity.
3. Declared: what a CMDB or a user filled in — MachineProfile, the scope master, declared edges.
4. Derived: views the core recomputes from observations — Finding, evidence_strength, QuantumPosture. They are not in collector output. Always regenerable from the raw original (reproducibility).
5. Action: an append-only record of what the tool did — ProvisioningRecord, Decision.
6. Identity model — three layers. Authority = node_id (the scope master / CMDB; stable and globally unique). Correlation = the MachineIdentity fingerprint (machine-id, hw-uuid, cloud-id, fqdn — verifies node_id, and derives a self-id when there is no CMDB). Locator = the IP (not an ID; used only to resolve a network observation to a node).
7. Derived-view reproducibility — derivations are produced from raw_capture (the immutable original) by enrichment rules. That is why derived messages carry derived_from_snapshot_id and ruleset_version (which original and which rule they can be reproduced from).
8. Secrets are never persisted — access secrets (SSH keys, passwords, accounts) have no field in any schema. MachineEndpoint is the representative case: its type cannot hold a secret, so it is guaranteed at compile time.

2. common.v1 — shared vocabulary (crosses stages)¶

Controlled vocabulary (enums) — shared by all stages¶

Messages¶

3. discovery.v1 — observation and derivation¶

collector.proto — the intake contract (what a collector returns)¶

The core depends only on the abstraction "give it a node, get back a canonical CBOM". This gRPC boundary is also the GPL contagion barrier (license notes).

Collector = steps 1–2 of the pipeline (raw capture + CycloneDX conversion) + the Envelope. It does not produce derived Findings.

cbom.proto — the derived Finding (produced by the normalization pipeline, steps 3–6)¶

The typed view the core normalization pipeline derives from the cbom_cyclonedx body. Recomputable.

asset.proto — the asset hierarchy (Machine → Application → Process)¶

Processes are not stored — a PID is volatile. It is resolved live through ProcessMatch right before provisioning.

edge.proto — communication edges (relations between nodes)¶

4. inventory.v1 — metadata and verdicts¶

machine.proto — machine metadata (human-facing information, separate from identity)¶

decision.proto — review verdicts (schema only — there is no verdict engine)¶

The inventory counterpart of FinalizedPlan (provisioning). When a verdict is finalized it leads into a finalized plan.

5. provisioning.v1 — generation and rollback¶

plan.proto — the finalized plan (the only grounds for provisioning to run)¶

rollback.proto — provisioning history and rollback (the schema is OSS, and this repo generates the rollback playbook too)¶

6. Relationship map — how the messages connect¶

[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)

Seen again as lanes: observed (CollectionResult, ObservedEdge) → derived (Finding, QuantumPosture) → declared/metadata (MachineProfile, Decision) → action (ProvisioningRecord). node_id is the anchor threading every lane, and app_key(s) attributes crypto assets to apps, flowing from discovery all the way to provisioning.

app_key is not always filled. Finding and ProvisioningRecord come straight from the process that was observed, so they always attribute. ObservedEdge also reaches the app, but only while the socket is still open at lookup time — passive wire observation carries no PID of its own, so the socket inode has to be correlated against /proc/*/fd to fill app_key.

A connection that closed quickly is therefore blank, and so is one whose process could not be read for lack of permission. An empty app_key means "could not attribute", not "this edge has no app", and the completeness note says which. A person can fill what was missed (pqcota-declare-attribution) — but that declaration does not edit the observation: it lands in its own lane, and the join happens on the inventory screen.

Runnable examples: examples/.