CBOMProfiles /Methodology ← Working group site
CONCEPT

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:

Reference rules

A reference rule names the kind it requires and sets these fields:

FieldWhat it says
contextThe context kind the pointer must have.
atWhere the pointer sits: on the document (the subject) or on each interface.
levelMUST, SHOULD or MAY.
hashRequiredWhether the pointer must carry a hash of the target. The value when-document requires a hash only when the target is a document.
withholdableWhether the producer may withhold the pointer. See Confidentiality.
orDeclaredAbsentWhether the producer may state instead that no such artefact exists, with a value from contextAbsenceVocabulary: not-published or not-applicable-to-subject.
requiredWhenThe 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.

KindPoints toFormExamples
InternalAnother object in the same documentA bom-refkeyStoreRef, which names another object in the same record by its bom-ref
Cross-documentAnother CBOM or SBOM, or one object in itA BOM-Link (urn:cdx:<serial>/<version>, optionally #<bom-ref>) and a SHA-256 hashcorrespondsTo, cited documents, the companion SBOM
ContextAn artefact that is not a BOMA URL, with a hash for a document and an access protocol for an endpointAdvisories, 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.

KindRuleRequirementFormCarrier typesKeycloak value
sbominterface-disclosure#R1MUST, productdocument, hash requiredbomProduct 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-statementsinterface-disclosure#R2MUST, product; or a stated absencedocument (with hash) or endpoint (with access protocol)vulnerability-assertion, exploitability-statementProduct 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.
advisoriesinterface-disclosure#R3SHOULD, productendpoint: web-page, csaf-provider, osv-api, ghsa-apiadvisoriesProduct record: https://github.com/keycloak/keycloak/security/advisories (web-page) and https://api.osv.dev/v1/query (osv-api)
security-contactinterface-disclosure#R4SHOULD, productendpointsecurity-contact, rfc-9116Product record: https://github.com/keycloak/keycloak/security/policy (web-page)
configuration-guidanceinterface-disclosure#R5MUST on an interface whenever I3, I4 or I5 is deployment-defineddocument or endpointdocumentation, configurationProduct record: https://www.keycloak.org/server/enabletls on the HTTPS listener, and https://www.keycloak.org/server/management-interface on the management listener
design-intentinterface-disclosure#R6MAYdocument or endpointthreat-model, adversary-model, documentationNone. The validator reports a warning.
cited-documentdeployment-disclosure#P1MUST, deploymentdocument: BOM-Link and SHA-256 hashbomConfigured record cites the product record. Observed record cites the configured record and the product record.
configuration-sourcedeployment-disclosure#R1MUST at configureddocument or endpointconfiguration, codified-infrastructure, vcsConfigured record: https://git.example.org/platform/sso-config/-/commit/4f2a9c1e7b
observation-evidencedeployment-disclosure#R2SHOULD at observed, on each interface; withholdabledocument, hash requiredevidence, runtime-analysis-report, logObserved 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-registerdeployment-disclosure#R3SHOULD; withholdabledocument or endpointrisk-assessment, otherConfigured 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-policydeployment-disclosure#R4MAYendpointdocumentationConfigured record: https://pki.example.org/cps, the practice statement of the internal CA that issues the ingress, database and directory certificates
support-lifecyclepqc-migration#R1SHOULD; or a stated absenceendpointsupport, release-notes, documentationProduct record: stated absence not-published
roadmappqc-migration#R2SHOULD; or a stated absencedocument (with hash) or endpointdocumentation, release-notes, otherProduct 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.

KindWhat it points to
code-analysisCode-analysis findings about how the product calls its cryptography (failure mode 6, integration).
protocol-testingProtocol tests of the running service (failure mode 10, composition and negotiation). CycloneDX 2.0 carries it as a test-report reference.
build-provenanceA build provenance attestation, such as a SLSA or Sigstore attestation.
platform-assessmentAn 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.

DocumentPointed to byWhat it shows
keycloak-26.7.3-sbom.cdx.jsonR1, by BOM-Link and SHA-256; and each library, by a BOM-Link to its own entryThe 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.jsonR2, by BOM-Link and SHA-256, access protocol vex-documentThree 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.jsonR5 on each interface whose certificate is deployment-defined, beside the Keycloak guide; and the record as a wholeFor 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.jsonpqc-migration#R2, with SHA-256Planned 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:

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

PKIC CBOM Profiles Working Group · draft for comment.