Context pointers
A CBOM records cryptographic facts about one subject at one stage. A consumer usually needs more than those facts: the SBOM of the same product, the vendor's vulnerability statements, the configuration a deployment record was read from, the evidence behind an observation. These artefacts change on their own schedule, or another party holds them. A CBOM therefore does not carry them. It points to them. A profile states which pointers a document must contain, and the validator checks them.
The construct
A profile declares two things: the kinds of context it knows about, and the rules that require a pointer to one of them. The rules form a separate kind of rule, with the letter R, beside product rules (P) and interface rules (I). They are cited like any other rule, for example interface-disclosure#R2.
Context kinds
The profile's contextKinds block defines each kind. For each kind, it names the CycloneDX externalReferences types that can carry it, and its form:
document: a fixed artefact. The pointer binds it by a hash, so a consumer can tell whether the artefact has changed.endpoint: a feed, an API or a web page whose content changes over time. The pointer names its access protocol, so a consumer knows how to read it.document-or-endpoint: either of the two, as the producer chooses.
Reference rules
A reference rule names the kind it requires and sets these fields:
| Field | What it says |
|---|---|
context | The context kind the pointer must have. |
at | Where the pointer sits: on the document (the subject) or on each interface. |
level | MUST, SHOULD or MAY. |
hashRequired | Whether the pointer must carry a hash of the target. The value when-document requires a hash only when the target is a document. |
withholdable | Whether the producer may withhold the pointer. See Confidentiality. |
orDeclaredAbsent | Whether the producer may state instead that no such artefact exists, with a value from contextAbsenceVocabulary: not-published or not-applicable-to-subject. |
requiredWhen | The condition under which the rule applies, such as a subject type, a document stage, or an attribute value. |
The baseline's rule R2 shows the fields together:
{
"id": "R2",
"context": "vulnerability-statements",
"at": "document",
"level": "MUST",
"hashRequired": "when-document",
"orDeclaredAbsent": "contextAbsenceVocabulary",
"withholdable": false,
"requiredWhen": { "subjectType": "product" }
}
The profile checker tests every profile against check C18. Every reference rule must name a context kind that the profile family defines, and that kind must be carried by real CycloneDX reference types. A profile cannot require a pointer that no document can express.
Two principles
Conformance checks the pointer, never the target
The validator checks that the pointer is present and well formed. It checks that a document pointer carries a hash where the rule requires one, and that an endpoint pointer names its access protocol. Where the evaluator receives the target itself, as with a cited document passed with --with, it checks that the hash matches. It never evaluates the target's content. A Keycloak product record that points to the OSV API passes rule R3 whether or not OSV holds any advisory for Keycloak. A deployment record that points to a data register passes rule R3 of the Deployment Disclosure profile without anyone reading the register.
This is decision 0020 generalised by decision 0025. A CBOM records facts that change when the product or the deployment changes. Context that changes on another trigger, or that another party holds, is joined and not merged.
Direction follows time
A record points to two kinds of target. The first kind exists when the producer writes the record: the companion SBOM, the configuration revision the record was read from, the evidence it was built on. The second kind is a place where later statements will appear: a VEX feed, an advisory API. The record can name that place in advance, because the place exists even though the statements do not yet.
Judgements made afterwards point the other way. A conformance claim and a policy result point to the record by its SHA-256 digest. A record never points to them. If it did, every new judgement would require a new revision of the record, and the record would stop being a stable statement of fact. Policy Evaluation describes the result format.
Three kinds of reference
A CBOM uses three kinds of reference. Only the third is a context pointer.
| Kind | Points to | Form | Examples |
|---|---|---|---|
| Internal | Another object in the same document | A bom-ref | keyStoreRef, which names another object in the same record by its bom-ref |
| Cross-document | Another CBOM or SBOM, or one object in it | A BOM-Link (urn:cdx:<serial>/<version>, optionally #<bom-ref>) and a SHA-256 hash | correspondsTo, cited documents, the companion SBOM |
| Context | An artefact that is not a BOM | A URL, with a hash for a document and an access protocol for an endpoint | Advisories, the security contact, the configuration source, the data register |
A BOM-Link is the CycloneDX way to name one revision of another BOM, and one object inside it. Two references look like pointers and are not. The PQC migration profile's per-purpose roadmapRef (group rule G1) stays a group attribute that holds a URL. Module validation and product certification are native certifications[] in CycloneDX 2.0, so they need no pointer.
The catalogue
The profiles define the following kinds. The last column gives the value in the Keycloak example records, where they carry one. The Keycloak hashes and the operator's URLs are illustrative.
| Kind | Rule | Requirement | Form | Carrier types | Keycloak value |
|---|---|---|---|---|---|
sbom | interface-disclosure#R1 | MUST, product | document, hash required | bom | Product record: examples/context/keycloak-26.7.3-sbom.cdx.json, by BOM-Link urn:cdx:6b3c1d2e-7a41-4c1e-9f0a-26730000b000/1 and SHA-256. Each library also points to its own entry in the SBOM. |
vulnerability-statements | interface-disclosure#R2 | MUST, product; or a stated absence | document (with hash) or endpoint (with access protocol) | vulnerability-assertion, exploitability-statement | Product record: examples/context/keycloak-26.7.3-vex.cdx.json, by BOM-Link and SHA-256, access protocol vex-document. Illustrative: upstream Keycloak publishes no VEX, so a real record states not-published, as cbom-keycloak-product-disclosure-states.cdx.json does. |
advisories | interface-disclosure#R3 | SHOULD, product | endpoint: web-page, csaf-provider, osv-api, ghsa-api | advisories | Product record: https://github.com/keycloak/keycloak/security/advisories (web-page) and https://api.osv.dev/v1/query (osv-api) |
security-contact | interface-disclosure#R4 | SHOULD, product | endpoint | security-contact, rfc-9116 | Product record: https://github.com/keycloak/keycloak/security/policy (web-page) |
configuration-guidance | interface-disclosure#R5 | MUST on an interface whenever I3, I4 or I5 is deployment-defined | document or endpoint | documentation, configuration | Product record: https://www.keycloak.org/server/enabletls on the HTTPS listener, and https://www.keycloak.org/server/management-interface on the management listener |
design-intent | interface-disclosure#R6 | MAY | document or endpoint | threat-model, adversary-model, documentation | None. The validator reports a warning. |
cited-document | deployment-disclosure#P1 | MUST, deployment | document: BOM-Link and SHA-256 hash | bom | Configured record cites the product record. Observed record cites the configured record and the product record. |
configuration-source | deployment-disclosure#R1 | MUST at configured | document or endpoint | configuration, codified-infrastructure, vcs | Configured record: https://git.example.org/platform/sso-config/-/commit/4f2a9c1e7b |
observation-evidence | deployment-disclosure#R2 | SHOULD at observed, on each interface; withholdable | document, hash required | evidence, runtime-analysis-report, log | Observed record: for example, a sensor summary for the ingress, https://evidence.example.org/sso-prod/2026-10-25/ing-tls-zeek-summary.json with a SHA-256 hash |
data-register | deployment-disclosure#R3 | SHOULD; withholdable | document or endpoint | risk-assessment, other | Configured and observed records: https://grc.example.org/registers/data/sso-prod. The register holds data classification and confidentiality lifetime per interface, which decide harvest-now-decrypt-later exposure. See Data Exposure. |
issuer-policy | deployment-disclosure#R4 | MAY | endpoint | documentation | Configured record: https://pki.example.org/cps, the practice statement of the internal CA that issues the ingress, database and directory certificates |
support-lifecycle | pqc-migration#R1 | SHOULD; or a stated absence | endpoint | support, release-notes, documentation | Product record: stated absence not-published |
roadmap | pqc-migration#R2 | SHOULD; or a stated absence | document (with hash) or endpoint | documentation, release-notes, other | Product record: examples/context/keycloak-pqc-roadmap.json, with SHA-256 |
Four further kinds have names, because assurance profiles will need them. No profile requires them yet.
| Kind | What it points to |
|---|---|
code-analysis | Code-analysis findings about how the product calls its cryptography (failure mode 6, integration). |
protocol-testing | Protocol tests of the running service (failure mode 10, composition and negotiation). CycloneDX 2.0 carries it as a test-report reference. |
build-provenance | A build provenance attestation, such as a SLSA or Sigstore attestation. |
platform-assessment | An assessment of the platform's randomness and environment (failure mode 9). |
Lifecycle Data describes the failure modes.
The Keycloak context set
The Keycloak product record points to four documents that are committed with the examples, so a reader can follow every pointer and the test suite can check every hash. Each is an example of what a supplier would publish beside its record. None is carried in the record.
| Document | Pointed to by | What it shows |
|---|---|---|
keycloak-26.7.3-sbom.cdx.json | R1, by BOM-Link and SHA-256; and each library, by a BOM-Link to its own entry | The companion SBOM of the image, in CycloneDX 2.0. It lists an illustrative subset of components and declares its composition incomplete. Its library entries carry the package URLs the record names under I9. |
keycloak-26.7.3-vex.cdx.json | R2, by BOM-Link and SHA-256, access protocol vex-document | Three vulnerability statements in CycloneDX 2.0: one resolved before 26.7.3, one not affected because it needs a configuration the image does not have, one in triage. Each names the affected component by a BOM-Link into the SBOM. The identifiers are illustrative, not CVEs. |
keycloak-configuration-guidance.json | R5 on each interface whose certificate is deployment-defined, beside the Keycloak guide; and the record as a whole | For each value the product leaves open, who decides it (operator, peer or product), the Keycloak setting that decides it, and the documentation page. It names each interface by a BOM-Link into the product record. |
keycloak-pqc-roadmap.json | pqc-migration#R2, with SHA-256 | Planned post-quantum availability per purpose: ML-DSA token signing committed for 27.0 and blocked by the JOSE standard; hybrid TLS key exchange planned and blocked by the Java runtime; SAML signing under evaluation; realm key encryption not planned. The record states the same statuses and blockers and no dates (decision 0007); the roadmap is where a target release may appear. |
The join runs through these documents. The record's I9 names a library's package URL. The SBOM entry for that library carries the same package URL. A VEX statement names the SBOM entry. A consumer can therefore go from an interface to the statements that concern its library without the CBOM carrying any vulnerability data. tests/check-context.py checks that each hash matches, that each VEX statement and each library link resolves, that every deployment-defined value has guidance, and that the roadmap agrees with the record's capability statuses.
How a pointer is carried in CycloneDX
A pointer is an entry in externalReferences. A document-level pointer sits on the subject. An interface-level pointer, such as configuration guidance or observation evidence, sits on the interface's component. Each entry carries four things:
- a CycloneDX reference
type, from the carrier types of its kind; - the property
pkic:profile:context, which names the kind. The property is needed because kinds share types:documentationalone can carry configuration guidance, design intent, an issuer policy or a support lifecycle; - for an endpoint, the property
pkic:profile:accessProtocol, fromweb-page,csaf-provider,osv-api,ghsa-api,vex-documentorother; - for a document, a
hashesentry with a SHA-256 value.
CycloneDX 2.0 allows properties on external references, which makes the two properties possible. Two pointers from the Keycloak product record show both forms:
"externalReferences": [
{
"type": "bom",
"url": "urn:cdx:6b3c1d2e-7a41-4c1e-9f0a-26730000b000/1",
"properties": [ { "name": "pkic:profile:context", "value": "sbom" } ],
"hashes": [ { "alg": "SHA-256", "content": "11234911bf74…" } ]
},
{
"type": "advisories",
"url": "https://api.osv.dev/v1/query",
"properties": [
{ "name": "pkic:profile:context", "value": "advisories" },
{ "name": "pkic:profile:accessProtocol", "value": "osv-api" }
]
}
]
A stated absence is a property on the subject, named after the kind. The Keycloak product record carries pkic:profile:contextAbsent:support-lifecycle with the value not-published. The record exercising the disclosure states carries the same for vulnerability-statements.
What is deliberately not pointed to
- Judgements made after the record. A record does not point to a conformance claim or a policy result about itself. Those point to the record by digest.
- The vulnerability data itself. The record points to where advisories and VEX statements are published. It carries none of them. Vulnerabilities follows the join from the record to the advisories.
- Facts that have a native field. Module validation and product certification are
certifications[]in CycloneDX 2.0. Key rotation and renewal are native too. A pointer would duplicate them. - Planning information per purpose. The PQC migration profile keeps
roadmapRefas a group attribute beside the capability status it explains, such as Keycloak's ML-DSA token signing,committed, with roadmap issue #43690. - The content of any target. No rule checks what a target says. A consumer who relies on a target reads it and judges it separately.