CBOMProfiles /Methodology ← Working group site
START HERE

Introduction

No prior knowledge of bills of materials is assumed. A buyer asks a question about one product. The product's CBOM cannot answer it. A profile changes that, by stating which facts the CBOM must contain. Every other section expands on a step in this example.

The problem, in one example

A vendor supplies Keycloak, an open-source identity server, as a container image, and with it a CBOM. Keycloak 26.7.3 is the example used throughout the methodology. From the CBOM you learn that the main HTTPS listener runs TLS 1.3 with the key exchange of the JDK 21 in the image (X25519 first), that tokens are signed with RS256 by default, and that the operator supplies the server certificate. Every statement in it is true.

Document A, as supplied
────────────────────────────────────────────────────────────
subject       Keycloak 26.7.3 (container image)
stage         implemented (the vendor's build record)
interfaces    11 declared

  [1]  TLS on the main listener (port 8443)     service
       protocol          TLS 1.3
       key exchange      X25519 first (JDK 21 defaults)
       encryption        AES-256-GCM
       authentication    deployment-defined (the operator
                         supplies the server certificate)
  [2]  OIDC token issuance                      service
       authentication    RS256
  ...  nine more: SAML, the plaintext HTTP listener,
       the connections to the database, directory, mail
       server and identity providers, the cluster
       transport and the realm key storage

not declared  the Admin REST API and Admin Console
              the management listener (port 9000)

Three months later a weakness is published that affects the interfaces an administrator uses to manage the server. The question that lands on your desk is whether this product is affected, and if it is, which of the several hundred instances you operate.

Document A cannot answer. It describes the interfaces that serve users and connect to other systems. It says nothing about the interfaces an administrator connects to. The vendor was not careless. It described eleven interfaces accurately and in full. Nothing required it to declare the management interfaces as well.

A CBOM format defines what a document may record. It does not define what a document must record. A vendor that answers a request for a CBOM with Document A has complied with the format and left the buyer no better off.

Document A is not an unusual document. It is the ordinary result of asking a supplier for a CBOM without saying what the CBOM is for.

Why asking for everything does not work

The obvious remedy is to ask for everything, and it makes matters worse. A large product performs thousands of cryptographic operations. A document listing all of them buries the two or three facts that any particular decision depends on. Covering everything does not make a document useful, and in practice no supplier would produce such a document.

There is no absolute standard of completeness for a CBOM. Completeness is relative to a purpose. The question "does this document contain everything?" therefore has no answer. The question "does it contain what this decision needs?" does have one. That second question can be answered only if the decision has first been written down in a form that a machine, and not only a person, can check.

What a profile is

A profile is a short list of rules stating which attributes a CBOM must carry to support one stated decision, for one stated reader. It is a minimum reporting requirement. It is not a schema, and it is not a format.

The example used throughout: the Interface Disclosure Baseline

Every profile begins by naming who reads the document and what they are deciding. Without a named reader and a named decision, there is no principled point at which to stop adding rules.

The Interface Disclosure Baseline, v0.9
ReaderAn operator or purchaser holding a product it did not build and cannot inspect, keeping a cryptographic inventory across an estate.
DecisionWhen a weakness is published against an algorithm, a protocol version or a library, which of the deployed interfaces are affected. And, set beside the record from last quarter, what has changed.
ActionsRecord the interfaces and take no further action. Act on an affected interface by reconfiguring, upgrading or isolating it. Ask the producer for a fuller disclosure. Reject the submission as insufficient to inventory.

Naming the four actions is what allows the rest of the profile to be justified or challenged. A reader with only one available action is not making a decision. A profile written for such a reader has no test for whether it asks for the right things.

The baseline has twenty-three rules, of three kinds. Product rules constrain the document as a whole. Interface rules constrain each interface. Reference rules constrain the pointers the document carries to context it does not contain.

Product rules: constraints on the set of interfaces

#The document mustLevelBecause
P1declare at least one cryptographic interfaceMUSTA CBOM describing no interface answers nothing.
P2declare at least one management interface, or state that there is noneMUSTThis is the rule Document A fails. A hardware token with no configuration surface hides nothing by not having one. A statement that there is no management interface therefore satisfies the rule. Saying nothing does not.
P3identify the subject it describesMUSTAn unidentified record cannot be matched to a deployment, or compared with the same product's record from last quarter.
P4state how complete its list of interfaces isMUSTOtherwise a missing interface is uninterpretable. It could mean the interface does not exist, or that the producer chose not to list it.
P5declare its subject type, product or deploymentMUSTA vendor writes a product record. An operator writes a deployment record. The reader needs to know which one it holds. P3 depends on the answer: a product is identified by a package URL, and a deployment by a tag URI (RFC 4151), such as tag:example.org,2026:deployment/sso-prod.
P6declare one lifecycle stage for the whole documentMUSTA value means something different at each stage. At implemented it is the product's default as shipped. At configured it is the set the deployment permits. At observed it is the set seen during the observation window. One document therefore carries one stage.

P1 and P2 catch omissions, which no rule about a single attribute can do. A document can describe its service interface impeccably, pass every attribute rule, and still fail P2.

Interface rules: constraints on each one

These apply uniformly to every interface the document declares, however many that is.

#AttributeLevelWhat it answers
I1protocolMUSTTLS, SSH, IPsec, and similar
I2protocolVersionMUSTWhich version, since an advisory usually names one
I3keyExchangeMUSTHow the session key is agreed
I4encryptionMUSTWhat protects the traffic once the key is agreed
I5authenticationMUSTHow each end proves who it is
I6endpointRolesMUSTWho is at each end, so the interface can be located in a topology
I7interfaceTypeMUSTOne of five values, among them service, management and interconnect. P2 is checked against this
I8lifecycleStageMUSTWhether the value was implemented, configured or observed, which is how much weight the reader should give it. It must agree with the stage the document declares under P6. The baseline does not accept intended
I9implementationPurlMUSTWhich library implements it, so an advisory against that library can be matched. This is the only rule in the profile that a producer may answer by withholding the value
I10keyWrappingMUSTOn a storage interface: how stored keys are protected. Keycloak stores its realm key material in the database in plaintext
I11defaultStateSHOULDAt implemented: whether the interface is enabled or disabled as shipped. Keycloak's plaintext HTTP listener is disabled by default

Some products do not fix a value themselves. Keycloak does not choose its server certificate; the operator does. For this reason I3 to I5 accept a literal value in place of an algorithm. none means that no algorithm does this job, and it is accepted at any stage. deployment-defined means that the operator chooses. peer-defined means that the other endpoint decides, or that the value is negotiated with it, as on the connection Keycloak opens to its database. These two literals are accepted only at implemented, because a deployment record knows the answer. The reason is set out in decision 0012: a rule that no honest subject can satisfy is wrong, not strict.

Reference rules: pointers to context

A CBOM does not carry everything a reader needs. It points to some things instead: the software bill of materials, the vendor's vulnerability statements, the advisory feed. The reference rules require those pointers. The validator checks the pointer and never the target. See Context Pointers.

#The document points toLevelBecause
R1its software bill of materials (SBOM)MUSTProduct records only. The SBOM lists the components; the CBOM does not repeat it.
R2the vendor's vulnerability statements, or a statement that none are publishedMUSTProduct records only. Upstream Keycloak publishes no VEX statements, so its record says not-published.
R3an advisory source and its access protocolSHOULDFor Keycloak, the OSV API. The reader queries it with the library package URLs from I9.
R4a security contactSHOULDThe reader needs to know where to report a problem.
R5configuration guidance, on any interface where I3 to I5 is deployment-definedMUSTIf the operator chooses the value, the operator needs to know where to set it.
R6a design documentMAYDesign intent is context, not a stage of the record.

Twenty-three rules is the entire profile. It is short on purpose. It names the minimum needed to support one decision and then stops. Because the profile is short, a vendor can satisfy it and a buyer can insist on it.

What the profile does not say

No rule asks whether the cryptography is any good. Whether a product is post-quantum ready is not a fact about the product. It is a judgement made against criteria that change over time, and it is kept outside the document, in versioned policy. The CBOM carries the facts. The policy reaches the verdict. The verdict is dated so that a reader can tell which criteria produced it.

Evaluating two documents against the profile

Document A is the one above, published as cbom-keycloak-product-fail-P2.cdx.json. Document B is the vendor's full build record, cbom-keycloak-product.cdx.json. It declares all thirteen interfaces, including the Admin REST API and the management listener.

RuleDocument ADocument B
P1  at least one cryptographic interfacepassespasses
P2  a management interface, or a statement that there is noneFAILSpasses
P3  the subject is identifiedpassespasses
P4  the interface list states its completenesspassespasses
P5, P6  subject type and one lifecycle stagepassespasses
I1 to I11  on every declared interfacepasses (11 interfaces)passes (13 interfaces)
R1 to R6  pointers to contextpassespasses
Verdictdoes not conformconforms

The Demo shows the reports the reference validator produced for both records, and for the other Keycloak records: the four disclosure outcomes, a design record, the deployment records and the CycloneDX 1.7 legacy form.

The four disclosure outcomes

One refinement recurs throughout the methodology. Suppose the vendor does not want to name the library behind the OIDC interface. The record then carries a marker saying the value is withheld, and rule I9 accepts that, because I9 is the one rule in this profile marked withholdable. The example cbom-keycloak-product-disclosure-states.cdx.json does this.

The marker matters to the reader of the document. A withheld value is a position the producer has taken, and the reader can challenge it in a negotiation. An absent value could mean anything. For this reason the methodology distinguishes four outcomes for any attribute. The CBOM formats distinguish only two: present and absent.

OutcomeWhat it says about the producerSatisfies a MUST rule?
valueIt knows the value and has published itYes
withheldIt knows the value and has decided not to publish itOnly where the rule is marked withholdable
unknownIt does not know the valueNo, but it is reported separately from an attribute that is simply missing
undeclaredNothing was said, and the reader cannot tell which of the other three appliesNo

In the same example the cluster transport declares its authentication unknown, and the SAML interface leaves its encryption undeclared. The record therefore fails I5 and I4, and the report names each outcome. The first three outcomes can be acted on. The fourth can only be guessed at. A buyer who cannot tell a deliberate omission from an oversight has no basis for asking the supplier to fix it.

Where to go next

Everything above can be understood without the rest of the documentation. The other sections expand on it.

Terms is a glossary and sits in the Reference group. Use it to look up an unfamiliar word. It is not intended to be read first.

The methodology works a single example all the way through: Keycloak 26.7.3, expressed in CycloneDX 2.0, with a CycloneDX 1.7 legacy form. The material is a draft for comment from the PKIC CBOM Profiles Working Group. Its positions are settled provisionally and can be reopened.

PKIC CBOM Profiles Working Group · draft for comment.